Core Concepts

Before you start building, familiarize yourself with the foundational concepts that underpin every PayItFast API integration.

Order Lifecycle

Every transaction in PayItFast -- whether a collection, payout, or ramp order -- follows a predictable lifecycle. Understanding these states is essential for building reliable integrations.

General Flow

At its simplest, an order moves through three primary phases:

Quote Caching & Rate Locking

When you request an exchange rate or create a quote, the API returns a quoteId that represents a locked rate for a limited time. This mechanism ensures that the rate your user sees is the rate they get -- as long as the quote has not expired.

How Quotes Work

• Request a quote by calling the exchange rate endpoint with the source currency, destination currency, and amount.
• The API returns a quoteId along with the locked exchange rate, fees, and estimated delivery amount.
• Pass the quoteId when you create the order to lock in that specific rate.
• If the quote expires before order creation, the API will return an error, and you must request a new quote.

{
  "quoteId": "qt_8f2a4b6c9d1e",
  "sourceCurrency": "USD",
  "destinationCurrency": "EUR",
  "exchangeRate": 0.9234,
  "sourceAmount": 1000.00,
  "destinationAmount": 918.40,
  "fee": 5.00,
  "expiresAt": "2025-06-15T14:31:00Z"
}

Headless Mode

By default, PayItFast order creation returns a hosted checkout URL where end-users complete their payment. If you want to build a fully custom UI and handle the payment flow entirely within your own application, set headlessMode to true.

When to Use Headless Mode

• You need complete control over the payment UI/UX.
• You are building a mobile-native or embedded experience.
• You want to collect payment details directly (e.g., bank account details for payouts).

Required Fields in Headless Mode

When headlessMode=true, the API does not generate a hosted page. You must supply additional fields in the order request:

{
  "headlessMode": true,
  "quoteId": "qt_8f2a4b6c9d1e",
  "userId": "usr_abc123",
  "deviceDetails": {
    "deviceIp": "203.0.113.42",
    "userAgent": "Mozilla/5.0 ...",
    "acceptLanguage": "en-US"
  },
  "additionalDetails": {
    "bankCode": "CHASE",
    "accountNumber": "****7890"
  }
}

Partner Context

The partnerContext field allows you to attach arbitrary metadata to any order. This is a free-form JSON object that PayItFast stores with the order and echoes back in every webhook notification related to that order.

Common Uses

• Store your internal order ID or invoice number for easy reconciliation.
• Pass customer identifiers from your system to correlate webhook events.
• Attach campaign or referral tracking codes.

{
  "partnerContext": {
    "internalOrderId": "ORD-2025-00847",
    "customerId": "cust_xyz789",
    "source": "mobile_app_v3"
  }
}

When you receive a webhook for this order, the partnerContext object is included in the payload, letting you match the event to your internal records without additional API calls.

MID (Merchant ID)

If your organization operates multiple business lines or brands, PayItFast supports a multi-merchant configuration. Each merchant profile has a unique Merchant ID (MID) that determines routing rules, fee structures, and settlement accounts.

How to Use MID

Pass the MID as an HTTP header on every API request that should be scoped to a specific merchant profile:

MID: merch_acme_payments

Settlement Models

PayItFast offers flexible settlement options depending on the type of transaction and your operational needs.

Batch Settlement (Fiat)

For fiat transactions, funds are typically settled in batches on a scheduled basis (e.g., daily or weekly). This is the default model for most collection and payout flows.

• Funds from multiple orders are aggregated and settled together.
• Settlement frequency is configurable per merchant profile (T+0, T+1, T+2, etc.).
• A settlement report is generated and delivered via webhook or made available through the API.

Instant Settlement (Crypto)

For crypto transactions, settlement is typically instant or near-instant, as the transfer occurs directly on the blockchain.

• On-chain confirmation times vary by network (e.g., a few seconds on Solana, several minutes on Ethereum).
• Transaction hash is returned in the order response and webhook payload for verification.
• No batching -- each order is settled individually.

Instant Fiat Settlement

For eligible corridors, PayItFast supports instant fiat settlement, where funds are delivered to the recipient's bank account in real-time or near-real-time.

What's Next

Now that you understand the core concepts, proceed to the API reference to explore specific endpoints: