With Belvo's Open Finance Payment Initiation (OFPI), you can collect 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 Customer to request fund from
• how to create a Payment Lntent to send to your user
• track the status of your payment requests

📘

Prerequisites

Please make sure you have completed all the steps in our dedicated prerequisites article before continuing this guide.

Data flow overview

As you can see in the diagram below, the data flow for creating a payment using Pix via Open Finance involves:

1. Creating a Customer for your user
2. Creating a Payment Link (containing the base information for the payment to be processed in the Open Finance Network).
3. Sending your user the Payment Link URL to process the payment.
4. Listening for the OBJECT_CREATED webhook from the transactions resource.
5. Getting the transaction details.

Create a Customer

To create a customer, you need to make a [POST] Create a new customer request:

📘

For each user that you want to collect funds from, you need to create a Customer. However, when requesting subsequent payments, you just need to use the id of the Customer you created.

{
  "identifier": "10187609363",
  "name": "Gustavo Veloso",
  "external_id": "2c75c041-9cc7-430a-84e9-3b234aae76a2",
  "email": "Gustavo.veloso@musicabrazil.br",
  "phone": "+5511987654321",
  "address": "Rua de Caetano Veloso 432, 70200 Brasilia"
}

You’ll receive the following response from our API, confirming that the customer was created. Make sure to save the id you receive, as this ID is required when creating a payment link 🤓.

{
  "id": "49f244ef-06cd-49cf-ad0c-f43796e370ad",
  "created_at": "2020-04-23T21:30:20.336854+00:00",
  "created_by": "1c83ead8-6665-429c-a17a-ddc76cb3a95e",
  "customer_type": "INDIVIDUAL",
  "name": "Caetano Veloso",
  "country": "BRA",
  "email": "caetano.veloso@musicabrazil.br",
  "identifier": "23******00",
  "identifier_type": "CPF",
}

{
  "id": "49f244ef-06cd-49cf-ad0c-f43796e370ad",
  "created_at": "2020-04-23T21:30:20.336854+00:00",
  "created_by": "1c83ead8-6665-429c-a17a-ddc76cb3a95e",
  "customer_type": "BUSINESS",
  "name": "Music Production Brazil",
  "country": "BRA",
  "email": "finance@musicabrazil.br",
  "identifier": "12300399900",
  "identifier_type": "CNPJ",
}

Create a Payment Link

To create a Payment Link, you need to make a [POST] Create a payment link request.

{
  "amount": "1234.12",
  "description": "B23A-Shoe-Brown-Sneaker",
  "statement_description": "Super Shoe Store - Brown Sneakers",
  "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
    }
  },
  "callback_urls": {
    "cancel": "https://www.acmecorp.com/checkout/3487548/cancel",
    "success": "https://www.acmecorp.com/checkout/3487548/success"
  },
  "expires_in": "7d"
}

Once you successfully create a Payment Link, you will need to send your user to the URL in the payment_url parameter. After confirming the payment, your user is redirected back to the callback_urls.success you provided in the Payment Intent request.

Payment Link process

You need to share the payment_url with your user so they can start Belvo’s Payment Link Widget. The widget will guide your user through the payment flow. When the Payment Link Widget starts up, your user will be:

1. Asked to select their institution
2. Asked to confirm the payment information
3. Redirected to their institution to complete the payment process in their bank.

📘

To help you keep track of your user’s process within the Payment Link widget, Belvo sends payment intent status update webhook events. In the diagrams below we annotate which payment intent status event will be sent at which step of the process.

Once your user confirms the payment in their institution, they are be redirected back to the Payment Link Widget and will see a Processing state while Belvo confirms the payment. Depending on the outcome from their institution, your user will either see a Payment Confirmed or a Payment Failed screen in the widget.

🚧

At the moment, the widget will display a generic error message. But we’re currently working on improving your experience and will be back soon with more in-depth explanations of all possible errors that can be displayed to the user. 😉

Listen for payment status updates

Once you create the Payment Link, Belvo will provide you updates regarding the payment via webhooks. As you can see in the image in the Data flow overview section, you will receive the following webhooks during the payment process:

Get details for successful transactions.

The OBJECT_CREATED webhook from the Transactions resource that indicates that the payment succeeded and funds were transferred from one account to another. This means that every time money has been successfully transferred to your account, you’ll receive the following notification:

{
  "webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "OBJECT_CREATED",
  "object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
  "data": {}, //For OBJECT_CREATED webhooks, the data field returns an empty object.
}

You can get the details about the transaction by making a GET details call using the object_id of the transaction (which you receive in the webhook event).

curl --request GET \
     --url https://api.belvo.com/payments/br/transactions/{id}/ \
     --header 'accept: application/json'

You will receive the following information regarding the transaction:

{
  "id": "fd0f3303-cafb-47ea-9753-21155cb144ab",
  "created_at": "2020-04-23T21:30:20.336854+00:00",
  "created_by": "1c83ead8-6665-429c-a17a-ddc76cb3a95e",
  "amount": "500",
  "currency": "BRA",
  "description": "Awesome training Sneaker",
  "transaction_type": "INFLOW",
  "beneficiary": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
  "payer": {},
  "payment_intent": "1c83ead8-6665-429c-a17a-ddc76cb3a95e",
  "customer": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

👍

And that's it! By following this guide you can make payments using Belvo's Payment Links.