Skip to main content

​
Nequi Payment Flow

Nequi is Colombia’s leading mobile wallet. Payments are completed via push notification — the buyer approves the payment directly in their Nequi app.

​
How it works

1

Create order

Call POST /v1/orders with the buyer’s phone_number, id_number, id_type, and the id_payment_gateway for Nequi.
2

Buyer receives push notification

Nequi sends a push notification to the buyer’s phone. The buyer opens the Nequi app and approves the payment.
3

Payment confirmed

Once the buyer approves, the order status changes to confirmed. You receive a webhook notification, or you can poll for the status.

​
Customer experience

  1. Customer receives push notification on their phone
  2. Opens Nequi app to review payment details
  3. Confirms or rejects the payment within the Nequi app
  4. Receives confirmation within the app

​
Suggested UX implementation

​
Show these steps to the user (in Spanish)

Display the following instructions to the buyer while waiting for payment approval:
  1. Recibirás una notificación push en tu teléfono
  2. Revisa los datos y acepta el cobro
  3. Tu compra se procesará automáticamente

​
Processing animation

Use the following GIF to give the buyer visual context while waiting for them to approve the payment in Nequi: 
https://wava-assets.s3.us-east-1.amazonaws.com/payment-gateways/nequi-flow-2025.gif
Nequi payment flow animation

​
Required fields

FieldRequiredDescription
shopper.phone_numberYesThe buyer’s Nequi-registered phone number
shopper.emailYesBuyer’s email
shopper.countryYesCO
shopper.id_numberYesBuyer’s national ID number (required for compliance)
shopper.id_typeYesDocument type ID from Document Types
payment_gateway.id_payment_gatewayYesNequi gateway ID from /v1/orders/paymentGateways

​
Example request

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": 1
    },
    "order_key": "order-12345"
  }'

​
Example response

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

​
Important notes

  • The buyer has a limited time window to approve the push notification before it expires.
  • If the notification expires, the order remains in processing status. You can cancel it and create a new one.
  • While Nequi uses the phone number for the push notification, national ID fields (id_number and id_type) are required on all direct API orders for compliance purposes.

​
Development testing

In the sandbox, Nequi push notifications are simulated. To confirm an order, call GET /v1/orders/{orderId} with the order ID. This call will automatically confirm the order and trigger the webhook. 
# In development: this call auto-confirms the Nequi order
curl -X GET "https://api.dev.wava.co/v1/orders/12345" \
  -H "merchant-key: YOUR_DEV_MERCHANT_KEY"
See Test Data for test phone numbers.