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

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": 1
    },
    "order_key": "order-12345"
  }'
Response:
{
  "data": {
    "id_order": 12345,
    "status": "processing",
    "payment_gateway": {
      "nequi": {
        "phone_number": "****567"
      }
    }
  }
}

​
Document types

The id_type field requires the integer ID of the document type. Use GET /v1/national-document-types/{countryCode} to retrieve valid values. See Document Types for details. 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.