Skip to main content

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.

    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.

    Nequi Icon Usage

  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:

    ParameterDescriptionRequired?
    operationSet to requestRequired
    integration_keyYour EBANX integration keyRequired
    payment_type_codeSet to code from step 2Required
    countrySet to co for ColombiaRequired

    Customer data:

    ParameterDescriptionRequired?
    nameCustomer nameRequired
    emailCustomer emailRequired

    Charge parameters:

    ParameterDescriptionRequired?
    merchant_payment_codeUnique merchant payment codeRequired
    currency_codeSupported values COP and USDRequired
    amount_totalTotal amount to be chargedRequired
    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:

    Voucher Nequi


    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

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

  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.


Still need help?

Help Image

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