Payment Links (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 um Customer para solicitar fundos
• como criar um Payment Intent para enviar ao seu usuário
• 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 um Customer para o seu usuário
2. Criar um Payment Link (contendo as informações básicas para o pagamento ser processado na Open Finance Network).
3. Enviar ao seu usuário a URL do Payment Link para processar o pagamento.
4. Escutar o OBJECT_CREATED webhook do recurso de transações.
5. Obter os detalhes da transação.

Criar um Cliente

Para cada usuário do qual você deseja coletar fundos, você precisa criar um Cliente ([POST] Criar um novo cliente). No entanto, ao solicitar pagamentos subsequentes, você só precisa usar o id do Cliente que você criou.

{
  "identifier": "10187609363",
  "name": "Gustavo Veloso",
  "external_id": "2c75c041-9cc7-430a-84e9-3b234aae76a2",
  "email": "Gustavo.veloso@musicabrazil.br",
  "phone": "+5511987654321",
  "address": "Rua de Caetano Veloso 432, 70200 Brasilia"
}

Você receberá a seguinte resposta da nossa API, confirmando que o cliente foi criado. Certifique-se de salvar o id que você recebe, pois este ID é necessário ao criar um link de pagamento 🤓.

{
  "id": "49f244ef-06cd-49cf-ad0c-f43796e370ad",
  "created_at": "2020-04-23T21:30:20.336854+00:00",
  "created_by": "1c83ead8-6665-429c-a17a-ddc76cb3a95e",
  "customer_type": "INDIVIDUAL",
  "name": "Caetano Veloso",
  "country": "BRA",
  "email": "caetano.veloso@musicabrazil.br",
  "identifier": "23******00",
  "identifier_type": "CPF",
}

Criar um Link de Pagamento

Para criar um Link de Pagamento, você precisa fazer uma solicitação [POST] Create a payment link.

{
  "amount": "1234.12",
  "description": "B23A-Shoe-Brown-Sneaker",
  "statement_description": "Super Shoe Store - Brown Sneakers",
  "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
    }
  },
  "callback_urls": {
    "cancel": "https://www.acmecorp.com/checkout/3487548/cancel",
    "success": "https://www.acmecorp.com/checkout/3487548/success"
  },
  "expires_in": "7d"
}

Uma vez que você cria com sucesso um Link de Pagamento, você precisará enviar seu usuário para a URL no parâmetro payment_url. Após confirmar o pagamento, seu usuário é redirecionado de volta para o callback_urls.success que você forneceu na solicitação do Link de Pagamento.

Processo de Link de Pagamento

Você precisa compartilhar o payment_url com seu usuário para que ele possa iniciar o Hosted Widget de Link de Pagamento da Belvo. O widget guiará seu usuário através do fluxo de pagamento. Quando o Hosted Widget de Link de Pagamento for iniciado, seu usuário será:

1. Solicitado a selecionar sua instituição
2. Solicitado a confirmar as informações de pagamento
3. Redirecionado para sua instituição para completar o processo de pagamento em seu banco.

Para ajudar você a acompanhar o processo do seu usuário dentro do Hosted Widget de Link de Pagamento, a Belvo envia eventos de webhook de atualização de status de intenção de pagamento. Nos diagramas abaixo, anotamos qual evento de status de intenção de pagamento será enviado em cada etapa do processo.

Assim que seu usuário confirmar o pagamento em sua instituição, ele será redirecionado de volta para o Hosted Widget de Link de Pagamento e verá um estado de Processamento enquanto a Belvo confirma o pagamento. Dependendo do resultado de sua instituição, seu usuário verá uma tela de Pagamento Confirmado ou Pagamento Falhou no widget.

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

Uma vez que você cria o Payment Link, 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"
}