Guides
Service statusPluggy.aiLogin

Scheduled Payments

Suggest Edits

📘

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

  1. 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
    }
}
  1. Authorize the Payment Request with our Payments App (by visiting the paymentUrl in the response)
  2. 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.
  3. Once authorized, the Payment Intent will change status to PAYMENT_COMPLETED. This triggers the payment_intent/completed webhook.
    Now, one or more Scheduled Payments (payments to occur in the future) will be created. Each creation will trigger the scheduled_payment/created webhook.
  4. 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"
        }
    ]
}
  1. 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 or scheduled_payment/error webhook.
  2. If the user cancels a Scheduled Payment from the institution, it will change status to CANCELED and trigger the scheduled_payment/canceled webhook.
  3. 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:

  1. Create the payment request, including a callbackUrlto 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
    }
}
  1. 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"
}
  1. 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.
  2. You will be redirected back to the corresponding callbackUrl (success or error).

Schedule Webhooks Flow

Updated about 2 months ago