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.first_name`	string	Yes	Buyer’s first name.
`shopper.last_name`	string	Yes	Buyer’s last name.
`shopper.email`	string	Yes	Buyer’s email address.
`shopper.phone_number`	string	Yes	Buyer’s phone number. Used as the payment identifier for Nequi.
`shopper.country`	string	Yes	ISO country code, e.g. `CO`.
`shopper.id_number`	string	Yes	Buyer’s national ID number (cedula).
`shopper.id_type`	integer	Yes	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).
`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.

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
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:

{
  "data": {
    "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:

{
  "data": {
    "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 uses the buyer’s national ID to generate a QR code and transfer key.Like Daviplata, Breb only accepts CC, CE, and TI document types.

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",
    "shopper": {
      "first_name": "Carlos",
      "last_name": "Rodriguez",
      "email": "carlos@email.com",
      "phone_number": "+573009876543",
      "country": "CO",
      "id_number": "87654321",
      "id_type": 1
    },
    "payment_gateway": {
      "id_payment_gateway": GATEWAY_ID
    },
    "order_key": "invoice-11111"
  }'

Response:

{
  "data": {
    "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 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.

Getting Started

Orders

Payment Flows

Payment Links

Partners

Webhooks

Integrations

Testing

Error Handling

Creating Orders

Creating Orders

Request body

Examples

Document types

What happens next

Nequi

Daviplata

Breb

Stripe

Partners

​Creating Orders

​Request body

​Examples

​Document types

​What happens next

Nequi

Daviplata

Breb

Stripe

​Partners

Creating Orders

Request body

Examples

Document types

What happens next

Partners