# API Direta (Pix Agendado)
Com a Iniciação de Pagamentos do 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 Payment Intent para coletar pagamentos agendados (um único pagamento ou uma série)
- os status de pagamento e notificações
- como cancelar pagamentos agendados
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 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 relacionadas ao 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, 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 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, você precisará fazer uma solicitação POST Create a 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` | true | O valor do pagamento como uma string. |
| `description` | true | 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` | true | 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` | true | Indica que o pagamento está pronto para processamento. |
| `payment_method_details.open_finance` | true | 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á realizando o pagamento. |
| `customer` | true | 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 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:
```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** se repetem 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 Scheduled 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 agendados devem começar, no formato `YYYY-MM-DD`. | `2024-08-01` |
| `occurrences` | O número de vezes que este pagamento deve se repetir. O valor mínimo é `2` e o valor máximo é `60`. | `52` |
### Semanal
Pagamentos agendados **semanalmente** se repetem em um dia específico de cada semana. Isso é útil para serviços semanais ou obrigações regulares 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 Agendado 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 agendados devem começar, no formato `YYYY-MM-DD`. Atualmente, essa data deve ser a mesma que o 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 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 Agendado Mensal
{
"amount": "1234.12",
"customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
"description": "Pagamento de sapato - Mensal",
"statement_descrption": "Super Loja de Sapatos - Tênis Marrom",
"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 agendados 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 ocorre, 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 deve se repetir. O valor mínimo é `2` e o valor máximo é `24`. | `12` |
### Customizado
Pagamentos agendados **customizados** oferecem flexibilidade ao permitir que você especifique um array de datas para seus pagamentos. Esta opção é perfeita para cronogramas irregulares ou planos de pagamento sob medida que não se encaixam em cronogramas padrão. Para criar um pagamento agendado customizado, adicione as seguintes informações à sua solicitação de Payment Intent:
```json Custom Scheduled Payment
{
"amount": "1234.12",
"customer": "06dc2f14-1217-4480-9b36-550a944a39d1",
"description": "Pagamento de sapato - Cronograma Customizado",
"statement_descrption": "Super Loja de Sapatos - Tênis Marrom",
"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 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 que 720 dias no futuro. | `["2024-06-27", "2024-07-27"]` |
| `description` | Uma descrição do pagamento agendado customizado 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)` |
## Intenções de Pagamento, Cobranças e Transações
Para cada pagamento agendado, a Belvo gera um objeto **Charge** dentro do corpo de resposta da Payment Intent. Uma vez que uma Charge é processada com sucesso, a Belvo gera uma **Transaction** associada a essa Charge.
Por exemplo, se você criar um pagamento agendado que ocorrerá duas vezes, o array `charges` na Payment Intent incluirá **duas** Charges. E assim que a primeira Charge for processada, a Belvo gera uma Transaction associada.
## Status de Pagamentos 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 que se repete 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` para uma Transaction, isso indica que o pagamento agendado foi liquidado.
Uma vez que todas as Charges agendadas tenham sido concluídas (incluindo aquelas que falham), o status do Payment Intent será definido como `SCHEDULE_FINISHED`.
Para verificar se um Payment Intent possui alguma 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 as 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.