# Direct API (Pix Agendado e Pix Agendado 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 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 agendado ou recorrente envolve: 1. Criar uma Payment Intent (contendo as informações necessárias para que o pagamento seja processado na Open Finance Network). 2. Escutar notificações sobre o pagamento agendado. 3. No dia do pagamento agendado, escutar o webhook `OBJECT_CREATED` 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. ```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->>Inst: Payment information sent to institution Belvo-->>App: 201 - Created Note over App,Inst: Institution processes payment and communicates with other institution Belvo-->>App: WEBHOOK STATUS_UPDATE (PAYMENT_INTENTS)
Status: REQUIRES_ACTION Belvo-->>App: WEBHOOK STATUS_UPDATE (PAYMENT_INTENTS)
Status: PROCESSING Belvo-->>App: WEBHOOK STATUS_UPDATE (PAYMENT_INTENTS)
Status: SCHEDULED rect rgba(0, 100, 255, .05) Note over App,Inst: For each scheduled payment, you will receive a Charge webhook Belvo-->>App: WEBHOOK STATUS_UPDATE (CHARGES)
Status: SCHEDULED end rect rgba(0, 200, 100, .05) Note over App,Inst: On the day of a scheduled payment you will receive the following webhooks Belvo-->>App: WEBHOOK STATUS_UPDATE (CHARGES)
Status: SUCCEEDED Belvo-->>App: WEBHOOK OBJECT_CREATED (TRANSACTIONS) App->>Belvo: GET /transactions/{transaction.id}/ Belvo-->>App: 200 + Transaction Details end rect rgba(255, 150, 0, .05) Note over App,Inst: If there are no more scheduled payments, you will receive the following webhook Belvo-->>App: WEBHOOK STATUS_UPDATE (PAYMENT_INTENTS)
Status: SCHEDULE_FINISHED end ``` ## Criar uma Payment Intent agendada A Payment Intent 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 Payment Intent Agendada ou Recorrente, você precisará fazer uma solicitação POST Criar uma 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": 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" } ``` 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": 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": { "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 recomendada). **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 configurado 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. | | `payment_method_details.open_finance` | sim | No objeto `open_finance`, você deve fornecer os seguintes detalhes sobre o pagamento: `beneficiary_bank_account`: O `id` da conta bancária que receberá os fundos do pagamento. `payer_institution`: O `id` da instituição de onde o pagamento é feito. `callback_url`: A URL para a qual seu usuário deve ser redirecionado após aprovar o pagamento em sua instituição bancária. `schedule`: Veja as seções dedicadas abaixo para detalhes sobre cada agendamento que você pode solicitar. `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). | Uma vez que você criar 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 da 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: ```json Single Scheduled Payment { "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 } ``` | Campo | Descrição | Exemplo | | --- | --- | --- | | `date` | A data em que o pagamento deve ocorrer, no formato `YYYY-MM-DD`. A data deve ser pelo menos 1 dia no futuro e não mais que 720 dias no futuro. | `2024-08-01` | ### 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: ```json Daily Recurring Payment { "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 } ``` | Campo | Descrição | Exemplo | | --- | --- | --- | | `start_date` | A data em que os pagamentos recorrentes devem começar, no formato `YYYY-MM-DD`. | `2024-08-01` | | `occurrences` | O número de vezes que este pagamento recorrente deve se repetir. O valor mínimo é `2` e o valor máximo é `60`. | `52` | ### 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: ```json Pagamento Recorrente Semanal { "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 } ``` | Campo | Descrição | Exemplo | | --- | --- | --- | | `start_date` | A data em que os pagamentos recorrentes devem começar, no formato `YYYY-MM-DD`. Atualmente, essa data deve ser a mesma do primeiro `day_of_week` que você fornecer. | `2024-08-01` | | `day_of_week` | O dia da semana em que este pagamento deve ser liquidado. Pode ser um dos seguintes: `MONDAY`, `TUESDAY`, `WEDNESDAY`, `THURSDAY`, `FRIDAY`, `SATURDAY` ou `SUNDAY`. | `MONDAY` | | `occurrences` | O número de vezes que este pagamento recorrente deve se repetir. O valor mínimo é `2` e o valor máximo é `60`. | `52` | ### 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: ```json Pagamento Recorrente Mensal { "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 } ``` | Campo | Descrição | Exemplo | | --- | --- | --- | | `start_date` | A data em que os pagamentos recorrentes devem começar, no formato `YYYY-MM-DD`. Atualmente, esta data deve ser a mesma do primeiro `day_of_month` que você fornecer. | `2024-08-01` | | `day_of_month` | O dia do mês (entre `1` e `31`) em que o pagamento deve ocorrer. **Nota**: Se você escolher um dia que não aparece em todos os meses (por exemplo, `31`), então nos meses em que essa data não ocorrer, o pagamento será feito no dia seguinte. Por exemplo, como junho tem apenas 30 dias, o pagamento será processado em 1º de julho (e depois novamente em 31 de julho). Para evitar cobrar seus usuários duas vezes no mesmo mês, sugerimos que você escolha um dia até o 28º. | `26` | | `occurrences` | O número de vezes que este pagamento recorrente deve se repetir. O valor mínimo é `2` e o valor máximo é `24`. | `12` | ### 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: ```json Custom Recurring Payment { "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 } ``` | Campo | Descrição | Exemplo | | --- | --- | --- | | `dates` | O array de datas em que os pagamentos recorrentes devem ocorrer, no formato `YYYY-MM-DD`. O número mínimo de datas é `2` e o número máximo de datas é `60`. As datas devem ser pelo menos 1 dia no futuro e não mais do que 720 dias no futuro. | `["2024-06-27", "2024-07-27"]` | | `description` | Uma descrição do pagamento recorrente personalizado que será exibida ao seu usuário quando ele for redirecionado para o banco para dar seu consentimento e aceitar o pagamento. **Nota**: Recomendamos fortemente que esta mensagem esteja em português brasileiro e que explique claramente o propósito, bem como a natureza recorrente do pagamento. | `Os pagamentos ocorrerão a cada três dias até a data final (09.07.2024)` | ## 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 que falhou, você pode usar o método List all Charges, filtrando pelo `id` do Payment Intent: ```curl curl --request GET \ --url 'https://api.belvo.com/payments/br/payment-intents/{payment_intent_id}/charges/' \ --header 'accept: application/json' \ ---u SECRET_ID:SECRET_PASSWORD ``` | Campo | Descrição | Exemplo | | --- | --- | --- | | `payment_intent_id` | O `payment-intent.id` para o qual você deseja obter os Charges. | `65492eeb-344c-49fe-8dab-11da1be67d7a` | ## 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 Cancelar Cobrança Singular curl --request POST \ --header 'accept: application/json' \ -u SECRET_ID:SECRET_PASSWORD \ --url https://api.belvo.com/payments/br/payment-intents/{payment_intent_id}/charges/{charge_id}/cancel/ \ ``` | Campo | Descrição | Exemplo | | --- | --- | --- | | `payment_intent_id` | O `payment-intent.id` agendado ao qual a cobrança pertence. | `65492eeb-344c-49fe-8dab-11da1be67d7a` | | `charge_id` | O `charge.id` agendado que você deseja cancelar. | `414c6387-2d46-45cc-84a8-e1d175aebe53` | O mais tardar que você pode cancelar uma Cobrança agendada é até 23:59:00 (GMT-3) do dia anterior à data de pagamento agendada. Se você perder o prazo, receberá um erro de API da Belvo e o pagamento será processado. ### Cancelando uma Payment Intent inteira Para cancelar uma Payment Intent (e todos os Charges agendados associados), você só precisa fazer uma chamada de API POST Cancelar uma Payment Intent: ```curl Cancelar Payment Intent Inteira curl --request POST \ --header 'accept: application/json' \ -u SECRET_ID:SECRET_PASSWORD \ --url https://api.belvo.com/payments/br/payment-intents/{payment_intent_id}/cancel/ \ ``` | Campo | Descrição | Exemplo | | --- | --- | --- | | `id` | O `payment-intent.id` que você deseja cancelar. | `65492eeb-344c-49fe-8dab-11da1be67d7a` | 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`. O mais tardar que você pode cancelar uma Payment Intent agendada é até 23:59:00 (GMT-3) do dia anterior à data de pagamento agendada. Se você perder o prazo, receberá um erro de API da Belvo e o pagamento será processado.