# 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. Pagamentos Fixos versus Variáveis Com o Pix Automático, você pode escolher solicitar pagamentos do mesmo valor do seu usuário a cada vez (Fixo) ou estabelecer um valor variável (Variável). - Fixo = Assinaturas recorrentes estáveis (como Netflix, Spotify, academias) - Variável = Assinaturas medidas (como eletricidade, água, gás) 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 Cabeçalho de Versão O recurso de Autorização de Pagamento requer que você envie o cabeçalho `X-Belvo-API-Resource-Version` configurado para `Payments-BR.V2`. 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 Versão da API 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`. Diagrama de sequência das chamadas de API necessárias e webhooks enviados durante o processo de Pix Automático ## Criando uma Autorização de Pagamento Uma Autorização de Pagamento é o consentimento que seu usuário dá para que você debite 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). Fixo ```curl URL de Requisição de Autorização de Pagamento POST /payment-authorizations/ ``` Pix Automático Fixo { "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" } } Variável ```curl URL de Requisição de Autorização de Pagamento POST /payment-authorizations/ ``` Pix Automático Variável { "payment_method": "PIX_OF_AUTOMATIC_VARIABLE", "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": { "minimum_amount": 10000.01, "maximum_amount": 50000.5, "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.02 } }, "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. Assim que ele passar pelo processo de autorização no aplicativo da instituição, ele será redirecionado de volta para o `return_url` que você forneceu. Fixo Exemplo de Resposta de Autorização de Pagamento Fixo { "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" // [!code highlight] } } Variável Exemplo de Resposta de Autorização de Pagamento Variável { "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_VARIABLE", "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": { "minimum_amount": "10000.01", "maximum_amount": "50000.5", "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" // [!code highlight] } } O processo de Autorização de Pagamento, incluindo o redirecionamento e a obtenção de todas as confirmações necessárias, deve ser concluído em até 60 minutos. Após 60 minutos, a autorização é automaticamente definida como `FAILED`. Assim que o usuário confirmar 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. Cobrando Seu Cliente Agora que você tem a Autorização de Pagamento, você pode começar a cobrar seu cliente! ## 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**. O que é uma Cobrança? Uma **Cobrança** representa o pagamento individual (débito) que seu cliente fará. Regras de Solicitação de Cobrança Ao solicitar uma Cobrança, há algumas regras que você precisa seguir: 1. A solicitação deve ser feita **entre dois e dez dias** antes de quando a Cobrança deve ocorrer. Por exemplo, se você deseja debitar a conta do seu cliente em 30.05.2025, você precisa fazer a solicitação entre 20.05.2025 e 28.05.2025. 2. Apenas uma Cobrança pode ser feita em um ‘ciclo’ de pagamento. Por exemplo, se a `frequency` na Autorização de Pagamento é `WEEKLY`, então você só pode Cobrar seu cliente uma vez por semana. Isso significa que você só pode fazer **uma** solicitação no ciclo de pagamento. 3. A `date` da Cobrança. Esta data deve estar alinhada com a `frequency` na Autorização de Pagamento. Por exemplo, se a `frequency` é `MONTHLY` e a `start_date` é `2025-06-01`, então cada `date` que você fornecer deve estar de acordo com essa frequência e data (por exemplo, `2025-06-01`, `2025-07-01`, `2025-08-01`). **Nota: Se o dia cair em um fim de semana ou feriado bancário, você deve alterar a `date` para ser o primeiro dia útil que ocorre após a data original.** Para solicitar uma Cobrança, você precisará fazer a seguinte solicitação: ```curl URL de Solicitação de Cobrança POST /payment-authorizations/payment_authorization_id/charges/ ``` ```json Corpo da Solicitação de Cobrança { "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: Exemplo de Resposta de Cobrança { "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. Feito! E é isso! Agora, cada vez que você precisar solicitar um pagamento de um cliente, basta fazer outra solicitação de Cobrança! ## 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: Com Detalhes da Conta Bancária ```curl URL de Solicitação de Cobrança POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/ ``` Cobrança com Detalhes da Conta Bancária { "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" } } } Com ID da Conta Bancária ```curl URL de Solicitação de Cobrança POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/ ``` Cobrança com ID da Conta Bancária { "amount": 100.01, "date": "2025-05-15", "statement_description": "Monthly Gym - Premium Plan", "beneficiary": { "target": "046f9af7-1813-4830-b4e6-5231e8111ca1" } } ### Repetindo uma Cobrança 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 repetições (`retries: true`), então você poderá tentar novamente o pagamento e tentar debitar a conta do usuário novamente. Em relação às repetições, tenha em mente o seguinte: - Por cada ciclo de pagamento, você pode tentar novamente o pagamento até três vezes. - Você pode agendar uma repetição para o dia seguinte ao pedido. Por exemplo, se a Cobrança original falhar em 01.06.2025, você pode tentar novamente a Cobrança com a `date` definida para `02.06.2025`. - Cobranças repetidas estã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 repetição inicial é **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 novamente o pagamento. - Para todos os outros ciclos, o mais tardar que você pode fazer a repetição inicial é **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 novamente o pagamento. Para repetir uma Cobrança, você precisará fazer a seguinte solicitação: ```curl Retry a Charge Request URL POST /payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/retry/ ``` ```json Retry a Charge Request Body { "date": "2025-06-30" // A data em que você deseja tentar novamente a Cobrança, no formato YYYY-MM-DD. Deve ser pelo menos um dia no futuro. } ``` Em uma repetição 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: Explicação de listas duplamente ligadas para Cobranças na Belvo 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 Restrição de Tempo para Cancelamento O horário limite para cancelar uma Cobrança agendada é até 22:00:00 (GMT-3) do dia anterior à data da Cobrança. Se você perder o prazo, receberá um erro da API da Belvo e o pagamento será processado. Para cancelar uma Cobrança individual, você precisa enviar a seguinte solicitação: ```shell URL de Solicitação de Cancelamento de Cobrança curl --request POST 'https://api.belvo.com/payments/br/payment-authorizations/{payment_authorization_id}/charges/{charge_id}/cancel/' \ -u SECRET_ID:SECRET_PASSWORD \ -H 'X-Belvo-API-Resource-Version: Payments-BR.V2' \ ``` 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 Restrições de Tempo para Cancelamento O horário limite para cancelar uma Autorização de Pagamento é até 22:00:00 (GMT-3) no dia anterior à próxima data de Cobrança. Se você perder o prazo, a Autorização de Pagamento será cancelada, **mas a Cobrança ainda será processada**. Para cancelar uma Autorização de Pagamento, você precisa enviar a seguinte solicitação até as 22:00 (Horário de Brasília): ```shell URL de Solicitação de Cancelamento de Autorização de Pagamento curl --request POST 'https://api.belvo.com/payments/br/payment-authorizations/{payment_authorization_id}/cancel/' \ -u SECRET_ID:SECRET_PASSWORD \ -H 'X-Belvo-API-Resource-Version: Payments-BR.V2' \ ``` Se bem-sucedido, a Belvo responde com um `204 - No Content`. Você receberá uma notificação de webhook confirmando o cancelamento. ### Obter detalhes de uma Cobrança Quando você recebe uma notificação de webhook sobre uma Cobrança, pode solicitar os detalhes da Cobrança usando a seguinte solicitação: ```shell Get Charge Details Request URL curl --request GET 'https://api.belvo.com/payments/br/charges/{charge_id}/' \ -u SECRET_ID:SECRET_PASSWORD \ -H 'X-Belvo-API-Resource-Version: Payments-BR.V2' \ ``` ### Códigos e Mensagens de Razão de Status Quando uma Autorização de Pagamento ou Cobrança encontra um erro, a Belvo atualiza o `status` do recurso em questão. Além disso, a Belvo também fornece informações detalhadas sobre a mudança de status nos parâmetros `status_reason_code` e `status_reason_message` para ajudar você a entender o que deu errado. Por favor, consulte nosso artigo dedicado Códigos e Mensagens de Erro para uma lista mais detalhada de possíveis códigos e mensagens.