Skip to main content

​
Creating Orders

Once you have discovered the available gateways via Gateway Discovery, you can create an order to initiate a payment.

​
Request body

FieldTypeRequiredDescription
amountnumberYesPayment amount in the smallest currency unit (COP has no decimals).
descriptionstringYesDescription shown to the buyer during payment.
currencystringYesCurrency code. Currently COP for Colombian gateways.
shopper.first_namestringYesBuyer’s first name.
shopper.last_namestringYesBuyer’s last name.
shopper.emailstringYesBuyer’s email address.
shopper.phone_numberstringYesBuyer’s phone number. Used as the payment identifier for Nequi.
shopper.countrystringYesISO country code, e.g. CO.
shopper.id_numberstringYesBuyer’s national ID number (cedula).
shopper.id_typeintegerYesDocument type ID from Document Types endpoint. e.g. 1 for CC.
payment_gateway.id_payment_gatewaynumberYesGateway ID from Gateway Discovery.
order_keystringNoYour unique reference for this order (idempotency key).
redirect_linkstringNoURL to redirect buyer after successful payment.
redirect_link_cancelstringNoURL to redirect buyer if payment is cancelled.
redirect_link_failurestringNoURL to redirect buyer if payment fails.
National ID fields are always required. Every direct API order must include id_number and id_type in the shopper object, regardless of the payment gateway. This is required for compliance and buyer identification. Omitting these fields will return a validation error.
The API also accepts national_id_number and id_national_document_type as aliases for id_number and id_type respectively. Both formats are interchangeable.

​
Examples

The id_payment_gateway value in these examples is a placeholder. Always retrieve the correct ID for each gateway from the Gateway Discovery endpoint (GET /v1/orders/paymentGateways) — do not hardcode it.
Nequi uses the buyer’s phone_number to send a push notification. National ID fields are still required for compliance.
curl -X POST "https://api.wava.co/v1/orders" \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 50000,
    "description": "Premium subscription",
    "currency": "COP",
    "shopper": {
      "first_name": "Juan",
      "last_name": "Perez",
      "email": "juan@email.com",
      "phone_number": "+573001234567",
      "country": "CO",
      "id_number": "1234567890",
      "id_type": 1
    },
    "payment_gateway": {
      "id_payment_gateway": GATEWAY_ID
    },
    "order_key": "order-12345"
  }'
Response:
{
  "data": {
    "id_order": 12345,
    "status": "processing",
    "payment_gateway": {
      "nequi": {
        "phone_number": "****567"
      }
    }
  }
}

​
Document types

The POST /orders response includes an allowed_documents array with the valid document types for the store’s country. Use this field instead of calling GET /v1/national-document-types/{countryCode} separately. 
"allowed_documents": [
  { "id_national_document_type": 1, "country_code": "CO", "type": "CC", "description": "Cédula de Ciudadanía" },
  { "id_national_document_type": 2, "country_code": "CO", "type": "CE", "description": "Cédula de Extranjería" },
  { "id_national_document_type": 3, "country_code": "CO", "type": "TI", "description": "Tarjeta de Identidad" }
]
The id_type field requires the integer ID (id_national_document_type) from this list. The legacy endpoint GET /v1/national-document-types/{countryCode} still works but is deprecated. For Colombia, the most common types are:
IDCodeDescriptionAccepted by
1CCCédula de CiudadaníaAll gateways
2CECédula de ExtranjeríaAll gateways
3TITarjeta de IdentidadAll gateways
Daviplata and Breb only accept CC, CE, and TI document types. Sending a different document type for these gateways will result in a payment error.

​
What happens next

After creating the order, the payment flow depends on the selected gateway:

Nequi

Buyer receives a push notification and approves in the Nequi app.

Daviplata

Buyer receives an OTP via SMS and submits it to confirm.

Breb

Buyer completes a transfer using a QR code or transfer key.

Stripe

Buyer is redirected to complete the card payment.
To track the order result, see Order Status.

​
Partners

If you are a partner creating orders on behalf of a store, the request body is identical. The only difference is the authentication headers. See Partners — Creating Orders for details.