API Concepts

Base URLs

Sandbox:    https://sandbox-api.transfi.com
Production: https://api.transfi.com

The most important thing to know: orderType

📌
TransFi uses a single endpoint for all transactions: POST /v3/orders. The orderType parameter selects which flow executes. This is the #1 source of integration questions — use this table as your reference.

Use Case	orderType	headlessMode	What happens
Collect payment (Standard)	`payin`	`false`	TransFi returns a hosted payment link for making the payment.
Collect payment (your own UI)	`payin`	`true`	TransFi returns the payment details for making the payment.
Send Money (Payout)	`payout`	`false`	TransFi disburses to recipient's bank account or mobile wallet.
Buy Crypto (Onramp)	`onramp`	`false / true`	User pays fiat, receives cryto in their wallet.
Sell Crypto (Offramp)	`offramp`	`false`	User sends crypto to a deposit wallet address created by TransFi. TransFi disburses fiat to user's bank account / mobile wallet.
Pre-load balance — fiat	`fiat_prefund`	`false`	Wire funds into your MCA fiat balance.
Pre-load balance — crypto	`crypto_prefund`	`false`	Deposit crypto into your MCA.

headlessMode

false (default): TransFi returns a payUrl to a hosted payment page. Fastest to integrate
true: you build your own payment UI and show payment details retuned in the response.

Idempotency — partnerId

During order creation call you can pass a partnerId — your idempotency key. This key is used as the reference between your orderId and TransFi's orderId. If you send the same value twice, TransFi returns the original order instead of creating a duplicate. Pass your orderId or generate a UUID per order, store it before the API call, and retry with the same value if a request times out.

Pagination

List endpoints support limit (default 10, max 100) and page (from 1). The response includes a total count.

Rate Limits

Rate limits are enforced per API key. Exceeding them returns HTTP 429. Implement exponential backoff: 1s → 2s → 4s.

Timestamps & Amounts

Timestamps are ISO 8601 UTC (e.g. 2025-05-15T10:00:00Z)
Fiat amounts are full currency value (5000 = KES 5,000, not minor units)
Crypto amounts use full token units to 8 decimals.

Base URLs

The most important thing to know: orderType

TransFi uses a single endpoint for all transactions: POST /v3/orders. The orderType parameter selects which flow executes. This is the #1 source of integration questions — use this table as your reference.

TransFi uses a single endpoint for all transactions: `POST /v3/orders`. The `orderType` parameter selects which flow executes. This is the #1 source of integration questions — use this table as your reference.