# Direct API (Pix Key Beneficiary) Guide

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 Payment Intent to collect payments
- 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 Payment Intent (containing the required information for the payment to be processed in the Open Finance Network).
2. Requesting your user to confirm the Pix details.
3. Confirming the Payment Intent to initiate the payment.
4. Redirecting the Payer to their banking institution to approve the payment.
5. Listening for the `SUCCEEDED` webhooks from the Payment Intents and Charges resources.


## Create a Payment Intent

The Payment Intent contains all the information necessary to register and process the payment in the Open Finance Network. When using Pix Keys as the beneficiary, you will need to perform two API calls to complete the payment process: first, create the Payment Intent, and then confirm it.

To create a Payment Intent, you will need to make a POST Create a Payment Intent request with the following payload:

With a previously created customer

```json With previously created customer
{
  "amount": "1234.12",
  "description": "B23A-Shoe-Brown-Sneaker",
  "statement_description": "Super Shoe Store - Brown Sneakers",
  "allowed_payment_method_types": ["open_finance"],
  "external_id": "2c75c041-9cc7-430a-84e9-3b234aae76a2",
  "confirm": false,
  "payment_method_details": {
    "open_finance": {
      "pix_key": "chosen-pix-key",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "customer": "4714c93c-0132-4da4-b8fe-659515e1b1b6"
}
```

With a new customer

```json With new customer
{
  "amount": "1234.12",
  "description": "B23A-Shoe-Brown-Sneaker",
  "statement_description": "Super Shoe Store - Brown Sneakers",
  "allowed_payment_method_types": ["open_finance"],
  "confirm": false,
  "payment_method_details": {
    "open_finance": {
      "pix_key": "chosen-pix-key",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "customer": {
    "identifier": "10187609363",
    "name": "Caetano Veloso",
    "email": "caetano.veloso@musicabrazil.br",
    "phone": "+5511987654321",
    "address": "Rua de Caetano Veloso 432, 70200 Brasilia"
  }
}
```

| Parameter  | Required | Description |
|  --- | --- | --- |
| `amount` | true | The amount of the payment as a string. |
| `description` | true | The description of the payment for your internal purposes. |
| `statement_description` | optional (but recommended) | The description that will appear on the customer's bank statement (highly recommended). **Note**: If you do not use the `statement_description` parameter, the `description` value will be used as the statement description. |
| `allowed_payment_method_types` | true | The `allowed_payment_method_types` parameter indicates which payment method should be used. For payments in Brazil, this must be set to `["open_finance"]`. |
| `external_id` | optional (but recommended) | An additional unique identifier (UUID) for the resource for internal purposes. This can be useful for tracking the resource in your system and for debugging purposes. |
| `confirm` | true | Indicates that the payment is ready for processing. For the initial Payment Intent creation, this must be set to `false`. You will confirm the payment in a separate step. |
| `payment_method_details.open_finance` | true | In the `open_finance` object, you have to provide the following details about the payment:- `pix_key`: The Pix Key associated with the bank account that will receive the payment funds. This can be a CPF, CNPJ, email, phone number (including the country code "+55123124234234"), or a random key.
- `payer_institution`: The `id` of the institution from where the payment is made.
- `callback_url`: The URL that your user should be redirected to after approving the payment in their banking institution.
- `cpf`: (Only when the customer is a business) The CPF of the user that is making the payment.

 |
| `customer` | true | The `id` of the previously created customer that will make the payment. Optionally, you can also create the customer at the same time (see the code example). |


In the response of the Payment Intent, you will receive the following highlighted fields. You need to display them in your application to the user so that they can confirm that this is the correct payment information. After they confirm the details, you will need to confirm the Payment Intent in the next step.


```json Payment Intent Initial Response
{
  "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
  "customer": "1c83ead8-6665-429c-a17a-ddc76cb3a95e",
  "external_id": "4b8a81a0-e33c-45a6-8567-479efb105f73",
  "created_at": "2022-02-09T08:45:50.406032Z",
  "created_by": "bcef7f35-67f2-4b19-b009-cb38795faf09",
  "updated_at": "2022-02-09T08:45:50.406032Z",
  "status": "REQUIRES_PAYMENT_METHOD",
  "amount": "1234.12",
  "currency": "BRL",
  "description": "Training shoes",
  "statement_description": "Super Shoe Store - Brown Sneakers",
  "selected_payment_method_type": "open_finance",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "pix_key": "53497b80-81a2-4ea8-9296-83a909c05bdf",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "payment_method_information": {
    "open_finance": {
      "pix_key_details": { // [!code highlight]
        "identifier": "23******00", // [!code highlight]
        "name": "João da Silva" // [!code highlight]
      }
    }
  }
}
```

Pix Key Masking
In the case that the provided Pix Key is a CPF, email address, or phone number, value in `payment_method_details.open_finance.pix_key` will be masked. If it is a CNPJ or random Pix Key UUID, the value will not be masked.

## Confirm the Payment Intent

To confirm the Payment Intent, you will need to make a POST Complete a Payment Intent request with the following payload:


```json Confirm Payment Intent
{
  "confirm": true
}
```

Once you successfully completed 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.


```json Payment Intent Confirmed Response
{
  "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
  "customer": "1c83ead8-6665-429c-a17a-ddc76cb3a95e",
  "external_id": "4b8a81a0-e33c-45a6-8567-479efb105f73",
  "created_at": "2022-02-09T08:45:50.406032Z",
  "created_by": "bcef7f35-67f2-4b19-b009-cb38795faf09",
  "updated_at": "2022-02-09T08:45:50.406032Z",
  "status": "REQUIRES_ACTION",
  "amount": "1234.12",
  "currency": "BRL",
  "description": "Training shoes",
  "statement_description": "Super Shoe Store - Brown Sneakers",
  "selected_payment_method_type": "open_finance",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "pix_key": "53497b80-81a2-4ea8-9296-83a909c05bdf",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "payment_method_information": {
    "open_finance": {
      "provider_request_id": "978c0c97ea847e78e8849634473c1f1",
      "redirect_url": "https://wakandanational.com/", // [!code highlight]
      "end_to_end_id": "F203262942022211117487a213b1d140",
      "settlement_date": "2024-10-22",
      "pix_key_details": {
        "identifier": "23******00",
        "name": "João da Silva"
      }
    }
  }
}
```

## Payment statuses and notifications

For each confirmed Payment Intent, Belvo generates a **Charge** object within the Payment Intent response body.

You will receive webhook notifications for both the Payment Intent and the associated Charge as the payment goes through different statuses.

Below you can see an example of a payment and the associated statuses the 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 `SUCCEEDED` Payment Intent and Charge webhook events, this indicates that the given payment was settled.

## Listen for payment status updates

Once you create the Payment Intent, 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:

| Event | Resource | Description |
|  --- | --- | --- |
| `STATUS_UPDATE` | Payment Intents | The `STATUS_UPDATE` events for Payment Intents indicate the stage of the Pix via Open Finance payment process. You will receive the following status updates: `REQUIRES_ACTION`, `PROCESSING`, and `SUCCEEDED`.    > **Note**: Apart from responding to the event with a `200 OK`, no further action is required. |
| `STATUS_UPDATE` | Charges | The `STATUS_UPDATE` events for Charges indicates the stage of the Pix via Open Finance payment process. You will receive the following status updates:  `SUCCEEDED`.    > **Note**: Apart from responding to the event with a `200 OK`, no further action is required. |