# API Direta (Pix via Open Finance)

Com a Iniciação de Pagamentos de Open Finance (OFPI) da Belvo, você pode coletar pagamentos de seus clientes e otimizar a experiência de pagamento deles. Neste guia, mostraremos:

- o fluxo geral de dados
- como criar uma intenção de pagamento para coletar pagamentos
- acompanhar o status de suas solicitações de pagamento


Pré-requisitos
Por favor, certifique-se de ter concluído todas as etapas em nosso artigo dedicado de pré-requisitos antes de continuar este guia.

## Visão geral do fluxo de dados

Como você pode ver no diagrama abaixo, o fluxo de dados para criar um pagamento usando Pix via Open Finance envolve:

1. Criar uma intenção de pagamento (contendo as informações necessárias para que o pagamento seja processado na Rede Open Finance).
2. Aguardar o `OBJECT_CREATED` webhook do recurso de transações.
3. Obter os detalhes da transação.


## Criar uma Intenção de Pagamento

A Intenção de Pagamento contém todas as informações necessárias para registrar e processar o pagamento na Rede de Open Finance. Para reduzir a fricção para o seu cliente, recomendamos que você crie sua tela de pagamento de forma que possa enviar todas as informações em apenas uma chamada POST.

Para criar uma Intenção de Pagamento, você precisará fazer uma solicitação POST Criar uma Intenção de Pagamento com o seguinte payload:

Com um cliente previamente criado

```json Com cliente previamente criado
{
  "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": true,
  "payment_method_details": {
    "open_finance": {
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "customer": "4714c93c-0132-4da4-b8fe-659515e1b1b6"
}
```

Com um novo cliente

```json Com novo cliente
{
  "amount": "1234.12",
  "description": "B23A-Shoe-Brown-Sneaker",
  "statement_description": "Super Shoe Store - Brown Sneakers",
  "allowed_payment_method_types": ["open_finance"],
  "confirm": true,
  "payment_method_details": {
    "open_finance": {
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
      "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"
  },
}
```

| Parâmetro  | Obrigatório | Descrição |
|  --- | --- | --- |
| `amount` | sim | O valor do pagamento como uma string. |
| `description` | sim | A descrição do pagamento para seus propósitos internos. |
| `statement_description` | opcional (mas recomendado) | A descrição que aparecerá no extrato bancário do cliente (altamente recomendado). **Nota**: Se você não usar o parâmetro `statement_description`, o valor de `description` será usado como a descrição do extrato. |
| `allowed_payment_method_types` | sim | O parâmetro `allowed_payment_method_types` indica qual método de pagamento deve ser usado. Para pagamentos no Brasil, isso deve ser configurado como `["open_finance"]`. |
| `external_id` | opcional (mas recomendado) | Um identificador único adicional (UUID) para o recurso para fins internos. Isso pode ser útil para rastrear o recurso em seu sistema e para fins de depuração. |
| `confirm` | sim | Indica que o pagamento está pronto para processamento. |
| `payment_method_details.open_finance` | sim | No objeto `open_finance`, você deve fornecer os seguintes detalhes sobre o pagamento: `beneficiary_bank_account`: O `id` da conta bancária que receberá os fundos do pagamento. `payer_institution`: O `id` da instituição de onde o pagamento é feito. `callback_url`: A URL para a qual seu usuário deve ser redirecionado após aprovar o pagamento em sua instituição bancária. `cpf`: (Apenas quando o cliente é uma empresa) O CPF do usuário que está fazendo o pagamento. |
| `customer` | sim | O `id` do cliente previamente criado que fará o pagamento. Opcionalmente, você também pode criar o cliente ao mesmo tempo (veja o exemplo de código). |


Uma vez que você crie com sucesso uma Intenção de Pagamento, você precisará usar a URL no parâmetro `payment_method_information.open_finance.redirect_url` para redirecionar seu usuário para sua instituição financeira para confirmar o pagamento. Após confirmar o pagamento, seu usuário é redirecionado de volta para o `callback_url` que você forneceu na solicitação de Intenção de Pagamento.

## Payment Intents, Charges, and Transactions

Para cada pagamento, a Belvo gera um objeto **Charge** dentro do corpo de resposta do Payment Intent. Uma vez que um Charge é processado com sucesso, a Belvo gera uma **Transaction** associada a esse Charge.

## Status de pagamentos e notificações

Assim que você criar um pagamento imediato, você receberá atualizações de webhook para o Payment Intent, Charge e Transaction associados.

Abaixo você pode ver um exemplo de um pagamento imediato e os status associados pelos quais o pagamento passará. Você receberá notificações de webhook `STATUS_UPDATE` para cada status que está marcado com um ponto vermelho (🔴).

Quando você receber o evento de webhook `OBJECT_CREATED` da Transaction, isso indica que o pagamento foi liquidado.

## Ouça as atualizações de status de pagamento

Uma vez que você cria a Payment Intent, a Belvo fornecerá atualizações sobre o pagamento via webhooks. Como você pode ver na imagem na seção *Visão geral do fluxo de dados*, você receberá os seguintes webhooks durante o processo de pagamento:

| Evento | Recurso | Descrição |
|  --- | --- | --- |
| `STATUS_UPDATE` | Payment Intents | Os eventos `STATUS_UPDATE` para Payment Intents indicam a etapa do processo de pagamento Pix via Open Finance. Você receberá as seguintes atualizações de status: `REQUIRES_ACTION`, `PROCESSING` e `SUCCEEDED`.    > **Nota**: Além de responder ao evento com um `200 OK`, nenhuma ação adicional é necessária. |
| `STATUS_UPDATE` | Charges | Os eventos `STATUS_UPDATE` para Charges indicam a etapa do processo de pagamento Pix via Open Finance. Você receberá as seguintes atualizações de status: `SUCCEEDED`.    > **Nota**: Além de responder ao evento com um `200 OK`, nenhuma ação adicional é necessária. |
| `OBJECT_CREATED` | Transactions | O evento `OBJECT_CREATED` para Transactions indica que os fundos do pagamento foram transferidos de uma conta para outra.    > **Nota**: Além de responder ao evento com um `200 OK`, recomendamos que você também faça uma solicitação de Obter Detalhes da Transação para obter as informações da transação. |


## Obter detalhes para transações bem-sucedidas.

O `webhook` `OBJECT_CREATED` do recurso de Transações indica que o **pagamento foi bem-sucedido e os fundos foram transferidos** de uma conta para outra. Isso significa que toda vez que o dinheiro for transferido com sucesso para sua conta, você receberá a seguinte notificação:


```json Exemplo de webhook Transaction OBJECT_CREATED
{
  "webhook_id": "3b9a69f7-0f0a-455b-832d-49ad6fd4905c",
  "webhook_type": "TRANSACTIONS",
  "webhook_code": "OBJECT_CREATED",
  "object_id": "d2e40773-19f6-48d1-93c3-3590ec0c74df",
  "data": {}, //Para webhooks OBJECT_CREATED, o campo data retorna um objeto vazio.
}
```

Você pode obter os detalhes sobre a transação fazendo uma chamada GET details usando o `object_id` da transação (que você recebe no evento do webhook).


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

| Parâmetro | Tipo | Descrição | Exemplo |
|  --- | --- | --- | --- |
| `id` | string  (uuid) | O `transaction.id` sobre o qual você deseja obter informações detalhadas. Você pode recuperar este ID do campo `object_id` que você recebeu no webhook de transações `OBJECT_CREATED`. | a3b92311-1888-449f-acaa-49ae28d68fcd |


Você receberá as seguintes informações sobre a transação:


```json Payload de Resposta de Transações
{
  "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"
}
```

E é isso! Seguindo este guia, você pode fazer pagamentos usando o Pix da Belvo via produto Open Finance.