Settlement

When a batched settlement is finalized, kamiPay sends a settlement.settled webhook to your configured endpoint. The payload contains the aggregate amounts for the settlement and the full list of charges that were included in it, so you can reconcile each individual charge against your own system without an extra API round-trip. One webhook delivery per scheduled batch summarises the disbursement and lists every charge that was part of it.

settlement.settled

Sent once per settlement when the underlying transfer is confirmed — provider confirmation for Fiwind batched, or the bulk transfer being mined for blockchain batched — and the settlement transitions to DONE.

The payload shape is identical for both modes, but the currencies and amounts differ. The Fiwind batched payload settles in ARS (with the USDT amount kamiPay moved to the provider on the source_* fields). The blockchain batched payload settles in USDt and carries no ARS fields — there is no requote, and each charge's settlement_amount is in USDt.

Both payloads also carry a refunds[] array listing the pay-in refunds that were deducted from this settlement (documented in full further down). It is always present — an empty array when there were none. When it is non-empty, source_amount is lower than source_net_price by the total deducted:

Σ charges[].settlement_amount  −  Σ refunds[].deduction_amount  =  source_amount

{
  "event": "settlement.settled",
  "settlement_id": 12345,
  "provider_settlement_id": "psid_8f3c1d2a9e",
  "external_settlement_id": "0xa3f9b2c1e7d4865094bd28fa1c3e6b85907df42a3b9c1de80f5a672bc41e9d3f",
  "amount": 99325.0,
  "currency_id": 32,
  "source_amount": 68.5,
  "source_currency_id": 9999,
  "source_net_price": 68.3,
  "settled_at": "2026-05-13T15:00:42Z",
  "charges": [
    {
      "kamipay_id": "txc_01j3t9fxqffrva9s8d1ekm4g3v",
      "external_id": "merchant-order-aaa-11112",
      "kamipay_request_id": "ptxr_01j3t9fxqffrva9s8d1ekm4g3w",
      "charged_amount": 5.28,
      "charged_currency": "BRL",
      "settlement_amount": 29750.0,
      "settlement_currency": "ARS"
    },
    {
      "kamipay_id": "txc_01j4a2x6m1d8h6e5b3t7w1ku9k",
      "external_id": "merchant-order-aaa-11113",
      "kamipay_request_id": "ptxr_01j4a2x6m1d8h6e5b3t7w1ku9l",
      "charged_amount": 7.04,
      "charged_currency": "BRL",
      "settlement_amount": 39575.0,
      "settlement_currency": "ARS"
    },
    {
      "kamipay_id": "txc_01j4c8e7n3p2q5r9w1m6b8y4hj",
      "external_id": null,
      "kamipay_request_id": "ptxr_01j4c8e7n3p2q5r9w1m6b8y4hk",
      "charged_amount": 5.28,
      "charged_currency": "BRL",
      "settlement_amount": 29750.0,
      "settlement_currency": "ARS"
    }
  ],
  "refunds": []
}

{
  "event": "settlement.settled",
  "settlement_id": 67890,
  "provider_settlement_id": "0x9c1de80f5a672bc41e9d3fa3f9b2c1e7d4865094bd28fa1c3e6b85907df42a3b",
  "external_settlement_id": "0x9c1de80f5a672bc41e9d3fa3f9b2c1e7d4865094bd28fa1c3e6b85907df42a3b",
  "amount": 57.5,
  "currency_id": 9999,
  "source_amount": 57.5,
  "source_currency_id": 9999,
  "source_net_price": 60.0,
  "settled_at": "2026-05-13T15:00:42Z",
  "charges": [
    {
      "kamipay_id": "txc_01j3t9fxqffrva9s8d1ekm4g3v",
      "external_id": "merchant-order-aaa-11112",
      "kamipay_request_id": "ptxr_01j3t9fxqffrva9s8d1ekm4g3w",
      "charged_amount": 52.8,
      "charged_currency": "BRL",
      "settlement_amount": 10.0,
      "settlement_currency": "USDt"
    },
    {
      "kamipay_id": "txc_01j4a2x6m1d8h6e5b3t7w1ku9k",
      "external_id": "merchant-order-aaa-11113",
      "kamipay_request_id": "ptxr_01j4a2x6m1d8h6e5b3t7w1ku9l",
      "charged_amount": 105.6,
      "charged_currency": "BRL",
      "settlement_amount": 20.0,
      "settlement_currency": "USDt"
    },
    {
      "kamipay_id": "txc_01j4c8e7n3p2q5r9w1m6b8y4hj",
      "external_id": null,
      "kamipay_request_id": "ptxr_01j4c8e7n3p2q5r9w1m6b8y4hk",
      "charged_amount": 158.4,
      "charged_currency": "BRL",
      "settlement_amount": 30.0,
      "settlement_currency": "USDt"
    }
  ],
  "refunds": [
    {
      "kamipay_refund_id": "rpi_5b7c2d4e6a8f0b1c3d5e7f90",
      "kamipay_id": "txc_01j4a2x6m1d8h6e5b3t7w1ku9k",
      "external_id": "merchant-order-aaa-11113",
      "kamipay_request_id": "ptxr_01j4a2x6m1d8h6e5b3t7w1ku9l",
      "refunded_amount": 13.2,
      "refunded_currency": "BRL",
      "deduction_amount": 2.5,
      "deduction_currency": "USDt"
    }
  ]
}

Top-level fields

charges[] fields

The charges[] array contains one item per charge included in the settlement, ordered by the time each charge was added to the settlement (oldest first).

refunds[] fields

The refunds[] array contains one item per pay-in refund whose amount was subtracted from this settlement. A refund is deducted from the first settlement that runs after it is confirmed — which is usually not the settlement that contained the original charge, so the kamipay_id of a refund often refers to a charge you reconciled in an earlier batch.

Reconciliation

The intended flow for merchants:

1. As charges complete, you receive a done event on the charge webhook for each one. Match it against your order using external_id and record it as collected.
2. When the settlement is finalized you receive a single settlement.settled webhook. The charges[] array carries the same external_id for every charge you previously recorded.
3. Use external_id to match each entry in charges[] back to your collected orders, and use amount (in currency_id units) to record the disbursement against your bank/wallet account.
4. If refunds[] is non-empty, match each entry back by external_id too and record the deduction against that order. The originating charge was most likely settled in an earlier batch, so expect these to reference orders you have already reconciled.

Do not derive the disbursement by summing charges[] — that gives you the gross. amount is the net figure that hits your account, and the two differ by exactly Σ refunds[].deduction_amount.

Signature validation, retries, and ordering

• Signature: every webhook is signed with the same scheme as the charge and pay webhooks. Always validate the signature before processing the payload.
• Idempotency: settlement_id is the natural idempotency key. kamiPay may retry the delivery (e.g. on a non-2xx response from your endpoint) and you may receive the same settlement.settled payload more than once. Treat repeated deliveries with the same settlement_id as no-ops after the first successful processing.
• Ordering: settlement.settled is fired after all of the per-charge done events for the charges in charges[]. You may, however, receive a settlement.settled for one settlement before all done events for charges in a different settlement, so do not assume strict cross-settlement ordering.
• Delivery channel: this event uses the same webhook endpoint and authentication configuration as your other kamiPay webhooks. No separate configuration is required.