Nequi Recurrent

Nequi Recurrent allows merchants to set up and manage recurring payments through the EBANX API. This feature ensures that customers authorize merchants to process recurring payments without requiring repeated manual approvals. This guide will walk you through the integration of Nequi Recurrent payments. You’ll learn how to process recurring transactions for your customers.

Requirements

• API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.

How it works

The Nequi Recurrent payment process involves the following steps:

1. Enrollment - The merchant requests the creation of the subscription enrollment via the EBANX API, which triggers Nequi to send a push notification to the customer.

2. First payment

   • The customer authorizes the merchant to make debits from their Nequi account by responding to the push notification.
   • It is crucial to adhere to Nequi’s mandatory user experience guidelines. The user must be clearly informed that they need to view the notification sent to their mobile device, authenticate themselves, and confirm the subscription through the notification center.

3. Subsequent payments - After customer enrollment, the merchant can use the EBANX API to process recurring payments.

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. Define enrollment parameters

   Gather the required information in preperation for customer enrollment request.

   Parameter	Description
   integration_key	Your EBANX integration key.	Required
   operation	Set to enrollment.	Required
   payment_type_code	Set to nequi-recurrent.	Required
   enrollment.merchant_enrollment_code	Unique ID for the recurring payment.	Required
   enrollment.email	Customer email.	Required
   enrollment.phone_number	Customer phone number.	Required
   enrollment.country	Set to CO.	Required
   enrollment.back_urls.success	When the customer accepts the enrollment, they will be redirected to this URL. The merchant can determine the outcome of the enrollment process by detecting the customer's arrival at this URL.	Required
   enrollment.back_urls.failure	When the customer denies the enrollment, they will be redirected to this URL. The merchant can determine the outcome of the enrollment process by detecting the customer's arrival at this URL.	Required

3. Enrollment request

   Enroll the customer in Nequi Recurrent using the /ws/userenrollment endpoint.

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/userenrollment' \ // Enrollment endpoint.
     --header 'Content-Type: application/json' \
     --data '{
     "integration_key": "your_ebanx_integration_key",
     "operation": "enrollment",
     "payment_type_code": "nequi-recurrent",
     "enrollment": {
       "merchant_enrollment_code": "d057c598", // Must be a unique code provided by merchant.
       "email": "customer@example.com",
       "phone_number": "85228470358",
       "country": "co",
       "back_urls": {
         "success": "https://your-success-url.com",
         "failure": "https://your-failure-url.com"
       }
     }
   }'

4. Enrollment response

   The response will indicate the status of the operation, returning either SUCCESS or CANCELED.

   {
       "status": "SUCCESS",
       "redirect_url": "no-redirect",
       "enrollment": {
           "merchant_enrollment_code": "d057c598",
           "country": "co",
           "email": "customer@example.com",
           "phone_number": "85228470358",
           "back_urls": {
               "success": "https://your-success-url.com",
               "failure": "https://your-failure-url.com"
           }
       }
   }
   
   Subsequent payments

   It's important to save the merchant_enrollment_code for subsequent payment requests.

5. Push Notification

   When an enrollment request is sent, a push notification will be delivered to the customer’s phone.

   The user has 15 minutes to either accept or reject the authorization request made by the merchant. If no action is taken within this time frame, the enrollment will automatically expire and be rejected.

   Below is an example of the push notification that the customer will receive.

   

6. Query enrollment status

   Use the /ws/userenrollment endpoint to check if the customer has successfully accepted and authorized the enrollment request from the push notification.

   Sample request

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/userenrollment' \ // Enrollment endpoint.
     --header 'Content-Type: application/json' \
     --data '{
     "integration_key": "your_ebanx_integration_key",
     "operation": "query",
     "enrollment": {
       "merchant_enrollment_code": "d057c598"
     }
   }'

   Sample response

   {
       "status": "SUCCESS",
       "enrollment": {
           "status": "accepted",
           "email": "customer@example.com"
       }
   }

   The response will indicate one of the folowing values for status:

   • accepted
   • pending
   • canceled

7. Create payment request

   After the enrollment request is accepted by the customer, you may proceed by creating a payment request. When sending a payment request for Nequi Recurrent, please provide the merchant_enrollment_code.

   
   

   Defining API parameters

   You must provide required parameters for payment requests. These parameters ensure successful completion of transactions.
   
   

   Essential parameters

   • payment.payment_type_code - Specifies the payment method to be used for the transaction.
   • payment.currency_code - Three-letter code of the payment currency.
   • payment.amount_total - Total amount to be charged.

   
   

   Additional parameters

   • EBANX Integration Key - Used to authenticate and authorize API requests.
   • Customer Information
     • Includes details such as the customer name, email, address and document number (Depends on the requirements of the payment method or local regulations).
     • While not mandatory for all countries or payment methods, providing this information can enhance security and increase the likelihood of successful processing.
   • Additional Context - Extra data for specific methods or countries.

   
   

   To learn more about API parameters, please refer to the

   API Reference Guide chevron_right

   Sample 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":"80756.00",
       "country":"CO",
       "currency_code":"COP",
       "email": "customer@example.com",
       "phone_number": "3591408297",
       "metadata": {
         "merchant_enrollment_code": "d057c598"
       },
       "payment_type_code": "nequi-recurrent",
       "merchant_payment_code": "94e35c00-52f3-48aa-b147-5bfb-teste-1"
     }
    }  
   
   

8. Payment response

   Each request returns a response similar to the example below.

   {
       "payment": {
           "hash": "66b2cd02c44fdddd57287f95feb3cbfd122407e73f8cc40d",
           "country": "co",
           "merchant_payment_code": "94e35c00-52f3-48aa-b147-5bfb-teste-1",
           "order_number": null,
           "status": "CO",
           "status_date": null,
           "open_date": "2024-08-07 01:25:22",
           "confirm_date": null,
           "transfer_date": null,
           "amount_br": "80756.00",
           "amount_ext": "80756.00",
           "amount_iof": "0.00",
           "amount_ext_requested": "80756.00",
           "currency_rate": "1.0000",
           "currency_ext": "COP",
           "due_date": "2024-08-10",
           "instalments": "1",
           "payment_type_code": "nequi-recurrent",
           "pre_approved": false,
           "capture_available": null,
           "customer": {
               "document": "",
               "email": "customer@example.com",
               "name": "",
               "birth_date": null
           },
           "single_transaction": {
               "amount_local": "0.00",
               "amount_crossborder": "80756.00"
           },
           "requested_currency": "COP",
           "currency_ext_base": "COP",
       },
       "status": "SUCCESS"
   }
   At this stage, the payment will appear as Completed (CO) or Cancelled (CA) in your

   EBANX Dashboardchevron_right

   There will be no redirection.

9. Congratulations!

   You have succesfully integrated Nequi Recurrent.

   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.