Skip to main content

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.

This guide explores Yuno’s NuPay integration using the Direct workflow. 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 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 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 with the Yuno id.
  3. Use Retrieve Customer by External Id with query parameter merchant_customer_id.

​
Enroll NuPay payment method

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 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 with the vaulted_token. A successful enrollment returns:
  • status: ENROLLED
  • sub_status: ENROLLED
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.

​
Step 1: Create a payment

Use Create payment with the Direct workflow and the NU_PAY payment method type. In this mode, you don’t need a vaulted_token. 
{
  "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 to confirm the final status.

​
Payments with payment conditions (installments)

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

​
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 endpoint. The request parameters vary based on the integration flow. 
curl --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_code}}' \
--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}}"
}'
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 with the Direct workflow and NuPay type. Include the selected plan id and installments in the wallet card_data. 
{
  "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 to confirm final status.

​
Subscription flow

You can use NuPay for recurring charges.
  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
  4. Retrieve the subscription using Retrieve subscription
Limitations
  • Subscriptions with NuPay do not support payment conditions (installments)
  • Creating subscriptions directly within a payment request is not supported

​
Endpoints