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:

CampoDescriçã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:

CampoDescriçã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:

CampoDescriçã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:

CampoDescriçã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