Pay-In

After you generate a QR Code with our endpoint, kamiPay will keep you updated on the progress of this charge using our webhooks so you don't need to manually check status endpoints from your backend.

Handling Webhook Responses

In the normal flow, a charge's webhooks arrive in order: processing, then done. Only a redelivery can reverse them: a replay you request, or our automatic retry after a delivery to your endpoint failed. Handle each webhook by its status: done or failed wins over processing.

The following are all the possible notification status you will receive:

Processing

Release the payer when you receive processing. It means kamiPay has received the BRL and the payment is guaranteed, so don't make the payer wait for done. done follows when the USDt reaches your wallet, with its transaction hash; until then tx_id is null. In the rare case done doesn't follow, contact support with the kamipay_id.

{
  "pix_id": "ptxr_01kr3m9p7n2s4d8h6e5b3t7w1k",
  "status": "processing",
  "tx_id": null,
  "timestamp": "2026-04-27 15:48:07.129513-03:00",
  "type": "charge",
  "qr_type": "dynamic",
  "kamipay_id": "dqr_01kr3m9q5h7w2v4n6b8s3d5e9p",
  "data": {
    "bank_txid": "E29384756202604271548aB7cD3xY9mZ",
    "bank_account_nr": "29384756-0001-0001349872",
    "internal_pix_id": "8a3f1c9d72b46e08fd5a912ec47b3f06",
    "amount_brl": "5.28",
    "amount_usdt": "1.033355",
    "address_out": "0x7a3F9b2C1e8D5462bA9c7F3e6D85907df41A2c3B",
    "name": "Satoshi Nakamoto"
  }
}

Done

Done status means the USDt was settled to your wallet: tx_id carries its transaction hash on Polygon, which you can reconcile on.

{
  "pix_id": "ptxr_01kr3m9p7n2s4d8h6e5b3t7w1k",
  "status": "done",
  "tx_id": "0xa3f9b2c1e7d4865094bd28fa1c3e6b85907df42a3b9c1de80f5a672bc41e9d3f",
  "timestamp": "2026-04-27 15:51:40.171821-03:00",
  "type": "charge",
  "qr_type": "dynamic",
  "kamipay_id": "dqr_01kr3m9q5h7w2v4n6b8s3d5e9p",
  "data": {
    "bank_txid": "E29384756202604271548aB7cD3xY9mZ",
    "bank_account_nr": "29384756-0001-0001349872",
    "internal_pix_id": "8a3f1c9d72b46e08fd5a912ec47b3f06",
    "amount_brl": "5.28",
    "amount_usdt": "1.033355",
    "address_out": "0x7a3F9b2C1e8D5462bA9c7F3e6D85907df41A2c3B",
    "name": "Satoshi Nakamoto"
  }
}

Failed

failed is an atypical case, not a normal outcome, but your integration must handle it. A charge doesn't end failed in the normal flow: it goes from processing to done. It can still arrive in atypical cases, such as the same QR code being paid twice through a provider error. It means the charge failed and the money is returned to the payer's bank.

{
  "pix_id": "ptxr_01kr4n8t6m3q5y2x9d7b1f4j8h",
  "status": "failed",
  "tx_id": null,
  "type": "charge",
  "timestamp": "2026-04-29 11:42:18.503924-03:00"
}

The pix_id is the same identifier that was returned as operation_id in the response of the create_dynamic_pix endpoint when you created the QR code charge. You can use this ID to track the payment throughout its lifecycle.

Always validate the webhook signature using the method described in the Introduction before processing any webhook events.

Data Fields

These fields of data follow fixed rules, and read the same in Tx Status → Pay-In, whichever way kamiPay detected the payment:

Field	Description
`amount_brl`	The BRL paid, as a string with 2 decimals: `"5.00"`.
`amount_usdt`	The USDt the charge settles, as a string with 6 decimals: `"0.928010"`.
`bank_account_nr`	The payer's account: the bank's ISPB (8 digits), the branch (4 digits) and the account, zero-filled to at least 10 digits, joined by `-`: `"29384756-0001-0001349872"`. On some gateways, it ends in `-` and the account's check digit: `"18236120-0001-0000987654-4"`.
`address_out`	The wallet the USDt settles to, for every charge type, sales on a Printed Dynamic QR included.