Integration Guide
This guide walks you through integration flows for our three products: Crypto Checkout, Onramp, and Offramp. Each flow follows a similar pattern — create a user, handle compliance, fetch rates, and create an order.
Onramp and Offramp flows begin with user creation and KYC verification. Crypto Checkout has a separate integration via RedotPay Connect.
Crypto Checkout Integration
Accept stablecoin payments from any crypto wallet. Powered by RedotPay Connect, Crypto Checkout handles payment processing and settles funds in USD on T+1.
Call the Crypto Checkout API with the order amount, currency, and callback URL.
For Hosted Checkout, redirect the customer to the payment page. For Custom Checkout, display the QR code or deeplink.
The customer scans the QR code or clicks the deeplink from their wallet (MetaMask, Trust Wallet, exchange app, etc.).
Listen for the payment_confirmed webhook event once the blockchain transaction is confirmed.
Funds are converted and settled to your bank account in USD on the next business day.
For complete Crypto Checkout documentation including capabilities, settlement details, and supported stablecoins, see the Crypto Checkout page.
Typical Onramp Flow
Enable users to deposit fiat currency and receive stablecoins (USDC, USDT) in their crypto wallet.
Onramp does not support quote caching (quoteId). The rate is determined at order creation time.
Use the standard payin endpoint with withdrawDetails containing the crypto wallet:
The user completes the fiat payment in the PayItFast widget.
Listen for the asset_settled webhook event confirming crypto delivery to the user's wallet.
1. POST /v2/users/individual → Create user
2. POST /v2/kyc/standard → Complete KYC
3. GET /v2/config/list-tokens → Get crypto tokens
4. GET /v2/exchange-rates/fiat-to-crypto → Get conversion quote
5. POST /v2/orders/deposit → Create order with withdrawDetails (crypto wallet)
6. Redirect user to paymentUrl → User pays fiat
7. Receive webhook (asset_settled) → Crypto delivered to walletOnramp Order Example
{
"paymentType": "bank_transfer",
"purposeCode": "expense_or_medical_reimbursement",
"amount": 100,
"currency": "EUR",
"email": "john@example.com",
"redirectUrl": "https://www.example.com",
"sourceUrl": "https://example.com",
"withdrawDetails": {
"cryptoTicker": "USDC",
"walletAddress": "0xcf2888157e35d8595cba5abd7970f94a43f0d2d2"
}
}Onramp Order Status Flow
Typical Offramp Flow
Enable users to sell stablecoins (USDC, USDT) and receive fiat in their bank account or local wallet.
Use the payout endpoint with depositDetails containing the user's crypto wallet:
The response includes a walletAddress. The user sends stablecoins to this address.
Listen for the asset_deposited event confirming crypto was received.
Listen for the fund_settled event confirming fiat was sent to the user's bank account.
1. POST /v2/users/individual → Create user
2. POST /v2/kyc/standard → Complete KYC
3. GET /v2/exchange-rates/crypto-to-fiat → Get conversion quote
4. POST /v2/payout/orders → Create order with depositDetails (crypto wallet)
5. User sends stablecoin to walletAddress → From response
6. Receive webhook (asset_deposited) → Crypto received
7. Receive webhook (fund_settled) → Fiat delivered to bankOfframp Order Status Flow
Widget vs Headless Integration
PayItFast supports two integration modes. Choose based on your desired level of UI control.
Widget Mode (Default)
Set headlessMode: false (or omit it). The API returns a paymentUrl that redirects users to the PayItFast payment widget.
- Fastest integration path
- PayItFast handles payment UI
- Can embed via iframe
- Automatic payment method rendering
Headless Mode (API-only)
Set headlessMode: true. Full API-only integration where you control the entire user interface.
- Complete UI control
- Must provide
deviceDetails - Must provide
additionalDetails - Fields defined per payment method
When using headless mode, you must include deviceDetails (IP address + user agent) and all fields listed in the additionalDetails object returned by the /v2/payment-methods endpoint for the chosen payment method.
iFrame Embedding
To embed the payment widget directly in your page, use the paymentUrl from the order creation response in an iframe:
<html>
<head>
<meta name="viewport"
content="width=device-width, initial-scale=1.0,
maximum-scale=1.0, user-scalable=no" />
</head>
<body style="margin: 0; padding: 0; width: 100%;
height: 100%; overflow: hidden">
<iframe
src="PAYITFAST_PAYMENT_URL"
allow="payment"
style="width: 100%; height: 100%; border: none;
position: fixed; top: 0; left: 0;
right: 0; bottom: 0;"
></iframe>
</body>
</html>
Replace PAYITFAST_PAYMENT_URL with the paymentUrl value from the order creation response.
Sandbox Testing Tips
Use the sandbox environment to develop and test your integration before going live.
All sandbox requests should use: https://sandbox-api.payitfast.com
Simulating KYC Failure
To test KYC rejection flows, create a user with an email address ending in @kycfailure.sandbox. For example: testuser@kycfailure.sandbox. The KYC submission will automatically be rejected, allowing you to test failure handling.
Adding Test Balances
Use the sandbox-only prefunding endpoint to add dummy balances for payout testing. This is not available in production.
Quote Validity
Exchange rate quotes are valid for 1 minute. When testing, make sure to create the order within this window after fetching a rate. Expired quotes will return a QUOTES_EXPIRED error.