Creating Orders

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

Request body

Field	Type	Required	Description
`amount`	number	Yes	Payment amount in the smallest currency unit (COP has no decimals).
`description`	string	Yes	Description shown to the buyer during payment.
`currency`	string	Yes	Currency code. Currently `COP` for Colombian gateways.
`shopper`	object	Yes, except Breb	Buyer data. Optional for Breb: see Breb without shopper.
`shopper.first_name`	string	No	Buyer’s first name.
`shopper.last_name`	string	No	Buyer’s last name.
`shopper.email`	string	Yes, except Breb	Buyer’s email address.
`shopper.phone_number`	string	Yes, except Breb	Buyer’s phone number. Used as the payment identifier for Nequi.
`shopper.country`	string	Yes, except Breb	ISO country code, e.g. `CO`.
`shopper.id_number`	string	Yes, except Breb	Buyer’s national ID number (cedula).
`shopper.id_type`	integer	Yes, except Breb	Document type ID from Document Types endpoint. e.g. `1` for CC.
`payment_gateway.id_payment_gateway`	number	Yes	Gateway ID from Gateway Discovery.
`order_key`	string	No	Your unique reference for this order (idempotency key, scoped to your store). See Resending an order_key.
`redirect_link`	string	No	URL to redirect buyer after successful payment.
`redirect_link_cancel`	string	No	URL to redirect buyer if payment is cancelled.
`redirect_link_failure`	string	No	URL to redirect buyer if payment fails.

Nequi and Daviplata require the shopper. Their direct orders must include email, phone_number, country, id_number and id_type; omitting any of them returns a 422 validation error.

Breb orders without shopper

For Breb, the shopper object is optional: the QR code and transfer key are generated from the order, not from the buyer’s data. You can omit shopper entirely or send only the fields you have.

Fields you do send are still validated for format (an invalid email returns 422), but none of them is required.
Who actually paid is reported by the payer’s bank after the transfer is confirmed, and it is best-effort (see Payer data).
In webhooks and when reading the order, shopper fields you did not send arrive as null (the whole shopper object can be null). After confirmation, first_name and last_name may be filled with the payer’s name. Email and phone number are never guaranteed for Breb.

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
Daviplata
Breb

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:

{
  "result": {
    "id_order": 12345,
    "status": "processing",
    "payment_gateway": {
      "nequi": {
        "phone_number": "****567"
      }
    }
  }
}

Daviplata uses the buyer’s national ID to initiate the OTP flow. The buyer receives an OTP via SMS.Daviplata only accepts the following document types: CC (Cédula de Ciudadanía), CE (Cédula de Extranjería), and TI (Tarjeta de Identidad).

curl -X POST "https://api.wava.co/v1/orders" \
  -H "merchant-key: YOUR_MERCHANT_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 75000,
    "description": "Product purchase",
    "currency": "COP",
    "shopper": {
      "first_name": "Maria",
      "last_name": "Gonzalez",
      "email": "maria@email.com",
      "phone_number": "+573001234567",
      "country": "CO",
      "id_number": "12345678",
      "id_type": 1
    },
    "payment_gateway": {
      "id_payment_gateway": GATEWAY_ID
    },
    "order_key": "order-67890"
  }'

Response:

{
  "result": {
    "id_order": 12346,
    "status": "processing",
    "daviplata_token_required": true,
    "payment_gateway": {
      "daviplata": {
        "national_id_number": "****678",
        "id_national_document_type": 1,
        "id_type": "CC"
      }
    }
  }
}

After receiving this response, you must submit the OTP. See Daviplata flow for the full OTP submission step.

Breb generates a QR code and transfer key from the order. It has no gateway-specific fields, and the shopper object is optional (see Breb orders without shopper).The payer’s data (name and masked document) arrives after the payment is confirmed and is best-effort. Email and phone number are not guaranteed for Breb payers.

curl -X POST "https://api.wava.co/v1/orders"       -H "merchant-key: YOUR_MERCHANT_KEY"       -H "Content-Type: application/json"       -d '{
    "amount": 100000,
    "description": "Invoice payment",
    "currency": "COP",
    "payment_gateway": {
      "id_payment_gateway": GATEWAY_ID
    },
    "order_key": "invoice-11111"
  }'

Response:

{
  "result": {
    "id_order": 12347,
    "status": "processing",
    "payment_gateway": {
      "breb": {
        "qr_code": "iVBORw0KGgoAAAANSUhEUgAAAQAAAAEA...",
        "key": "BREB-TXN-2025-ABCDEF123456"
      }
    }
  }
}

Display the QR code and key to the buyer. See Breb flow for display guidelines.

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:

ID	Code	Description	Accepted by
1	CC	Cédula de Ciudadanía	All gateways
2	CE	Cédula de Extranjería	All gateways
3	TI	Tarjeta de Identidad	All gateways

Daviplata only accepts CC, CE, and TI document types. Sending a different document type 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.

Resending an order_key

order_key identifies one order on your store. Use a unique order_key per order. Resending it is safe — it is how you retry after a timeout or a network error without creating a second order — and the response depends on the order that already exists for it. A resend is the same order only if it has the same amount and currency. The rest of the body may change between attempts: a different payment_gateway (the buyer switches from Nequi to Daviplata), corrected shopper data or a new description.

Existing order with that `order_key`	Response
None	A new order is created.
Different `amount` or `currency`	`409 ORDER_KEY_CONFLICT`. Nothing is created or changed. The body includes `existing_amount` and `existing_currency`.
Already paid (`confirmed` or `refunded`)	`200` with the existing order, `already_processed: true` and `api_code: "ORDER_ALREADY_PROCESSED"`. No new payment is started, and no payment data (push, OTP, QR) is returned.
`pending`, `processing` or `expired`	The payment is started again over the same order. A payment still in progress is cancelled first.
`cancelled`	Error `INVALID_ORDER_STATUS`: a cancelled order cannot be retried. Create a new order with a new `order_key`.

Already paid

{
  "status": "success",
  "result": {
    "id_order": 159537,
    "id_external": "order-12345",
    "purchase_date": "2026-09-01 10:00:00",
    "status": "confirmed",
    "total_price": "50000.00",
    "currency": "COP",
    "wava_fee": null,
    "net_to_merchant": null,
    "already_processed": true,
    "api_code": "ORDER_ALREADY_PROCESSED",
    "message": "Order already processed",
    "isDynamicLink": false
  }
}

Do not reuse an order_key for a different payment — for example, several payments against the same invoice. A resend with another amount answers 409, and one with the same amount resolves to the existing order. Use a distinct order_key per payment.

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.

Getting Started

Orders

Payment Flows

Payment Links

Partners

Webhooks

Integrations

Testing

Error Handling

Creating Orders

Creating Orders

Request body

Breb orders without shopper

Examples

Document types

What happens next

Nequi

Daviplata

Breb

Stripe

Resending an order_key

Partners

​Creating Orders

​Request body

​Breb orders without shopper

​Examples

​Document types

​What happens next

Nequi

Daviplata

Breb

Stripe

​Resending an order_key

​Partners

Creating Orders

Request body

Breb orders without shopper

Examples

Document types

What happens next

Resending an order_key

Partners