Partner-Provided Deposit Flow
When using partner-provided settlement for deposits, the partner executes the crypto leg after Settle confirms fiat receipt. This page describes the modified lifecycle, the webhook event, and the request additions.
Modified Lifecycle
User pays fiat
The end user initiates a fiat payment (e.g. bank transfer in ARS).
Settle confirms fiat receipt
Settle detects the incoming bank transfer and confirms the fiat leg.
Settle sends FiatReceived event
A webhook event is sent to the partner's settlementWebhookUrl with order and settlement details.
Partner sends crypto
The partner transfers the crypto asset to the destination address provided in the order.
Settle confirms settlement
Settle verifies the on-chain transaction and marks the order as completed.
To activate partner-provided settlement, add the following fields to your deposit creation request (existing fields remain unchanged):
/settle/api/orders/depositsAdditional Fields
settlementMode (string, "partner"), settlementWebhookUrl (string, your settlement event endpoint)
Settlement Event Webhook
When Settle confirms fiat receipt, a webhook event is sent to the settlementWebhookUrl you provided during order creation. The event includes all details the partner needs to execute the crypto settlement.
{settlementWebhookUrl}Headers
X-Event-Id: unique-event-idX-Timestamp: unix-timestampX-Signature: HMAC_SHA256(secret, timestamp + rawBody)Body Fields
event, orderId, transactionRef, fromAsset, fromAmount, toAsset, toAmount, network, settlementId, confirmSettlementUrl
Note: Order status transitions to AwaitingPartnerSettlement after the FiatReceived event is sent. If settlement is not completed within the defined window, the order may expire.
Confirm Settlement
After the partner sends the crypto to the user, call this endpoint to confirm settlement. This allows Settle to close the order and finalize the transaction. The request must include the HMAC signature headers for verification.
/settle/api/orders/deposits/{orderId}/confirm-settlementHeaders
Content-Type: application/jsonX-Timestamp: unix-timestampX-Signature: HMAC_SHA256(secret, timestamp + rawBody)Request Body Fields
settlementId, cryptoTxHash, confirmedAt (ISO 8601)
Status Transitions
Partner-provided deposit orders progress through the following statuses:
| Status | Description |
|---|---|
AwaitingClientPayment | Initial status. The order is created and waiting for the user to complete the fiat transfer. |
AwaitingPartnerSettlement | Fiat received. Settle notifies the partner via webhook and awaits crypto settlement. |
Completed | Partner has sent the crypto and confirmed settlement via the confirmSettlementUrl endpoint. |