Intro

Before you can use our OFPI solution and start collecting payments, you’ll need to:

1. Create your Payments secret keys. Make sure you've already created your Belvo account. For instructions on how to generate your Payments secret keys, see Authentication (Payments).

2. Register your webhook so we can let you know about important events during the payment process, such as payment confirmations. For instructions on how to register your Payments webhooks, see Webhooks (Payments).

3. List the Belvo-supported payment institutions. Here we return the institution id that you’ll need to create your bank account.

4. Register your organization’s bank account. This is the beneficiary account that will collect successful payments.

5. (Optional) Have your callback URLs prepared. These are URLs that the user should be redirected to when they complete or cancel a payment, or if an error occurs during the payment process.

6. (Payment Intents only) Implement the OFPI redirection flow to complete the payment intents process (link to specific instructions).

Postman collection

We’ve created a private Postman collection for you to quickly get set up using Belvo’s Open Finance Payment Initiation (OFPI). 😉

👍

If you need any help, just reach out to our team at [email protected] and we’ll get right to it. 🙂

Get your payment institution id

You’ll need to provide an institution id (this is a unique ID in Belvo’s systems) to register your organization’s bank account. To get your institutions.id , you need to make a GET List all payment institutions call and then query our Institutions resource to find your banks’ id. We return the following response:

{
  "id": "bbaceead-7b96-46d8-9354-38dec9707004",
  "active": true,
  "name": "wakanda_national",
  "display_name": "Wakanda National Bank",
  "legal_entity_name": "Wakanda Bank, National Association",
  "website": "https://www.wakandanational.com",
  "logo": "https://belvo-api-media.s3.amazonaws.com/logos/wakandanational_logo.png",
  "icon_logo": "https://belvo-api-media.s3.amazonaws.com/logos/wakandanational_icon_logo.png",
  "text_logo": "https://belvo-api-media.s3.amazonaws.com/logos/wakandanational_text_logo.png",
  "primary_color": "#fdbc24",
  "country": "BRA",
  "form_fields": [] // An array of input form fields for an institution.
}

Register your organization’s bank account

You can register your organization’s bank account to be the beneficiary account that will collect all successful payments. To register your bank account, you need to make a POST Create a new bank account call to our Bank Accounts resource. You can register as many organization bank accounts as you want.

{
  "institution": "f512d996-583a-4a91-8b5b-eba2e103b068",
  "holder": {
    "type": "BUSINESS", // Must be set to BUSINESS
    "information": {
        "identifier_type": "CNPJ",
        "name": "Caetano Veloso Entertainment Universe",
        "identifier": "23100299900"
          }
     },
   "details": {
        "country": "BRA",
        "account_type": "CHECKINGS",
        "agency": "0444",
        "number": "45722-0"
     }
}

You’ll receive the following response from our API. Make sure you save the id from the response - you’ll use it as the beneficiary_bank_account in the future when you create payment links. 🤓.

{
  "id": "1c83ead8-6665-429c-a17a-ddc76cb3a95e",
  "created_at": "2020-04-23T21:30:20.336854+00:00",
  "created_by": "62053a72-e2d5-4c95-a578-6b16616900ac",
  "customer": "49f244ef-06cd-49cf-ad0c-f43796e370ad",
  "institution": "f512d996-583a-4a91-8b5b-eba2e103b068",
  "details": {
    "country": "BRA",
    "account_type": "CHECKINGS",
    "agency": "0444",
    "number": "45722-0"
  },
  "holder": {
    "type": "BUSINESS",
    "information": {
      "identifier_type": "CNPJ",
      "name": "Caetano Veloso Entertainment Universe",
      "identifier": "23100299900"
    }
  }
}

📘

Registering your customer's bank account as the beneficiary

You can also register and set your customer's bank account as the beneficiary account to collect all successful payments. Check our OFPI Payment Linksguide for more info.

Have your callback URLs ready

These are URLs that you’ll need to provide in a payment link request and will redirect your customer when they complete or cancel a payment, or if an error occurs during the payment process. You’ll need to provide cancel and success URLs:

{
  "callback_urls": {
    "cancel": "https://www.acmecorp.com/checkout/3487548/cancel",
    "success": "https://www.acmecorp.com/checkout/3487548/success"
  }
}

📘

You won't need to provide callback URLs if your integration only generates payment links through the Belvo Dashboard. 🙂

What's next?

You're all set! To start collecting payments from your customers, check our OFPI Payment Links or OFPI Payments Intents guides!