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
Por favor, certifique-se de ter concluído todas as etapas em nosso artigo dedicado de pré-requisitos antes de continuar este guia.
Como você pode ver no diagrama abaixo, o fluxo de dados para criar um pagamento usando Pix via Open Finance envolve:
- Criar uma Payment Intent (contendo as informações necessárias para que o pagamento seja processado na Rede Open Finance).
- Solicitar ao seu usuário que confirme os detalhes do Pix.
- Confirmar a Payment Intent para iniciar o pagamento.
- Redirecionar o Pagador para sua instituição bancária para aprovar o pagamento.
- Aguardar os webhooks
SUCCEEDEDdos recursos Payment Intents e Charges.
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:
{
"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"
}| 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:
|
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.
{
"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": {
"identifier": "23******00",
"name": "João da Silva"
}
}
}
}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.
Para confirmar a Payment Intent, você precisará fazer uma solicitação POST Complete a Payment Intent com o seguinte payload:
{
"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.
{
"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/",
"end_to_end_id": "F203262942022211117487a213b1d140",
"settlement_date": "2024-10-22",
"pix_key_details": {
"identifier": "23******00",
"name": "João da Silva"
}
}
}
}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.
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. |