curl --request POST \
  --url https://api.wava.co/v1/orders \
  --header 'Content-Type: application/json' \
  --header 'merchant-key: <api-key>' \
  --data '
{
  "amount": 50000,
  "description": "Premium subscription - Monthly",
  "currency": "COP",
  "shopper": {
    "first_name": "Juan",
    "last_name": "Pérez",
    "email": "juan.perez@email.com",
    "phone_number": "+573001234567",
    "country": "CO",
    "id_number": "1234567890",
    "id_type": 1
  },
  "payment_gateway": {
    "id_payment_gateway": 1
  },
  "order_key": "order-12345",
  "redirect_link": "https://mystore.com/success",
  "redirect_link_cancel": "https://mystore.com/cancel",
  "redirect_link_failure": "https://mystore.com/error"
}
'

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

Orders

Create direct order

Create and process a payment order directly. The API initiates payment processing immediately based on the selected gateway.

All direct API orders require id_number and id_type in the shopper object for compliance and buyer identification, regardless of the selected gateway. Use the Get Document Types endpoint to retrieve valid id_type values.

Gateway-specific behavior:

Nequi — Additionally requires phone_number in the shopper object. A push notification is sent to the buyer’s Nequi app. The buyer approves or rejects in-app. You receive a webhook when the payment is confirmed or cancelled.

Daviplata — Uses id_number and id_type to initiate the OTP flow. Only accepts CC, CE, and TI document types. The buyer receives an OTP via SMS. You must submit the OTP using the Daviplata OTP endpoint to complete payment.

Breb — Uses id_number and id_type to generate a transfer. Only accepts CC, CE, and TI document types. The API returns a QR code (base64 encoded) and a transfer key. The buyer uses either to complete the interbank transfer via their banking app. You receive a webhook when the payment is confirmed.

The id_payment_gateway value must come from the Get Payment Gateways endpoint. Do not hardcode gateway IDs as they may vary by store configuration.

POST

orders

curl --request POST \
  --url https://api.wava.co/v1/orders \
  --header 'Content-Type: application/json' \
  --header 'merchant-key: <api-key>' \
  --data '
{
  "amount": 50000,
  "description": "Premium subscription - Monthly",
  "currency": "COP",
  "shopper": {
    "first_name": "Juan",
    "last_name": "Pérez",
    "email": "juan.perez@email.com",
    "phone_number": "+573001234567",
    "country": "CO",
    "id_number": "1234567890",
    "id_type": 1
  },
  "payment_gateway": {
    "id_payment_gateway": 1
  },
  "order_key": "order-12345",
  "redirect_link": "https://mystore.com/success",
  "redirect_link_cancel": "https://mystore.com/cancel",
  "redirect_link_failure": "https://mystore.com/error"
}
'

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

Authorizations

merchant-key

string

header

required

Merchant key for store identification. Required for all API requests.

merchant-key: YOUR_MERCHANT_KEY

Body

application/json

amount

number

required

Order amount. Must be greater than 0.

Required range: x >= 0.01

Example:

50000

description

string

required

Order description displayed to the buyer during checkout.

Required string length: 1 - 255

Example:

"Premium subscription - Monthly"

payment_gateway

object

required

Show child attributes

currency

string

ISO 4217 currency code. Defaults to store currency if omitted.

Required string length: 3

Pattern: ^[A-Z]{3}$

Example:

"COP"

shopper

object

Show child attributes

order_key

string

Your external order reference. Use this to correlate Wava orders with your system.

Maximum string length: 100

Example:

"order-12345"

redirect_link

string<uri>

URL to redirect buyer after successful payment.

Example:

"https://mystore.com/success"

redirect_link_cancel

string<uri>

URL to redirect buyer if payment is cancelled.

Example:

"https://mystore.com/cancel"

redirect_link_failure

string<uri>

URL to redirect buyer if payment fails.

Example:

"https://mystore.com/error"

device_key

string

Device identifier for session tracking.

Maximum string length: 100

Example:

"device-12345"

Response

Order created and payment initiated successfully

data

object

Show child attributes

Get available payment gateways

Get order details

API Reference

Endpoints

Create direct order

Authorizations

Body

Response