# 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. Escutar os webhooks `SUCCEEDED` dos recursos Payment Intents e Charges.
```mermaid
sequenceDiagram
autonumber
participant App as Application
participant Belvo as Belvo
participant Inst as Payment Institution
App->>Belvo: POST /payment-intents/
Note over App,Belvo: Body: Payment Intent Details
Belvo-->>App: 201 - Created
Note over App,Belvo: Payment Intent ID + Pix Key Details
Belvo-->>App: WEBHOOK STATUS_UPDATE (PAYMENT_INTENTS)
Status: REQUIRES_PAYMENT_METHOD
Note over App,Belvo: Your user confirms their Pix Key details in your application
App->>Belvo: PATCH /payment-intents/
Note over App,Belvo: Body: Confirm = True
Belvo-->>App: 200 - OK
Note over App,Belvo: Payment Intent ID + Redirect URL
Belvo->>Inst: Payment information sent to institution
Belvo-->>App: WEBHOOK STATUS_UPDATE (PAYMENT_INTENTS)
Status: REQUIRES_ACTION
Note over App,Inst: Redirect the payer to the URL provided to complete the payment. Once completed, they are redirected back to your application
Note over App,Inst: Institution processes payment and communicates with other institution
Belvo-->>App: WEBHOOK STATUS_UPDATE (PAYMENT_INTENTS)
Status: PROCESSING
Belvo-->>App: WEBHOOK STATUS_UPDATE (PAYMENT_INTENTS)
Status: SUCCEEDED
Belvo-->>App: WEBHOOK STATUS_UPDATE (CHARGES)
Status: SUCCEEDED
```
## 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ê tenha completado com sucesso uma Payment Intent, será necessário 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 será redirecionado de volta para o `callback_url` que você forneceu na solicitação de Payment Intent.
Validade e sensibilidade da URL de redirecionamento
A `redirect_url` da payment intent é **válida por até 5 minutos**. Além disso, devido às medidas de segurança implementadas pelas instituições bancárias, a URL de redirecionamento é altamente sensível e pode ser invalidada nos seguintes cenários:
- Sendo carregada dentro de um **WebView**
- Sendo carregada dentro de um **iframe**
- Se uma **consulta DNS** ocorrer antes do usuário ser redirecionado
Para evitar falhas no pagamento, certifique-se de que a URL de redirecionamento seja aberta diretamente no navegador padrão do usuário imediatamente após recebê-la. Não pré-carregue, armazene em cache ou resolva a URL antes do redirecionamento real.
```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": "Tênis de treino",
"statement_description": "Super Shoe Store - Tênis Marrom",
"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 o 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`, `SUCCEEDED` e `FAILED` (por exemplo, quando a Chave Pix do beneficiário é inválida: `failure_code` `invalid_pix_key`, `failure_message` `The provided Pix Key is invalid.`). Para exemplos de payload de webhook, veja Webhooks de Pagamentos (Brasil). > **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. |