Introdução

Pix Automático da Belvo é um método de pagamento recorrente estabelecido pelo Banco Central do Brasil que simplifica como as transferências recorrentes via Pix são iniciadas, permitindo que sejam processadas automaticamente após uma autorização única do usuário final (pagador).

Uma vez autorizado, o comerciante pode iniciar pagamentos recorrentes subsequentes sem exigir aprovação individual para cada transação. Esses pagamentos recorrentes podem ser configurados para valores fixos ou variáveis, dependendo da lógica de negócios específica.

Neste guia, você aprenderá:

1. Os pré-requisitos que você precisa completar antes de qualquer outra coisa.
2. Como configurar uma Autorização de Pagamento
3. Como solicitar pagamento de seus clientes (Cobranças)

Pré-requisitos

Certifique-se de ter concluído todas as etapas em nosso artigo dedicado de pré-requisitos antes de continuar este guia. O guia irá orientá-lo sobre como:

• Configurar webhooks (necessário, pois nossas soluções de pagamento utilizam webhooks para informá-lo sobre o progresso de seus pagamentos, quaisquer erros que ocorram e quando um pagamento é concluído com sucesso).
• Criar uma conta bancária de beneficiário (necessário para receber fundos de pagamento).
• Configurar uma URL de retorno (callback) (necessário, pois após o usuário autorizar o pagamento, ele precisa ser redirecionado para sua aplicação).

Visão geral do fluxo

Como você pode ver no diagrama abaixo, o fluxo de dados para criar um pagamento usando Pix Automático envolve:

1. Criar uma Autorização de Pagamento.
2. Redirecionar seu usuário para o authorization_url para que ele possa confirmar essa Autorização de Pagamento. Uma vez confirmada, ele é redirecionado para o return_url que você forneceu.
3. Aguardar um webhook PAYMENT_AUTHORIZATION com o status definido como AUTHORIZED.
4. Solicitar a Cobrança pelo menos dois dias antes de o pagamento ocorrer.
5. No dia do pagamento, aguardar um webhook CHARGES com o status definido como SETTLED.

Criando uma Autorização de Pagamento

Uma Autorização de Pagamento é o consentimento que seu usuário lhe dá para debitar (retirar dinheiro de) suas contas. Você precisa realizar uma Autorização de Pagamento por ‘contrato’ (por exemplo, se sua empresa fornece tanto eletricidade quanto água, mas elas são cobradas separadamente, então você criará duas Autorizações de Pagamento separadas).

 POST /payment-authorizations/

{
  "payment_method": "PIX_OF_AUTOMATIC_FIXED",
  "description": "Monthly gym subscription payment",
  "external_id": "c169a8a9-e9f5-48db-9f4a-818caef9356b",
  "return_url": "https://merchant.com/return",
  "payer": {
    "customer": {
      "identifier": "12345678901",
      "name": "João da Silva",
      "external_id": "4b8a81a0-e33c-45a6-8567-479efb105f73"
    },
    "institution": "ef685cf7-d143-4671-a1e5-4d1d019a3f5c",
    "representative_identifier": "12345678901234"
  },
  "beneficiary": {
    "type": "BANK_ACCOUNT",
    "target": {
      "holder": {
        "identifier": "12345678901122",
        "name": "Frangos Enlatados"
      },
      "details": {
        "account_type": "CHECKINGS",
        "agency": "0444",
        "institution": "f512d996-583a-4a91-8b5b-eba2e103b068",
        "number": "457220"
      },
      "external_id": "4b8a81a0-e33c-45a6-8567-479efb105f73",
      "metadata": {
        "internal_reference_id": "GGq73487w2"
      }
    }
  },
  "payment_method_configuration": {
    "amount": 3000.01,
    "statement_description": "Monthly Gym - Premium Plan",
    "frequency": "MONTHLY",
    "start_date": "2025-06-01",
    "end_date": "2026-06-01",
    "contract_id": "PREMIUMPLAN123456",
    "contract_debtor": {
      "identifier": "12345678901",
      "name": "João da Silva"
    },
    "retries": true,
    "first_payment": {
      "date": "2025-05-15",
      "amount": 3000.01
    }
  },
  "metadata": {
    "internal_reference_id": "GGq73487w2"
  }
}

Em uma requisição bem-sucedida à API, a Belvo responde com um 201 - OK. Você precisará redirecionar seu usuário para o authorization_url que você recebe na resposta para que ele possa autorizar os pagamentos em sua instituição. Uma vez que ele passe pelo processo de autorização no aplicativo da instituição, ele será redirecionado de volta para o return_url que você forneceu.

{
  "id": "9fc68b84-f2d6-4142-b2ad-9d2d1ad70432",
  "created_at": "2025-05-20T09:55:02Z",
  "updated_at": "2025-05-20T09:55:02Z",
  "status": "AWAITING_AUTHORIZATION",
  "status_reason_code": null,
  "status_reason_message": null,
  "status_updated_at": "2025-05-20T09:55:02Z",
  "authorized_at": "2025-05-20T09:55:02Z",
  "external_id": "c169a8a9-e9f5-48db-9f4a-818caef9356b",
  "description": "Internal description used by the merchant only",
  "return_url": "https://merchant.com/return",
  "payment_method": "PIX_OF_AUTOMATIC_FIXED",
  "payer": {
    "customer": "533e7a9b-e6c7-4bd4-be79-3a3c3bd78044",
    "institution": "770932b4-8f1f-4b0f-8470-1c605903fdb2",
    "representative_identifier": "12345678901122"
  },
  "beneficiary": {
    "type": "BANK_ACCOUNT",
    "target": "b6278377-f710-4d1a-a026-7bab757256d0"
  },
  "payment_method_configuration": {
    "amount": "10000.05",
    "statement_description": "Description to show on the bank statement",
    "frequency": "WEEKLY",
    "start_date": "2025-06-01",
    "end_date": null,
    "contract_id": "id-with-max-len-35",
    "contract_debtor": {
      "identifier": "12345678901",
      "name": "João da Silva"
    },
    "retries": true,
    "authorization_url": "url_to_redirect_user"
  }
}

Uma vez que o usuário confirma a autorização, você precisará escutar por um webhook PAYMENT_AUTHORIZATION com o status definido como AUTHORIZED. Quando você receber este webhook, o processo de autorização estará completo.

Cobrança do Seu Cliente

Uma vez que você tenha uma Autorização de Pagamento com o status AUTHORIZED, para cada pagamento que você deseja receber do seu cliente, você precisa criar uma Cobrança.

Para solicitar uma Cobrança, você precisará fazer a seguinte solicitação:

POST /payment-authorizations/payment_authorization_id/charges/

{
  "amount": 10000.05,
  "date": "2025-06-01",
  "statement_description": "Descrição a ser exibida no extrato bancário",
}

Em uma solicitação de Cobrança bem-sucedida, você receberá esta resposta:

{
  "id": "0d3ffb69-f83b-456e-ad8e-208d0998d71d",
  "created_at": "2022-02-09T08:45:50.406032Z",
  "status_updated_at": "2025-06-09T08:45:50.406032Z",
  "status": "PENDING",
  "status_reason_code": null,
  "status_reason_message": null,
  "amount": "100.12",
  "date": "2025-06-09",
  "end_to_end_id": "1234567890abcdef",
  "statement_description": "Super Shoe Store - Brown Sneakers",
  "external_id": "4b8a81a0-e33c-45a6-8567-479efb105f73",
  "beneficiary": {
    "bank_account": {
      "id": "088bc38f-1430-40c5-a5d2-80bd67189d11",
      "holder": {
        "name": "Jane Smith",
        "identifier": "12345678901"
      },
      "details": {
        "institution": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "agency": "5678",
        "number": "987654321",
        "account_type": "SAVINGS",
        "code": "678901"
      }
    }
  },
  "payer": {
    "bank_account": {
      "holder": {
        "identifier": "12345678902"
      },
      "details": {
        "institution": "f9f40aa0-a864-45d6-a5d4-43ce9d28dd0b",
        "code": "123345",
        "account_type": "CHECKING",
        "agency": "1234",
        "number": "123456789"
      }
    }
  },
  "metadata": {
    "internal_reference_id": "GGq73487w2"
  }
}

No dia do pagamento, você precisará ouvir por um webhook CHARGES com o status definido como SETTLED, o que indicará que o pagamento foi concluído.

Recursos Adicionais

Alterando a conta bancária para uma Cobrança individual

Pode haver uma situação em que você precise solicitar que o pagamento seja direcionado para uma conta bancária diferente da que você forneceu inicialmente na Autorização de Pagamento. E com o Pix Automático, isso é possível!

No entanto, a conta bancária que você fornecer deve estar associada ao mesmo CNPJ e Nome da Empresa que a Autorização de Pagamento inicial. Por exemplo, se na conta bancária inicial estava registrado Frangos Enlatados com o CNPJ de 12345678901122, então a nova conta bancária deve estar registrada com o mesmo nome e identificador de CNPJ. Caso contrário, quando você fizer a solicitação, a Rede de Open Finance gerará um erro.

Para solicitar uma Cobrança com uma conta bancária diferente, você precisará fazer a seguinte solicitação:

 POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/ 

{
  "amount": 100.01,
  "date": "2025-05-15",
  "statement_description": "Monthly Gym - Premium Plan",
  "beneficiary": {
    "holder": {
      "identifier": "12345678901122",
      "name": "Frangos Enlatados"
    },
    "details": {
      "account_type": "CHECKINGS",
      "agency": "0444",
      "institution": "f512d996-583a-4a91-8b5b-eba2e103b068",
      "number": "457220"
    },
    "external_id": "4b8a81a0-e33c-45a6-8567-479efb105f73",
    "metadata": {
      "internal_reference_id": "GGq73487w2"
    }
  }
}

Tentando uma Cobrança Novamente

No caso de uma Cobrança falhar, você receberá um webhook no dia indicando qual Cobrança falhou. Se a Autorização de Pagamento permitir novas tentativas (retries: true), então você poderá tentar o pagamento novamente e tentar debitar a conta do usuário novamente.

Em relação às novas tentativas, tenha em mente o seguinte:

• Por cada ciclo de pagamento, você pode tentar o pagamento novamente até três vezes.
• Você pode agendar uma nova tentativa para o dia seguinte ao pedido. Por exemplo, se a Cobrança original falhar em 01.06.2025, você pode tentar a Cobrança novamente com a date definida para 02.06.2025.
• Cobranças tentadas novamente são vinculadas 1-para-1 com outra Cobrança. Veja a seção Cobranças Vinculadas abaixo para uma explicação detalhada.
• Para ciclos semanais, o mais tardar que você pode fazer a primeira nova tentativa é cinco dias (exclusivo) após a primeira Cobrança falhada. Por exemplo, se a data original da Cobrança foi 01.06.2025, você tem até 06.06.2025 para tentar o pagamento novamente.
• Para todos os outros ciclos, o mais tardar que você pode fazer a primeira nova tentativa é sete dias (exclusivo) após a primeira Cobrança falhada. Por exemplo, se a data original da Cobrança foi 01.07.2025, você tem até 08.07.2025 para tentar o pagamento novamente.

Para tentar uma Cobrança novamente, você precisará fazer a seguinte solicitação:

 POST /payments/br/payment-authorizations/payment_authorization_id/charges/charge_id/retry/

{
  "date": "2025-06-30" // A data em que você deseja tentar a Cobrança novamente, no formato YYYY-MM-DD. Deve ser pelo menos um dia no futuro.
}

Em uma nova tentativa bem-sucedida, você receberá um novo ID de Cobrança (e objeto). Por favor, veja a seção Cobranças Vinculadas abaixo para uma explicação detalhada.

Cobranças Vinculadas

A Belvo utiliza uma estrutura de lista duplamente ligada para representar o ciclo de vida de uma Cobrança e suas tentativas, permitindo que você acompanhe todas as tentativas individuais associadas a uma Cobrança. Cada vez que uma Cobrança é tentada novamente, uma nova Cobrança é gerada e vinculada à Cobrança anterior. Você pode navegar por essas Cobranças usando os campos previous e next. No exemplo abaixo, a Cobrança foi tentada novamente três vezes:

1. A Cobrança original (1546) falhou. O parâmetro previous está definido como null (indicando que é a primeira Cobrança). O parâmetro next está definido como 3444.
2. A primeira tentativa (3444) falhou. O parâmetro previous está definido como 1546. O parâmetro next está definido como 8342.
3. A segunda tentativa (8342) falhou. O parâmetro previous está definido como 3444. O parâmetro next está definido como 9977.
4. A terceira tentativa (9977) falhou. O parâmetro previous está definido como 8342. O parâmetro next está definido como null (indicando que é a última tentativa e nenhuma outra tentativa foi feita).

Cancelando uma Cobrança individual

Para cancelar uma Cobrança individual, você precisa enviar a seguinte solicitação:

 POST /payments/br/payment-authorizations/payment_authorization_id/charges/charge_id/cancel/

Se bem-sucedido, a Belvo responde com um 204 - No Content. Você receberá uma notificação de webhook confirmando o cancelamento.

Cancelando uma Autorização de Pagamento

Para cancelar uma Autorização de Pagamento, você precisa enviar a seguinte solicitação até as 22:00 (Horário de Brasília):

 POST /payments/br/payment-authorizations/payment_authorization_id/cancel/

Se bem-sucedido, a Belvo responde com um 204 - No Content. Você receberá uma notificação de webhook confirmando o cancelamento.