Money & currency

Amounts are integers in the minor unit

Every monetary amount in every request, response, and webhook is an integer in the smallest unit of the currency.

Never use floats for money. Don’t try to be clever with division. If the value is 1250 cents USD, it’s 1250 — the API will reject 12.50 as a VALIDATION_ERROR.

If your language doesn’t have a non-float integer type for currency, use a decimal library (Python decimal, JavaScript bignumber.js, Java BigDecimal). Convert to/from cents at the API boundary, not in the middle of your code.

Supported currencies

Phase 1 (current):

The two currencies share infrastructure but are separate balances. A user has a USD wallet AND an LRD wallet, not one wallet with two currencies. Cross-currency moves (USD ↔ LRD swap) lock a rate for 60 seconds before executing.

Currency codes always required

Even when there’s only one plausible currency for an endpoint, requests must specify the currency. There is no “default currency” anywhere in the API. The currency is part of the operation’s identity.

# Always include "currency"
curl -X POST "$SOXARA_BASE/v1/api/payment-links" \
  -H "Authorization: Bearer $SOXARA_KEY" \
  -d '{"title": "…", "amount": 1250, "currency": "USD"}'

A payment link is one currency for its whole lifetime — you can’t create a pay-any-currency link, and a payment against it settles in the currency it was created with.

Cross-currency conversion isn’t exposed on this API

Soxara does move money between USD and LRD internally — cross-currency gift-card funding, wallet conversion inside the app — but there’s no merchant-API endpoint to quote or execute an FX conversion yourself today. If your integration needs one currency in and a different one out, that’s not something to build against yet; talk to us at [email protected] about your specific case.