OFPI Prerequisites

Set everything up to use Belvoโ€™s Open Finance Payment Initiation (OFPI) ๐Ÿš€

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.

  2. Register your webhook so we can let you know about important events during the payment process, such as payment confirmations.

  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.

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. ๐Ÿ™‚

Create your secret API keys

In order to use Belvo's Payments API, you need to first request your secret keys (see the code example below):

Where:

  • usernameย is the username you use to log in to the Belvo dashboard (in plain text).
  • passwordย is the password you use to log in to the Belvo dashboard (in plain text).

If you have entered your credentials correctly, you will receive aย 201 Responseย with your secret keys:

[
    {
      "id": "Your Belvo secretID",
      "password": "Your Belvo secretPassword", // This value is obfuscated.
      "created_at": "2022-01-09T08:45:50.406032Z",
      "last_used": "2022-01-09T08:45:50.406032Z"
    }
]

๐Ÿšง

For security reasons, we only show the secretPassword once after the generation. Make sure you store it securely to be able to retrieve it later.

Using your API keys for Basic Authentication

After you've retrieved your API keys, all following calls to the Belvo Payments API must be done using Basic Authentication.

curl \
-u username:password
https://api.belvo.com/payments/

Where:

  • usernameย is your secretID (in plain text).
  • passwordย is your secretPassword (in plain text).

Register a webhook

Registering a webhook will let you know about any relevant updates that occur during the payment process. To set up a webhook, you need to make a POST request toย Register a new payment webhook with the following information:

{
  "name": "Your webhook name", 
  "url": "Your webhook URL",
  "auth_header": "Authorization",
  "auth_token": "Bearer hv7alD71j0dzXf09iKfg7u" 
}

In the response, weโ€™ll confirm the webhook was created and return the webhook id (you can save this ID for future debugging purposes).

{
  "id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "name": "Your webhook name",
  "url": "Your webhook URL",
  "auth_header": "Authorization",
  "auth_token": "*******",
  "created_at": "2022-02-09T08:45:50.406032Z",
  "created_by": "c232d66c-90cd-4aca-a32d-5c2e7f7799ba"
}

๐Ÿ“˜

Webhooks notifications

Throughout this guide, weโ€™ll let you know when certain webhooks (and their types) are sent to the webhook URL. In this way, you can track the payment lifecycle and know when:

  • a payment link is created is created
  • thereโ€™s a status update in your userโ€™s payment process
  • payments are completed

Check our Webhooks article for more info. ๐Ÿค“

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 inflow payments guide 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 Inflow Payments guide! :money-with-wings: