OFPI Scheduled Payments

Want to schedule one or more payments in the future? Look no further! 😎

With Belvo’s OFPI product, you can schedule your payments to occur in the future. Belvo currently supports the following scheduled payment types for our Payment Intents resource:

  • Single
  • Daily
  • Weekly
  • Monthly
  • Custom recurring dates

📘

At the moment, you can only schedule recurring payments for fixed amounts.

Single

A single scheduled payment allows you to set up a one-time transaction for a specific future date. This is ideal for one-off payments where you need to ensure the transaction occurs on a particular day.

Request example

To create a single scheduled payment, add the following information to your Payment Intent request:

{
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "single": {
          "date": "2024-08-01",
        }
      }
    }
  }
}
{
  "amount": "1234.12",
  "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
  "description": "Shoe payment - Single",
  "statement_descrption": "Super Shoe Store - Brown Sneakers",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "single": {
          "date": "2024-08-01"
        }
      },
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "confirm": true
}
FieldDescriptionExample
dateThe date when the payment should occur on, in YYYY-MM-DD format. The date must be at least 1 day into the future and no more than 720 days into the future.2024-08-01

Daily

Daily scheduled payments enable recurring transactions every day starting from a specified date. This is perfect for frequent, regular payments such as daily subscriptions or repetitive services.

To create a daily scheduled payment, add the following information to your Payment Intent request:

{
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "daily": {
          "start_date": "2025-04-09",
          "occurrences": 2
        }
      }
    }
  }
}
{
  "amount": "1234.12",
  "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
  "description": "Shoe payment - Daily",
  "statement_descrption": "Super Shoe Store - Brown Sneakers",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "daily": {
          "start_date": "2025-04-09",
          "occurrences": 2
        }
      },
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "confirm": true
}

FieldDescriptionExample
start_dateThe date when the recurring payments should begin, in YYYY-MM-DD format.2024-08-01
occurrencesThe number of times this recurring payment should repeat. The minimum value is 2 and the maximum value is 60.52

Weekly

Weekly scheduled payments allow you to set up recurring transactions on a specific day of each week. This is useful for weekly services or recurring obligations that occur on the same weekday.

To create a weekly scheduled payment, add the following information to your Payment Intent request:

{
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "weekly": {
          "start_date": "2025-04-09",
          "day_of_week": "MONDAY",
          "occurrences": 52
        }
      }
    }
  }
}
{
  "amount": "1234.12",
  "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
  "description": "Shoe payment - Weekly",
  "statement_descrption": "Super Shoe Store - Brown Sneakers",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "weekly": {
          "start_date": "2025-04-09",
          "day_of_week": "MONDAY",
          "occurrences": 2
        }
      },
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "confirm": true
}
FieldDescriptionExample
start_dateThe date when the recurring payments should begin, in YYYY-MM-DD format.

At present, this date must be the same as the first day_of_week you provide.
2024-08-01
day_of_weekThe day of the week that this payment should be settled on. Can be one of the following: MONDAY, TUESDAY, WEDNESDAY, THURSDAY, FRIDAY, SATURDAY, or SUNDAY.MONDAY
occurrencesThe number of times this recurring payment should repeat. The minimum value is 2 and the maximum value is 60.52

Monthly

Monthly scheduled payments are designed for transactions that repeat on the same day each month. This setup is ideal for monthly bills, subscriptions, or any regular monthly payments.

To create a monthly scheduled payment, add the following information to your Payment Intent request:

{
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "monthly": {
          "start_date": "2025-04-26",
          "day_of_month": 26,
          "occurrences": 12
        }
      }
    }
  }
}
{
  "amount": "1234.12",
  "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
  "description": "Shoe payment - Monthly",
  "statement_descrption": "Super Shoe Store - Brown Sneakers",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "weekly": {
          "start_date": "2025-04-26",
          "day_of_month": 26,
          "occurrences": 12
        }
      },
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "confirm": true
}
FieldDescriptionExample
start_dateThe date when the recurring payments should begin, in YYYY-MM-DD format.

At present, this date must be the same as the first day_of_month you provide.
2024-08-01
day_of_monthThe day of the month (between 1 and 31) that the payment should occur on. Note: If you choose a day that does not appear in all months (for example, 31), then in months that this date does not occur the payment will be made on the next day. For example, as June only has 30 days, the payment will be processed on July 1st (and then again on July 31st). To avoid charging your users twice in the same month, we suggest you choose a day up to the 28th.26
occurrencesThe number of times this recurring payment should repeat. The minimum value is 2 and the maximum value is 24.12

Custom

Custom scheduled payments offer flexibility by allowing you to specify an array of dates for recurring transactions. This option is perfect for irregular schedules or bespoke payment plans that do not fit standard recurrence patterns.

To create a custom scheduled payment, add the following information to your Payment Intent request:

{
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "custom": {
          "dates": ["2024-06-27", "2024-07-27", "2024-08-26", "2024-09-25", "2024-10-25"]
        }
      }
    }
  }
}
{
  "amount": "1234.12",
  "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
  "description": "Shoe payment - Custom Schedule",
  "statement_descrption": "Super Shoe Store - Brown Sneakers",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "custom": {
          "dates": ["2024-06-27", "2024-07-27", "2024-08-26", "2024-09-25", "2024-10-25"]
        }
      },
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "confirm": true
}

FieldDescriptionExample
datesThe array of dates when the recurring payments should occur on, in YYYY-MM-DD format. The minimum number of dates is 2 and the maximum number of dates is 60.

The dates must be at least 1 day into the future and no more than 720 days into the future.
["2024-06-27", "2024-07-27"]

Payment Intents, Charges, and Transactions

For each scheduled payment, Belvo generates a Charge object within the Payment Intent response body. Once a Charge is processed successfully, Belvo generates a Transaction associated with that Charge.

For example, if you create a recurring payment that will occur two times, the charges array in the Payment Intent will include two Charges. And once the first Charge is processed, Belvo generates an associated Transaction.

Payment statuses and notifications

Once you schedule a payment, you will receive webhook updates for the associated Payment Intent, Charges, and Transactions.

Below you can see an example of a recurring scheduled payment and the associated statuses each payment will go through. You will receive STATUS_UPDATE webhook notifications for each status that is marked with a red dot (🔴).

When you receive the OBJECT_CREATED Transaction webhook event, this indicates that the given scheduled payment was settled.

Once all the scheduled Charges have been completed (even if any or all have failed), the Payment Intent status will be set to SCHEDULE_FINISHED.

To see whether a Payment Intent has any failed Charges, you can use the List all Charges method, filtering by the id of the Payment Intent:

curl --request GET \
     --url 'https://api.belvo.com/payments/br/charges/?payment_intent={id}' \
     --header 'accept: application/json'
FieldDescriptionExample
idThe payment-intent.id that you want to filter Charges by.65492eeb-344c-49fe-8dab-11da1be67d7a

Cancelling a Payment Intent

To cancel a Payment Intent (and all associated scheduled Charges), you just need to make a POST Cancel a Payment ntent API call:

curl 
--request POST \
--header 'accept: application/json' \
--url https://api.belvo.com/payments/br/payment-intents/{id}/cancel/ \
FieldDescriptionExample
idThe payment-intent.id that you want to cancel.65492eeb-344c-49fe-8dab-11da1be67d7a

After you make your cancellation request, Belvo will respond with a 204 - No Content, and notify you using a webhook that the status of the Payment Intent has been changed to CANCELED.

🚧

Note: The latest you can cancel a scheduled Payment Intent is by 23:59:00 (GMT-3) on the day before the scheduled payment date. If you miss the cutoff time, you will receive and API error from Belvo and the payment will go through.

Failed scheduled payments

In the case that a singular Charge fails (the payment cannot be settled) from a set of scheduled Charges, it does not affect the remaining scheduled Charges.

For example, in the case that you have five scheduled weekly Charges, and the second Charge is unsuccessful, the remaining three remain scheduled:

Charge NumberDateOutcome
One2024-06-03Successful
Two2024-06-10Failed
Three2024-06-17Remains scheduled
Four2024-06-24Remains scheduled
Five2024-07-01Remains scheduled

📘

It is not possible to retry a failed Charge. We recommend you contact your user and then create a separate one-time Payment Intent to retrieve funds from the user.

When are scheduled payments processed?

According to Brazil's Open Finance Network regulations, financial institutions must process scheduled payments according to the table below.

AttemptTimeframe (GMT-3)Notified if failed?
First00:00 - 08:00No
Second18:00 - 21:00Yes

If the first attempt to extract funds results in a failure, the institution will try again to process the payment later the same day. You are only notified that the given payment has failed after all attempts result in a failure.

📘

Multiple retry attempts

Financial institutions in the Open Finance Network must at least make one attempt to retry the payment in the 18:00-21:00 timeframe. However, the institution can make additional attempts in this period if they want to.