API Direta (Pix Agendado e Recorrente)

Com a Iniciação de Pagamentos de Open Finance (OFPI) da Belvo, você pode coletar pagamentos agendados 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 agendados ou recorrentes
• os status de pagamento e notificações
• como cancelar pagamentos agendados ou recorrentes

Visão geral do fluxo de dados

Como você pode ver no diagrama abaixo, o fluxo de dados para criar um pagamento agendado ou recorrente envolve:

1. Criar uma intenção de pagamento (contendo as informações necessárias para que o pagamento seja processado na Open Finance Network).
2. Ouvir notificações sobre o pagamento agendado.
3. No dia do pagamento agendado, ouvir o OBJECT_CREATED webhook do recurso de transações.
4. Obter os detalhes da transação quando o pagamento for concluído.

Para mais detalhes sobre as notificações que você pode receber, bem como o ciclo de vida de um pagamento agendado ou recorrente, consulte a Seção de status e notificações de pagamento deste guia.

Criar uma Payment Intent agendada

A Payment Intent contém todas as informações necessárias para registrar e processar o pagamento na Open Finance Network. Para reduzir a fricção para o seu cliente, recomendamos que você crie sua tela de pagamento para que possa enviar todas as informações em apenas uma chamada POST.

Para criar uma Payment Intent Agendada ou Recorrente, você precisará fazer uma solicitação POST Criar uma 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": 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",
      "schedule": {} // veja as seções dedicadas abaixo
    }
  },
  "customer": "4714c93c-0132-4da4-b8fe-659515e1b1b6"
}

Uma vez que você cria 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 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 Payment Intent.

Single

Um single pagamento agendado permite que você configure uma transação única para uma data futura específica. Isso é ideal para pagamentos pontuais onde você precisa garantir que a transação ocorra em um dia específico. Para criar um pagamento agendado único, adicione as seguintes informações à sua solicitação de Payment Intent:

{
  "amount": "1234.12",
  "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
  "description": "Shoe payment - Single",
  "statement_descrption": "Super Shoe Store - Brown Sneakers",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "single": {
          "date": "2024-08-01"
        }
      },
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "confirm": true
}

Diário

Pagamentos agendados Diariamente permitem transações recorrentes todos os dias a partir de uma data especificada. Isso é perfeito para pagamentos frequentes e regulares, como assinaturas diárias ou serviços repetitivos. Para criar um pagamento agendado diário, adicione as seguintes informações à sua solicitação de Payment Intent:

{
  "amount": "1234.12",
  "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
  "description": "Pagamento de sapato - Diário",
  "statement_descrption": "Super Loja de Sapatos - Tênis Marrom",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "daily": {
          "start_date": "2025-04-09",
          "occurrences": 2
        }
      },
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "confirm": true
}

Semanal

Pagamentos agendados Semanalmente permitem que você configure transações recorrentes em um dia específico de cada semana. Isso é útil para serviços semanais ou obrigações recorrentes que ocorrem no mesmo dia da semana. Para criar um pagamento agendado semanalmente, adicione as seguintes informações à sua solicitação de Payment Intent:

{
  "amount": "1234.12",
  "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
  "description": "Pagamento de sapato - Semanal",
  "statement_descrption": "Super Loja de Sapatos - Tênis Marrom",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "weekly": {
          "start_date": "2025-04-09",
          "day_of_week": "MONDAY",
          "occurrences": 2
        }
      },
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "confirm": true
}

Mensal

Pagamentos agendados Mensalmente são projetados para transações que se repetem no mesmo dia de cada mês. Esta configuração é ideal para contas mensais, assinaturas ou qualquer pagamento mensal regular. Para criar um pagamento agendado mensalmente, adicione as seguintes informações à sua solicitação de Payment Intent:

{
  "amount": "1234.12",
  "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
  "description": "Pagamento de sapato - Mensal",
  "statement_descrption": "Super Loja de Sapatos - Tênis Marrons",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "monthly": {
          "start_date": "2025-04-26",
          "day_of_month": 26,
          "occurrences": 12
        }
      },
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "confirm": true
}

Custom

Custom pagamentos agendados oferecem flexibilidade ao permitir que você especifique um array de datas para transações recorrentes. Esta opção é perfeita para agendas irregulares ou planos de pagamento sob medida que não se encaixam em padrões de recorrência padrão. Para criar um pagamento agendado personalizado, adicione as seguintes informações à sua solicitação de Payment Intent:

{
  "amount": "1234.12",
  "customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
  "description": "Shoe payment - Custom Schedule",
  "statement_descrption": "Super Shoe Store - Brown Sneakers",
  "allowed_payment_method_types": ["open_finance"],
  "payment_method_details": {
    "open_finance": {
      "schedule": {
        "custom": {
          "dates": ["2024-06-27", "2024-07-27", "2024-08-26", "2024-09-25", "2024-10-25"]
        }
      },
      "beneficiary_bank_account": "a80d5a9d-20ae-479a-8dd7-ff3443bcbbfc",
      "payer_institution": "600f1b4a-1ef9-4f89-b341-1a35f0c32cc0",
      "callback_url": "https://www.acmecorp.com/checkout/3487321"
    }
  },
  "confirm": true
}

Payment Intents, Charges, and Transactions

Para cada pagamento agendado, 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.

Por exemplo, se você criar um pagamento recorrente que ocorrerá duas vezes, o charges array no Payment Intent incluirá dois Charges. E uma vez que o primeiro Charge é processado, a Belvo gera uma Transaction associada.

Status de Pagamento e Notificações

Uma vez que você agenda um pagamento, você receberá atualizações de webhook para o Payment Intent, Charges e Transactions associados. Abaixo você pode ver um exemplo de um pagamento agendado recorrente e os status associados que cada pagamento passará. Você receberá notificações de webhook STATUS_UPDATE para cada status que está marcado com um ponto vermelho (🔴).

Quando você recebe o evento de webhook OBJECT_CREATED da Transaction, isso indica que o pagamento agendado foi liquidado.

Uma vez que todos os Charges agendados tenham sido concluídos (incluindo aqueles que falham), o status do Payment Intent será definido como SCHEDULE_FINISHED.

Para ver se um Payment Intent tem algum Charge falhado, você pode usar o método List all Charges, filtrando pelo id do Payment Intent:

curl --request GET \
--url 'https://api.belvo.com/payments/br/payment-intents/{payment_intent_id}/charges/' \
--header 'accept: application/json' \
---u [Secret Key ID]:[Secret Key PASSWORD]

Cancelar um pagamento

Cancelando uma cobrança específica

Para cancelar uma cobrança agendada específica, você só precisa fazer uma chamada de API POST Cancelar uma Cobrança Agendada:

curl 
--request POST \
--header 'accept: application/json' \
-u [Secret Key ID]:[Secret Key PASSWORD] \
--url https://api.belvo.com/payments/br/payment-intents/{payment_intent_id}/charges/{charge_id}/cancel/ \

Cancelando uma Payment Intent inteira

Para cancelar uma Payment Intent (e todas as Charges agendadas associadas), você só precisa fazer uma chamada de API POST Cancelar uma Payment Intent:

curl 
--request POST \
--header 'accept: application/json' \
-u [Secret Key ID]:[Secret Key PASSWORD] \
--url https://api.belvo.com/payments/br/payment-intents/{payment_intent_id}/cancel/ \

Após fazer sua solicitação de cancelamento, a Belvo responderá com um 204 - No Content, e notificará você usando um webhook que o status da Payment Intent foi alterado para CANCELED.