PixIn Webhook (Deposits)

Receive automatic notifications whenever an incoming (PIX) transaction changes status.

Endpoint and Authentication

POSTURL set by you through the /api/SendWebhook route

Example: https://mysite.com/api/webhook/baanko

Headers Sent

Headers

Content-Type: application/json
X-Webhook-Event-Id: <event id, the same on every retry>
X-Webhook-Correlation-Id: <id>
X-Webhook-Sent-At: 2025-11-27T11:07:15Z
X-Webhook-Attempt: 1
X-Webhook-Secret: <your webhook secret, when configured>

Use X-Webhook-Event-Id to ignore duplicates, and compare X-Webhook-Secret with the secret you configured to make sure the call came from Baanko.

QR Code Created / Awaiting Payment

Webhook Payload - Awaiting

{
  "object": "transaction",
  "type": "cashin",
  "status": "awaiting",
  "companyId": "7719342c-a3f4-443b-9c8c-a06ec7a43b7d",
  "transactionId": "cmw4csk200mfy6nr3eibya4va",
  "subTransactionId": 1607988,
  "externalRef": "ORDER-10001",
  "method": "pix",
  "value": 500,
  "amount": 5,
  "currency": "BRL",
  "providerTxId": "cmw4csk200mfy6nr3eibya4va",
  "endToEndId": null,
  "providerEndToEndId": null,
  "pixKey": null,
  "providerAmount": 5,
  "providerCreditedAt": null,
  "providerPayload": null,
  "payer": { "name": null, "documentId": null, "document": null, "bankName": null, "ispb": null, "issuer": null, "number": null, "accountType": null },
  "receiver": { "name": null, "documentId": null, "document": null, "ispb": null, "issuer": null, "number": null, "accountType": null },
  "createdAt": "2026-11-05T23:15:02.118",
  "updatedAt": "2026-11-05T23:15:02.118+00:00",
  "processedAt": "2026-11-05T23:15:02Z"
}

Payment Confirmed

Webhook Payload - Successful

{
  "object": "transaction",
  "type": "cashin",
  "status": "successful",
  "companyId": "7719342c-a3f4-443b-9c8c-a06ec7a43b7d",
  "transactionId": "6dcf2aee0d6148e1a12b78db78",
  "subTransactionId": 41394,
  "externalRef": "LEAD-1764252408748_52740",
  "method": "pix",
  "value": 500,
  "amount": 5,
  "currency": "BRL",
  "endToEndId": "E22896431202511271407sjUGQflhcVE",
  "providerEndToEndId": "E22896431202511271407sjUGQflhcVE",
  "providerTxId": "6dcf2aee0d6148e1a12b78db78",
  "pixKey": "c32361fa-44de-4be7-815f-0e782a10860c",
  "providerAmount": 5,
  "providerCreditedAt": "2025-11-27T11:07:14.997603",
  "providerPayload": "{\"id\":\"6dcf2aee...\",\"status\":\"paid\"}",
  "localInstrument": null,
  "transactionType": null,
  "creditDebitType": null,
  "remittanceInformation": null,
  "payer": {
    "name": "JOHN EXAMPLE",
    "documentId": "12345678909",
    "document": "12345678909",
    "bankName": null,
    "ispb": null,
    "issuer": null,
    "number": null,
    "accountType": null
  },
  "receiver": {
    "name": null,
    "documentId": "48969523000177",
    "document": "48969523000177",
    "ispb": null,
    "issuer": null,
    "number": null,
    "accountType": null
  },
  "createdAt": "2025-11-27T11:05:40.218",
  "updatedAt": "2025-11-27T11:07:15.104+00:00",
  "processedAt": "2025-11-27T11:07:14Z"
}

Field Descriptions

companyIdstring (UUID)Your company ID

transactionIdstringThe id returned when you created the transaction

subTransactionIdnumberInternal Baanko ID of the transaction

externalRefstring | nullYour reference sent on creation

valueintegerAmount in cents (500 = R$ 5.00)

amountnumberAmount in reais (5 = R$ 5.00)

endToEndIdstringUnique PIX transaction identifier (E2E)

providerEndToEndIdstringE2E returned by the provider

providerTxIdstringTransaction ID at the provider

pixKeystringPIX key that received the payment

providerAmountnumberAmount in reais returned by the provider

providerCreditedAtstringDate/time the provider credited the payment

providerPayloadstring | nullRaw payload returned by the provider, as a JSON string

payerobjectPayer data (who sent the PIX)

receiverobjectReceiver data (your company)

createdAtstringWhen the transaction was created

updatedAtstringLast update of the transaction

processedAtstringProcessing date/time (UTC)

Possible Statuses

awaitingAwaiting payment

successfulPaid / confirmed

failurePayment failed

refundedRefunded / returned

Automatic Retries

OKThe first delivery is immediate. Reply with any 2xx status within 10 seconds to confirm receipt.

OKAny other response, or a timeout, is retried up to 16 times at growing intervals (5s, 15s, 30s, 1 min, 2 min, 5 min ... up to 24 h), for about 2 days in total.

OKRetries keep the same X-Webhook-Event-Id, so you can safely skip an event you already processed. X-Webhook-Attempt tells you which attempt it is.

Response Example

Response

{ "received": true, "idempotent": false }

Handler Example

Node.js / Express

app.post('/webhook/baanko', async (req, res) => {
  const {
    type,
    status,
    transactionId,
    value,
    amount,
    endToEndId,
    payer,
    providerCreditedAt
  } = req.body;
  const eventId = req.headers['x-webhook-event-id'];
  // Check the secret you configured
  if (req.headers['x-webhook-secret'] !== process.env.BAANKO_WEBHOOK_SECRET) {
    return res.status(401).end();
  }
  // Skip events that were already processed
  const processed = await checkIdempotency(eventId);
  if (processed) {
    return res.status(200).json({ received: true, idempotent: true });
  }
  if (type === 'cashin' && status === 'successful') {
    console.log(`Payment received: R$ ${amount}`);
    console.log(`Amount in cents: ${value}`);
    console.log(`Payer: ${payer.name}`);
    console.log(`E2E ID: ${endToEndId}`);
    console.log(`Credited at: ${providerCreditedAt}`);
    // Process the payment...
    await processPayment(transactionId, value);
  }
  // Mark as processed
  await markAsProcessed(eventId);
  res.status(200).json({ received: true, idempotent: false });
});