Nequi

Nequi is a popular e-wallet in Colombia that allows customers to make payments through QR codes or push notifications. As a free financial platform available on mobile phones, Nequi enables users to manage and access their money whenever they need it. Users can load funds into their Nequi accounts via bank transfer (PSE) or through cash deposits at various charge points throughout Colombia. Payments can be made easily at both physical stores and e-commerce websites by scanning a QR code or accepting a payment request sent by push notification to their phone. To complete a payment, customers must have sufficient funds in their Nequi account. They also need to approve the amount, and confirm their identity by logging into the Nequi app.

This guide will take you through the process of integrating Nequi payments with EBANX Direct.

Requirements

• API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.
• Familiarity with EBANX Direct - This setup follows the same general structure as other payment methods, with a few unique parameters.

Instructions

Follow the steps below.

1. Select your environment

   Select the appropriate environment for your integration. Use the sandbox environment for testing, or the production environment for live transactions. Use the URL for your HTTP requests based on your selection.

   SandboxProduction

   https://sandbox.ebanx.com/ws/direct

2. Retrieve available Digital Wallets

   Check which wallets are available by selected country using the /ws/ewallet-availableEWallets endpoint.

   Sample Request

   curl -X POST 
     --location 'https://api.ebanx.com/ws/ewallet-availableEWallets' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "your_ebanx_integration_key",
       "operation": "request",
       "country": "br" // country code
     }'

   The API response will return an array of available digital wallets for the selected country. Look for Nequi to confirm availability.

     // Sample response: an array of digital-wallet objects.
   [
     {
       "code": "nequi",
       "name": "Nequi",
       "icon_url": "https://s3-sa-east-1.amazonaws.com/assets.ebanx.com/gateway/nequi/icon.png",
       "promotional_text": "Pay easily with Nequi"
     },
     {
       "code": "paypal",
       "name": "PayPal",
       "icon_url": "https://s3-sa-east-1.amazonaws.com/assets.ebanx.com/gateway/paypal/icon.png",
       "promotional_text": "Pay easily with PayPal."
     }
   ]
   For more information, refer to the

   API reference for digital walletschevron_right

3. Render Nequi option at checkout

   You can render the Nequi details on your checkout page using the information provided in the API response.

   • Display the icon_url to show the Nequi logo.
   • Use the promotional_text to display a message for Nequi.
   
   

   Example usage
   Not sure how to implement it? You can refer to our payment page as a reference to see how it should appear in your checkout process.

   

4. Get the digital wallet code

   Each digital wallet in the response contains a unique code that identifies the wallet (e.g., "nequi", "nupay", "paypal"). You’ll need this code to create a payment. In this case nequi.

5. Define your parameters

   Nequi operates as a voucher-based payment method, so you’ll need to redirect your customer to a page displaying the voucher details. To obtain this redirection link, call the ws/direct endpoint with the required parameters.

   Basic parameters:

   Parameter	Description	Required?
   operation	Set to request	Required
   integration_key	Your EBANX integration key	Required
   payment_type_code	Set to code from step 2	Required
   country	Set to co for Colombia	Required

   Customer data:

   Parameter	Description	Required?
   name	Customer name	Required
   email	Customer email	Required

   Charge parameters:

   Parameter	Description	Required?
   merchant_payment_code	Unique merchant payment code	Required
   currency_code	Supported values COP and USD	Required
   amount_total	Total amount to be charged	Required

   For more API information, refer to the

   Direct API reference guidechevron_right

6. Payment request

   Use the following example to initiate a request.

   curl -X POST \
     --location 'https://api.ebanx.com/ws/direct' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "your_ebanx_integration_key",
       "operation": "request",
       "payment": {
         "amount_total": 20.00,
         "currency_code": "COP",
         "name": "Jose Silva",
         "email": "jose.silva@example.com",
         "country": "co",
         "payment_type_code": "nequi", // The digital wallet code
         "merchant_payment_code": "xyz-123-1001",
         "redirect_url": "https://your-call-back-url.com",
       }
     }'

7. Payment response

   Each request returns a response similar to the example below, with the status set to "PE". You will also receive a redirect_url and a qr_code_value, which you can use either to guide your customer through the next steps to complete the payment using the Nequi wallet.

   {
     "payment": {
       "hash": "5ec27f3b86fa8e3123452345626aec3989aa2ceccdb7",
       "country": "co",
       "merchant_payment_code": "xyz-123-1001",
       "order_number": null,
       "status": "PE",
       "status_date": null,
       "open_date": "2020-05-18 12:27:38",
       "confirm_date": null,
       "transfer_date": null,
       "amount_br": "20.00",
       "amount_ext": "20.00",
       "amount_iof": "0.00",
       "currency_rate": "1.0000",
       "currency_ext": "COP",
       "due_date": "2020-05-21",
       "instalments": "1",
       "payment_type_code": "nequi",
       "redirect_url": "https://api.ebanxpay.com/ws/redirect/execute?hash=5ec27f3b86fa8e318dd345234523553626aec3989aa2ceccdb7",
       "pre_approved": false,
       "capture_available": null,
       "ewallet": {
         "qr_code_value": "000201010212500000000870662.005802CO5909EBANX_COL6009BOGOTA_DC9021C001-14260-001p4wncii"
       }
     },
     "status": "SUCCESS",
     "redirect_url": "https://api.ebanxpay.com/ws/redirect/execute?hash=5ec27f3b86fa8e318dd345234523553626aec3989aa2ceccdb7"
   }
   At this stage, the payment will appear as Pending (PE) in your

   EBANX Dashboardchevron_right

   There will be no redirection.

8. Complete payment

   Option 1 - Redirect URL

   To complete the payment, redirect the customer to the redirect_url provided in the response. This will take them to the EBANX voucher page.

   There, the customer will need to scan the QR code using the Nequi app to authorize the payment.

   
   

   Example:

   

   
   

   Option 2 - Render the QR Code on Your Own Page

   Alternatively, you can use the qr_code_value to display the QR code directly in your own user interface. It’s important to include both the QR image and the option to copy the code, as shown on the EBANX voucher page above.

   Option 3 - Push Notification

   If the customer has a mobile number registered with their Nequi app, they will receive a push notification and can complete the payment directly from their phone.

9. Monitor payment for status changes

   Notifications

   • EBANX will send a notification whenever a payment status changes.

   • Make sure your system is set up to receive notifications from EBANX for any changes in payment status.

   • Learn more about Payment Notificationschevron_right

   Status

   • After receiving a notification, retrieve the payment status.

   • When a payment is confirmed, the status will change from pending (PE) to confirmed (CO). If the customer does not complete the payment, the status will automatically update to cancelled (CA).

   • Learn more about Retrieving Payment Statuschevron_right

10. Congratulations!

    You have succesfully integrated Nequi.

    For more information, refer to the

    Direct API reference guidechevron_right

Resources

Use the following resources when testing in your sandbox environment.

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right

Mock Customer Data

Click here to view mock customer data for testing and validating user flows.

Click to explorechevron_right

Error Codes

Click here to review common error codes to troubleshoot and resolve issues quickly.

Click to explorechevron_right

Still need help?

We hope this article was helpful. If you still have questions, you can explore the following options:

• Merchant support: Contact our support team at sales.engineering@ebanx.com for assistance.
• Not a partner yet? Please complete the Merchant Signup Form, and our commercial team will reach out to you.