Skip to main content

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

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

    ParameterDescription
    integration_keyYour EBANX integration key.Required
    operationSet to enrollment.Required
    payment_type_codeSet to nupay-recurrent.Required
    enrollment.merchant_enrollment_codeUnique ID for the recurring payment.Required
    enrollment.emailCustomer email.
    Required , if no phone_number.
    Required
    enrollment.phone_numberCustomer phone number.
    Required , if no email.
    Required
    enrollment.countryCustomer country code ( e.g., br ).Required
    enrollment.back_urls.successWhen 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.failureWhen 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.documentCustomer's document (CPF).
    Required for Web-to-app flow
    enrollment.identification_typeMust be cpf.
    Optional
  3. Enrollment request

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

    {
    "integration_key": "{{integration_key}}",
    "operation": "enrollment",
    "payment_type_code": "nupay-recurrent",
    "enrollment": {
    "merchant_enrollment_code": "{{unique_enrollment_code}}",
    "phone_number": "{{customer_nupay_phone}}",
    "email": "{{customer_email}}",
    "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.

    {
    "redirect_url": "https://nuapp.nubank.com.br/bdc/omniknight/expr/pre-authorized-payments.home-screen?...",
    "status": "SUCCESS",
    "enrollment": {
    "merchant_enrollment_code": "{{unique_enrollment_code}}",
    "phone_number": "{{customer_nupay_phone}}",
    "email": "{{customer_email}}",
    "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.

    nupay-sandbox-redirect_url

  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.

    ParameterDescriptionRequired
    integration_keyYour EBANX integration key.Required
    operationSet to enrollment.Required
    payment_type_codeSet to nupay-recurrent.Required
    enrollment.merchant_enrollment_codeUnique ID for the recurring payment.Required
    enrollment.countryCustomer’s country code (e.g., br).Required

    Sample request:

    curl -X POST 'https://sandbox.ebanx.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.

    ParameterDescriptionRequired
    integration_keyYour EBANX integration key.Required
    operationSet to request.Required
    payment.nameCustomer’s full name.Required
    payment.emailCustomer’s email.Required
    payment.documentCustomer’s document (CPF).Required
    payment.countryCustomer’s country code (e.g., br).Required
    payment.phone_numberCustomer’s phone number.Required
    payment_type_codeSet to nupay-recurrent.Required
    payment.merchant_payment_codeUnique ID for the transaction.Required
    payment.currency_codeSet to BRL or USD.Required
    payment.amount_totalTotal payment amount.Required
    payment.metadata.merchant_enrollment_codeThe unique identifier associated with the recurrence, obtained in the enrollment step.Required
    payment.metadata.funding_sourceThe source of funds for the payment. Can be debit or credit.Required
    payment.metadata.installmentsNumber of installments. Only applicable when funding_source is credit.Optional

    Sample request:

    curl -X POST 'https://sandbox.ebanx.com/ws/direct' \  
    --header 'Content-Type: application/json' \
    --data '{
    "integration_key": "{{integration_key}}",
    "operation": "request",
    "payment": {
    "name": "{{customer_name}}",
    "email": "{{customer_email}}",
    "document": "{{customer}}",
    "country": "br",
    "phone_number": "{{customer_nupay_phone}}",
    "payment_type_code": "nupay-recurrent",
    "merchant_payment_code": "{{merchant_payment_code}}",
    "currency_code": "BRL",
    "amount_total": 2.00,
    "metadata": {
    "merchant_enrollment_code": "{{merchant_enrollment_code}}",
    "funding_source": "credit",
    "installments": "1"
    }
    }
    }
    '
  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": "65ce22f8b25d9ee309f4e3ac5188c76b30f4c31e647f1cfb",
    "country": "br",
    "merchant_payment_code": "9546ee48-f876-4ecd-acc6-cdc5f87e938a",
    "order_number": null,
    "status": "PE",
    "status_date": null,
    "open_date": "2024-02-15 14:43:04",
    "confirm_date": null,
    "transfer_date": null,
    "amount_br": "2.01",
    "amount_ext": "2.00",
    "amount_iof": "0.01",
    "currency_rate": "1.0000",
    "currency_ext": "BRL",
    "due_date": "2024-02-17",
    "instalments": "1",
    "payment_type_code": "nupay-recurrent",
    "redirect_url": "https://api.ebanx.com/ws/redirect/execute?hash=65ce22f8b25d9ee309f4e3ac5188c76b30f4c31e647f1cfb",
    "pre_approved": false,
    "capture_available": null,
    "currency_ext_base": "BRL",
    "type": ""
    },
    "status": "SUCCESS",
    "redirect_url": "https://api.ebanx.com/ws/redirect/execute?hash=65ce22f8b25d9ee309f4e3ac5188c76b30f4c31e647f1cfb"
    }
  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.

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

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


Still need help?

Help Image

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