Dynamic Settlement

Choose the currency each payment and deposit account is settled into.

Open the interactive version or read this guide as markdown.

API reference

• POST /api/v1/payments: Create a payment
• POST /api/v1/deposits/accounts: Create a deposit account

Price in one currency, let your customer pay in whichever token they hold, and choose the currency you end up with. Settlement currency is set per payment and per deposit account, so a single account can take NGN prices and hold USDT, or take USDT deposits from one customer and NGN from another.

How it works

1. Set an account currency in the dashboard. Every payment settles into it unless you say otherwise.
2. Override it on a single payment by passing settlementCurrency to POST /api/v1/payments.
3. Override it for a deposit account by passing settlementCurrency to POST /api/v1/deposits/accounts. It applies to every deposit into that account.
4. Read settlements.currency on the payment to see what it settled into, and settlements.net for the amount credited.

The currency is fixed when the payment is created. Changing your account currency later does not move a payment that is already open.

settlementCurrency takes any supported balance, e.g. USDT. Deposit accounts also take default, where the deposited token decides.

Pricing and settlement are separate

currency is what you price in and what your customer sees. settlementCurrency is what you are paid in. They do not have to match.

POST /api/v1/payments
{
  "amount": "10000.00",
  "currency": "NGN",
  "settlementCurrency": "USDT",
  "customer": { "email": "customer@example.com" }
}

The customer is quoted 10,000 NGN, pays in the token they chose, and your USDT balance is credited. When the two currencies differ, settlements.gross.conversionRate records the rate used.

Deposit accounts

On default, the deposited token decides. Supported balances are credited directly, e.g. a USDT deposit credits your USDT balance. Other tokens are converted, e.g. an ETH deposit lands as USDT.

Set a currency and the account decides instead: every deposit is settled into it, converting where needed. Your parent account is always default.

POST /api/v1/deposits/accounts
{
  "customerId": "123e4567-e89b-12d3-a456-426614174000",
  "settlementCurrency": "USDC"
}

Use cases

• Pricing in local currency while holding stablecoins
• Holding NGN for local payouts without managing conversions yourself
• Giving each customer a deposit account that settles in the currency they fund you in

NGN has no on-chain token, so a crypto deposit into an NGN deposit account always converts.