Scheduled Payments (Pix Agendado)
With our payment initiation functionality, you can schedule payments to occur in the future (also called PIX RECORRENTE) using any of the following modes:
- SINGLE: Schedule a payment to occur at a specific moment in the future.
- DAILY: Schedule several payments to occur every day, starting from a specific date.
- WEEKLY: schedule several payments to occur every week, starting from a specific date
- MONTHLY: schedule several payments to occur every month, starting from a specific date
- CUSTOM: Schedule several payments to occur on specific dates in the future.
Scheduling a payment
- Create a Payment Request including a
schedule
object:
{
"amount": 1333.33, // The amount to be paid every day/week/month/custom schedule
"description": "My payment request 2",
"schedule": {
"type": "DAILY",
"startDate": "2024-06-26", // Date of the first payment
"occurrences": 2 // How many times to repeat it
},
"recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}
{
"id": "4f05247c-d9ee-4d5b-a0ea-c1c52cc30f69",
"amount": 1333.33,
"description": "My payment request 2",
"status": "CREATED",
"createdAt": "2024-06-24T19:42:37.349Z",
"updatedAt": "2024-06-24T19:42:37.349Z",
"callbackUrls": null,
"paymentUrl": "https://pay.pluggy.ai/4f05247c-d9ee-4d5b-a0ea-c1c52cc30f69",
"bulkPaymentId": null,
"recipient": {
"type": "BANK_ACCOUNT",
"id": "4c35f7bf-55c2-4fbf-9b13-4c9697bdc4cd",
"name": "Nicolas Diaz Loiola",
"taxNumber": "219.078.298-81",
"isDefault": true,
"paymentInstitution": {
"id": "71e8cb09-f590-466e-9b6e-b71bcde5a196",
"name": "ITAÚ UNIBANCO S.A.",
"tradeName": "ITAÚ UNIBANCO S.A.",
"ispb": "60701190",
"compe": "341",
"createdAt": "2023-12-08T17:52:21.001Z",
"updatedAt": "2023-12-08T17:52:21.001Z"
},
"account": {
"type": "CHECKING_ACCOUNT",
"number": "3213213",
"branch": "5431"
},
"pixKey": null,
"createdAt": "2023-12-08T18:04:53.340Z",
"updatedAt": "2024-03-14T16:20:36.668Z"
},
"clientPaymentId": null,
"customer": null,
"fees": null,
"pixQrCode": null,
"boleto": null,
"smartAccount": null,
"schedule": {
"type": "DAILY",
"startDate": "2024-06-26",
"occurrences": 2
}
}
- Authorize the Payment Request with our Payments App (by visiting the
paymentUrl
in the response) - After the user chooses the institution to pay with, enters their CPF/CNPJ and clicks Pay, a Payment Intent with status CONSENT_AWAITING_AUTHORIZATION is created. This triggers the
payment_intent/created
webhook. The user is now redirected to their institution to authorize the scheduled payment. - Once authorized, the Payment Intent will change status to
PAYMENT_COMPLETED
. This triggers thepayment_intent/completed
webhook.
Now, one or more Scheduled Payments (payments to occur in the future) will be created. Each creation will trigger thescheduled_payment/created
webhook. - You can now obtain the list of Scheduled Payments:
{
"total": 2,
"totalPages": 1,
"page": 1,
"results": [
{
"id": "9f12b911-a064-4310-89f2-8d411e10b160",
"status": "SCHEDULED",
"scheduledDate": "2024-06-26",
"description": "My payment request 1/2"
},
{
"id": "1f1f04e8-0bcf-4baf-bbbd-8bedf8478503",
"status": "SCHEDULED",
"scheduledDate": "2024-06-27",
"description": "My payment request 2/2"
}
]
}
- On each of the scheduled dates, a payment will be triggered in the institution. This will result in the Scheduled Payment changing status to COMPLETED or ERROR in the case of failure. This triggers the
scheduled_payment/completed
orscheduled_payment/error
webhook. - If the user cancels a Scheduled Payment from the institution, it will change status to CANCELED and trigger the
scheduled_payment/canceled
webhook. - After all Scheduled Payments are COMPLETED, the Payment Request will change status to COMPLETED.
Modifying or cancelling scheduled payments
If the user has not authorized a scheduled payment yet, you can modify it using the PATCH /payment-requests/{id}
endpoint, or delete it using the DELETE /payment-requests/{id}
endpoint.
After the user has authorized a Scheduled Payment, you can not add or edit the resulting Schedules. However, you can delete a particular schedule or cancel the entire payment altogether.
The authorizing user can also cancel all schedules from their bank directly. You can react to this change with a webhook.
Schedule Modes
Here are examples of how to set up all the different schedule modes:
{
"amount": 1333.33,
"description": "Test",
"schedule": {
"type": "SINGLE",
"date": "2024-06-26T00:00:000Z"
},
"recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}
{
"amount": 1333.33,
"description": "Test",
"schedule": {
"type": "DAILY",
"startDate": "2024-06-26",
"occurrences": 2
},
"recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}
{
"amount": 1333.33,
"description": "Test",
"schedule": {
"type": "WEEKLY",
"startDate": "2024-06-26",
"dayOfWeek": "MONDAY",
"occurrences": 2
},
"recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}
{
"amount": 1333.33,
"description": "Test",
"schedule": {
"type": "MONTHLY",
"startDate": "2024-06-26",
"dayOfMonth": 1,
"occurrences": 2
},
"recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}
{
"amount": 1333.33,
"description": "Test",
"schedule": {
"type": "CUSTOM",
"dates": ["2024-06-26", "2024-06-28"]
},
"recipientId": "376af75c-05fa-4a50-9347-d790a2d19940"
}
Using a custom UI
If you want to use your own UI to implement the Scheduled Payment flow instead of our Payments App:
- Create the payment request, including a
callbackUrl
to your website:
{
"amount": 1333.33,
"description": "My payment request 2",
"schedule": {
"type": "DAILY",
"startDate": "2024-06-26", // Date of the first payment
"occurrences": 2 // How many times to repeat it
},
"recipientId": "376af75c-05fa-4a50-9347-d790a2d19940",
"callbackUrls": {
"success": "<your-website>/success",
"error": "<your-website>/error"
}
}
{
"id": "4f05247c-d9ee-4d5b-a0ea-c1c52cc30f69",
"amount": 1333.33,
"description": "My payment request 2",
"status": "CREATED",
"createdAt": "2024-06-24T19:42:37.349Z",
"updatedAt": "2024-06-24T19:42:37.349Z",
"callbackUrls": null,
"paymentUrl": "https://pay.pluggy.ai/4f05247c-d9ee-4d5b-a0ea-c1c52cc30f69",
"bulkPaymentId": null,
"recipient": {
"type": "BANK_ACCOUNT",
"id": "4c35f7bf-55c2-4fbf-9b13-4c9697bdc4cd",
"name": "Nicolas Diaz Loiola",
"taxNumber": "219.078.298-81",
"isDefault": true,
"paymentInstitution": {
"id": "71e8cb09-f590-466e-9b6e-b71bcde5a196",
"name": "ITAÚ UNIBANCO S.A.",
"tradeName": "ITAÚ UNIBANCO S.A.",
"ispb": "60701190",
"compe": "341",
"createdAt": "2023-12-08T17:52:21.001Z",
"updatedAt": "2023-12-08T17:52:21.001Z"
},
"account": {
"type": "CHECKING_ACCOUNT",
"number": "3213213",
"branch": "5431"
},
"pixKey": null,
"createdAt": "2023-12-08T18:04:53.340Z",
"updatedAt": "2024-03-14T16:20:36.668Z"
},
"clientPaymentId": null,
"customer": null,
"fees": null,
"pixQrCode": null,
"boleto": null,
"smartAccount": null,
"schedule": {
"type": "DAILY",
"startDate": "2024-06-26",
"occurrences": 2
}
}
- Create a Payment Intent for that Payment Request:
{
"paymentRequestId": "4f05247c-d9ee-4d5b-a0ea-c1c52cc30f69",
"connectorId": 600, // this is sandbox
"parameters": {
"cpf": "76109277673"
}
}
{
"id": "751caf12-1bcf-4915-a604-5a1756e7497c",
"status": "CONSENT_AWAITING_AUTHORIZATION",
"createdAt": "2024-06-24T20:14:29.489Z",
"updatedAt": "2024-06-24T20:14:29.489Z",
"paymentRequest": {
"id": "cd23f635-ffcc-4bb0-8dfe-5726e14b5b79",
"amount": 1333.33,
"description": "My payment request 2",
"status": "IN_PROGRESS",
"createdAt": "2024-06-24T20:10:26.464Z",
"updatedAt": "2024-06-24T20:14:29.521Z",
"callbackUrls": null,
"paymentUrl": "https://pay.pluggy.ai/cd23f635-ffcc-4bb0-8dfe-5726e14b5b79",
"bulkPaymentId": null,
"recipient": {
"type": "BANK_ACCOUNT",
"id": "4c35f7bf-55c2-4fbf-9b13-4c9697bdc4cd",
"name": "Nicolas Diaz Loiola",
"taxNumber": "219.078.298-81",
"isDefault": true,
"paymentInstitution": {
"id": "71e8cb09-f590-466e-9b6e-b71bcde5a196",
"name": "ITAÚ UNIBANCO S.A.",
"tradeName": "ITAÚ UNIBANCO S.A.",
"ispb": "4312151",
"compe": "531",
"createdAt": "2023-12-08T17:52:21.001Z",
"updatedAt": "2023-12-08T17:52:21.001Z"
},
"account": {
"type": "CHECKING_ACCOUNT",
"number": "3213123",
"branch": "3215"
},
"pixKey": null,
"createdAt": "2023-12-08T18:04:53.340Z",
"updatedAt": "2024-03-14T16:20:36.668Z"
},
"clientPaymentId": null,
"customer": null,
"fees": null,
"pixQrCode": null,
"boleto": null,
"smartAccount": null,
"schedule": {
"type": "DAILY",
"startDate": "2024-06-26",
"occurrences": 2
}
},
"bulkPayment": null,
"connector": {
"id": 600,
"name": "Sandbox Open Finance",
"primaryColor": "48be9d",
"institutionUrl": "https://cdn.raidiam.io/directory-ui/brand/obbrazil/0.2.0.112/favicon.svg",
"country": "BR",
"type": "PERSONAL_BANK",
"credentials": [
{
"validation": "^\\d{3}\\.?\\d{3}\\.?\\d{3}-?\\d{2}$",
"validationMessage": "CPF deve ter 11 números.",
"label": "CPF",
"name": "cpf",
"type": "number",
"placeholder": "",
"optional": false
}
],
"imageUrl": "https://cdn.pluggy.ai/assets/connector-icons/sandbox.svg",
"hasMFA": false,
"oauth": true,
"health": {
"status": "ONLINE",
"stage": null
},
"products": [
"ACCOUNTS",
"TRANSACTIONS",
"IDENTITY",
"CREDIT_CARDS",
"PAYMENT_DATA",
"LOANS",
"INVESTMENTS"
],
"createdAt": "2023-09-01T18:05:09.145Z",
"isSandbox": true,
"isOpenFinance": true,
"updatedAt": "2024-06-24T19:33:44.725Z",
"supportsPaymentInitiation": true
},
"consentUrl": "https://payment-institution-consent-url.pluggy.ai",
"referenceId": null,
"pixData": null,
"paymentMethod": "PIS"
}
- Redirect the user to the
consentUrl
in the response, which will take them to the institution's Open Finance Payment Initiation screen to authorize the payment. - You will be redirected back to the corresponding
callbackUrl
(success or error).
Updated 13 days ago