Scheduled Payments
Feature only by invite
For the moment, this feature is in beta and has to be enabled for your client specifically.
If you're interested in trying it out, please contact our Sales team!
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 at 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 editing under construction
Cancelling a whole scheduled payment or a specific schedule and reacting to the user cancelling the schedules from their bank will be available soon.
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-26T00:00:000Z"]
},
"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).
Schedule Webhooks Flow
Updated about 2 months ago