API Concepts
The handful of rules behind every call
TransFi's API is RESTful — standard HTTP methods, JSON bodies, HTTP status codes. Eight things to know before you build.
1. One endpoint creates every order
POST /v3/orders. The orderType selects the flow. This is the single most common integration question.
| You want to… | orderType | What happens |
|---|---|---|
| Collect a payment | payin | Returns a payUrl (hosted page) or payment details (headless) |
| Collect through a wallet in the user's name | gaming | Same as payin; funds pass through a custodial wallet |
| Pay someone | payout | Delivered to a bank account, mobile wallet, QR code or crypto wallet |
| User buys crypto | onramp | User pays local currency, receives crypto in their wallet |
| User sells crypto | offramp | User sends crypto to an address TransFi issues, receives local currency |
| Add your own money — fiat | fiat_prefund | Returns bank details to transfer to |
| Add your own money — crypto | crypto_prefund | Returns a wallet address to send to |
| Convert money you hold | swap | Balance in one currency becomes another |
→ Flow Guides show each one end to end.
2. Hosted page or your own UI — headlessMode
headlessModefalse (default): TransFi returns a payUrl to a hosted payment page. Fastest to integrate.
true: you build the payment step and show the payment details returned in the response. deviceDetails becomes required.
3. partnerId is your idempotency key
partnerId is your idempotency keyYour own reference for the order. Generate it, store it, then call. Send the same value twice and TransFi returns the original order instead of creating a duplicate — so retry a timed-out request with the same value, and never reuse it for a new attempt.
4. The amount goes in source or destination — never both
source or destination — never bothsource.amount = spend exactly this; the receiver gets the converted equivalent. destination.amount = the receiver gets exactly this; you're charged the converted amount. Sending both is rejected.
5. purposeCode on every order
purposeCode on every orderRequired. It says why money is moving. Use other plus purposeCodeReason if nothing fits. → Purpose Codes
6. Amounts and timestamps
Fiat amounts are the full currency value (5000 = KES 5,000, not minor units). Crypto amounts use full token units to 8 decimals. Timestamps are ISO 8601 UTC.
7. Pagination and rate limits
List endpoints take limit (default 10, max 100) and page (from 1), and return a total. Rate limits are per API key; 429 means back off — 1s, 2s, 4s.
8. Orders finish later
The create call means "accepted". The result arrives by webhook or when you check the order. Act only on a final status. → Orders & Statuses
Updated 29 days ago