Nequi Push

Nequi is a digital wallet managed by Bancolombia and widely used in Colombia. DEUNA's integration with Nequi enables users to pay through a push notification flow, fully handled within the DEUNA Payment Widget — no external redirections required.

This guide walks you through the end-to-end integration process to enable Nequi as a payment method in your checkout using DEUNA.

Integration Steps

Environments:

• Sandbox: https://api.sandbox.deuna.io
• Production: https://api.deuna.io

1 - Create Order

Create an order with DEUNA. This API will return back a DEUNA’s order_token which will be required to follow the next steps.

• Documentation: https://docs.deuna.com/reference/order_token

2- Retrieve Order

It is possible to get the order information using a GET Request

• Documentation: https://docs.deuna.com/reference/get-order-by-token

3- Update Order

Is the same endpoint to create an order, but if any field is changed, the order will be updated with the new value/information.

• Documentation: https://docs.deuna.com/reference/update-order-by-token

4- Expiring the Order (optional)

Is it possible to set an expiration time for the order by sending the expires_at field with the desired expiration time. The value should be in UTC timezone.

Example:

{
    "order": {
      ...
        "expires_at": "2025-02-03T14:35:00+00:00",
			...
    }
}

It is also posible to expire an order manually by using the endpoint below:
Documentation: https://docs.deuna.com/reference/expire-order

5- Render the Payment Widget

After receiving the order token, you can render the DEUNA widget.

Documentations:

• Payment Widget First Steps: https://docs.deuna.com/docs/integracion-payment-widget
• Web: https://docs.deuna.com/docs/primeros-pasos-web
• iOS: https://docs.deuna.com/docs/primeros-pasos-instalacion-ios-sdk
• Android: https://docs.deuna.com/docs/primeros-pasos-instalacion-android-sdk

You can configure the Payment Widget to render only Nequi by passing the paymentMethods parameter during initialization.

await DeunaSDK.initPaymentWidget({
    orderToken: "<DEUNA order token>",
    callbacks: ...,
    paymentMethods: [
        {
            paymentMethod: "voucher",
            processors: ["nequi_push_voucher"],
        },
    ],
});

6- Nequi Test Data

❗️

Important Note – Nequi Testing

Nequi can only be tested using real user data. When using Nequi, an actual charge will be made to the customer’s real account.

If needed, the payment can be refunded via the DEUNA Admin Panel or through the Refunds API.

7- Nequi Push payment flow

1. The user selects Nequi inside the Payment Widget.
2. Enters their real Nequi phone number.
3. A push notification is sent to their Nequi mobile app.
4. The user approves (or rejects) the payment directly in the app.
5. DEUNA receives the payment status and triggers the appropriate callback event in the widget — either onSuccess for approved payments or onError for declined or expired ones.
   For more details, refer to the step #5.
6. All steps are handled inside the widget — no redirections.

🚧

Important Notes

• Refunds are supported and can be initiated via DEUNA Admin Panel or Refunds API.
• The push notification expires after 45 minutes if the user does not respond.
• The entire flow — from phone number input to notification response verification and payment confirmation — is handled fully within the widget.
• Payment approval may take up to 30 seconds to be confirmed or declined after the user approves or refuses it in the Nequi app.
• Your Nequi sandbox and production credentials must be requested directly from your Bancolombia / Nequi account manager.