Endpoints
Flow Overview
1
Look up bank codes
Call
GET /v1/bank/list to get CEFTS bank codes. This is a one-time reference — cache the list and reuse it.2
Create or retrieve end-user
Call
POST /v1/aggregator/user once per end-user. Safe to call on every offramp — returns the existing record if the user already exists.3
Register their bank account
Call
POST /v1/aggregator/user/:id/bank-account to add a Sri Lankan bank account. Store the returned userBankId.4
Lock an FX rate
Call
GET /v1/aggregator/quote with the USDT amount. The returned fxLockId is valid for 60 seconds.5
Initiate the transfer
Call
POST /v1/aggregator/offramp with the fxLockId, userId, and userBankId.6
Poll status or receive webhook
Call
GET /v1/aggregator/offramp/:id to check status, or provide a webhookUrl to receive payment.completed / payment.failed events.Authentication
All endpoints require HMAC authentication:x-api-key: Your API key ID (e.g.ak_live_xxx)x-timestamp: Current Unix timestamp in millisecondsx-signature: HMAC-SHA256 signature
List Supported Banks
Returns all active Sri Lankan banks and their CEFTS codes. Use this to look up thebankCode required when registering a bank account.
Example Request
Example Response
Response Fields
Create or Retrieve User
Upserts an end-user by your internal user ID. Returns the existing record if the user already exists.Request Body
CeyPay only stores the
externalUserId you provide. No personal or identifying information about your end-users is collected or retained on our end.
Example Request
Example Response
Response Fields
Add Bank Account
Registers a Sri Lankan bank account for an end-user. Returns auserBankId used when creating offramps. A single end-user can have multiple bank accounts registered — each gets its own userBankId.
Path Parameters
Request Body
Example Request
Example Response
Response Fields
List Bank Accounts
Returns all registered bank accounts for an end-user.Path Parameters
Example Request
Example Response
Get a Quote
Fetches the current USDT/LKR exchange rate and locks it for 60 seconds. Use the returnedfxLockId in POST /v1/aggregator/offramp before it expires.
Query Parameters
Example Request
Example Response
Response Fields
Create Offramp
Initiates a USDT → LKR bank transfer. This endpoint is idempotent onexternalRef — submitting the same key twice returns the original offramp unchanged.
Request Body
Example Request
Example Response
Response Fields
Get Offramp
Retrieve the current status of an offramp.Path Parameters
Example Request
Example Response (Completed)
Error Responses
Offramp Status
Webhooks
SetwebhookUrl in your offramp request to receive a notification when the transfer settles or fails. Webhooks use the same ED25519 signature scheme as other CeyPay webhooks — see Webhook Integration Guide for signature verification details.
payment.completed
Fired when the bank transfer settles successfully.payment.failed
Fired when the bank transfer cannot be completed.Webhook Headers
Retry Policy
CeyPay retries on connection timeout, non-2xx responses, or network errors. Respond with
200 immediately and process the event asynchronously.
Idempotency
POST /v1/aggregator/offramp is idempotent on externalRef. If you submit the same key twice (e.g. after a network timeout), CeyPay returns the original offramp unchanged — no duplicate transfer is created.
Use a stable, meaningful key such as your internal withdrawal ID:
Error Responses
See Error Codes for detailed error handling.
Reconciliation Reports
Two read-only endpoints are available for reconciling your float balance and offramp activity against your own records. Both endpoints are paginated and support date-range filtering.Float Balance Ledger Report
Returns a paginated log of every LKR movement on your float (top-ups, offramp debits, and refunds) together with period summary statistics.Query Parameters
Example Request
Example Response
Summary Fields
Ledger Item Fields
Offramp Transaction Report
Returns a paginated list of offramps with per-status summary statistics and a weighted average FX rate. Each row includes the partner user ID and bank details so the report is self-contained for export.Query Parameters
The summary block always covers the full date window regardless of the
status filter, so all per-status breakdowns remain visible even when the item list is filtered to a single status.
Example Request
Example Response
Summary Fields
Offramp Item Fields
Related Documentation
- Authentication — HMAC signature details
- Webhooks — Signature verification and retry policy
- Rate Limits — API rate limiting
- Errors — Error codes reference