Skip to main content

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​

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.

  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.


    ParameterRequirementDescription
    integration_keyRequiredYour EBANX integration key.
    country_abbreviationRequiredTwo-letter country code (e.g., BR).
    currency_codeRequiredThree-letter currency code (ISO 4217). Set to BRL.
    amountRequiredTotal payment amount (cannot contain comma).
    payment_typeRequiredPayment type code (e.g., nupay, nupay-recurrent).
    documentConditionalCustomer's CPF. Required when no enrollment_code is provided.
    enrollment_codeConditionalCustomer'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):
    curl -X POST \
    --location 'https://sandbox.ebanx.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):
    curl -X GET \
    --location 'https://sandbox.ebanx.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.

    • Response example:
    {
      "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.10,
            "interest": 0.049,
            "interestAmount": 4.90,
            "iof": 0.41,
            "cet": 77.54,
            "totalAmountWithInterest": 105.31
          }
        ],
        "credit_with_additional_limit": [
          {
            "totalAmount": 100,
            "quantity": 1,
            "instalmentAmount": 376.30,
            "interest": 0.11,
            "additionalLimit": 833,
            "totalAmountWithInterest": 376.30
          }
        ]
      }
    }
    Response fields

    Each entry in the instalmentsPlan object includes: totalAmount (base payment amount), quantity (number of installments), instalmentAmount (per-installment value), and totalAmountWithInterest (total amount including fees). Additional fields such as interest, interestAmount, iof, and cet may appear for options that include fees.

  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.

    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?

Help Image

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