> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wava.co/llms.txt
> Use this file to discover all available pages before exploring further.
# Creating Orders
> Create payment orders using the Wava API with any available gateway.
# Creating Orders
Once you have discovered the available gateways via [Gateway Discovery](/orders/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](/orders/document-types) endpoint. e.g. `1` for CC. |
| `payment_gateway.id_payment_gateway` | number | Yes | Gateway ID from [Gateway Discovery](/orders/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](/orders/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.
```bash theme={null}
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:**
```json theme={null}
{
"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).
```bash theme={null}
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:**
```json theme={null}
{
"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](/payment-flows/daviplata) 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.
```bash theme={null}
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:**
```json theme={null}
{
"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](/payment-flows/breb) 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.
```json theme={null}
"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:
Buyer receives a push notification and approves in the Nequi app.
Buyer receives an OTP via SMS and submits it to confirm.
Buyer completes a transfer using a QR code or transfer key.
Buyer is redirected to complete the card payment.
To track the order result, see [Order Status](/orders/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](/partners/creating-orders) for details.