# Guia da API Direta (Beneficiário Chave Pix)

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 Payment Intent 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 Payment Intent (contendo as informações necessárias para que o pagamento seja processado na Rede Open Finance).
2. Solicitar ao seu usuário que confirme os detalhes do Pix.
3. Confirmar a Payment Intent para iniciar o pagamento.
4. Redirecionar o Pagador para sua instituição bancária para aprovar o pagamento.
5. Aguardar os webhooks `SUCCEEDED` dos recursos Payment Intents e Charges.


## Criar uma Payment Intent

A Payment Intent contém todas as informações necessárias para registrar e processar o pagamento na Rede de Open Finance. Ao usar Chaves Pix como beneficiário, você precisará realizar duas chamadas de API para completar o processo de pagamento: primeiro, criar a Payment Intent e, em seguida, confirmá-la.

Para criar uma Payment Intent, você precisará fazer uma solicitação POST Create a Payment Intent 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": 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"
}
```

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": 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"
  }
}
```

| 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 definido 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. Para a criação inicial da Payment Intent, isso deve ser definido como `false`. Você confirmará o pagamento em uma etapa separada. |
| `payment_method_details.open_finance` | sim | No objeto `open_finance`, você deve fornecer os seguintes detalhes sobre o pagamento:- `pix_key`: A Chave Pix associada à conta bancária que receberá os fundos do pagamento. Isso pode ser um CPF, CNPJ, email, número de telefone (incluindo o código do país "+55123124234234") ou uma chave aleatória.
- `payer_institution`: O `id` da instituição de onde o pagamento é feito.
- `callback_url`: A URL para a qual o 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). |


Na resposta da Payment Intent, você receberá os seguintes campos destacados. Você precisa exibi-los em sua aplicação para o usuário para que ele possa confirmar que estas são as informações corretas do pagamento. Após confirmar os detalhes, você precisará confirmar a Payment Intent na próxima etapa.


```json Resposta Inicial da Payment Intent
{
  "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]
      }
    }
  }
}
```

Mascaramento de Chave Pix
No caso de a Chave Pix fornecida ser um CPF, endereço de email ou número de telefone, o valor em `payment_method_details.open_finance.pix_key` será mascarado. Se for um CNPJ ou UUID de Chave Pix aleatória, o valor não será mascarado.

## Confirmar a Payment Intent

Para confirmar a Payment Intent, você precisará fazer uma solicitação POST Complete a Payment Intent com o seguinte payload:


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

Uma vez que você completou com sucesso uma Payment Intent, você precisará usar a URL no parâmetro `payment_method_information.open_finance.redirect_url` para redirecionar seu usuário para a instituição financeira dele 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 Payment Intent.


```json Resposta de Payment Intent Confirmada
{
  "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"
      }
    }
  }
}
```

## Status de pagamentos e notificações

Para cada Payment Intent confirmado, a Belvo gera um objeto **Charge** dentro do corpo de resposta do Payment Intent.

Você receberá notificações de webhook tanto para o Payment Intent quanto para o Charge associado à medida que o pagamento passa por diferentes status.

Abaixo você pode ver um exemplo de um pagamento 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 os eventos de webhook `SUCCEEDED` do Payment Intent e Charge, 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 o estágio 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 o estágio 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. |