NuPay Payment Conditions

The /ws/instalmentsPlan endpoint retrieves available funding sources and installment options from a customer's NuPay wallet. The response provides tailored payment conditions that vary based on the customer profile and purchase details.

When used, calling this endpoint before initiating a NuPay or NuPay Recurring payment allows you to verify whether the customer has available payment conditions (e.g., sufficient balance or an eligible credit line). If no conditions are available, you can avoid presenting NuPay as a payment option, resulting in higher effective conversion rates.

Optional feature

Calling this endpoint is optional and is not required to process NuPay payments. It is a recommended optimization step that can improve conversion rates, but it should not block your integration. If you choose not to call this endpoint, NuPay payments will still work normally.

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

There are two query modes depending on your integration:

• Query with CPF only (NuPay and NuPay Recurring): Use this to check customer eligibility and retrieve installment options before the customer selects a payment method. For NuPay Recurring, this also serves as a pre-validation step before enrollment creation.

• Query with enrollment code or CPF (NuPay Recurring only): After the customer is enrolled, use this to retrieve the specific installment options available for that enrollment.

Availability

This endpoint is currently available only for Brazil (BR) with BRL currency.

When to call this endpoint

The right moment to call /ws/instalmentsPlan depends on your integration flow. For standard Direct API integrations, it is typically called before rendering the checkout so that NuPay only appears as a payment option if the customer is eligible. However, other integration flows (such as Meta) may require a different approach. We strongly recommend reaching out to your EBANX account manager before implementing this endpoint to ensure the integration is optimized for your specific use case.

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.

   • Sandbox: https://sandbox.ebanxpay.com/ws/instalmentsPlan

   • Production: https://api.ebanxpay.com/ws/instalmentsPlan

2. Define your request parameters

   To fetch the available plans, the request must include one of the following identifiers:

   • Customer Document (document): The customer's CPF.

   • Merchant Enrollment Code (enrollment_code): The specific code of the customer's enrollment, for NuPay Recurring active enrollments.

   
   

   Parameter	Requirement	Description
   integration_key	Required	Your EBANX integration key.
   country_abbreviation	Required	Two-letter country code (e.g., BR).
   currency_code	Required	Three-letter currency code (ISO 4217). Set to BRL.
   amount	Required	Total payment amount (cannot contain comma).
   payment_type	Required	Payment type code (e.g., nupay, nupay-recurrent).
   document	Conditional	Customer's CPF. Required when no enrollment_code is provided.
   enrollment_code	Conditional	Customer's enrollment code. Required when no document is provided.

3. Send the request

   The /ws/instalmentsPlan endpoint is flexible and can be accessed via two methods depending on your integration needs.

   • Post (recommended):
   Shell

   curl -X POST \
     --location 'https://sandbox.ebanxpay.com/ws/instalmentsPlan' \
     --header 'Content-Type: application/json' \
     --data '{
       "integration_key": "{{integration_key}}",
       "country_abbreviation": "BR",
       "currency_code": "BRL",
       "amount": 100,
       "document": "{{tax_id}}",
       "payment_type": "nupay-recurrent",
       "enrollment_code": "{{unique_enrollment_code}}"
   }'

   • Get (use this method to retrieve plans by passing parameters directly in the URL query string):
   Shell

   curl -X GET \
     --location 'https://sandbox.ebanxpay.com/ws/instalmentsPlan?integration_key={{integration_key}}&country_abbreviation=BR&currency_code=BRL&amount=100&document={{tax_id}}&payment_type=nupay-recurrent'

4. Installments plan response

   The response to this call will indicate what are the payment conditions available for the referred customer or enrollment in NuPay.

   The instalmentsPlan object is keyed by funding source (debit, credit, credit_with_additional_limit), and each key holds the installment options available for that funding source.

   • Response example (nupay):
   JSON

   {
     "instalmentsPlan": {
       "debit": [
         {
           "totalAmount": 100,
           "quantity": 1,
           "instalmentAmount": 100,
           "totalAmountWithInterest": 100
         }
       ],
       "credit": [
         {
           "totalAmount": 100,
           "quantity": 1,
           "instalmentAmount": 100,
           "totalAmountWithInterest": 100
         },
         {
           "totalAmount": 100,
           "quantity": 2,
           "instalmentAmount": 50,
           "totalAmountWithInterest": 100
         },
         {
           "totalAmount": 100,
           "quantity": 3,
           "instalmentAmount": 35.1,
           "interest": 0.049,
           "interestAmount": 4.9,
           "iof": 0.41,
           "iofPercentage": 0.0041,
           "cet": 77.54,
           "totalAmountWithInterest": 105.31
         }
       ],
       "credit_with_additional_limit": [
         {
           "totalAmount": 100,
           "quantity": 1,
           "instalmentAmount": 376.3,
           "interest": 0.11,
           "interestAmount": 276.3,
           "iof": 0.8,
           "iofPercentage": 0.008,
           "cet": 1.06,
           "installmentPlanAdditionalLimit": 376.3,
           "additionalLimit": 833,
           "additionalLimitMessage": "{{additional_limit_message}}",
           "totalAmountWithInterest": 376.3
         }
       ]
     }
   }

   • Response example (nupay-recurrent): for this payment type, additionalLimitMessage is not repeated inside each installment option. It is returned once per funding source in a top-level additionalInfo object.
   JSON

   {
     "instalmentsPlan": {
       "credit_with_additional_limit": [
         {
           "totalAmount": 100,
           "quantity": 1,
           "instalmentAmount": 376.3,
           "interest": 0.11,
           "interestAmount": 276.3,
           "iof": 0.8,
           "iofPercentage": 0.008,
           "cet": 1.06,
           "installmentPlanAdditionalLimit": 376.3,
           "additionalLimit": 833,
           "totalAmountWithInterest": 376.3
         }
       ]
     },
     "additionalInfo": {
       "credit_with_additional_limit": {
         "additionalLimitMessage": "{{additional_limit_message}}"
       }
     }
   }

   
   

   The fields below can be returned for each installment option. Fields marked as conditional are returned only when the funding source provides them — for example, fee and tax fields are absent for interest-free options.

   Field	Requirement	Description
   totalAmount	Always	Base payment amount, as sent in the request.
   quantity	Always	Number of installments.
   instalmentAmount	Always	Amount of each installment.
   totalAmountWithInterest	Always	Total amount the customer pays, including interest and taxes.
   instalmentAmountPercentage	Conditional	Installment amount as a percentage of the total.
   interest	Conditional	Interest rate applied to the option, as a decimal fraction (0.049 = 4.9%).
   interestAmount	Conditional	Total interest charged, in BRL.
   iof	Conditional	IOF (Tax on Financial Operations) amount, in BRL.
   iofPercentage	Conditional	IOF rate, as a decimal fraction.
   cet	Conditional	CET (Total Effective Cost), the annualized cost of the credit operation.
   totalAmountPercentage	Conditional	Total amount as a percentage of the contracted amount.
   amountContracted	Conditional	Contracted amount (principal plus IOF).
   amountContractedPercentage	Conditional	Contracted amount as a percentage.
   installmentPlanAdditionalLimit	Conditional	Additional credit limit used by this specific installment option.
   additionalLimit	Conditional	Total additional credit limit available to the customer.
   additionalLimitMessage	Conditional	Message from Nubank describing how the additional limit behaves. Returned for nupay inside each installment option, and for nupay-recurrent in additionalInfo.{funding_source}.additionalLimitMessage.

   Display requirements

   Nubank requires that the cost of the credit operation is shown to the customer before they confirm the payment. Whenever the fields are present in the response, your checkout must display iof, cet, the interest (interest and interestAmount), and the additionalLimitMessage text as returned by the API. The message is localized by Nubank, so render it verbatim instead of translating or rewriting it. If these conditions cannot be displayed, do not offer the installment option at checkout.

5. Use the response

   Eligibility check (NuPay and NuPay Recurring): If the instalmentsPlan object is empty or the request returns an error, the customer is not eligible for NuPay. In this case, do not render NuPay as a payment option at checkout.

   Displaying installment options (NuPay Recurring only): Use the response data to render payment conditions in your own checkout. Present each option showing the number of installments (quantity), the per-installment amount (instalmentAmount), and the total cost (totalAmountWithInterest) so the customer can make an informed choice.

   Also display the cost breakdown returned for the option — iof, cet, interest, interestAmount — and, for options with an additional limit, the additionalLimitMessage text. For nupay-recurrent, read the message from additionalInfo.{funding_source}.additionalLimitMessage, since it is not repeated inside each installment option.

   Once the customer selects their preferred installment plan, include it in your payment request to /ws/direct, using the fields payment.metadata.funding_source and payment.metadata.installments.

6. Congratulations!

   You have successfully queried the NuPay Payment Conditions.

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.