Nupay Recurrent

Nupay 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. Whether for subscriptions or one-click payments, Nupay Recurrent simplifies the payment experience while providing robust authorization workflows.

Requirements

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

How it works

• Enrollment - Customers authorize recurring payments through an app-to-app or web-to-app flow. This step ensures that merchants can process future transactions seamlessly.
• First payment - Customers authorize the initial payment via the NuPay platform, choosing a payment source (credit or debit).
• Subsequent payments - Once enrolled, future payments occur automatically using the merchant_enrollment_code, without requiring additional customer action.
• Notifications - EBANX notifies merchants of payment status updates via webhooks.

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/userenrollment/nupay

2. Define your parameters

   You must enroll the customer in Nupay Recurrent using the /ws/userenrollment/nupay endpoint.

   You can send both parameters (email and phone_number), or just one of them.

   Parameter	Description
   integration_key	Your EBANX integration key.	Required
   operation	Set to enrollment.	Required
   payment_type_code	Set to nupay-recurrent.	Required
   enrollment.merchant_enrollment_code	Unique ID for the recurring payment.	Required
   enrollment.email	Customer email. Required, if no phone_number.	Required
   enrollment.phone_number	Customer phone number. Required, if no email.	Required
   enrollment.country	Customer country code (e.g., br).	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

   The enrollment step is essential for registering customers for automatic payments. This process is handled through the /ws/userenrollment/nupay endpoint.

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

4. Enrollment response

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

   {
       "redirect_url": "https://nuapp.nubank.com.br/bdc/omniknight/expr/pre-authorized-payments.home-screen?merchant-name=ebanx&ticket=tGEA1cmF_5VNQGZqmcU7LPvyTS10rtH43rZ-BdxAnz8&merchant-source-id=025cf1db-fe93-4c50-a949-05fc04d400a3&state=SGNgAbfNYDtMA9YweBJUe4",
       "status": "SUCCESS",
       "enrollment": {
           "merchant_enrollment_code": "d057c598",
           "phone_number": "85228470358",
           "email": "customer@example.com",
           "country": "br",
           "back_urls": {
               "success": "https://your-success-url.com",
               "failure": "https://your-failure-url.com"
           }
       }
   }

   Sandbox Behavior - When working in a sandbox environment, the redirect_url will lead to a sandbox interface where you can simulate customer acceptance or cancellation of the enrollment agreement.

   See example below.

   
   
   

5. Enrollment status check

   To confirm customer enrollment status, send a request to the /ws/userenrollments/query endpoint.

   Use the following parameters when preparing your request.

   Parameter	Description	Required
   integration_key	Your EBANX integration key.	Required
   operation	Set to enrollment.	Required
   payment_type_code	Set to nupay-recurrent.	Required
   enrollment.merchant_enrollment_code	Unique ID for the recurring payment.	Required
   enrollment.country	Customer’s country code (e.g., br).	Required

   Sample request:

   curl -X POST \ 
     --location 'https://sandbox.ebanxpay.com/ws/userenrollments/query' \ // Enrollment endpoint.
     --header 'Content-Type: application/json' \
     --data '{
     "integration_key": "your_ebanx_integration_key",
     "operation": "enrollment",
     "payment_type_code": "nupay-recurrent",
     "enrollment": {
       "merchant_enrollment_code": "d057c598",
       "country": "br"
     }
   }'
   
   Sample response:

   {
       "status": "SUCCESS",
       "enrollment": {
           "status": "accepted"
       }
   }

6. Payment request

   After the customer is successfully enrolled, call the ws/direct endpoint with the required parameters.

   
   

   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

   At the API Reference Guide, select Brazil and Nupay Recurrent from the dropdown menues.

   
   

   Sample request:

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/direct' \  
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "**********************", // Your EBANX integration key.
       "operation": "request",
       "payment": {
           "name": "Jose Silva",
           "email": "customer@example.com",
           "phone_number": "85228470358",
           "document": "123.456.789-09",  // Valid Document ID
           "country": "br",
           "payment_type_code": "nupay-recurrent",
           "merchant_payment_code": "hgh09akajdk", // Unique merchant payment code.
           "currency_code": "BRL",
           "amount_total": 1.55,
           "metadata": {
               "merchant_enrollment_code": "d057c598"
           }
       }
   }'

7. Payment response

   The response of this call will have either a Completed (CO) or Canceled, (CA) status, and there will be no redirection.

   Response:

   {
       "payment": {
           "hash": "67647c6bb99656134f80b508c609f83d7bec2b3e3fabcf1a",
           "country": "br",
           "merchant_payment_code": "hgh09akajdk",
           "order_number": null,
           "status": "PE", 
           "status_date": "2024-12-19 20:04:59",
           "open_date": "2024-12-19 20:04:59",
           "confirm_date": "2024-12-19 20:04:59",
           "transfer_date": null,
           "amount_br": "1.56",
           "amount_ext": "1.55",
           "amount_iof": "0.01",
           "currency_rate": "1.0000",
           "currency_ext": "BRL",
           "due_date": "2024-12-21",
           "instalments": "1",
           "payment_type_code": "nupay-recurrent",
           "pre_approved": false,
           "capture_available": null,
           "type": ""
       },
       "status": "SUCCESS"
   }

8. Monitor payment for status changes

   Notifications

   • Once the payment is confirmed, EBANX will send a notification to the notification_url sent with your payment request, or the one stored in your EBANX Dashboard.

   • 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 that status has changed, 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 eventually change to cancelled (CA).

   • Learn more about Retrieving Payment Statuschevron_right

9. Congratulations!

   You have succesfully integrated Nupay Recurrent.

   For more information, refer to the

   Direct API reference guidechevron_right

Cancel an existing enrollment

Enrollments can be cancelled by sending a POST request to the /ws/userenrollment/nupay/cancel endpoint.

1. Sample request

   See example request below.

   curl -X POST \
     --location 'https://sandbox.ebanx.com/ws/userenrollment/nupay' \ // Enrollment endpoint.
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "**********************", // Your EBANX integration key.
       "operation": "cancel",
       "payment_type_code": "nupay-recurrent",
       "enrollment": {
           "merchant_enrollment_code": "user_xxxx",
           "email": "myemail@email.com",
           "country": "br",
           "back_urls": {
               "success": "https://your-success-url.com",
               "failure": "https://your-failure-url.com"
           }
       }
    }'

2. Sample response

   See example response below.

   {
       "status": "SUCCESS",
       "enrollment": {
           "status": "revoked"
       }
   }

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.