Skip to main content

Endpoints

The Offramp API is only available to merchants with the AGGREGATOR role. Contact support@ceypay.io to enable this for your account.

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.
Steps 2 and 3 only need to run once per end-user and bank account. Both IDs are reusable across multiple offramps.

Authentication

All endpoints require HMAC authentication:
  • x-api-key: Your API key ID (e.g. ak_live_xxx)
  • x-timestamp: Current Unix timestamp in milliseconds
  • x-signature: HMAC-SHA256 signature

List Supported Banks

Returns all active Sri Lankan banks and their CEFTS codes. Use this to look up the bankCode 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 a userBankId 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 returned fxLockId in POST /v1/aggregator/offramp before it expires.

Query Parameters

Example Request

Example Response

Response Fields

Submit the offramp before expiresAt. Expired or already-used fxLockId values are rejected. Fetch a fresh quote if the lock expires before you submit.

Create Offramp

Initiates a USDT → LKR bank transfer. This endpoint is idempotent on externalRef — 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

Set webhookUrl 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