Skip to main content
Nupay

NuPay, developed by Nubank, is a payment method aimed at providing a seamless and secure payment experience for consumers in Brazil. This guide will walk you through the steps to integrate NuPay with EBANX's Direct API, allowing your customers to use NuPay for their transactions.

Requirements​

  • API credentials - Ensure you have your EBANX integration key. If not, complete the Merchant Signup Form.

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

  2. Retrieve available Digital Wallets

    Check which wallets are available by selected country using the /ws/ewallet-availableEWallets endpoint.

    Sample Request

    curl -X POST 
      --location 'https://api.ebanx.com/ws/ewallet-availableEWallets' \
      --header 'Content-Type: application/json' \
      --data '{
        "integration_key": "your_ebanx_integration_key",
        "operation": "request",
        "country": "br" // country code
      }'

    The API response will return an array of available digital wallets for the selected country. Look for Nupay to confirm availability.

      // Sample response: an array of digital-wallet objects.
    [
      {
        "code": "nupay",
        "name": "NuPay",
        "icon_url": "https://s3-sa-east-1.amazonaws.com/assets.ebanx.com/gateway/nupay/icon.png",
        "promotional_text": "Pay easily with Nupay"
      },
      {
        "code": "paypal",
        "name": "PayPal",
        "icon_url": "https://s3-sa-east-1.amazonaws.com/assets.ebanx.com/gateway/paypal/icon.png",
        "promotional_text": "Pay easily with PayPal."
      }
    ]
    For more information, refer to the
    API reference for digital walletschevron_right

  3. Render digital wallets options

    You can render the Nupay details on your checkout page using the information provided in the API response.

    • Display the icon_url to show the Nupay logo.
    • Use the promotional_text to display a message for Nupay.

    Example HTML

      <div class="digital-wallet">
        <img src="https://s3-sa-east-1.amazonaws.com/assets.ebanx.com/gateway/nupay/icon.png" alt="Nupay logo image">
        <p>Pay easily with Nupay.</p>
      </div>

  4. Get the digital wallet code

    Each digital wallet in the response contains a unique code that identifies the wallet (e.g., "nupay", "nequi", "paypal"). You’ll need this code to create a payment. In this case nupay.

  5. Payment request

    Once your customer submits a Nupay payment at checkout, create a payment request using the ws/direct endpoint. Assign the payment_type_code parameter to the digital wallet code.


    Sample request

    curl -X POST \
      --location 'https://api.ebanx.com/ws/direct' \
      --header 'Content-Type: application/json' \
      --data '{
        "integration_key": "your_ebanx_integration_key",
        "operation": "request",
        "payment": {
          "amount_total": 100.00,
          "currency_code": "COP",
          "name": "John Doe",
          "email": "john.doe@example.com",
          "country": "br",
          "payment_type_code": "nupay", // The digital wallet code
          "merchant_payment_code": "xyz-123-1001",
          "redirect_url": "https://your-call-back-url.com",
        }
      }'

  6. Payment response

    Each request returns a response similar to the example below.

    {
      "payment": {
        "hash": "5ec27f3b86fa8e3123452345626aec3989aa2ceccdb7",
        "country": "co",
        "merchant_payment_code": "xyz-123-1001",
        "order_number": null,
        "status": "PE",
        "status_date": null,
        "open_date": "2020-05-18 12:27:38",
        "confirm_date": null,
        "transfer_date": null,
        "amount_br": "1.00",
        "amount_ext": "1.00",
        "amount_iof": "0.00",
        "currency_rate": "1.0000",
        "currency_ext": "COP",
        "due_date": "2020-05-21",
        "instalments": "1",
        "payment_type_code": "nupay",
        "pre_approved": false,
        "capture_available": null
      },
      "status": "SUCCESS",
      "redirect_url": "https://api.ebanxpay.com/ws/redirect/execute?hash=5ec27f3b86fa8e318dd345234523553626aec3989aa2ceccdb7"
    }
    At this stage, the payment will appear as pending (PE) in your
    EBANX Dashboardchevron_right

  7. Redirect customer

    Redirect the customer to the link provided in the response to complete the payment.

       "redirect_url": "https://api.ebanxpay.com/ws/redirect/execute?hash=5ec27f3b86fa8e318ddcc9727453626aec3989aa2ceccdb7",

    Alternatively, if the customer has registered a mobile number with their NuPay app, they will receive a push notification and can finalize the payment directly.


    Nupay app workflow:

    Voucher NUPAY

  8. Monitor payment for status changes

    Notifications

    Status

    • After receiving a notification, 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 automatically update to cancelled (CA).

  9. Congratulations!

    You have succesfully integrated Nupay.

    For more information, refer to the
    Direct API reference guidechevron_right

Resources​

Use the following resources when testing in your sandbox environment.

Globe Icon

API Reference

Click here to access detailed API documentation to integrate efficiently.

Click to explorechevron_right
Mock Data Icon

Mock Customer Data

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

Click to explorechevron_right
Debit Card Icon

Error Codes

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

Click to explorechevron_right

Still need help?

Help Image

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