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", "nequi", "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.

   {
     "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
     },
     "status": "SUCCESS",
     "redirect_url": "https://api.ebanxpay.com/ws/redirect/execute?hash=5ec27f3b86fa8e318dd345234523553626aec3989aa2ceccdb7"
   }
   At this stage, the payment will appear as Completed (CO) or Cancelled (CA) 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.

   The customer will need to scan the QR code with the Nequi app to authorize payment.

   
   

   Example:

   

   
   

   Option 2 - Push Notifications:

   Alternatively, if the customer has registered a mobile number with their Nequi app, they will receive a push notification and can finalize the payment directly.

9. 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.