Create direct order on behalf of a store

curl --request POST \
  --url 'https://api.wava.co/v1/orders#partners' \
  --header 'Content-Type: application/json' \
  --header 'merchant-key: <api-key>' \
  --data '
{
  "amount": 50000,
  "description": "Premium subscription - Monthly",
  "payment_gateway": {
    "id_payment_gateway": 1
  },
  "currency": "COP",
  "shopper": {
    "first_name": "Juan",
    "last_name": "Pérez",
    "email": "juan.perez@email.com",
    "phone_number": "+573001234567",
    "country": "CO",
    "id_number": "12345678",
    "id_type": 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",
  "device_key": "device-12345"
}
'

const options = {
  method: 'POST',
  headers: {'merchant-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 50000,
    description: 'Premium subscription - Monthly',
    payment_gateway: {id_payment_gateway: 1},
    currency: 'COP',
    shopper: {
      first_name: 'Juan',
      last_name: 'Pérez',
      email: 'juan.perez@email.com',
      phone_number: '+573001234567',
      country: 'CO',
      id_number: '12345678',
      id_type: 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',
    device_key: 'device-12345'
  })
};

fetch('https://api.wava.co/v1/orders#partners', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.wava.co/v1/orders#partners"

payload = {
    "amount": 50000,
    "description": "Premium subscription - Monthly",
    "payment_gateway": { "id_payment_gateway": 1 },
    "currency": "COP",
    "shopper": {
        "first_name": "Juan",
        "last_name": "Pérez",
        "email": "juan.perez@email.com",
        "phone_number": "+573001234567",
        "country": "CO",
        "id_number": "12345678",
        "id_type": 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",
    "device_key": "device-12345"
}
headers = {
    "merchant-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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

{
  "code": 4007,
  "api_code": "INVALID_MERCHANT_KEY",
  "message": "Invalid merchant key",
  "description": "The provided merchant key is invalid or expired",
  "error": true
}

{
  "code": 7001,
  "api_code": "INTERNAL_SERVER_ERROR",
  "message": "Internal server error",
  "description": "An unexpected error occurred while processing your request",
  "error": true
}

Partners

Create direct order on behalf of a store

Partners create and process orders for a merchant using that merchant’s merchant-key, delivered to the partner in the store_onboarded webhook. The request body is identical to the standard Create Direct Order endpoint.

The merchant-key is what authorizes the call and what decides which store the order belongs to. Partner credentials may be sent alongside it for attribution, but never change the target store; on their own they are rejected with 403.

All payment gateways available to the merchant can be used.

POST

orders#partners

Create direct order on behalf of a store

curl --request POST \
  --url 'https://api.wava.co/v1/orders#partners' \
  --header 'Content-Type: application/json' \
  --header 'merchant-key: <api-key>' \
  --data '
{
  "amount": 50000,
  "description": "Premium subscription - Monthly",
  "payment_gateway": {
    "id_payment_gateway": 1
  },
  "currency": "COP",
  "shopper": {
    "first_name": "Juan",
    "last_name": "Pérez",
    "email": "juan.perez@email.com",
    "phone_number": "+573001234567",
    "country": "CO",
    "id_number": "12345678",
    "id_type": 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",
  "device_key": "device-12345"
}
'

const options = {
  method: 'POST',
  headers: {'merchant-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 50000,
    description: 'Premium subscription - Monthly',
    payment_gateway: {id_payment_gateway: 1},
    currency: 'COP',
    shopper: {
      first_name: 'Juan',
      last_name: 'Pérez',
      email: 'juan.perez@email.com',
      phone_number: '+573001234567',
      country: 'CO',
      id_number: '12345678',
      id_type: 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',
    device_key: 'device-12345'
  })
};

fetch('https://api.wava.co/v1/orders#partners', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.wava.co/v1/orders#partners"

payload = {
    "amount": 50000,
    "description": "Premium subscription - Monthly",
    "payment_gateway": { "id_payment_gateway": 1 },
    "currency": "COP",
    "shopper": {
        "first_name": "Juan",
        "last_name": "Pérez",
        "email": "juan.perez@email.com",
        "phone_number": "+573001234567",
        "country": "CO",
        "id_number": "12345678",
        "id_type": 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",
    "device_key": "device-12345"
}
headers = {
    "merchant-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

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

{
  "code": 4007,
  "api_code": "INVALID_MERCHANT_KEY",
  "message": "Invalid merchant key",
  "description": "The provided merchant key is invalid or expired",
  "error": true
}

{
  "code": 7001,
  "api_code": "INTERNAL_SERVER_ERROR",
  "message": "Internal server error",
  "description": "An unexpected error occurred while processing your request",
  "error": true
}

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

Buyer data. Required for Nequi and Daviplata direct orders, where email, phone_number, country, id_number and id_type must all be present (a missing one returns 422). Optional for Breb: omit it or send only the fields you have; fields you send are validated for format.

Show child attributes

order_key

string

Your reference for this order, used to correlate Wava orders with your system. It is also the idempotency key of the order, scoped to your store: resending an order_key with the same amount and currency resolves to the existing order (an already paid one answers 200 with already_processed: true and starts no new payment), and resending it with a different amount or currency answers 409 ORDER_KEY_CONFLICT. Use a unique order_key per order.

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 on behalf of store

result

object

Show child attributes

API Reference

Endpoints

Create direct order on behalf of a store

Authorizations

Body

Response