Nequi Payments

Accept payments through Nequi, one of the most popular digital wallets in Colombia. The buyer selects Nequi at checkout and enters their registered phone number. The buyer then receives a push notification on their phone to complete the payment.

This guide shows you how to create a payment intent for Nequi. It also covers the Push payment flow, how to resolve the final status asynchronously, and how refunds work.

This document applies to the following country:

Colombia

How It Works

Use Nequi to reach Nequi customers in Colombia with a card-free mobile experience. You need only a single integration with Web Checkout. Nequi has these key characteristics:

Payment flow: Push: the buyer receives a push notification in the Nequi app and accepts it. This flow requires the buyer's phone number.
Single integration: you integrate only with Web Checkout.
Asynchronous: the payment stays in PENDING until the buyer approves it in the Nequi app. You receive the final status through a webhook or by querying GET /payment-intent/{id}.
Refunds: Nequi supports total and partial refunds on settled transactions.

The end-to-end flow involves the buyer, your backend, the Getnet Web Checkout API, and SEP:

Before You Start

Make sure the following are in place before you integrate:

The seller has Nequi enabled in the Web Checkout configuration.
You have generated your token as described in the Authentication document.
Your payments are in Colombian pesos (COP).

Step 1: Create the Payment Intent

Call the Web Checkout API to create a payment intent.

Endpoint
`POST /payment-intent`

Required fields

Field	Type	Description	Example
`order_id`	string	Unique order reference defined by the merchant. Maximum 32 characters.	`ORDER_NEQUI_97532`
`payment.currency`	string	Currency code. Must be `COP` for Nequi.	`COP`
`payment.amount`	integer	Purchase amount in integer format, in cents.	`400`
`customer`	object	Customer data. Required for Nequi.	—
`customer.phone_number`	string	Customer's Nequi phone number, with 10 digits. Required for Nequi Push: it identifies the payment.	`3001234567`
`customer.first_name`	string	Customer's first name. Required if you use Payout.	`Jose`
`customer.last_name`	string	Customer's last name. Required if you use Payout.	`da Silva`

Optional fields

Field	Type	Description	Example
`configurations.3ds`	boolean	Controls 3D Secure authentication. Does not apply to Nequi.	`false`
`configurations.preauthorization`	boolean	Indicates if the payment is a pre-authorization. Does not apply to Nequi.	`false`
`configurations.card_verification`	boolean	Indicates if this is a card verification flow. Does not apply to Nequi.	`false`
`configurations.success_url`	string	Redirect URL in case of successful payment. Overrides the seller configuration.	`https://www.mystore.com/checkout/success`
`configurations.error_url`	string	Redirect URL in case of an error during payment. Overrides the seller configuration.	`https://www.mystore.com/checkout/error`
`product[].product_type`	string	Product type.	`service`
`product[].title`	string	Product title.	`Suscripción mensual`
`product[].description`	string	Product description.	`Plan Pro - 1 mes`
`product[].value`	integer	Product value. Must match `payment.amount`.	`400`
`product[].quantity`	integer	Product quantity.	`1`
`customer.customer_id`	string	Customer identifier.	`customer_co_006`
`customer.name`	string	Customer's full name.	`Jose da Silva`
`customer.email`	string	Customer's email address.	`customer@email.com`
`customer.document_type`	string	Customer's document type (for example, `CC`).	`CC`
`customer.document_number`	string	Customer's document number.	`50506468`
`customer.checked_email`	boolean	Indicates whether the customer's email has been verified.	`true`
`customer.billing_address.street`	string	Name of a street.	`Avenida Siempre Viva`
`customer.billing_address.number`	string	Number that identifies the position of a building on a street.	`123`
`customer.billing_address.complement`	string	Address complement.	`Apto 601`
`customer.billing_address.district`	string	District or neighborhood.	`Centro`
`customer.billing_address.city`	string	City.	`Bogota`
`customer.billing_address.state`	string	State or department.	`DC`
`customer.billing_address.country`	string	Country code.	`CO`
`customer.billing_address.postal_code`	string	Postal or ZIP code.	`110111`
`soft_descriptor`	string	Payment description that appears on the customer's receipt.	`Tienda CO`
`expires_at`	string	Payment intent expiration. If omitted, the payment intent does not expire.	`1h`

Example of Request

The following example creates a Nequi payment intent for a customer in Colombia, including the phone number required for the Push flow.

JSON

{
  "mode": "instant",
  "order_id": "ORDER_NEQUI_97532",
  "configurations": {
    "3ds": false,
    "preauthorization": false,
    "card_verification": false,
    "success_url": "https://www.mystore.com/checkout/success",
    "error_url": "https://www.mystore.com/checkout/error"
  },
  "payment": {
    "currency": "COP",
    "amount": 400
  },
  "product": [
    {
      "product_type": "service",
      "title": "Suscripción mensual",
      "description": "Plan Pro - 1 mes",
      "value": 400,
      "quantity": 1
    }
  ],
  "customer": {
    "customer_id": "customer_co_006",
    "first_name": "Jose",
    "last_name": "da Silva",
    "name": "Jose da Silva",
    "email": "customer@email.com",
    "document_type": "CC",
    "document_number": "50506468",
    "phone_number": "3001234567",
    "checked_email": true,
    "billing_address": {
      "street": "Avenida Siempre Viva",
      "number": "123",
      "complement": "Apto 601",
      "district": "Centro",
      "city": "Bogota",
      "state": "DC",
      "country": "CO",
      "postal_code": "110111"
    }
  },
  "soft_descriptor": "Tienda CO",
  "expires_at": "1h"
}

JSON

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
{
  "mode": "instant",
  "order_id": "ORDER_NEQUI_97532",
  "configurations": {
    "3ds": false,
    "preauthorization": false,
    "card_verification": false,
    "success_url": "https://www.mystore.com/checkout/success",
    "error_url": "https://www.mystore.com/checkout/error"
  },
  "payment": {
    "currency": "COP",
    "amount": 400
  },
  "product": [
    {
      "product_type": "service",
      "title": "Suscripción mensual",
      "description": "Plan Pro - 1 mes",
      "value": 400,
      "quantity": 1
    }
  ],
  "customer": {
    "customer_id": "customer_co_006",
    "first_name": "Jose",
    "last_name": "da Silva",
    "name": "Jose da Silva",
    "email": "customer@email.com",
    "document_type": "CC",
    "document_number": "50506468",
    "phone_number": "3001234567",
    "checked_email": true,
    "billing_address": {
      "street": "Avenida Siempre Viva",
      "number": "123",
      "complement": "Apto 601",
      "district": "Centro",
      "city": "Bogota",
      "state": "DC",
      "country": "CO",
      "postal_code": "110111"
    }
  },
  "soft_descriptor": "Tienda CO",
  "expires_at": "1h"
}

Example 200/201 Response

The following example shows a successful response, which returns the payment intent ID, the trade name and the redirect URL.

JSON

{
  "payment_intent_id": "d4fb9559-09f3-43ac-8ba5-c0d786506ea9",
  "trade_name": "Tienda Colombiana",
  "redirect_url": "https://www.globalgetnet.com/hosted-web-checkout/eyJraWQiOi..."
}

JSON

1
2
3
4
5
{
  "payment_intent_id": "d4fb9559-09f3-43ac-8ba5-c0d786506ea9",
  "trade_name": "Tienda Colombiana",
  "redirect_url": "https://www.globalgetnet.com/hosted-web-checkout/eyJraWQiOi..."
}

Step 2: Let the Buyer Choose the Flow and Approve the Payment

You don't send any additional request in this step. The buyer chooses Nequi in the checkout, and Web Checkout sends the operation. The next steps depend on the flow the buyer chooses:

Flow	What happens	Requirement
Push	The buyer receives a push notification in the Nequi app and accepts it to approve the payment.	Phone number with 10 digits

If the buyer does not accept the push, the transaction expires. Use the webhook to get the final status.

Step 3: Confirm the Result

Nequi is asynchronous: the payment stays in PENDING until the buyer approves it in the Nequi app. Resolve the final status in one of two ways:

Webhook: receive the approved or denied notification (see payloads below).
Query: call GET /payment-intent/{id} to check the current status.

We recommend that you validate every webhook against GET /payment-intent/{id}.

Example of Response — Approved

The following webhook payload shows an approved payment, with the result status Authorized.

JSON

{
  "payment_intent_id": "2a8b58fe-76dd-5cae-b518-1f28ea0b3f3d",
  "checkout_id": "6bc26e2f-fb9c-4671-95e3-0c4e13280648",
  "order_id": "ORDER_NEQUI_97532",
  "mode": "instant",
  "seller": {
    "id": "716d899e-9091-4577-a12f-8a77ec4d1e0b",
    "trade_name": "GetNet Shop",
    "merchant_document": "00000000000",
    "settings": { "notification_url_configured": true }
  },
  "customer": {
    "customer_id": "customer_co_006",
    "name": "Jose da Silva",
    "email": "customer@email.com",
    "document_type": "CC",
    "document_number": "50506468"
  },
  "payment": {
    "method": "nequi",
    "amount": 400,
    "currency": "COP",
    "result": {
      "payment_id": "42853760-f2a5-4dff-b4f2-a60689c19965",
      "status": "Authorized",
      "authorization_code": "888888",
      "transaction_datetime": "2026-07-08T12:05:00.000Z"
    }
  },
  "created_at": "2026-07-08T12:03:00.000Z",
  "updated_at": "2026-07-08T12:05:00.000Z"
}

JSON

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
{
  "payment_intent_id": "2a8b58fe-76dd-5cae-b518-1f28ea0b3f3d",
  "checkout_id": "6bc26e2f-fb9c-4671-95e3-0c4e13280648",
  "order_id": "ORDER_NEQUI_97532",
  "mode": "instant",
  "seller": {
    "id": "716d899e-9091-4577-a12f-8a77ec4d1e0b",
    "trade_name": "GetNet Shop",
    "merchant_document": "00000000000",
    "settings": { "notification_url_configured": true }
  },
  "customer": {
    "customer_id": "customer_co_006",
    "name": "Jose da Silva",
    "email": "customer@email.com",
    "document_type": "CC",
    "document_number": "50506468"
  },
  "payment": {
    "method": "nequi",
    "amount": 400,
    "currency": "COP",
    "result": {
      "payment_id": "42853760-f2a5-4dff-b4f2-a60689c19965",
      "status": "Authorized",
      "authorization_code": "888888",
      "transaction_datetime": "2026-07-08T12:05:00.000Z"
    }
  },
  "created_at": "2026-07-08T12:03:00.000Z",
  "updated_at": "2026-07-08T12:05:00.000Z"
}

Example of Response — Denied

The following webhook payload shows a denied payment. In this example, the buyer rejected the payment or it expired in the Nequi app.

JSON

{
  "payment_intent_id": "2a8b58fe-76dd-5cae-b518-1f28ea0b3f3d",
  "checkout_id": "6bc26e2f-fb9c-4671-95e3-0c4e13280648",
  "order_id": "ORDER_NEQUI_97532",
  "mode": "instant",
  "payment": {
    "method": "nequi",
    "amount": 400,
    "currency": "COP",
    "result": {
      "payment_id": "42853760-f2a5-4dff-b4f2-a60689c19965",
      "status": "Denied",
      "transaction_datetime": "2026-07-08T12:07:00.000Z",
      "return_message": "Payment rejected/expired in Nequi app"
    }
  },
  "created_at": "2026-07-08T12:03:00.000Z",
  "updated_at": "2026-07-08T12:07:00.000Z"
}

JSON

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
  "payment_intent_id": "2a8b58fe-76dd-5cae-b518-1f28ea0b3f3d",
  "checkout_id": "6bc26e2f-fb9c-4671-95e3-0c4e13280648",
  "order_id": "ORDER_NEQUI_97532",
  "mode": "instant",
  "payment": {
    "method": "nequi",
    "amount": 400,
    "currency": "COP",
    "result": {
      "payment_id": "42853760-f2a5-4dff-b4f2-a60689c19965",
      "status": "Denied",
      "transaction_datetime": "2026-07-08T12:07:00.000Z",
      "return_message": "Payment rejected/expired in Nequi app"
    }
  },
  "created_at": "2026-07-08T12:03:00.000Z",
  "updated_at": "2026-07-08T12:07:00.000Z"
}

Nequi Status Values

For Nequi, the expected flow is PENDING → APPROVED or REJECTED, notified through the webhook.

Your webhook must be idempotent and handle duplicate notifications. Release the order only after the payment is approved.

On this page

Nequi Payments

First Steps

Core Concept

Reference

Payment Guides

Alternative Payment Methods

(Deprecated) Legacy Checkout Brasil

Nequi Payments

How It Works

Before You Start

Step 1: Create the Payment Intent

Example of Request

Example 200/201 Response

Step 2: Let the Buyer Choose the Flow and Approve the Payment

Step 3: Confirm the Result

Example of Response — Approved

Example of Response — Denied

Nequi Status Values