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).
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": "b6cf34ae-476c-4b9f-99bc-6f94cafc7734",
"type": "deposit",
"amount": "1.89",
"source": {
"name": "Pedro Henrique e Jennifer Limpeza",
"type": "corporate",
"taxId": "15077054000122",
"account": {
"ispb": "03311443",
"type": "payment",
"bankBranch": "0001",
"bankNumber": "10000007673"
}
},
"states": [
{
"id": "48be51b3-71b6-427d-a0a1-5fa7f54b9244",
"status": "success",
"createdAt": "2023-08-02T17:43:41.029Z",
"additionalData": {}
},
{
"id": "96986068-4414-4440-ae76-f6dc38661fbb",
"status": "pending",
"createdAt": "2023-08-02T17:43:40.999Z",
"additionalData": {}
}
],
"status": "success",
"wallet": {
"id": "f259d2f8-006e-44cc-a016-f15dc206144a",
"ispb": "03311443",
"client": "df718bab-a2a5-4551-9d4d-742238584ed3",
"status": "ready",
"clientId": "df718bab-a2a5-4551-9d4d-742238584ed3",
"accountId": "fe44dcf8-8c92-4e68-b594-664301a57fda",
"createdAt": "2022-08-17T14:31:34.249Z",
"deletedAt": null,
"updatedAt": null,
"bankBranch": "0001",
"bankNumber": "10000007673",
"isPixoleto": false,
"additionalData": {},
"isCustomerName": true,
"notificationUrl": "https://webhook-site-develop.bitcapital.teleport.sh/c6c7031f-9e9c-4e00-98b5-3f454683c47d"
},
"customID": "customGUCAILS1",
"walletId": "f259d2f8-006e-44cc-a016-f15dc206144a",
"createdAt": "2023-08-02T17:43:40.995Z",
"endToEndId": "E033114432023080217432GsxJ0ULdEU",
"destination": {
"type": "corporate",
"taxId": "15077054000122",
"account": {
"ispb": "03311443",
"type": "payment",
"bankBranch": "0001",
"bankNumber": "10000007673"
}
},
"additionalData": {},
"clientExternalId": "COBdR0ppGl8j2uErHaQ6Ey04eHG",
"initiationMethod": "QRDN",
"externalTransactionId": "8cb26981-8dbf-412a-85b4-9aab88b3d4c3"
}
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": "7753e14d-166b-4533-b9b1-f786bc20e28d",
"createdAt": "2023-08-04T14:27:19.654Z",
"type": "withdrawal",
"additionalData": {
"clientWalletId": "ddfbfcd1-d094-4136-a908-ee489e694c6e",
"key": "66008158920",
"description": "PIX-OUT de 0.87 para uma CHAVE EXTERNA",
"priority": "high",
"authorizerId": "b89c9bc5-26a1-4b57-9307-7072752568e8"
},
"amount": "0.87",
"clientExternalId": "KAI79be7fa19a284b6581e9f9e56abf5eae",
"wallet": {
"id": "ddfbfcd1-d094-4136-a908-ee489e694c6e",
"createdAt": "2022-09-20T14:24:29.109Z",
"updatedAt": null,
"deletedAt": null,
"client": "7d8d40b2-28db-4e6c-abe8-f0ee2520b3c0",
"clientId": "7d8d40b2-28db-4e6c-abe8-f0ee2520b3c0",
"accountId": "92bc81ae-f7bf-4437-ad58-9dd61b1ff4c4",
"additionalData": {},
"status": "ready",
"ispb": "03311443",
"bankBranch": "0001",
"bankNumber": "10000052202",
"isPixoleto": false,
"notificationUrl": "https://webhook-site-staging.bitcapital.teleport.sh/8918b4b9-572f-4820-a955-254dd615c62c"
},
"idempotenceKey": "IK5520750bcb5c4bd685742d3b12f8762d",
"externalTransactionId": "7753e14d-166b-4533-b9b1-f786bc20e28d",
"endToEndId": "E03311443202308041427o8IDp517bkz",
"source": {
"account": {
"bankBranch": "0001",
"bankNumber": "10000052202",
"ispb": "03311443"
}
},
"states": [
{
"id": "129e6fbd-d7b8-45aa-bc30-22d9edba4cd9",
"createdAt": "2023-08-04T14:27:21.579Z",
"additionalData": {},
"status": "success"
},
{
"id": "4803726a-64d6-45c4-8a5a-bf04a8c6cfb0",
"createdAt": "2023-08-04T14:27:19.796Z",
"additionalData": {},
"status": "approved"
}
],
"updatedAt": "2023-08-04T14:27:19.787Z",
"status": "success"
}
{
"id": "6ae45b53-f3d8-4e54-b327-1818df47830d",
"type": "withdrawal",
"amount": "1.44",
"source": {
"name": "Donna Frasson Teste",
"type": "corporate",
"taxId": "92949282000196",
"account": {
"ispb": "03311443",
"type": "payment",
"bankBranch": "0001",
"bankNumber": "10000052202"
}
},
"states": [
{
"id": "8f3d9294-c786-41c8-bbdb-ce3c204cbe5b",
"status": "approved",
"createdAt": "2023-08-14T15:13:36.769Z",
"deletedAt": null,
"updatedAt": null,
"additionalData": {}
},
{
"id": "11169960-df1c-4d3d-a14e-ef630c36f8c7",
"status": "pending",
"createdAt": "2023-08-14T15:13:37.597Z",
"deletedAt": null,
"updatedAt": null,
"additionalData": {}
},
{
"id": "5d6332d0-c4bf-46a4-a721-1176ff7eb823",
"status": "success",
"createdAt": "2023-08-14T15:13:39.006Z",
"additionalData": {}
}
],
"wallet": {
"id": "ddfbfcd1-d094-4136-a908-ee489e694c6e",
"ispb": "03311443",
"client": "7d8d40b2-28db-4e6c-abe8-f0ee2520b3c0",
"status": "ready",
"clientId": "7d8d40b2-28db-4e6c-abe8-f0ee2520b3c0",
"accountId": "92bc81ae-f7bf-4437-ad58-9dd61b1ff4c4",
"createdAt": "2022-09-20T14:24:29.109Z",
"deletedAt": null,
"updatedAt": null,
"bankBranch": "0001",
"bankNumber": "10000052202",
"isPixoleto": false,
"additionalData": {},
"notificationUrl": "https://webhook-site-staging.bitcapital.teleport.sh/8918b4b9-572f-4820-a955-254dd615c62c"
},
"walletId": "ddfbfcd1-d094-4136-a908-ee489e694c6e",
"createdAt": "2023-08-14T15:13:36.733Z",
"updatedAt": "2023-08-14T15:13:39.003Z",
"endToEndId": "E03311443202308141513nkzVjtw0GHB",
"destination": {
"name": "Cliente Externo ISPB BACEN SANDBOX",
"type": "personal",
"taxId": "40422863807",
"account": {
"ispb": "99999004",
"type": "checking",
"bankBranch": "8008",
"bankNumber": "295761"
},
"taxIdHash": "c6535ac9eac51e9385fd4c6a20c768fcdd96c17c2e00e5bb3f1f1c6bfc4b5b9b"
},
"derivativeId": null,
"instructionId": null,
"additionalData": {
"bank": {
"bank": "99999004",
"name": "Cliente Externo ISPB BACEN SANDBOX",
"taxId": "40422863807",
"agency": "8008",
"account": "295761"
},
"description": "PIX-OUT de 1.44 para uma conta ISPB SANDBOX BACEN",
"authorizerId": "30b1924e-5436-4a9f-b37f-ca5f864480fb",
"clientWalletId": "ddfbfcd1-d094-4136-a908-ee489e694c6e"
},
"idempotenceKey": "IK5520750bcb5c4bd685742d3b12ff432d",
"clientExternalId": "KAIbc57a2e3359b4ad6ba8ca5f4a728f607",
"initiationMethod": null,
"externalTransactionId": "6ae45b53-f3d8-4e54-b327-1818df47830d"
}
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
{
"walletId": "6cdc6601-f85f-43d1-bad0-2df4f136cf65",
"amount": "1.15",
"wallet": {
"bankNumber": "10000055120",
"notificationUrl": "http://ipn-stg.checkoutogate.com/api/bitcapital_pix/ip/ipn",
"createdAt": "2023-08-23T16:13:25.240Z",
"accountId": "fcc8615d-6e2b-4f9f-a860-0ad65367c3e4",
"clientId": "2328dacf-8eb7-47c9-8324-ee164cd1b6a3",
"isPixoleto": false,
"bankBranch": "0001",
"client": "2328dacf-8eb7-47c9-8324-ee164cd1b6a3",
"id": "6cdc6601-f85f-43d1-bad0-2df4f136cf65",
"ispb": "03311443",
"status": "ready"
},
"destination": {
"taxId": "18773832000106",
"name": "company br",
"type": "corporate",
"account": {
"bankNumber": "10000097520",
"bankBranch": "0001",
"type": "payment",
"ispb": "03311443"
}
},
"clientExternalId": "00000000000000000000000000000004982",
"source": {
"taxId": "18773832987876",
"type": "corporate",
"account": {
"bankNumber": "10000055187",
"bankBranch": "0001",
"type": "payment",
"ispb": "03311443"
}
},
"type": "deposit_refund",
"endToEndId": "E03311443202308241613oka9IusrEiX",
"states": [
{
"createdAt": "2023-08-24T16:13:07.165Z",
"id": "9479b9a2-ad83-4179-a184-a438c077a939",
"additionalData": {
"reason": "PIX IN not accepted due to issuer and payer CPF divergence."
},
"status": "success"
},
{
"createdAt": "2023-08-24T16:13:05.667Z",
"id": "d755749f-6bf1-43b0-b38b-cc60154374b7",
"status": "pending"
}
],
"createdAt": "2023-08-24T16:13:05.658Z",
"initiationMethod": "QRDN",
"instructionId": "D03311443202308241613baM7wNlQ6k2",
"id": "4e308b85-feef-4e96-9ec0-17fe3f22dbb1",
"externalTransactionId": "58a65d43-48e6-46be-9b42-6c4b68053f1b",
"derivativeId": "d3038b9b-5c20-4798-983b-6b0703962427",
"status": "success"
}
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
{
"amount": "0.02",
"wallet": {
"bankNumber": "10000000091",
"notificationUrl": "https://webhook-site.bt-production.app/f3f538de-68b5-4a12-a81e-e1c977a856f0",
"createdAt": "2022-08-26T15:21:36.272Z",
"accountId": "baf0a04f-4185-4819-b41b-7bd21ceff131",
"clientId": "66b7be28-33d1-44a5-b56d-9ce6ce6cc80b",
"isPixoleto": false,
"bankBranch": "0001",
"client": {
"createdAt": "2022-08-26T15:21:35.982Z",
"taxId": "29079725000107",
"name": "BIT CAPITAL LTDA",
"id": "66b7be28-33d1-44a5-b56d-9ce6ce6cc80b",
"type": "corporate",
"status": "active"
},
"id": "22955a54-5252-40b7-927f-44a9ed7f52ad",
"ispb": "03311443",
"updatedAt": "2023-08-02T20:57:34.368Z",
"status": "ready"
},
"destination": {
"account": {
"bankNumber": "10000000091",
"bankBranch": "0001",
"ispb": "03311443"
}
},
"source": {
"account": {
"ispb": "18236120"
}
},
"clientExternalId": "KAI26206ba278da482eb23f436790afd921",
"type": "withdrawal_refund",
"endToEndId": "E03311443202308140930vxbF8MS0Tb9",
"states": [
{
"createdAt": "2023-08-14T09:32:54.164Z",
"id": "451a87b1-8b78-40b3-8d40-416e9c39c7e9",
"status": "pending"
},
{
"createdAt": "2023-08-14T09:32:54.169Z",
"id": "1d5f769b-b1f1-45a9-8a83-82dcc2aa2c9f",
"status": "success"
}
],
"createdAt": "2023-08-14T09:32:54.163Z",
"instructionId": "D18236120202308140932s01f5e8ac80",
"id": "d2f12dab-1801-4cbc-bcd3-8c8bafd46db1",
"externalTransactionId": "895821df-b667-462e-9cb3-7e73a239a816",
"derivativeId": "c15c482d-0e42-4077-b8c2-7bd2cb6a14bd",
"status": "success"
}
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 3 months ago