NuPay is a high-conversion payment method exclusive to Nubank customers in Brazil. Unlike traditional methods, it operates entirely within the bank’s secure ecosystem, allowing consumers to authorize purchases directly in their app with just one click or biometric scan. This eliminates the need to share card details with the merchant, significantly reducing friction and security risks. It offers a flexible experience where the transaction can be processed via credit or debit (using the account balance), often providing customers with higher approval rates and exclusive installment options.

Payment method properties


Markets (consumer)	`BR`
Processing currencies	`BRL`
Consumer currencies	`BRL`
Authentication methods	`APP_NOTIFICATION`
Authentication timeout	20 minutes
Minimum payment amount	0.01 1USD
Maximum payment amount	N/A
Payment instrument	`PASSTHROUGH_WALLET`
Recurring payments	Yes
Separate captures	No
Refund	Full - Partial - Multiple
Refund validity	N/A
Disputes	No
Settlement risk	No

Make a NuPay payment

NuPay payments follow our standardized APP_NOTIFICATION payment flow. This enables you to offer a seamless experience where the consumer approves the payment on their mobile device.

To create a NuPay payment, you'll need to provide the following data at minimum when calling our payment charges endpoint:

Field	Description
`paymentMethod`	`NUPAY`
`amount.value`	The amount to be paid in the smallest units of the currency used.
`amount.currency`	`BRL`
`consumer.country`	The country of residence of the consumer.
`consumer.taxIdentification`	The individual taxId (CPF).
`consumer.email`	The consumer’s email address.
`consumer.name`	Full name of the consumer.

Request

POST /v1/payment-charges

{
    "paymentMethod": "NUPAY",
    "paymentDescriptor": "Payment Descriptor",
    "merchantPaymentChargeReference": "4f7cee38-1619-45b4-bdf4-083cb64881cb",
    "amount": {
        "value": 100,
        "currency": "BRL"
    },
    "consumer": {
        "name": "John Doe",
        "email": "[email protected]",
        "country": "BR",
        "taxIdentification": "16473518045"
    }
}

Response

You'll receive our standard payment charge response with the available authentication methods:

{
    "id": "charge_O00XzRGMelLWnGrzAq3EH",
    "paymentMethod": "NUPAY",
    "paymentMedium": "ECOMMERCE",
    "scheduleType": "UNSCHEDULED",
    "instrumentId": "instr_4dZy093A7pluH4wR0n8KA",
    "currency": "BRL",
    "country": "BR",
    "paymentDescriptor": "Payment Descriptor",
    "status": "AUTHENTICATION_PENDING",
    "consumer": {
        "name": "John Doe",
        "email": "[email protected]",
        "country": "BR",
        "taxIdentification": "16473518045"
    },
    "authenticationMethods": [
        {
            "details": {},
            "type": "APP_NOTIFICATION"
        }
    ],
    "authorizations": [
        {
            "id": "authz_nIC25JxDFTBttzhbJK74T",
            "amount": 100,
            "status": "AUTHENTICATION_PENDING",
            "merchantPaymentChargeReference": "54473241-2eea-478d-9cac-80add73b3386",
            "createdAt": "2026-02-13T12:01:09.574Z",
            "updatedAt": "2026-02-13T12:01:09.574Z"
        }
    ],
    "captures": [],
    "refunds": [],
    "discards": [],
    "voids": [],
    "createdAt": "2026-02-13T12:01:09.416Z",
    "updatedAt": "2026-02-13T12:01:09.574Z",
    "_links": {
        "authorizations": {
            "href": "/v1/payment-charges/charge_O00XzRGMelLWnGrzAq3EH/authorizations"
        },
        "captures": {
            "href": "/v1/payment-charges/charge_O00XzRGMelLWnGrzAq3EH/captures"
        },
        "refunds": {
            "href": "/v1/payment-charges/charge_O00XzRGMelLWnGrzAq3EH/refunds"
        },
        "discards": {
            "href": "/v1/payment-charges/charge_O00XzRGMelLWnGrzAq3EH/discards"
        },
        "voids": {
            "href": "/v1/payment-charges/charge_O00XzRGMelLWnGrzAq3EH/voids"
        }
    }
}

Handling the payment result

APP_NOTIFICATION

The payment charge will remain in the AUTHENTICATION_PENDING state until the consumer confirms the payment.
Webhooks are sent to inform you of the agreement and/or payment outcome.
Alternatively, check the agreement and/or payment status and use the Status that you received to display the outcome to the consumer. GET /v1/payment-agreements/{agreement-id} GET [/v1/payment-charges/{paymentChargeId}] (https://developerhub.ppro.com/global-api/reference/getpaymentcharge.
Store the Payment Agreement ID for subsequent payments.

Payment instrument

A PASSTHROUGH_WALLET instrument will be created for NuPay, with no additional data provided.

Request

GET /v1/payment-instruments/{instrument-id}

Response

{
  "id": "instr_ExampleInstrumentId",
  "type": "PASSTHROUGH_WALLET"
}

Sandbox testing

Please, follow below instructions to use the NuPay sandbox.

To simulate possible authorization scenarios, enter one of the taxIds (CPFs) below in the consumer.taxIdentification parameter of the request:

taxId	Description
`58188896454`	Authorization accepted by the customer for any type of charge. The billing method (credit or debit) is defined on payment creation.
`31457612500`	Authorization denied by the customer.

It is possible to simulate different payment scenarios in sandbox by replacing the amount.value attribute. See the pre-defined values and their respective simulations in the table below:

Value range (amount)	Charge Status	Description
Between R$ 0.01 and R$ 702.00	CAPTURED	Payment charge successfully captured
Between R$703.00 and R$803.00	FAILED	Payment charge failed with ProviderErrorCode SYSTEM_ERROR
Between R$804.00 and R$1005.00	FAILED	Payment charge failed with ProviderErrorCode CANCELLED_BY_INSTITUTION
Between R$1006.00 and R$1106.00	FAILED	Payment charge failed with ProviderErrorCode CANCELLED_BY_TIMEOUT
Any value above R$ 1106.0	CAPTURED	Payment charge successfully captured