With Belvo's Open Finance Payment Initiation (OFPI), you can collect scheduled payments from your customers and optimize their payment experience. In this guide, we’ll show you:

• the general flow of data
• how to create a payment intent to collect scheduled or recurring payments
• the payment statuses and notifications
• how to cancel scheduled or recurring payments

Data flow overview

As you can see in the diagram below, the data flow for creating a scheduled or recurring payment involves:

1. Creating a payment intent (containing the required information for the payment to be processed in the Open Finance Network).
2. Listening for notifications regarding the scheduled payment.
3. On the day of the scheduled payment, listening for the OBJECT_CREATED webhook from the transactions resource.
4. Getting the transaction details when the payment is completed.

For more details regarding the notifications you can receive as well as the lifecycle of a scheduled or recurring payment, please see the Payment statuses and notifications section of this guide.

Create a scheduled Payment Intent

The Payment Intent contains all the information necessary to register and process the payment in the Open Finance Network. To reduce friction for your customer, we recommend that you create your payment screen so that you can send all the information in just one POST call.

To create a Scheduled or Recurring Payment Intent, check out the recipe below which guides you through all the required parameters:

Once you successfully create a Payment Intent, you will need to use the URL in the payment_method_information.open_finance.redirect_url parameter to redirect your user to their financial institution to confirm the payment. After confirming the payment, your user is redirected back to the callback_url you provided in the Payment Intent request.

For details regarding the response from the Payment Intent request, please see our dedicated Payment Intent (OFPI) Model and States article.

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
}

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
}

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
}

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": {
        "monthly": {
          "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
}

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-06-30", "2024-07-03", "2024-07-06", "2024-07-09"],
          "description": "Description to appear on consent screen"
        }
      }
    }
  }
}

{
  "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
}

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/payment-intents/{payment_intent_id}/charges/' \
     --header 'accept: application/json'

Cancel a payment

Cancelling a specific charge

To cancel a specific scheduled charge, you just need to make a POST Cancel a scheduled Charge API call:

curl 
--request POST \
--header 'accept: application/json' \
--url https://api.belvo.com/payments/br/payment-intents/{payment_intent_id}/charges/{charge_id}/cancel/ \

🚧

Note: The latest you can cancel a scheduled Charge 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.

Cancelling an entire 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/ \

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.