Nequi

nequi logo
Nequi is a widely used digital wallet in Colombia. The API integration supports Pay-ins (collecting funds via QR Code or Push Notification) and Payouts (disbursing funds directly to a Nequi account). A webhook confirms every flow asynchronously.

Available payment methods

The payment_method field determines which of two primary ways the customer uses to complete a Nequi payment:
  1. Nequi QR (WALLET): The API returns a redirect_url. You can redirect the customer to this URL or render it as a QR code. The customer scans the QR code with the Nequi app.
  2. Nequi Push (WALLET_PUSH): You trigger a push notification to the customer's phone number. The customer accepts the payment directly within the Nequi app.

Requirements

Before you integrate Nequi, you need to:

  • Generate an access token through the Authentication endpoint.
  • Configure a public HTTPS callback_url to receive asynchronous status updates when the customer completes or rejects the payment.
  • Ensure that the merchant account is configured for Colombia (CO) and COP currency.
  • For Payouts: Ensure your merchant account has sufficient balance to cover the disbursement amount.

Use case specifics

When you integrate Nequi through Getnet, specific market requirements apply. Nequi is only available in Colombia and supports COP currency.

Characteristics

The table below summarizes the behavior and requirements for Nequi payment flows.

CapabilityDetails
Customer experienceQR Flow: Customer scans a code generated from the redirect URL.
Push Flow: Customer receives a notification on their phone to approve.
ConfirmationAsynchronous — A webhook notification informs you when the payment is approved or rejected.
Idempotency & uniquenessEach request must include a unique idempotency_key.

Available features

Use the matrix below to confirm the scenarios currently supported for Nequi.

Payment flowSupported countriesPurchasesRefundsPartial refundsPre-authorizationsRecurring paymentsPayouts
Direct (QR / Push)Colombia✅✅✅❌✅✅

Payment flow

This section guides you through the complete process of implementing Nequi payments. The following diagram gives an overview of the Nequi payment process:

1. Create the payment request

To initiate a Nequi payment, call the Create - Authorize endpoint.

You must choose the flow by setting the payment_method. You must also provide the customer's mobile phone number, which is critical for the Push flow.

The following table lists the minimum fields required for a Nequi payment.

AttributeDescriptionRequired value
payment_methodDefines the flow typeWALLET (for QR Code flow) or WALLET_PUSH (for Push Notification flow)
brandNequi brand identifierNEQUI
callback_urlWhere status updates are sentYour HTTPS endpoint
amountTransaction amount in centsInteger (e.g., 10000 for $100.00 COP)
currencyISO currency codeCOP
order_idMerchant reference for reconciliationUnique string (max 32 characters)
customer.phone_numberCustomer's mobile numberString (e.g., 3001234567)

Nequi Push notification

Use WALLET_PUSH. The customer receives a notification on their phone. No redirect URL is returned in the response.

The following sample request shows how to initialize a Nequi push notification payment.

bash
curl --location --request POST '[https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments](https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments)' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <ACCESS_TOKEN>' \ --data-raw '{ "idempotency_key": "bcad559e-ae27-480c-86ff-fe6c17c762c3", "request_id": "894d2718-3966-4df2-b9c2-1a7ddece28ff", "order_id": "35541354322", "data": { "amount": 400, "currency": "COP", "customer_id": "47377104-827e-4143-b461-fdf768fb2903", "payment": { "payment_id": "42853760-f2a5-4dff-b4f2-a60689c19965", "payment_method": "WALLET_PUSH", "brand": "NEQUI", "soft_descriptor": "NEQUI TESTE" }, "additional_data": { "callback_url": "https://localhost:8080/notification/fake/1", "customer": { "email": "stevan.viapiana@getnet.net", "document_number": "50506468", "document_type": "uyci", "name": "Jose da Silva", "phone_number": "34700000000", "billing_address": { "street": "R a", "number": "1", "district": "B", "city": "City Z", "state": "SP", "country": "CO", "postal_code": "05781000", "complement": "N/A" } }, "order": { "items": [ { "name": "Item2", "quantity": 1, "sku": "sku1", "price": 1022 } ] } } } }'

The API responds with a payload similar to the example below.

json
{ "idempotency_key": "bcad559e-ae27-480c-86ff-fe6c17c762c3", "seller_id": "your-seller-id", "payment_id": "42853760-f2a5-4dff-b4f2-a60689c19965", "order_id": "35541354322", "amount": "400", "currency": "COP", "status": "PENDING", "payment_method": "WALLET_PUSH", "received_at": "2025-11-15T10:00:00.000Z", "reason_code": "00", "reason_message": "Waiting for customer approval in Nequi app." }

Nequi QR code

Use WALLET. The API returns a redirect_url that you use to generate a QR code.

The following sample request shows how to initialize a Nequi QR payment.

bash
curl --location --request POST '[https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments](https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments)' \ --header 'Content-Type: application/json' \ --header 'Authorization: Bearer <ACCESS_TOKEN>' \ --data-raw '{ "idempotency_key": "qr-flow-unique-key-123", "request_id": "qr-req-001", "order_id": "35541354323", "data": { "amount": 400, "currency": "COP", "customer_id": "47377104-827e-4143-b461-fdf768fb2903", "payment": { "payment_id": "55853760-f2a5-4dff-b4f2-a60689c19966", "payment_method": "WALLET", "brand": "NEQUI", "soft_descriptor": "NEQUI QR TEST" }, "additional_data": { "callback_url": "https://localhost:8080/notification/fake/1", "customer": { "email": "stevan.viapiana@getnet.net", "document_number": "50506468", "document_type": "uyci", "name": "Jose da Silva", "phone_number": "34700000000", "billing_address": { "street": "R a", "number": "1", "district": "B", "city": "City Z", "state": "SP", "country": "CO", "postal_code": "05781000", "complement": "N/A" } } } } }'

The API responds with a payload similar to the example below.

json
{ "idempotency_key": "qr-flow-unique-key-123", "seller_id": "your-seller-id", "payment_id": "55853760-f2a5-4dff-b4f2-a60689c19966", "order_id": "35541354323", "amount": "400", "currency": "COP", "status": "PENDING", "payment_method": "WALLET", "received_at": "2025-11-15T10:05:00.000Z", "reason_code": "00", "reason_message": "Waiting for payment confirmation.", "additional_data": { "redirect_url": "[https://payment.nequi.com/qr/transaction-token-12345](https://payment.nequi.com/qr/transaction-token-12345)" } }

2. Customer action

The customer action depends on the chosen flow:

QR code

In the QR code flow, the customer scans a QR code with the Nequi mobile app.

  1. The customer is redirected to a page that shows a QR code.
nequi QR code

The customer can scan the QR code with the Nequi mobile app. They can also take a screenshot of the QR code and upload it to the app.

nequi app flow

Push notification

The customer receives a push notification in the Nequi mobile app.

nequi app notification

3. Verify payment status

After the customer approves the payment, your configured callback_url receives a webhook notification. The notification includes the updated status (APPROVED or REJECTED).

You can also check the status using the Get Transaction endpoint.

Payouts

With the Nequi Payout solution, you disburse funds directly to a customer's Nequi digital wallet in Colombia. It's ideal for gig economy earnings, refunds, or gaming withdrawals.

The Getnet API simplifies the underlying process into a single request. You don't need to register the user or token manually. Provide the customer's phone number and details in the payout request.

Characteristics

The table below summarizes the behavior and requirements for Nequi Payouts.

CapabilityDetails
Transaction typeDisbursement (you send funds to the customer).
ConfirmationAsynchronous — A webhook notification informs you when the funds are credited.
Data requirementsPhone number: Must be exactly 10 digits.
Customer details: First and last name are required for the provider registration.

Payout flow

The following diagram shows the business flow for a Nequi Payout:

1. Create the payout request

To initiate the transfer, call the Create Payout endpoint. You must specify the payment_method as WALLET_PAYOUT and provide the customer's Nequi phone number.
information icon
Important The customer.phone_number is the key identifier for the Nequi account. It must be exactly 10 digits long.
Sample Request:
bash
curl --location --request POST '[https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payouts](https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payouts)' \ --header 'Content-Type: application/json' \ --header 'x-seller-id: your-seller-id' \ --header 'country: CO' \ --header 'Authorization: Bearer <ACCESS_TOKEN>' \ --data-raw '{ "idempotency_key": "payout-unique-key-001", "request_id": "req-payout-001", "order_id": "payout-ref-12345", "data": { "amount": 50000, "currency": "COP", "customer_id": "cust-001", "payment": { "payment_method": "WALLET_PAYOUT", "brand": "NEQUI", "soft_descriptor": "PAYOUT MERCHANT" }, "additional_data": { "callback_url": "[https://your-domain.com/webhook/payouts](https://your-domain.com/webhook/payouts)", "customer": { "phone_number": "3001234567", "email": "john.smith@email.com", "document_number": "12345678", "document_type": "CC", "first_name": "John", "last_name": "Smith" } } } }'
Sample Response:
json
{ "idempotency_key": "payout-unique-key-001", "seller_id": "your-seller-id", "payment_id": "payout-nequi-998877", "order_id": "payout-ref-12345", "amount": "50000", "currency": "COP", "status": "PENDING", "payment_method": "WALLET_PAYOUT", "received_at": "2025-11-20T14:30:00.000Z", "reason_code": "00", "reason_message": "Payout request accepted. Processing funds transfer." }

2. Verify payout status

The API processes the request asynchronously. Don't poll the API. Instead, listen for the webhook notification sent to your callback_url.
  • APPROVED: The funds are now available in the customer's Nequi account.
  • DECLINED: The payout failed (invalid phone number, inactive account, or monthly limits exceeded).

Refunds and cancellations

Nequi payments support refunds:

  • Refunds: Available for settled transactions. You can perform full or partial refunds.
  • Cancellations: A payment still in a PENDING state (e.g., the customer hasn't accepted the push yet) may be cancellable, depending on the specific provider timeout. Typically, though, Nequi transactions are either approved or expire.

To process a refund, follow the instructions in the Refund a Payment guide.

Read more

The following page gives more detail on related topics.

  • Review Authentication for token management and security best practices.

On this page

Nequi