> ## Documentation Index
> Fetch the complete documentation index at: https://docs.y.uno/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Test in the sandbox first: base URL https://api-sandbox.y.uno (Test Mode in the Dashboard). Production is https://api.y.uno (Live Mode).
> Every API request needs the public-api-key and private-secret-key headers. Get them in the Dashboard at https://dashboard.y.uno/developers (Developers > Credentials); sandbox and production keys are different.
> Send an X-Idempotency-Key (a UUID) when creating payments, refunds and cancels, so retries do not create duplicates.
> Start with the Quickstart (https://docs.y.uno/docs/quickstart.md) and the agent guide (https://docs.y.uno/agents.md). To search these docs from a coding agent, connect the docs MCP server at https://docs.y.uno/mcp.

# NuPay

> Accept payments with NuPay, the digital payment method from NuBank, using either Yuno's SDK or Direct API workflows for one-time payments, enrollment, and 2FA mode.

This guide explores how to integrate NuPay, the digital payment method from NuBank, into your checkout. Yuno supports both the **Yuno SDK** (recommended) and **Direct API** workflows. You'll learn how to:

* Enroll NuPay as a customer payment method
* Make payments without enrollment (2FA mode)
* Make payments with installments (payment conditions)
* Set up subscriptions

## Requirements

Before starting, you need:

* A Yuno account with Dashboard access
* API keys and an `account_id` (found in the dashboard)
* A customer created in Yuno (or create one in Step 1)

## Create and manage customers

Create the customer once using your external `merchant_customer_id`, then retrieve by Yuno `id` or by `merchant_customer_id` as needed.

1. Use the [Create Customer](https://docs.y.uno/reference/customers/create-customer.md) endpoint and provide your own `merchant_customer_id` (the unique id of the customer in your system). The response returns `id` which is the Yuno customer id.
2. Use [Retrieve Customer](https://docs.y.uno/reference/customers/retrieve-customer.md) with the Yuno `id`.
3. Use [Retrieve Customer by External Id](https://docs.y.uno/reference/customers/retrieve-customer-by-external-id.md) with query parameter `merchant_customer_id`.

## Enroll NuPay payment method

Follow the steps below to enroll the `NU_PAY_ENROLLMENT` payment method to a customer.

> [tab] Yuno SDK
>
> With the SDK integration, Yuno handles displaying the NuPay payment method, redirecting the customer to NuBank for authentication, and managing the return flow.
>
> ### Step 1: Create a customer
>
> Create a customer and obtain their Yuno customer `id` using the [Create Customer](https://docs.y.uno/reference/customers/create-customer.md) endpoint.
>
> ### Step 2: Create a customer session
>
> Use the customer `id` and the [Create Customer Session](https://docs.y.uno/reference/customer-sessions-enrollment/create-customer-session.md) endpoint to receive a `customer_session`.
>
> ### Step 3: Initialize the SDK and enroll
>
> Initialize Yuno's SDK (Web, Android, or iOS) with the `customer_session`.
>
> If using the SDK checkout or headless integration, call [Enroll Payment Method (Checkout)](https://docs.y.uno/reference/payment-methods-checkout/enroll-payment-method-checkout.md) (`POST /customers/sessions/{customer_session}/payment-methods`) with `payment_method_type`: `NU_PAY_ENROLLMENT`.
>
> The SDK automatically displays the NuPay payment method, manages the customer redirection to NuBank, and handles the authentication flow.
>
> ### Step 4: Confirm enrollment
>
> Listen to [webhooks](https://docs.y.uno/docs/webhooks.md) or retrieve enrolled payment methods to verify the status is `ENROLLED`.

> [tab] Direct API
>
> Follow these steps to enroll `NU_PAY_ENROLLMENT` to a customer using the Direct workflow.
>
> ### Step 1: Create a customer
>
> If you don't have a customer yet, create one as shown above. You'll use the returned customer `id`.
>
> ### Step 2: Enroll the payment method
>
> Use [Enroll Payment Method](https://docs.y.uno/reference/payment-methods-direct-workflow/enroll-payment-method-api.md) with the following request parameters:
>
> * **type**: `NU_PAY_ENROLLMENT`
> * **account\_id**: UUID of your account (from the Yuno Dashboard)
> * **workflow**: `DIRECT`
>
> Expected response fields:
>
> * **vaulted\_token**: UUID for the enrolled payment method
> * **status**: `READY_TO_ENROLL`
> * **sub\_status**: `WAITING_ADDITIONAL_STEP`
> * **action**: `REDIRECT_URL`
> * **redirect\_url**: URL to redirect the customer to Nu for authentication
>
> ### Step 3: Redirect the customer
>
> Redirect the customer to the `redirect_url`. The customer completes the Nu flow. Nu notifies Yuno of the final state.
>
> ### Step 4: Confirm enrollment
>
> Use [Retrieve Enrolled Payment Method by id](https://docs.y.uno/reference/payment-methods-direct-workflow/retrieve-enrolled-payment-method-by-id-api.md) with the `vaulted_token`. A successful enrollment returns:
>
> * **status**: `ENROLLED`
>
> * **sub\_status**: `ENROLLED`
>
> > [!WARNING]
> >
> > The enrollment is only complete after Yuno receives Nu’s confirmation.

## Payments without enrollment (2FA mode)

You can accept one-time payments with NuPay without requiring the customer to enroll their payment method. This is often referred to as **2FA mode**, as the customer authenticates each transaction individually.

> [tab] Yuno SDK
>
> Accept payments without enrollment using Yuno's SDK. The SDK handles displaying NuPay and redirecting the customer to complete the authentication.
>
> ### Step 1: Create a checkout session
>
> Start by creating a checkout session using the [Create Checkout Session](https://docs.y.uno/reference/checkout-sessions/create-checkout-session.md) endpoint.
>
> ```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> {
>   "country": "BR",
>   "customer_id": "{{customer_id}}",
>   "merchant_order_id": "order-0000024",
>   "amount": {
>     "currency": "BRL",
>     "value": 15000
>   }
> }
> ```
>
> The response returns a `checkout_session` ID.
>
> ### Step 2: Initialize the SDK
>
> Initialize Yuno's SDK (Web, Android, or iOS) with the `checkout_session` ID. NuPay will automatically render as an available payment option in the SDK interface.
>
> ### Step 3: Customer completes payment
>
> When the customer selects NuPay:
>
> 1. The SDK prompts the customer for authentication.
> 2. The customer is redirected to Nu for 2FA authentication.
> 3. The SDK receives the result and processes the payment through Yuno.
>
> ### Step 4: Handle SDK workflow payments (Optional)
>
> If you are calling the Yuno payments API directly while using the SDK checkout, set the `workflow` to `SDK_CHECKOUT` and pass the `checkout.session` token:
>
> ```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> {
>   "description": "One-time NuPay Payment via SDK",
>   "account_id": "{{account_id}}",
>   "merchant_order_id": "0000024",
>   "country": "BR",
>   "amount": {
>     "currency": "BRL",
>     "value": 150
>   },
>   "customer_payer": {
>     "id": "{{customer_id}}"
>   },
>   "workflow": "SDK_CHECKOUT",
>   "checkout": {
>     "session": "{{checkout_session_id}}"
>   },
>   "payment_method": {
>     "type": "NU_PAY"
>   }
> }
> ```

> [tab] Direct API
>
> ### Step 1: Create a payment
>
> Use [Create payment](https://docs.y.uno/reference/payments/create-payment.md) with the Direct workflow and the `NU_PAY` payment method type. In this mode, you don't need a `vaulted_token`.
>
> ```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> {
>   "description": "One-time NuPay Payment",
>   "account_id": "{{account_id}}",
>   "merchant_order_id": "0000024",
>   "country": "BR",
>   "amount": {
>     "currency": "BRL",
>     "value": 150
>   },
>   "customer_payer": {
>     "id": "{{customer_id}}"
>   },
>   "workflow": "DIRECT",
>   "callback_url": "https://your-callback.com",
>   "payment_method": {
>     "type": "NU_PAY"
>   }
> }
> ```
>
> ### Step 2: Handle the response
>
> Since this mode requires customer authentication, the response will return an action to redirect the user.
>
> * **status**: `READY_TO_PAY`
> * **sub\_status**: `WAITING_ADDITIONAL_STEP`
> * **action**: `REDIRECT_URL`
> * **redirect\_url**: URL to redirect the customer to Nu for 2FA authentication.
>
> ### Step 3: Confirm payment
>
> After the customer completes the authentication, use [Retrieve payment by id](https://docs.y.uno/reference/payments/retrieve-payment-by-id) to confirm the final status.

## Payments with payment conditions (installments)

NuPay supports installments for both enrolled payment methods and one-time payments (2FA mode).

> [tab] Yuno SDK
>
> NuPay supports installments for enrolled payment methods and one-time payments (2FA mode) within the SDK.
>
> ### Step 1: Get payment conditions
>
> Request available installment options using the [APM installments](https://docs.y.uno/reference/installments/apm-installments) endpoint, depending on the flow:
>
> > [tab] Enrollment Flow
> >
> > ```bash theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> > curl -X POST --location 'https://api-sandbox.y.uno/v1/apm-installments' \
> > --header 'public-api-key: {{your_public_api_key}}' \
> > --header 'private-secret-key: {{your_secret_api_key}}' \
> > --header 'X-account-code: {{your_account_id}}' \
> > --header 'Content-Type: application/json' \
> > --data '{
> >   "country": "BR",
> >   "amount": {
> >     "currency": "BRL",
> >     "value": "250"
> >   },
> >   "customer": {
> >     "id": "{{customer_id}}"
> >   },
> >   "payment_method": "NU_PAY_ENROLLMENT",
> >   "vaulted_token": "{{vaulted_token}}"
> > }'
> > ```
>
> > [tab] 2FA Mode
> >
> > ```bash theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> > curl -X POST --location 'https://api-sandbox.y.uno/v1/apm-installments' \
> > --header 'public-api-key: {{your_public_api_key}}' \
> > --header 'private-secret-key: {{your_secret_api_key}}' \
> > --header 'X-account-code: {{your_account_id}}' \
> > --header 'Content-Type: application/json' \
> > --data '{
> >   "country": "BR",
> >   "payment_method": "NU_PAY",
> >   "amount": {
> >     "currency": "BRL",
> >     "value": "250"
> >   },
> >   "customer": {
> >     "document": {
> >       "document_type": "CPF",
> >       "document_number": "52998224725"
> >     },
> >     "email": "customer@email.com"
> >   }
> > }'
> > ```
>
> Select the plan `id` and installments number from the response.
>
> ### Step 2: Create payment using SDK workflow
>
> Create the payment using the SDK workflow by setting `workflow: "SDK_CHECKOUT"` and passing the `checkout.session` along with the plan details:
>
> ```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> {
>   "description": "NuPay Installment Payment via SDK",
>   "account_id": "{{account_id}}",
>   "merchant_order_id": "0000023",
>   "country": "BR",
>   "amount": {
>     "currency": "BRL",
>     "value": 250
>   },
>   "customer_payer": {
>     "id": "{{customer_id}}"
>   },
>   "workflow": "SDK_CHECKOUT",
>   "checkout": {
>     "session": "{{checkout_session_id}}"
>   },
>   "payment_method": {
>     "type": "NU_PAY_ENROLLMENT",
>     "vaulted_token": "{{vaulted_token}}",
>     "detail": {
>       "wallet": {
>         "card_data": {
>           "installments_plan_id": "{{plan_id}}",
>           "installments": 2
>         }
>       }
>     }
>   }
> }
> ```

> [tab] Direct API
>
> ### Step 1: Ensure prerequisites
>
> Depending on the flow, you'll need:
>
> * **Enrollment Flow**: A Yuno customer `id` and an enrolled NuPay `vaulted_token`.
> * **2FA Mode**: Customer details, specifically their tax ID (CPF) and email.
>
> ### Step 2: Get payment conditions
>
> Request available installment options for NuPay using the [APM installments](https://docs.y.uno/reference/installments/apm-installments) endpoint. The request parameters vary based on the integration flow.
>
> > [tab] Enrollment Flow
> >
> > ```bash theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> > curl -X POST --location 'https://api-sandbox.y.uno/v1/apm-installments' \
> > --header 'public-api-key: {{your_public_api_key}}' \
> > --header 'private-secret-key: {{your_secret_api_key}}' \
> > --header 'X-account-code: {{your_account_id}}' \
> > --header 'Content-Type: application/json' \
> > --data '{
> >   "country": "BR",
> >   "amount": {
> >     "currency": "BRL",
> >     "value": "250"
> >   },
> >   "customer": {
> >     "id": "{{customer_id}}"
> >   },
> >   "payment_method": "NU_PAY_ENROLLMENT",
> >   "vaulted_token": "{{vaulted_token}}"
> > }'
> > ```
>
> > [tab] 2FA Mode
> >
> > ```bash theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> > curl -X POST --location 'https://api-sandbox.y.uno/v1/apm-installments' \
> > --header 'public-api-key: {{your_public_api_key}}' \
> > --header 'private-secret-key: {{your_secret_api_key}}' \
> > --header 'X-account-code: {{your_account_id}}' \
> > --header 'Content-Type: application/json' \
> > --data '{
> >   "country": "BR",
> >   "payment_method": "NU_PAY",
> >   "amount": {
> >     "currency": "BRL",
> >     "value": "250"
> >   },
> >   "customer": {
> >     "document": {
> >       "document_type": "CPF",
> >       "document_number": "52998224725"
> >     },
> >     "email": "customer@email.com"
> >   }
> > }'
> > ```
>
> The response returns an array of installment plans, including `id`, available `installments`, and amounts. Select a plan `id` and an allowed installments number.
>
> ### Step 3: Create payment
>
> Use [Create payment](https://docs.y.uno/reference/payments/create-payment.md) with the Direct workflow and NuPay type. Include the selected plan id and installments in the wallet `card_data`.
>
> ```json theme={"theme":{"light":"github-dark","dark":"github-dark-dimmed"}}
> {
>   "description": "test",
>   "account_id": "{{account_id}}",
>   "merchant_order_id": "0000023",
>   "country": "BR",
>   "merchant_reference": "ref-merchant-AA01",
>   "amount": {
>     "currency": "BRL",
>     "value": 250
>   },
>   "customer_payer": {
>     "id": "{{customer_id}}"
>   },
>   "workflow": "DIRECT",
>   "callback_url": "https://your-callback.com",
>   "payment_method": {
>     "type": "NU_PAY_ENROLLMENT",
>     "vaulted_token": "{{vaulted_token}}",
>     "detail": {
>       "wallet": {
>         "card_data": {
>           "installments_plan_id": "{{plan_id}}",
>           "installments": 2
>         }
>       }
>     }
>   }
> }
> ```
>
> ### Step 4: Retrieve payment
>
> Use [Retrieve payment by id](https://docs.y.uno/reference/payments/retrieve-payment-by-id) to confirm final status.

## Subscription flow

You can use NuPay for recurring charges.

> [tab] Yuno SDK
>
> Recurring payments/subscriptions with NuPay can be easily set up using the SDK enrollment token:
>
> 1. Create a customer.
> 2. Enroll NuPay via Yuno SDK (Checkout workflow) to obtain a `vaulted_token`.
> 3. Create a subscription with the enrolled `vaulted_token` using the [Create subscription](https://docs.y.uno/reference/subscriptions/create-subscription.md) endpoint.
> 4. Retrieve and manage subscription state as needed.

> [tab] Direct API
>
> 1. Create a customer
> 2. Enroll NuPay as a payment method (see above)
> 3. Create a subscription with the enrolled `vaulted_token` using [Create subscription](https://docs.y.uno/reference/subscriptions/create-subscription.md)
> 4. Retrieve the subscription using [Retrieve subscription](https://docs.y.uno/reference/subscriptions/retrieve-subscription.md)

> [!NOTE]
>
> **Limitations**
>
> * Subscriptions with NuPay do not support payment conditions (installments)
> * Creating subscriptions directly within a payment request is not supported

## Endpoints

* [Create customer](https://docs.y.uno/reference/customers/create-customer.md)
* [Retrieve customer](https://docs.y.uno/reference/customers/retrieve-customer.md)
* [Retrieve customer by external id](https://docs.y.uno/reference/customers/retrieve-customer-by-external-id.md)
* [Enroll payment method (Direct)](https://docs.y.uno/reference/payment-methods-direct-workflow/enroll-payment-method-api.md)
* [Enroll payment method (Checkout)](https://docs.y.uno/reference/payment-methods-checkout/enroll-payment-method-checkout.md)
* [Retrieve enrolled payment method by id](https://docs.y.uno/reference/payment-methods-direct-workflow/retrieve-enrolled-payment-method-by-id-api.md)
* [Create payment](https://docs.y.uno/reference/payments/create-payment.md)
* [Retrieve payment by id](https://docs.y.uno/reference/payments/retrieve-payment-by-id)
* [APM installments](https://docs.y.uno/reference/installments/apm-installments)
* [Create subscription](https://docs.y.uno/reference/subscriptions/create-subscription.md)
* [Retrieve subscription](https://docs.y.uno/reference/subscriptions/retrieve-subscription.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.