Para os casos em que, por alguma razão, não foi possível realizar o pagamento, é possível realizar retentativas utilizando o fluxo descrito abaixo. Esse fluxo é necessário porque não existe retentativas executadas de forma automática pelo sistema da Celcoin.
Pré-requisito: A CCB precisa estar com o statusDISBURSEMENT_ATTEMPT_FAILEDpara que a retentativa seja permitida.
Notificação de Falha via Webhook
Ao ocorrer uma falha no desembolso, um evento é disparado automaticamente para a URL pré-cadastrada pelo Originador, sinalizando que a retentativa é necessária.
Payload do Webhook
{
"payload": {
"application_id": "ca81a0be-b732-41a9-9c64-03d92daa3a96",
"status": "DISBURSEMENT_ATTEMPT_FAILED",
"entry_payment_info": null,
"status_description": "Não encontramos nenhuma transação através do parâmetro informado"
},
"createdAt": "2026-02-13T12:42:54.062395Z",
"type": "APPLICATION_STATUS_UPDATED"
}| Campo | Descrição |
|---|---|
payload.application_id | Identificador da solicitação com falha |
payload.status | Sempre DISBURSEMENT_ATTEMPT_FAILED neste evento |
payload.status_description | Mensagem descritiva do motivo da falha |
payload.entry_payment_info | Informações do pagamento — null em caso de falha |
createdAt | Data e hora do disparo do evento (UTC) |
type | Tipo do evento — sempre APPLICATION_STATUS_UPDATED |
Fluxo de Retentativa
sequenceDiagram
autonumber
participant O as Originador
participant A as API Celcoin
participant P as Sist. Pagamento
Note over O,P: Falha anterior
A-->>O: Webhook: DISBURSEMENT_ATTEMPT_FAILED
Note over O,A: 1. Corrigir dados da Pessoa
O->>A: PUT /persons/{person_id}
A-->>O: 200 OK
Note over O,A: 2. Atualizar Ordem de Pagamento
O->>A: PUT /applications/{id}/payment-orders/{id}
A-->>O: 200 OK
Note over O,P: 3. Retentar Pagamento
O->>A: POST /disbursement-attempts {}
A-->>O: 201 Accepted
A->>P: Tentativa de desembolso (PIX/TED)
P-->>A: Confirmação de pagamento
A-->>O: Webhook: APPLICATION_STATUS_UPDATED
Note over A: Status: ISSUED
Passo 1 — Atualizar Cadastro de Pessoa
Corrija os dados da conta bancária ou chave PIX do Tomador.
| Campo | Valor |
|---|---|
| Método | PUT |
| Endpoint | {{api_host}}/banking/originator/persons/{{person_id}} |
Exemplo de Payload de Requisição
{
"full_name": "João da Silva Sauro",
"taxpayer_id": "12345678901",
"nationality": "Brasileiro",
"birth_date": "1985-05-20",
"birthplace": "São Paulo",
"sex": "MALE",
"occupation": "Engenheiro de Software",
"pep": false,
"monthly_income": 8500.50,
"education_level": "POST_GRADUATED",
"mothers_name": "Maria da Silva Sauro",
"marital_status": "MARRIED",
"marital_property_system": "PARTIAL_COMMUNION",
"spouse_full_name": "Maria Oliveira Sauro",
"spouse_taxpayer_id": "98765432100",
"spouse_date_of_birth": "1988-08-15",
"id_document": {
"number": "12345678X",
"type": "RG",
"issuer": "SSP",
"issue_date": "2010-10-10"
},
"email_address": "[email protected]",
"phone": {
"country_code": "55",
"area_code": "11",
"number": "987654321"
},
"address": {
"street_name": "Avenida Paulista",
"street_number": 450,
"postal_code": "01310100",
"district": "Bela Vista",
"city": "São Paulo",
"state_code": "SP",
"country_code": "BRA",
"extra_info": "Apto 101"
},
"external_bank_account": {
"bank_code": "001",
"bank_branch": "0001",
"bank_account": "123456",
"bank_account_digit": "7",
"bank_account_type": "CACC",
"ispb_code": "00000000"
},
"pix": {
"key_type": "TAXPAYER_ID",
"key": "12345678901"
}
}Passo 2 — Atualizar Ordem de Pagamento na Solicitação
Atualize o método e os dados de pagamento vinculados à solicitação.
| Campo | Valor |
|---|---|
| Método | PUT |
| Endpoint | {{api_host}}/banking/originator/applications/{{application_id}}/payment-orders/{{payment_order_id}} |
Payload de Requisição
{
"payment_order": {
"method": "PIX",
"pix": {
"key_type": "TAXPAYER_ID",
"key": "12345678901"
},
"external_bank_account": {
"bank_code": "001",
"bank_branch": "0001",
"bank_account": "123456",
"bank_account_digit": "7",
"bank_account_type": "CACC",
"ispb_code": "00000000"
}
}
}Passo 3 — Retentar Pagamento
Após corrigir os dados, dispare uma nova tentativa de desembolso.
| Campo | Valor |
|---|---|
| Método | POST |
| Endpoint | {{api_host}}/banking/originator/applications/{{application_id}}/disbursement-attempts |
Payload de Requisição
{}
O payload deve ser enviado vazio. Nenhum corpo adicional é necessário para disparar a retentativa.
Se executado com sucesso, após a realização do desembolso, o status da ccb (application) irá alterar para "issued" finalizando assim a jornada de contratação do crédito.