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

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:

{
  "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"
}

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:

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:

{
  "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 --request GET \
     --url https://api.belvo.com/payments/br/transactions/{id}/ \
     --header 'accept: application/json'

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

{
  "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"
}