Bill Payment Webhook Events

Payment Status

Cada pagamento de contas (bill-payment) progride através de um ciclo de vida definido. O campo Status presente nos webhooks e respostas da API indica o estágio atual do pagamento. É fundamental entender este fluxo para conciliar as transações e lidar com possíveis falhas.

O diagrama abaixo ilustra o ciclo de vida completo de um pagamento.

CREATED

Este é o estado inicial e representa a criação bem-sucedida de uma intenção de pagamento.

O sistema recebeu a solicitação de pagamento de conta, validou as informações iniciais (como a linha digitável) e criou uma transação correspondente no sistema, debitando o valor da conta do usuário. Neste ponto, a ordem de pagamento foi registrada, mas ainda não foi enviada à rede bancária.

Gatilho: Uma chamada bem-sucedida para o endpoint de criação de pagamento de contas.

Próximos Status Possíveis: PROCESSING ou CANCELED.

Detalhes do Payload: Este evento é o que contém a maior quantidade de dados, incluindo todos os detalhes da conta (BillPayment), a confirmação do provedor externo (ExternalConfirmation) e os dados da transação financeira (Transaction) que movimentou o saldo na conta de origem.

{
    "eventId": "0197e373-0e5e-70b1-9cbf-668c4bc3ae53",
    "subscription": "bill-payment",
    "organizationId": "0197e5c8-bf20-7946-92c7-a7878a307da9",
    "createdAt": "2025-07-07T05:54:17.847678",
    "isDelivered": true,
    "data": {
        "Status": "CREATED",
        "BillPayment": {
            "Id": "0197e370-3ee5-716a-ab57-46914dec0304",
            "Line": "826000000008743900970919095587510389000045845732",
            "BarCode": "82600000000743900970910955875103800004584573",
            "TaxId": null,
            "ReceiverName": "SABESP",
            "ReceiverBankNumber": null,
            "ReceiverBankName": null,
            "Expiration": "2025-06-24T00:00:00",
            "Amount": 7439,
            "DiscountAmount": 0,
            "RebateAmount": 0,
            "BonusAmount": 0,
            "LatePaymentInterestAmount": 0,
            "FinePenaltyAmount": 0,
            "FinalAmount": 7439,
            "BillPaymentType": "Sanitation",
            "Description": "Água e Esgoto",
            "Metadata": {
                "external_trx_id": "105236",
                "external_user_id": "1234"
            },
            "FinalPayerTaxId": "12345678900",
            "AccountId": "0197e328-e406-7dc4-b3b1-8fa7d861cdd7",
            "CreatedAt": "2025-07-07T05:51:13.641443Z",
            "UpdatedAt": "2025-07-07T06:11:23.270994Z"
        },
        "ExternalConfirmation": {
            "Id": "64cee8ef-3685-4f50-a0c0-bec6770b9d79",
            "Amount": 7439,
            "Description": "Sanitation Bill Payment - SABESP",
            "ProviderTrxId": "5992427F3C19415DB3FB4F227702D163DAABCCA0DEAD430080505C7225E40C009552D57AD654449C87CD0C540A3AC46A0CACB5673B454E92AE63E20EBFE25334",
            "ProviderAuthenticationCode": "369604aa-8304-4eab-80bd-3abebb874b27"
        },
        "Transaction": {
            "Id": "0197e383-08cf-74c1-9d23-3ecd49e4f5e8",
            "Status": "Completed",
            "CreatedAt": "2025-07-07T06:11:44.9731211",
            "UpdatedAt": null,
            "ExternalId": "fc82fe24-4cb6-4583-bb57-85e66158fd48",
            "Description": "Sanitation Bill Payment - SABESP",
            "ExchangeRate": 1,
            "SourceAmount": 7439,
            "SourceAssetCode": "BRL",
            "DestinationAmount": 7439,
            "ParentTransactionId": null,
            "ChartOfAccountsGroup": "BILL_PAYMENT",
            "DestinationAssetCode": "BRL"
        }
    }
}

PROCESSING

O pagamento foi submetido à rede bancária e está aguardando a confirmação e compensação. Este é um estado transitório enquanto a comunicação entre as instituições financeiras ocorre.

Gatilho: Ocorre automaticamente após o status CREATED, quando o processo de envio ao parceiro bancário é iniciado.

Próximos Status Possíveis: PAID ou FAILED.

 {
        "eventId": "0197e5d5-688b-70e1-b5f9-e408ad150118",
        "subscription": "bill-payment",
        "organizationId": "0197e5c8-bf20-7946-92c7-a7878a307da9",
        "createdAt": "2025-07-07T05:54:17.847678",
        "isDelivered": true,
        "data": {
            "Status": "PROCESSING",
            "BillPayment": {
                "Id": "0197e370-3ee5-716a-ab57-46914dec0304",
                "Line": "826000000008743900970919095587510389000045845732",
                "BarCode": "82600000000743900970910955875103800004584573",          
                "Amount": 7439,
                "Metadata": {
                    "external_trx_id": "105236",
                    "external_user_id": "1234"
                },
                "AccountId": "0197e328-e406-7dc4-b3b1-8fa7d861cdd7",
                "CreatedAt": "2025-07-07T05:51:13.641443Z",
                "UpdatedAt": "2025-07-07T06:11:23.270994Z"
            }
        }
    }

CANCELED

O pagamento foi cancelado antes de ser enviado para processamento. Isso pode ocorrer por uma ação explícita via API ou por uma falha interna antes do envio (ex: falha na validação de saldo). Este é um estado terminal.

Gatilho: Chamada à API para cancelar um pagamento que ainda está no estado CREATED.

Próximos Status Possíveis: Nenhum (estado final).

 {
        "eventId": "0197e5d2-43f0-7b83-8534-56faf4ca330a",
        "subscription": "bill-payment",
        "organizationId": "0197e5c8-bf20-7946-92c7-a7878a307da9",
        "createdAt": "2025-07-07T05:54:17.847678",
        "isDelivered": true,
        "data": {
            "Status": "CANCELED",
            "BillPayment": {
                "Id": "0197e370-3ee5-716a-ab57-46914dec0304",
                "Line": "826000000008743900970919095587510389000045845732",
                "BarCode": "82600000000743900970910955875103800004584573",          
                "Amount": 7439,
                "Metadata": {
                    "external_trx_id": "105236",
                    "external_user_id": "1234"
                },
                "AccountId": "0197e328-e406-7dc4-b3b1-8fa7d861cdd7",
                "CreatedAt": "2025-07-07T05:51:13.641443Z",
                "UpdatedAt": "2025-07-07T06:11:23.270994Z"
            }
        }
    }

FAILED

Ocorreu uma falha durante a etapa de PROCESSING. Isso pode ser causado por diversos motivos, como o sistema do conveniado estar offline, a linha digitável ser inválida ou ter ocorrido um erro de comunicação com o parceiro bancário. O valor debitado da conta do usuário é estornado. Este é um estado terminal.

Gatilho: Erro retornado pelo parceiro bancário ou pela rede de pagamentos durante o processamento.

Próximos Status Possíveis: Nenhum (estado final).

 {
        "eventId": "0197e5d4-1a8d-7439-b430-facb3cd27e00",
        "subscription": "bill-payment",
        "organizationId": "0197e5c8-bf20-7946-92c7-a7878a307da9",
        "createdAt": "2025-07-07T05:54:17.847678",
        "isDelivered": true,
        "data": {
            "Status": "FAILED",
            "BillPayment": {
                "Id": "0197e370-3ee5-716a-ab57-46914dec0304",
                "Line": "826000000008743900970919095587510389000045845732",
                "BarCode": "82600000000743900970910955875103800004584573",          
                "Amount": 7439,
                "Metadata": {
                    "external_trx_id": "105236",
                    "external_user_id": "1234"
                },
                "AccountId": "0197e328-e406-7dc4-b3b1-8fa7d861cdd7",
                "CreatedAt": "2025-07-07T05:51:13.641443Z",
                "UpdatedAt": "2025-07-07T06:11:23.270994Z"
            }
        }
    }

PAID

Um estado intermediário de sucesso. O parceiro bancário confirmou o recebimento e a execução do pagamento. Na prática, o "comprovante" do pagamento já foi emitido. No entanto, o dinheiro ainda está no fluxo de compensação e não foi formalmente liquidado na conta do recebedor final.

Gatilho: Confirmação de sucesso do parceiro bancário após o estado PROCESSING.

Próximos Status Possíveis: SETTLED ou REJECTED.

 {
        "eventId": "0197e5d4-1a8d-7439-b430-facb3cd27e00",
        "subscription": "bill-payment",
        "organizationId": "0197e5c8-bf20-7946-92c7-a7878a307da9",
        "createdAt": "2025-07-07T05:54:17.847678",
        "isDelivered": true,
        "data": {
            "Status": "PAID",
            "BillPayment": {
                "Id": "0197e370-3ee5-716a-ab57-46914dec0304",
                "Line": "826000000008743900970919095587510389000045845732",
                "BarCode": "82600000000743900970910955875103800004584573",          
                "Amount": 7439,
                "Metadata": {
                    "external_trx_id": "105236",
                    "external_user_id": "1234"
                },
                "AccountId": "0197e328-e406-7dc4-b3b1-8fa7d861cdd7",
                "CreatedAt": "2025-07-07T05:51:13.641443Z",
                "UpdatedAt": "2025-07-07T06:11:23.270994Z"
            }
        }
    }

REJECTED

Estado de falha que ocorre após o pagamento ter sido considerado PAID. Indica que, durante a compensação final, o recebedor (conveniado) rejeitou o pagamento. Motivos comuns incluem o cancelamento da dívida pelo credor ou o pagamento do mesmo boleto por outro meio antes da liquidação deste. O valor é estornado para o usuário. Este é um estado terminal.

Gatilho: Notificação assíncrona de rejeição vinda do recebedor final, após o status PAID.

Próximos Status Possíveis: Nenhum (estado final).

 {
        "eventId": "0197e5d4-1a8d-7439-b430-facb3cd27e00",
        "subscription": "bill-payment",
        "organizationId": "0197e5c8-bf20-7946-92c7-a7878a307da9",
        "createdAt": "2025-07-07T05:54:17.847678",
        "isDelivered": true,
        "data": {
            "Status": "REJECTED",
            "Reason": "Bill already paid",
            "BillPayment": {
                "Id": "0197e370-3ee5-716a-ab57-46914dec0304",
                "Line": "826000000008743900970919095587510389000045845732",
                "BarCode": "82600000000743900970910955875103800004584573",          
                "Amount": 7439,
                "Metadata": {
                    "external_trx_id": "105236",
                    "external_user_id": "1234"
                },
                "AccountId": "0197e328-e406-7dc4-b3b1-8fa7d861cdd7",
                "CreatedAt": "2025-07-07T05:51:13.641443Z",
                "UpdatedAt": "2025-07-07T06:11:23.270994Z"
            }
        }
    }

SETTLED

O estado final de sucesso. O pagamento foi processado, compensado, e o valor foi liquidado e confirmado pelo recebedor final. O ciclo de vida do pagamento está concluído.

Gatilho: Confirmação final da liquidação na rede bancária, após o status PAID.

Próximos Status Possíveis: Nenhum (estado final).

 {
        "eventId": "0197e5d5-474c-7dc6-8629-08e31a40a7da",
        "subscription": "bill-payment",
        "organizationId": "0197e5c8-bf20-7946-92c7-a7878a307da9",
        "createdAt": "2025-07-07T05:54:17.847678",
        "isDelivered": true,
        "data": {
            "Status": "SETTLED",
            "BillPayment": {
                "Id": "0197e370-3ee5-716a-ab57-46914dec0304",
                "Line": "826000000008743900970919095587510389000045845732",
                "BarCode": "82600000000743900970910955875103800004584573",          
                "Amount": 7439,
                "Metadata": {
                    "external_trx_id": "105236",
                    "external_user_id": "1234"
                },
                "AccountId": "0197e328-e406-7dc4-b3b1-8fa7d861cdd7",
                "CreatedAt": "2025-07-07T05:51:13.641443Z",
                "UpdatedAt": "2025-07-07T06:11:23.270994Z"
            }
        }
    }

Payment Status#

CREATED#

PROCESSING#

CANCELED#

FAILED#

PAID#

REJECTED#

SETTLED#

Payment Status

CREATED

PROCESSING

CANCELED

FAILED

PAID

REJECTED

SETTLED