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.
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/nupayDefine 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 nophone_number
.Required enrollment.phone_number
Customer phone number.
Required , if noemail
.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
{
"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"
}
}}{
"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",
"document": "{{customer_document}}",
"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
{
"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"
}
}
}{
"redirect_url": "no-redirect",
"status": "SUCCESS",
"enrollment": {
"merchant_enrollment_code": "d057c598-b7e5-4509-b9c5-23f6de8f1fac",
"phone_number": "{{customer_nupay_phone}}",
"email": "{{customer_email}}",
"country": "br",
"document": "{{customer_document}}",
"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:
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"
}
}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 operation
Set to request
.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
orUSD
.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
orcredit
.Required payment.metadata.installments
Number of installments. Only applicable when funding_source
iscredit
.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"
}
}
}
'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"
}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).
Congratulations!
You have succesfully integrated Nupay Recurrent.
For more information, refer to theDirect API reference guidechevron_right
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.
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"
}
}
}'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.
Mock Customer Data
Click here to view mock customer data for testing and validating user flows.
Error Codes
Click here to review common error codes to troubleshoot and resolve issues quickly.
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.