Callbacks¶

When a settlement reaches a terminal state (executed or failed), Bitlipa sends a POST request to the partner's callback_url provided at confirmation.

Callback body¶

Field	Type	Description
`tx_id`	string	Bitlipa transaction ID.
`external_tx_id`	string	Partner's transaction reference.
`status`	string	`executed` or `failed`.
`tx_hash`	string	Blockchain hash (when executed).
`chain`	string	Blockchain network (CAIP-2).
`destination_amount`	number	Net amount delivered (after fee).
`platform_fee`	number	Fixed platform fee (in destination currency).
`failure_reason`	string	Error description (when failed).
`executed_at`	string	Execution timestamp (when executed).

About destination_amount

This is the net amount actually delivered to the wallet, after platform_fee deduction.

Approval callback¶

If a settlement required manual approval and you supplied a callback_url when creating it, Bitlipa POSTs an approval callback to that URL the moment an admin approves it — so you can prompt the merchant to confirm without polling.

This callback is distinct from the terminal (executed / failed) callback above; it fires earlier, when the settlement becomes confirmable.

Field	Type	Description
`tx_id`	string	Bitlipa transaction ID.
`external_tx_id`	string \| null	Partner's transaction reference (null until confirmation).
`event`	string	`settlement.approved`.
`status`	string	`approved`.
`chain`	string	Blockchain network (CAIP-2).
`source_amount`	integer	Gross source amount (minor units).
`destination_amount`	number	Net amount to be delivered (after fee), at the re-priced rate.
`platform_fee`	number	Fixed platform fee (in destination currency).
`expires_at`	string	New quote expiration — confirm before this time.

{
  "tx_id": "tx_abc123def456",
  "external_tx_id": null,
  "event": "settlement.approved",
  "status": "approved",
  "chain": "eip155:137",
  "source_amount": 5000000,
  "destination_amount": 382.50,
  "platform_fee": 2.50,
  "expires_at": "2024-01-15T11:05:00Z"
}

After receiving it, call POST /confirm before the new expires_at. The same retry policy below applies.

Expected response¶

Return HTTP 200 with an acknowledgment:

{
  "received": true
}

Retry policy¶

Attempt	Delay
1	Immediate
2	1 minute
3	5 minutes
4	30 minutes
5	2 hours
6	12 hours

Callbacks time out after 30 seconds.
Success = any HTTP 2xx response.
After 6 failed attempts, the callback is marked as undelivered.
Undelivered callbacks can be retrieved via GET /settlements/:tx_id.