NuPay-Recurring Integration Guide

Nupay Recurring 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 Recurring simplifies the payment experience while providing robust authorization workflows.

Requirements

API authentication - All API requests must be authenticated using JWS (JSON Web Signature). The legacy integration_key is being deprecated — if you still use it, follow the Migration Guide to transition to JWS. If you don't have credentials yet, 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. The enrollment process has two different user experiences depending on where the customer is coming from:
- App-to-App: Ideal for purchases made within your mobile application. The customer is redirected from your app to the Nubank app to grant authorization and then returns.
- Web-to-App: Ideal for purchases made on a website (desktop or mobile). The customer receives a push notification on their phone to approve the authorization in the Nubank app.
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.

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.
Check the method's availability for your country and tenant in Payment Methods by Country. Questions about tenant and environment? Check our API Operability and API Endpoints.
Cross-border sandbox
https://sandbox.ebanxpay.com/ws/userenrollment/nupay

Define your parameters

You must enroll the customer in Nupay Recurring 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 for App-to-app flow
`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 for App-to-app flow
`enrollment.document`	Customer's document (CPF).	Required for Web-to-app flow
`enrollment.identification_type`	Must be `cpf`.	Optional

Enrollment request

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

App-to-App Request
Web-to-App Request

Shell
curl -X POST \
  --location 'https://sandbox.ebanxpay.com/ws/userenrollment/nupay' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "{{integration_key}}",
    "operation": "enrollment",
    "payment_type_code": "nupay-recurrent",
    "enrollment": {
        "merchant_enrollment_code": "{{unique_enrollment_code}}",
        "phone_number": "5555555555",
        "email": "john.doe@example.com",
        "country": "br",
        "back_urls": {
            "success": "https://your-success-url.com",
            "failure": "https://your-failure-url.com"
        }
    }
}'

Shell
curl -X POST \
  --location 'https://sandbox.ebanxpay.com/ws/userenrollment/nupay' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "{{integration_key}}",
    "operation": "enrollment",
    "payment_type_code": "nupay-recurrent",
    "enrollment": {
        "merchant_enrollment_code": "{{unique_enrollment_code}}",
        "phone_number": "5555555555",
        "email": "john.doe@example.com",
        "country": "br",
        "document": "{{tax_id}}",
        "identification_type": "cpf"
    }
}'

Enrollment response

The response to this call will indicate the status of the operation.

App-to-App Response
Web-to-App Response

JSON
{
  "redirect_url": "{{redirect_url}}",
  "status": "SUCCESS",
  "enrollment": {
    "merchant_enrollment_code": "{{unique_enrollment_code}}",
    "phone_number": "5555555555",
    "email": "john.doe@example.com",
    "country": "br",
    "back_urls": {
      "success": "https://your-success-url.com",
      "failure": "https://your-failure-url.com"
    }
  }
}

JSON
{
  "redirect_url": "no-redirect",
  "status": "SUCCESS",
  "enrollment": {
    "merchant_enrollment_code": "{{unique_enrollment_code}}",
    "phone_number": "5555555555",
    "email": "john.doe@example.com",
    "country": "br",
    "document": "{{tax_id}}",
    "identification_type": "cpf"
  }
}

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.

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:

Shell
curl -X POST \
  --location 'https://sandbox.ebanxpay.com/ws/userenrollments/query' \
  --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:

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

Payment request

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

Parameter	Description	Required
`integration_key`	Your EBANX integration key.	Required
`payment.name`	Customer’s full name.	Required
`payment.email`	Customer’s email.	Required
`payment.document`	Customer’s document (CPF).	Required
`payment.country`	Customer’s country code (e.g., `br`).	Required
`payment.phone_number`	Customer’s phone number.	Required
`payment_type_code`	Set to `nupay-recurrent`.	Required
`payment.merchant_payment_code`	Unique ID for the transaction.	Required
`payment.currency_code`	Set to `BRL` or `USD`.	Required
`payment.amount_total`	Total payment amount.	Required
`payment.metadata.merchant_enrollment_code`	The unique identifier associated with the recurrence, obtained in the enrollment step.	Required
`payment.metadata.funding_source`	The source of funds for the payment. Can be `debit` or `credit`.	Required
`payment.metadata.installments`	Number of installments. Only applicable when `funding_source` is `credit`.	Optional

Use the /ws/instalmentsPlan endpoint to retrieve the available installment plans and amounts before submitting the payment request. When calling this endpoint for NuPay Recurring, the document and payment_type fields are required.

Sample request:

Shell
curl -X POST \
  --location 'https://sandbox.ebanxpay.com/ws/direct' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "{{integration_key}}",
    "payment": {
        "name": "John Doe",
        "email": "john.doe@example.com",
        "document": "{{tax_id}}",
        "country": "br",
        "phone_number": "5555555555",
        "payment_type_code": "nupay-recurrent",
        "merchant_payment_code": "{{merchant_payment_code}}",
        "currency_code": "BRL",
        "amount_total": 99.85,
        "metadata": {
            "merchant_enrollment_code": "{{unique_enrollment_code}}",
            "funding_source": "credit"
        }
    }
}'

Payment response

The response of this call will have no redirection. Immediate responses will have either a Completed (CO) or Canceled (CA) status, while a Pending (PE) status means the payment is still being processed by NuPay.

Response:

JSON
{
  "payment": {
    "hash": "59acc5f00945fa382ab051651440826da7701533249b3a475",
    "country": "br",
    "merchant_payment_code": "{{merchant_payment_code}}",
    "order_number": null,
    "status": "PE",
    "status_date": "{{YYYY-MM-DD HH:mm:ss}}",
    "open_date": "{{YYYY-MM-DD HH:mm:ss}}",
    "confirm_date": null,
    "transfer_date": null,
    "amount_br": "99.85",
    "amount_ext": "99.85",
    "amount_ext_requested": "99.85",
    "amount_iof": "0.00",
    "currency_rate": "1.0000",
    "currency_ext": "BRL",
    "due_date": "{{YYYY-MM-DD HH:mm:ss}}",
    "instalments": "1",
    "payment_type_code": "nupay-recurrent",
    "redirect_url": "https://acquirer.redirect.example.com",
    "pre_approved": false,
    "capture_available": null,
    "currency_ext_base": "BRL",
    "type": "",
    "transaction_status": {
      "acquirer": "EBANX",
      "code": "OK",
      "description": "Payment successfully paid",
      "description_code": "ACCEPTED"
    }
  },
  "status": "SUCCESS"
}

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 Merchant Area.
- Make sure your system is set up to receive notifications from EBANX for any changes in payment status.
- Learn more about Payment Notifications
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 Status
Congratulations!

You have successfully integrated Nupay Recurring.
For more information, refer to the
Direct API reference guide

Cancel an existing enrollment

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

Sample request

See example request below.

Shell
curl -X POST \
  --location 'https://sandbox.ebanxpay.com/ws/userenrollment/nupay/cancel' \
  --header 'Content-Type: application/json' \
  --data '{
    "integration_key": "{{integration_key}}",
    "operation": "cancel",
    "payment_type_code": "nupay-recurrent",
    "enrollment": {
        "merchant_enrollment_code": "{{unique_enrollment_code}}",
        "email": "john.doe@example.com",
        "country": "br",
        "back_urls": {
            "success": "https://your-success-url.com",
            "failure": "https://your-failure-url.com"
        }
    }
}'

Sample response

See example response below.

JSON
{
  "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 explore

Mock Customer Data

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

Click to explore

Error Codes

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

Click to explore

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.

Nupay Recurring

Requirements​

How it works​

Instructions​

Select your environment​

Define your parameters​

Enrollment request​

Enrollment response​

Enrollment status check​

Payment request​

Payment response​

Monitor payment for status changes​

Congratulations!​

Cancel an existing enrollment​

Sample request​

Sample response​

Resources​

API Reference

Mock Customer Data

Error Codes

Still need help?

Requirements

How it works

Instructions

Select your environment

Define your parameters

Enrollment request

Enrollment response

Enrollment status check

Payment request

Payment response

Monitor payment for status changes

Congratulations!

Cancel an existing enrollment

Sample request

Sample response

Resources