Callbacks (Webhooks)

SettleRamp is asynchronous by design. Partners can optionally provide callback URLs so SettleRamp can push status updates for KYC verifications and order lifecycle events. Partners should still support polling as a fallback for reliability.

Where Callbacks Are Configured

There are two callback fields, each provided at the time of resource creation. SettleRamp does not expose a webhook endpoint itself -- instead, it POSTs to URLs you provide.

1. KYC Status Callback

Provided during KYC submission in the request body of POST {{apiUrl}}/api/partner/kyc. The field name is statusCallbackUrl.

{
  "...": "...",
  "statusCallbackUrl": "https://your-domain.com/settle-ramp/kyc-callback"
}

2. Order Lifecycle Callback

Provided when creating a deposit or withdraw order. The field name is callbackUrl, defined in the request body for:

• POST {{apiUrl}}/api/orders/deposits
• POST {{apiUrl}}/api/orders/withdraws

{
  "...": "...",
  "callbackUrl": "https://your-domain.com/settle-ramp/order-callback"
}

Delivery Behavior

• Callback is an HTTP POST to the provided URL.

• Triggered on relevant lifecycle changes (KYC status changes, order status changes).

• Callbacks are best-effort; partner must also support polling.

• Partner endpoint should respond quickly (e.g., under 2 seconds).

• Partner should return HTTP 2xx to acknowledge receipt.

Recommended Partner Implementation

• Validate requests server-side (no client-side callback handlers).

• Implement idempotency on your side (same event may be delivered more than once).

• Store the raw payload for troubleshooting.

• Use correlation keys (like orderId / kycId / transactionRef) to match internal records.

• Return 200 OK immediately and process asynchronously (queue/job).

Example Callback Payloads

Below are placeholder blocks for the callback payloads. The exact schema and event types will be documented in a future revision.

KYC Callback Payload

{
  // payload example pending
}

Order Callback Payload

{
  // payload example pending
}

Polling Fallback

If callbacks fail or are delayed, partners can query status directly using the following endpoints:

• KYC status: GET {{apiUrl}}/api/partner/kyc/{{_kycId}}
• Deposit order status: GET {{apiUrl}}/api/orders/deposits/{{_dOrderId}}
• Withdraw order status: GET {{apiUrl}}/api/orders/withdraws/{{_wOrderId}}

Next Steps