NuPay supports recurring payments, and we streamline this process for you with Payment agreements.

Create the payment agreement

To create a NuPay payment agreement, provide the following information when calling our payment agreements endpoint:

Data Field	Description
`paymentMethod`	`NUPAY`
`consumer.taxIdentification`	The individual taxId (CPF).
`consumer.country`	The country from which the consumer is shopping.
`consumer.email`	The consumer’s email address.
`consumer.name`	Full name of the consumer.
`instrument.details.fundingType`	To indicate the preferred option of the consumer (DEBIT or CREDIT)

❗️
For recurring transactions, your checkout interface must explicitly provide "Debit" and "Credit" options for the consumer to choose from.
The consumer's selection must be passed in the Payment Instrument object of your request (instrument.details.fundingType), using the values DEBIT or CREDIT

You can also include the initialPaymentCharge object in this agreement creation call to immediately initiate the first payment without making a separate call. If you include this object, you'll need to specify:

The exact amount.value and amount.currency of the first payment

If you don't include an initialPaymentCharge during agreement creation, you'll need to make a separate API call to /v1/payment-agreements/{agreement_id}/payment-charges to create the first charge.

Request

POST /v1/payment-agreements

{
   "paymentMethod": "NUPAY",
   "consumer": {
       "name": "John Smith",
       "country": "BR",
       "taxIdentification": "58188896454",
       "email": "[email protected]"
   },
   "instrument": {
       "type": "PASSTHROUGH_WALLET",
       "details": {
           "fundingType": "CREDIT"
        }
   },
   "authenticationSettings": [
       {
           "type": "APP_NOTIFICATION",
           "settings": {
               "instrumentProviderIdentity": "58188896454"
           }
       }
   ]
}

{
   "paymentMethod": "NUPAY",
   "consumer": {
       "name": "John Smith",
       "country": "BR",
       "taxIdentification": "58188896454",
       "email": "[email protected]"
   },
   "instrument": {
       "type": "PASSTHROUGH_WALLET",
       "details": {
           "fundingType": "CREDIT"
        }
   },
   "initialPaymentCharge": {
       "paymentDescriptor": "paymentDescriptor",
       "amount": {
           "value": 2500,
           "currency": "BRL"
       },
       "merchantPaymentChargeReference": "7c9b8631-323a-45a9-99e5-50ca854f858d"
   },
   "authenticationSettings": [
       {
           "type": "APP_NOTIFICATION",
           "settings": {
               "instrumentProviderIdentity": "58188896454"
           }
       }
   ]
}

Response

You'll receive a response with the available authentication methods:

{
   "id": "agr_e6eWbbtH6ZPO5fn42OCW4",
   "status": "AUTHENTICATION_PENDING",
   "paymentMethod": "NUPAY",
   "startDate": "2026-01-20T10:16:57.497Z",
   "instrumentId": "instr_iBoe8kZYcgoiYUmklJ7Aw",
   "consumer": {
       "name": "Pix Tester 919",
       "email": "[email protected]",
       "country": "BR",
       "taxIdentification": "58188896454"
   },
   "authenticationMethods": [
       {
           "details": {},
           "type": "APP_NOTIFICATION"
       }
   ],
   "history": [
       {
           "id": "ahist_p4YXN1n2hfspMkWCO7sxK",
           "status": "AUTHENTICATION_PENDING",
           "createdAt": "2026-01-20T10:17:05.406Z"
       }
   ],
   "revocations": [],
   "createdAt": "2026-01-20T10:17:05.406Z",
   "updatedAt": "2026-01-20T10:17:05.406Z"
}

{
   "id": "agr_dLYIxJ7sokaxWzj4eDIwi",
   "status": "AUTHENTICATION_PENDING",
   "paymentMethod": "NUPAY",
   "startDate": "2026-01-20T10:43:06.849Z",
   "instrumentId": "instr_XfXCunw95Tu7BvZImTklK",
   "consumer": {
       "name": "John Smith",
       "email": "[email protected]",
       "country": "BR",
       "taxIdentification": "58188896454"
   },
   "authenticationMethods": [
       {
           "details": {},
           "type": "APP_NOTIFICATION"
       }
   ],
   "history": [
       {
           "id": "ahist_MojcCwZbCdQJfaEd93tbf",
           "status": "AUTHENTICATION_PENDING",
           "createdAt": "2026-01-20T10:43:11.599Z"
       }
   ],
   "revocations": [],
   "createdAt": "2026-01-20T10:43:11.599Z",
   "updatedAt": "2026-01-20T10:43:11.599Z"
}

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.# Handling the payment result.

Create a recurring payment

To initiate a subsequent recurring payment, send a request against an active agreement using our payment agreements API.

Request

POST /v1/payment-agreements/{agreement-id}/payment-charges

{
   "paymentDescriptor": "paymentDescriptor",
   "amount": {
       "value": 10000,
       "currency": "BRL"
   },
   "merchantPaymentChargeReference": "7c9b8631-323a-45a9-99e5-50ca854f858d"
}

Response

{
   "id": "charge_38einOJKaanAiInRZH89I",
   "paymentMethod": "NUPAY",
   "currency": "BRL",
   "country": "BR",
   "paymentDescriptor": "paymentDescriptor",
   "instrumentId": "instr_5weOvmmUbus12j0XYjNwN",
   "status": "AUTHORIZATION_ASYNC",
   "consumer": {
       "name": "John Smith",
       "email": "[email protected]",
       "country": "BR",
       "taxIdentification": "58188896454"
   },
   "order": {
       "orderItems": [],
       "industryData": [],
       "installmentPlan": {
           "numberOfInstallments": 1
       }
   },
   "authorizations": [
       {
           "id": "authz_cniicX5fawtn4xHRYOY1p",
           "amount": 12345,
           "status": "PROVIDER_CONFIRMATION_PENDING",
           "merchantPaymentChargeReference": "f4b749a5-5554-4f6a-a8ed-1a68f61623ad",
           "createdAt": "2026-01-20T10:54:59.926Z",
           "updatedAt": "2026-01-20T10:54:59.926Z"
       }
   ],
   "captures": [],
   "refunds": [],
   "voids": [],
   "createdAt": "2026-01-20T10:54:56.216Z",
   "updatedAt": "2026-01-20T10:54:59.926Z"
}