PixIn Webhook (Deposits)

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

Endpoint and Authentication

POSTDefined by the customer on the /api/SendWebhook route

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

The URL must use HTTPS, port 443 and a public domain. Private network or local IP addresses are rejected.

Headers Sent

Headers

Content-Type: application/json
X-Idempotency-Key: <uuid>
X-Webhook-Event-Id: <uuid>   (same value)
X-Webhook-Correlation-Id: <id>
X-Webhook-Sent-At: 2025-11-27T11:07:15Z
X-Webhook-Secret: <secret>   (only if you registered a secret on the webhook)

Use X-Idempotency-Key (same value as X-Webhook-Event-Id) to detect repeated deliveries of the same event. X-Webhook-Secret is the secret you registered on the webhook, sent as is so you can check it.

How to Configure

In the dashboard: open the Webhooks menu, create a webhook and enter the URL, the scope (cash-in, cash-out or both) and the statuses you want to receive (awaiting, pending, success, failure and refund).

Through the API: use POST /api/SendWebhook with your X-Client-Id and X-API-Key. To change it, use PUT /api/SendWebhook/{id}.

POST /api/SendWebhook

{
  "companyId": "2f3c1c0e-6a52-4a0f-9d34-6a7b3f6f2b10",
  "sendLink": "https://mysite.com/api/webhook/respawn",
  "webhookSecret": "your-own-secret-up-to-500-characters",
  "onlyTransaction": false,
  "onlyWithdraw": false,
  "awaiting": true,
  "pending": true,
  "successful": true,
  "failure": true,
  "refunded": true
}

You only receive the statuses you selected. The postbackUrl field on transaction creation does not replace this configuration.

How to Verify the Origin

The webhook body carries no HMAC signature. To be sure the notice came from Respawn Pay, combine:

1. Confirm the event through the API: look up the transaction or withdrawal with your credentials and trust only that response.

2. Register a webhookSecret (optional field of the configuration). It arrives in every notice in the X-Webhook-Secret header; compare it with yours and reject if it differs.

3. Allow the source IPs 144.126.159.43 (IPv4) and 2605:a140:2365:9572::1 (IPv6).

QR Code Creation / Awaiting payment

Webhook Payload - Awaiting

{
  "object": "transaction",
  "type": "cashin",
  "status": "awaiting",
  "companyId": "2f3c1c0e-6a52-4a0f-9d34-6a7b3f6f2b10",
  "transactionId": "6dcf2aee0d6148e1a12b78db78",
  "subTransactionId": 234,
  "externalRef": "LEAD-1762647077342_322066",
  "method": "pix",
  "value": 500,
  "amount": 5,
  "currency": "BRL",
  "providerTxId": "6dcf2aee0d6148e1a12b78db78",
  "endToEndId": null,
  "providerEndToEndId": null,
  "pixKey": null,
  "providerAmount": 5,
  "providerCreditedAt": null,
  "providerPayload": null,
  "payer": { "name": "Joao Silva", "document": "12345678900", "documentId": "12345678900" },
  "receiver": { "name": null, "document": null, "documentId": null },
  "createdAt": "2025-11-09T00:10:00.000000",
  "updatedAt": "2025-11-09T00:10:00.000000",
  "processedAt": "2025-11-09T00:10:00Z"
}

Payment Confirmed

Webhook Payload - Successful

{
  "object": "transaction",
  "type": "cashin",
  "status": "successful",
  "companyId": "2f3c1c0e-6a52-4a0f-9d34-6a7b3f6f2b10",
  "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": "{... JSON text from the provider ...}",
  "localInstrument": null,
  "transactionType": null,
  "creditDebitType": null,
  "remittanceInformation": null,
  "payer": {
    "name": "MARIA SILVA SANTOS",
    "documentId": "50651470862",
    "document": "50651470862",
    "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:06:58.120000",
  "updatedAt": "2025-11-27T11:07:15.010000",
  "processedAt": "2025-11-27T11:07:14.997603Z"
}

Field Descriptions

companyIdstringYour company ID (UUID)

transactionIdstringTransaction ID, the same id returned on creation

subTransactionIdnumberInternal transaction ID

externalRefstringYour reference, sent in customer.externalRef on creation

methodstringPayment method (pix)

valuenumberAmount 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

providerCreditedAtstringCredit date/time at the provider

providerPayloadstringPayload returned by the provider, as JSON text (parse it if you need inner fields). Null until the provider confirms the payment

payerobjectPayer data. Before payment it holds the customer name and document you sent (or the placeholders, see Create Transaction); after payment, the data reported by the bank

receiverobjectReceiver data (your company)

localInstrumentstringPayment instrument reported by the provider (when available)

transactionTypestringTransaction type reported by the provider (when available)

creditDebitTypestringCredit or debit, reported by the provider (when available)

remittanceInformationstringMessage sent by the payer (when available)

createdAtstringTransaction creation date/time

updatedAtstringLast update date/time

processedAtstringProcessing date/time

Possible Statuses

awaitingAwaiting payment

pendingProcessing

successfulPaid / confirmed

failurePayment failure, canceled or expired transaction

refundedRefunded / returned

You only receive the webhook for the statuses enabled in your webhook configuration. There is no expired transaction status: expired, canceled and chargeback arrive as failure.

Automatic Retry

OKUp to 3 consecutive attempts, 1 second and 2 seconds apart, with a 15-second limit per attempt

OKReply with HTTP 2xx to confirm. Any other code, or a body with received, success or ok equal to false, or with status failed, counts as a failure and triggers a new attempt

OKAvoid processing the same event twice by using the X-Idempotency-Key header

Response Example

Response

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

Handler Example

Node.js / Express

app.post('/webhook/respawn', async (req, res) => {
  const { 
    type, 
    status, 
    transactionId, 
    value, 
    amount,
    endToEndId,
    payer,
    providerCreditedAt 
  } = req.body;
  const idempotencyKey = req.headers['x-idempotency-key'];
  // Check whether this event was already processed
  const processed = await checkIdempotency(idempotencyKey);
  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(idempotencyKey);
  res.status(200).json({ received: true, idempotent: false });
});