Postbacks - Callbacks - Webhooks
Comunicação Transacional
A API de PIX Cobrança oferece uma variedade de tipos de postbacks (callbacks/webhooks) que têm a finalidade de notificar o cliente sobre o progresso ou conclusão de transações que seguem um fluxo assíncrono.
O postback é uma funcionalidade que permite a transmissão de dados em tempo real entre sistemas ou aplicativos distintos, possibilitando a integração de diferentes sistemas para manter os dados da aplicação e dos clientes sincronizados. Sempre que um evento relevante ocorre em um dos sistemas, relacionado a uma transação, os dados são enviados por meio de um postback. Por exemplo, isso ocorre quando um pagamento é realizado por meio de um QR Code (PIX IN).
Saiba sobre Notificações Assinadas acessando: Assinatura de Notificação
A seguir, apresentamos os diversos modelos de postbacks disponíveis na aplicação do PIX Cobrança, organizados de acordo com o tipo de transação:
PIX IN - Pagamento de QR Code
{
"id": "b3f030e1-f905-4c8e-a926-6fb08c57c49b",
"type": "deposit",
"amount": "0.05",
"source": {
"ispb": "18236120",
"name": "Fulano Fulano",
"type": "personal",
"taxId": "12121212121",
"taxIdHash": "f673e952d3315506816030a31f6fd207ef40516679e29e333ae92e3ea6a586ef"
},
"states": [
{
"id": "13de778a-098c-4f59-87fc-1d5e2b78b58a",
"status": "success",
"createdAt": "2024-03-06T00:02:12.459Z",
"additionalData": {}
},
{
"id": "14dbe662-3168-48ea-9c90-14a8c9b8bc8d",
"status": "pending",
"createdAt": "2024-03-06T00:02:12.452Z",
"additionalData": {}
}
],
"status": "success",
"wallet": {
"id": "22955a54-5252-40b7-927f-44a9ed7f52ad",
"ispb": "03311443",
"status": "ready",
"clientId": "66b7be28-33d1-44a5-b56d-9ce6ce6cc80b",
"accountId": "baf0a04f-4185-4819-b41b-7bd21ceff131",
"createdAt": "2022-08-26T15:21:36.272Z",
"bankBranch": "0001",
"bankNumber": "10000000091"
},
"walletId": "22955a54-5252-40b7-927f-44a9ed7f52ad",
"createdAt": "2024-03-06T00:02:12.452Z",
"endToEndId": "E18236120202403060001s018c1248e1",
"destination": {
"ispb": "03311443",
"type": "corporate",
"taxId": "29079725000107"
},
"additionalData": {
"customID": "Teste Pix-Cob",
"externalCustomerName": "BETBET"
},
"clientExternalId": "KAIf57963721dd34dfdaa8843c069ff1535",
"initiationMethod": "QRDN"
}
Descrição dos campos:
| Campo | Descrição |
|---|---|
| type | - Tipo de transação: - deposit (PIX IN) - withdraw (PIX OUT) - deposit_refund (Refund IN) - withdraw_refund (Refund OUT) |
| source | - Referente aos dados do pagador do QR Code |
| states | - Referente ao histórico de status da transação (success) |
| wallet | - Referente aos dados da conta origem do QR Code |
| endToEndId | - ID principal da transação de PIX |
| destination | - Referente aos dados da wallet que recebeu o PIX IN |
| clientExternalId | - Código de identificação do QR Code |
| initiationMethod | - Tipo de PIX IN, QR Code = QRDN |
PIX OUT por Chaves - Retirada de valor
{
"id": "0b151fd0-e247-46cd-8eb5-46dc899bf800",
"type": "withdrawal",
"amount": "0.01",
"source": {
"ispb": "03311443",
"name": "BIT CAPITAL LTDA",
"type": "corporate",
"taxId": "29079725000107"
},
"states": [
{
"id": "2f8cad71-dd07-4f10-b8db-4a3595495ce8",
"status": "success",
"createdAt": "2024-03-06T00:08:32.856Z",
"additionalData": {}
},
{
"id": "78c0901d-3de8-4beb-9951-b4b4d92c8382",
"status": "pending",
"createdAt": "2024-03-06T00:08:30.436Z",
"deletedAt": null,
"updatedAt": null,
"additionalData": {}
},
{
"id": "c99bc980-dd9c-4ce7-9ccf-d27cc84fbd73",
"status": "approved",
"createdAt": "2024-03-06T00:08:28.473Z",
"deletedAt": null,
"updatedAt": null,
"additionalData": {}
}
],
"status": "success",
"wallet": {
"id": "22955a54-5252-40b7-927f-44a9ed7f52ad",
"ispb": "03311443",
"status": "ready",
"clientId": "66b7be28-33d1-44a5-b56d-9ce6ce6cc80b",
"accountId": "baf0a04f-4185-4819-b41b-7bd21ceff131",
"createdAt": "2022-08-26T15:21:36.272Z",
"bankBranch": "0001",
"bankNumber": "10000000091"
},
"walletId": "22955a54-5252-40b7-927f-44a9ed7f52ad",
"createdAt": "2024-03-06T00:08:28.330Z",
"endToEndId": "E03311443202403060008r1lisLK8Xk1",
"destination": {
"key": "[email protected]",
"ispb": "18236120",
"name": "Fulano Fulano",
"type": "personal",
"taxId": "121212121212",
"taxIdHash": "f673e952d3315506816030a31f6fd207ef40516679e29e333ae92e3ea6a586ef"
},
"instructionId": null,
"additionalData": {
"key": "[email protected]",
"priority": "high",
"description": "Teste PIX OUT 05-03-24"
},
"idempotenceKey": "39207861-63e1-4780-aa92-dd46e7bb7e0c",
"clientExternalId": "KAId323424ffd2f4d7497f8a73067018d4d",
"initiationMethod": "DICT"
}
{
"id": "0e2672f4-111c-49ac-8d04-b44164ba52ea",
"type": "withdrawal",
"amount": "0.69",
"source": {
"ispb": "03311443",
"name": "Donna Frasson LTDA",
"type": "corporate",
"taxId": "92949282000196"
},
"states": [
{
"id": "deb46cc9-0254-4d58-b7a3-2adf452a7459",
"status": "success",
"createdAt": "2024-03-06T16:40:34.174Z",
"additionalData": {}
},
{
"id": "e926528e-f2a0-4088-9903-31799f935f90",
"status": "pending",
"createdAt": "2024-03-06T16:40:32.701Z",
"deletedAt": null,
"updatedAt": null,
"additionalData": {}
},
{
"id": "2c17a0b7-9cb2-4cca-85ca-ca6006ddeda7",
"status": "approved",
"createdAt": "2024-03-06T16:40:32.451Z",
"deletedAt": null,
"updatedAt": null,
"additionalData": {}
}
],
"status": "success",
"wallet": {
"id": "ddfbfcd1-d094-4136-a908-ee489e694c6e",
"ispb": "03311443",
"status": "ready",
"clientId": "7d8d40b2-28db-4e6c-abe8-f0ee2520b3c0",
"accountId": "92bc81ae-f7bf-4437-ad58-9dd61b1ff4c4",
"createdAt": "2022-09-20T14:24:29.109Z",
"bankBranch": "0001",
"bankNumber": "10000052202"
},
"walletId": "ddfbfcd1-d094-4136-a908-ee489e694c6e",
"createdAt": "2024-03-06T16:40:32.312Z",
"endToEndId": "E03311443202403061340f08a6b91000",
"destination": {
"ispb": "99999004",
"name": "Fulano Fulano",
"type": "personal",
"taxId": "40422863807",
"branch": "99999004",
"number": "295761",
"taxIdHash": "c6535ac9eac51e9385fd4c6a20c768fcdd96c17c2e00e5bb3f1f1c6bfc4b5b9b"
},
"instructionId": null,
"additionalData": {
"bank": {
"bank": "99999004",
"name": "Fulano Fulano",
"taxId": "40422863807",
"agency": "8008",
"account": "295761"
},
"description": "PIX-OUT de 0.69 para uma conta ISPB SANDBOX BACEN"
},
"idempotenceKey": "92d78676-2119-4dd0-b7c5-801b18e6e76a",
"clientExternalId": "KAIfbbfa157b43f43ca8a9e7bea242bbb59",
"initiationMethod": "MANU"
}
{
"id": "8fae40ef-2e00-4841-8723-246a28d9d94c",
"type": "withdrawal",
"amount": "0.01",
"source": {
"ispb": "03311443"
},
"states": [
{
"id": "f797f36d-4e1c-4448-8698-10b6ba1f163c",
"status": "failed",
"createdAt": "2024-03-06T16:52:23.777Z",
"additionalData": {
"errorMessage": "The order was rejected by the bank side (for reasons concerning content)"
}
},
{
"id": "2fedb99d-32ed-48f3-b498-b0cb2bcde437",
"status": "approved",
"createdAt": "2024-03-06T16:52:21.009Z",
"additionalData": {}
}
],
"status": "failed",
"wallet": {
"id": "22955a54-5252-40b7-927f-44a9ed7f52ad",
"ispb": "03311443",
"status": "ready",
"clientId": "66b7be28-33d1-44a5-b56d-9ce6ce6cc80b",
"accountId": "baf0a04f-4185-4819-b41b-7bd21ceff131",
"createdAt": "2022-08-26T15:21:36.272Z",
"bankBranch": "0001",
"bankNumber": "10000000091"
},
"walletId": "22955a54-5252-40b7-927f-44a9ed7f52ad",
"createdAt": "2024-03-06T16:52:20.929Z",
"endToEndId": "E03311443202403061652zPBWChGXP21",
"destination": {
"key": "32322929840"
},
"additionalData": {
"key": "32322929840",
"priority": "high",
"description": "Teste PIX OUT 06-03-24"
},
"idempotenceKey": "cdb7cb0a-605d-4e6d-a6b6-b59ca6edb14c",
"clientExternalId": "KAI77ddae78c53c4e6a89c961abcf8d9316"
}
Descrição dos campos:
| Campo | Descrição |
|---|---|
| type | - Tipo de transação: - deposit (PIX IN) - withdraw (PIX OUT) - deposit_refund (Refund IN) - withdraw_refund (Refund OUT) |
| key | - Chave destino da retirada |
| states | - Referente ao histórico de status da transação (ver lista abaixo) |
| endToEndId | - ID principal da transação de PIX |
| source | - Referente aos dados bancários de destino |
| idempotenceKey | - idempotenceKey da transação de pix-out |
Fluxo de aprovação de PIX OUT
Para retiradas de valores temos o subfluxo de aprovação, que vai validar se aquele PIX OUT deve ou não passar por uma análise. O fator principal para essa análise é o limite configurado na wallet do Cliente, ou seja, todo PIX OUT que for acima desse valor, passará pelo fluxo de aprovação, antes de ser executado.
Status de PIX OUT
Como a transação de PIX OUT possui o subfluxo de aprovação, os status desse fluxo também são replicados ao Cliente:
- denied - recusado pelo serviço de alçadas (status final)
- failed - foi aprovado (serviço de alçadas) e houve erro ao liquidar (status final)
- success - foi aprovado (serviço de alçadas) e houve sucesso na liquidação (status final)
Refund OUT - Reembolso de PIX IN
{
"id": "3f8b69f9-a6f2-433c-92bc-cb99eede136e",
"type": "deposit_refund",
"amount": "0.04",
"source": {
"ispb": "03311443",
"type": "corporate",
"taxId": "29079725000107"
},
"states": [
{
"id": "eb41481a-01d2-4905-a2bd-527a15973530",
"status": "success",
"createdAt": "2024-03-06T00:05:38.438Z",
"additionalData": {}
},
{
"id": "aef15f1a-1636-4ca8-ba89-2503a423c813",
"status": "pending",
"createdAt": "2024-03-06T00:05:35.531Z",
"deletedAt": null,
"updatedAt": null,
"additionalData": {}
}
],
"status": "success",
"wallet": {
"id": "22955a54-5252-40b7-927f-44a9ed7f52ad",
"ispb": "03311443",
"status": "ready",
"clientId": "66b7be28-33d1-44a5-b56d-9ce6ce6cc80b",
"accountId": "baf0a04f-4185-4819-b41b-7bd21ceff131",
"createdAt": "2022-08-26T15:21:36.272Z",
"bankBranch": "0001",
"bankNumber": "10000000091"
},
"walletId": "22955a54-5252-40b7-927f-44a9ed7f52ad",
"createdAt": "2024-03-06T00:05:35.531Z",
"endToEndId": "E18236120202403060001s018c1248e1",
"destination": {
"ispb": "18236120",
"name": "Fulano Fulano",
"type": "personal",
"taxId": "12121212121",
"taxIdHash": "f673e952d3315506816030a31f6fd207ef40516679e29e333ae92e3ea6a586ef"
},
"instructionId": "D03311443202403061716ReMBMpeMkXE",
"additionalData": {},
"idempotenceKey": null,
"clientExternalId": "KAIf57963721dd34dfdaa8843c069ff1535",
"initiationMethod": "QRDN"
}
Descrição dos campos:
| Campo | Descrição |
|---|---|
| type | - Tipo de transação: - deposit (PIX IN) - withdraw (PIX OUT) - deposit_refund (Refund IN) - withdraw_refund (Refund OUT) |
| key | - Chave destino da retirada |
| states | - Referente ao histórico de status da transação (success ou failed) |
| source | - Referente aos dados do pagador do Refund |
| destination | - Referente aos dados do recebedor do Refund |
| derivativeId | - ID da transação original PIX IN |
| instructionId | - ID da transação de Refund |
Refund IN - Reembolso de PIX OUT
{
"id": "0b151fd0-e247-46cd-8eb5-46dc899bf800",
"type": "withdrawal",
"amount": "0.01",
"source": {
"ispb": "03311443",
"name": "BIT CAPITAL LTDA",
"type": "corporate",
"taxId": "29079725000107"
},
"states": [
{
"id": "2f8cad71-dd07-4f10-b8db-4a3595495ce8",
"status": "success",
"createdAt": "2024-03-06T00:08:32.856Z",
"additionalData": {}
},
{
"id": "78c0901d-3de8-4beb-9951-b4b4d92c8382",
"status": "pending",
"createdAt": "2024-03-06T00:08:30.436Z",
"deletedAt": null,
"updatedAt": null,
"additionalData": {}
},
{
"id": "c99bc980-dd9c-4ce7-9ccf-d27cc84fbd73",
"status": "approved",
"createdAt": "2024-03-06T00:08:28.473Z",
"deletedAt": null,
"updatedAt": null,
"additionalData": {}
}
],
"status": "success",
"wallet": {
"id": "22955a54-5252-40b7-927f-44a9ed7f52ad",
"ispb": "03311443",
"status": "ready",
"clientId": "66b7be28-33d1-44a5-b56d-9ce6ce6cc80b",
"accountId": "baf0a04f-4185-4819-b41b-7bd21ceff131",
"createdAt": "2022-08-26T15:21:36.272Z",
"bankBranch": "0001",
"bankNumber": "10000000091"
},
"walletId": "22955a54-5252-40b7-927f-44a9ed7f52ad",
"createdAt": "2024-03-06T00:08:28.330Z",
"endToEndId": "E03311443202403060008r1lisLK8Xk1",
"destination": {
"key": "[email protected]",
"ispb": "18236120",
"name": "Fulano Fulano",
"type": "personal",
"taxId": "21212121211",
"taxIdHash": "f673e952d3315506816030a31f6fd207ef40516679e29e333ae92e3ea6a586ef"
},
"instructionId": null,
"additionalData": {
"key": "[email protected]",
"priority": "high",
"description": "Teste PIX OUT 05-03-24"
},
"idempotenceKey": "39207861-63e1-4780-aa92-dd46e7bb7e0c",
"clientExternalId": "KAId323424ffd2f4d7497f8a73067018d4d",
"initiationMethod": "DICT"
}
Descrição dos campos:
| Campo | Descrição |
|---|---|
| type | - Tipo de transação: - deposit (PIX IN) - withdraw (PIX OUT) - deposit_refund (Refund IN) - withdraw_refund (Refund OUT) |
| states | - Referente ao histórico de status da transação (success) |
| source | - Referente aos dados do recebedor do Refund |
| destination | - Referente aos dados do pagador do Refund |
| derivativeId | - ID da transação original PIX OUT |
| instructionId | - ID da transação de Refund |
Updated 8 months ago