Docs / API Reference / Orders & Payments

Orders & Payments

Comprehensive reference for all order types: fiat payins (collections), gaming payins, fiat payouts, crypto payins, crypto payouts, onramp (fiat-to-crypto), and offramp (crypto-to-fiat). This page also covers invoice management and iFrame integration.

On This Page
  1. Invoice Management
  2. Fiat Payin Orders — Collections
  3. Fiat Payin with Wallet — Gaming
  4. Fiat Payout Orders
  5. Crypto Payin Orders
  6. Crypto Payout Orders
  7. Onramp — Fiat to Stablecoin
  8. Offramp — Stablecoin to Fiat

1. Invoice Management

Invoices can be uploaded as PDFs and associated with orders for compliance purposes. The returned invoiceId can be passed when creating any order to link the invoice to the transaction.

Upload Invoice

POST /v2/invoices/create Upload a PDF invoice
Content Type

This endpoint requires Content-Type: multipart/form-data since it accepts a binary PDF file upload.

Parameters

Parameter Type Required Description
email string Required User email address
invoiceType string Required invoice, receipt, contract, or commercial_document
invoice binary Required PDF file only
direction string Required deposit or withdraw
Response 200 OK
JSON 
{
  "invoiceId": "IN-250527142029127",
  "url": "https://production-invoices-s3.s3.ap-southeast-1.amazonaws.com/..."
}

2. Fiat Payin Orders — Collections

Accept fiat payments from end users. Settlement can be batch or instant (crypto or fiat). This is the primary collections flow used for e-commerce, wallets, and marketplace platforms.

Settlement Models

Model Description Key Parameters
Batch Settlement Transactions accumulate and are settled in batches Default behavior — no extra params needed
Instant Crypto Settlement Immediate settlement to a crypto wallet withdrawDetails.cryptoTicker, withdrawDetails.walletAddress
Instant Fiat Settlement Immediate settlement to bank account or local wallet withdrawDetails.currency, withdrawDetails.paymentCode, withdrawDetails.additionalDetails

Create Payin Order

POST /v2/orders/deposit Create a fiat collection order

Required Fields

Parameter Type Description
amount Required number Order value (min: 1)
currency Required string Fiat currency code (e.g., EUR, PHP)
email Required string User email address
paymentType Required string bank_transfer, local_wallet, or card
purposeCode Required string Transaction purpose for regulatory compliance
redirectUrl Required string Post-payment redirect URL
sourceUrl Required string Originating merchant website URL

Optional Fields

Parameter Type Description
balanceCurrency string Settlement currency
paymentCode string Specific payment method code (from payment methods endpoint)
quoteId string Rate lock quote (1-minute validity)
partnerId string Your internal order reference
headlessMode boolean API-only integration without the payment widget
partnerContext object Custom metadata echoed in webhooks and order retrieval
invoiceId string Associated invoice reference (from invoice upload)

Nested Objects

additionalDetails — Required in headless mode; fields vary per payment method:

JSON 
{
  "accountNumber": "string",
  "bic": "string",
  "phone": "string",
  "phoneCode": "string"
}

deviceDetails — Required in headless mode:

JSON 
{
  "ipInfo": { "ip": "string" },
  "userAgent": "string"
}

withdrawDetails — For instant settlement:

JSON 
{
  "cryptoTicker": "string",
  "walletAddress": "string",
  "currency": "string",
  "paymentCode": "string",
  "additionalDetails": {}
}

Full Request Example

JSON 
{
  "amount": 5000,
  "currency": "PHP",
  "email": "john@example.com",
  "paymentType": "bank_transfer",
  "purposeCode": "expense_or_medical_reimbursement",
  "redirectUrl": "https://www.example.com/callback",
  "sourceUrl": "https://www.example.com",
  "paymentCode": "qris",
  "quoteId": "d89f063f-d69c-4792-8c90-40d3598cdafa",
  "partnerId": "MY-ORDER-12345",
  "headlessMode": false,
  "partnerContext": {
    "internalRef": "REF-9876"
  },
  "additionalDetails": {
    "phone": "1234567890",
    "phoneCode": "+62"
  },
  "deviceDetails": {
    "ipInfo": { "ip": "186.228.23.255" },
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
  }
}
Response 200 OK
JSON 
{
  "orderId": "OR-240105131206526",
  "paymentUrl": "https://sandbox-pay-widget.payitfast.com/trade?paytoken=...",
  "redirectUrl": "https://www.example.com/callback",
  "partnerContext": {
    "internalRef": "REF-9876"
  }
}
Field Description
orderId Unique PayItFast order identifier
paymentUrl URL to redirect user to the payment widget (when not headless)
redirectUrl Your redirect URL echoed back
partnerContext Your custom metadata echoed back

Order Status Flow (Collections)

Initiated Fund Processing Fund Settled
Initiated Fund Processing Fund Failed
Status Type Description
initiated Intermediate Order created, awaiting user payment
fund_processing Intermediate User submitted payment, awaiting bank confirmation
fund_settled Terminal Payment successfully received
fund_failed Terminal Payment not received or reverted
manual_review Intermediate Held for compliance team review

Get Order Details

GET /v2/orders/{orderId} Retrieve full order object and status

Returns the full order object including current status, amounts, payment details, and any associated metadata. Use this endpoint to poll for order status updates as an alternative to webhooks.

iFrame Integration

To embed the payment widget directly in your application, use the paymentUrl returned from order creation as the src for an iframe element:

HTML 
<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>
Note

Replace PAYITFAST_PAYMENT_URL with the paymentUrl value from the order creation response. Ensure the allow="payment" attribute is present to enable the Payment Request API within the iframe.

3. Fiat Payin with Wallet — Gaming

iGaming-specific flow where fiat deposits are converted and settled to a crypto wallet, triggering a balance top-up on the gaming platform.

Create Gaming Payin Order

POST /v2/orders/gaming Create a gaming payin order

This endpoint accepts the same request body as Create Payin Order (POST /v2/orders/deposit). All required and optional fields, nested objects, and headless mode behavior are identical.

Response 200 OK

Returns the same structure: orderId, paymentUrl, redirectUrl, and partnerContext.

Order Status Flow (Gaming)

Initiated Fund Settled Asset Deposited Completed
Initiated Fund Failed
Initiated Fund Settled Asset Deposited Expired
Status Type Description
initiated Intermediate Order created, awaiting payment
fund_settled Intermediate Bank confirmed payment receipt
fund_failed Terminal Payment declined
asset_deposited Intermediate Stablecoin deposited to user's wallet
completed Terminal Order complete — trigger balance top-up
expired Terminal Transaction not completed in time
manual_review Intermediate Held for compliance review

4. Fiat Payout Orders

Process fiat payouts to bank accounts or local wallets of end-users and businesses.

Prerequisites

Prefunding required — You must have sufficient balance before creating payout orders. See the Balance & Prefunding page.

Recipient user must exist — Create the recipient via the User Management endpoints before initiating a payout.

Valid bank details required — Invalid bank codes or account numbers will cause the order to be rejected.

Create Payout Order

POST /v2/payout/orders Create a fiat payout order

Required Fields

Parameter Type Description
amount Required number Payout amount (min: 1)
currency Required string Fiat currency code
email Required string Recipient email address
paymentType Required string bank_transfer, local_wallet, or card
purposeCode Required string Transaction purpose for regulatory compliance
redirectUrl Required string Post-transaction redirect URL
sourceUrl Required string Originating merchant URL

Optional Fields

Parameter Type Description
balanceCurrency string Source balance currency
paymentCode string Specific payment method
quoteId string Rate lock quote (1-minute validity)
partnerId string Your internal order reference
partnerContext object Custom metadata
invoiceId string Associated invoice reference
headlessMode boolean API-only mode (no widget)

Nested Objects

withdrawDetails — Recipient bank / wallet details:

JSON 
{
  "paymentCode": "string",
  "currency": "string",
  "additionalDetails": {
    "accountNumber": "string",
    "phone": "string",
    "bic": "string",
    "documentType": "string",
    "documentNumber": "string",
    "accountType": "string"
  }
}

deviceDetails — Required in headless mode:

JSON 
{
  "userAgent": "string",
  "ipInfo": { "ip": "string" }
}

Full Request Example

JSON 
{
  "amount": 5000,
  "currency": "PHP",
  "email": "recipient@example.com",
  "paymentType": "bank_transfer",
  "purposeCode": "remittance",
  "redirectUrl": "https://www.example.com/callback",
  "sourceUrl": "https://www.example.com",
  "paymentCode": "gcash",
  "quoteId": "d89f063f-d69c-4792-8c90-40d3598cdafa",
  "partnerId": "PAYOUT-67890",
  "partnerContext": {
    "internalRef": "PAY-9876"
  },
  "withdrawDetails": {
    "paymentCode": "gcash",
    "currency": "PHP",
    "additionalDetails": {
      "accountNumber": "09171234567",
      "phone": "09171234567"
    }
  },
  "deviceDetails": {
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)",
    "ipInfo": { "ip": "186.228.23.255" }
  }
}
Response 200 OK
JSON 
{
  "orderId": "OR-240105131206526",
  "partnerContext": {},
  "paymentUrl": "https://sandbox-pay-widget.payitfast.com/trade?paytoken=...",
  "redirectUrl": "https://www.example.com/callback"
}

Order Status Flow (Payouts)

Initiated Fund Processing Fund Settled
Initiated Fund Processing Fund Failed
Initiated Fund Processing Fund Returned
Status Type Description
initiated Intermediate Order created
fund_scheduled Intermediate Payout scheduled for processing
fund_processing Intermediate Awaiting bank confirmation
fund_settled Terminal Funds successfully transferred to recipient
fund_failed Terminal Payout failed (prefund returned to balance)
fund_returned Terminal Funds returned from recipient's bank

5. Crypto Payin Orders

Accept cryptocurrency payments from end users. The API returns a deposit wallet address that the user must send crypto to.

Settlement Options

Option Description
Instant Settlement (Crypto) Settles immediately to a specified wallet using the token/network in the request
Batch Settlement (Stable/Fiat) Aggregated and settled in batches to a pre-agreed wallet or bank account

Create Crypto Payin Order

POST /v2/crypto/payin Create a crypto collection order

Parameters

Parameter Type Required Description
amount number Required Order value
currency string Required Fiat currency code
email string Required User email
paymentType string Required bank_transfer, local_wallet, or card
purposeCode string Required Transaction purpose
redirectUrl string Required Redirect URL
sourceUrl string Required Merchant URL
partnerId string Optional Your internal reference
cryptoTicker string Optional Crypto identifier (e.g., USDTPOLYGON)
Response 200 OK
JSON 
{
  "orderId": "OR-241043569613457",
  "walletAddress": "0xbd09d42285b27626b23cd2e2d4517943df008606"
}
Deposit Address

The response includes the deposit wallet address the user must send crypto to. Display this address to your user or use it to initiate a programmatic transfer.

Order Status Flow (Crypto Payin)

Initiated Asset Settled
Status Description
initiated Order created, awaiting crypto payment from user
asset_settled Crypto received from user's wallet

6. Crypto Payout Orders

Send cryptocurrency to end-user wallet addresses.

Prerequisites

Prefunding required — You must have a prefunding balance (via crypto prefund, fiat prefund, or unsettled payin balance).

Wallet screening — All destination wallet addresses undergo exposure screening for compliance.

Create Crypto Payout Order

POST /v2/crypto/payout Send crypto to user wallet

Parameters

Parameter Type Required Description
amount number Required Payout amount
cryptoTicker string Required Crypto symbol (e.g., USDT, USDC)
walletAddress string Required Destination wallet address
currency string Required Settlement currency
email string Required User email
partnerId string Optional Your internal reference
quoteId string Optional Rate lock (1-minute validity)
purposeCode string Optional Transaction purpose
prefundCurrency string Optional Prefund source currency
partnerContext object Optional Custom metadata
Response 200 OK
JSON 
{
  "orderId": "OR-250101123456789"
}

Order Status Flow (Crypto Payout)

Initiated Asset Deposited
Status Description
initiated Order created, crypto transfer in progress
asset_deposited User received crypto; blockchain transaction hash generated

7. Onramp — Fiat to Stablecoin

Users deposit fiat currency which is converted and settled to a crypto wallet address. This flow enables end users to buy stablecoins (USDC, USDT) using local payment methods.

Workflow Steps

  1. Create user — Register the end user via user management endpoints
  2. Complete KYC — User must pass identity verification
  3. Fetch configuration — Get supported currencies, payment methods, and crypto tokens
  4. Get fiat-to-crypto rate — Use the exchange rates endpoint for conversion quotes
  5. Create order — Use POST /v2/orders/deposit with withdrawDetails containing cryptoTicker and walletAddress

Create Onramp Order

POST /v2/orders/deposit Create an onramp (fiat-to-crypto) order

Uses the standard payin endpoint with withdrawDetails specifying the crypto destination:

JSON 
{
  "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"
  }
}
Important

Onramp does NOT support quote caching. Do not pass a quoteId parameter when creating onramp orders — it will be ignored or cause an error.

Order Status Flow (Onramp)

Initiated Fund Processing Fund Settled Asset Processing Asset Settled
Initiated Fund Processing Fund Failed
Fund Settled Asset Processing Asset Deposit Failed
Status Phase Description
initiated Funding Order created, awaiting user payment
fund_processing Funding Payment details submitted, awaiting confirmation
fund_settled Funding Fiat payment received
fund_failed Funding Payment not received or reversed
asset_processing Transfer Stablecoin transfer to wallet initiated
asset_settled Transfer Stablecoins delivered to wallet
asset_deposit_failed Transfer Stablecoin transfer failed
expired — Order expired due to inactivity

8. Offramp — Stablecoin to Fiat

Users send stablecoins (USDC, USDT) to a PayItFast wallet address, which are converted to fiat and distributed to their bank account or local wallet.

Workflow Steps

  1. Create user — Register the end user via user management endpoints
  2. Complete KYC — User must pass identity verification
  3. Fetch configuration — Get supported currencies, payment methods, and crypto tokens
  4. Get crypto-to-fiat rate — Use the exchange rates endpoint for conversion quotes
  5. Create order — Use POST /v2/payout/orders with depositDetails containing cryptoTicker and sendersWalletAddress

Create Offramp Order

POST /v2/payout/orders Create an offramp (crypto-to-fiat) order

Uses the payout endpoint with depositDetails specifying the crypto source:

JSON — Request 
{
  "purposeCode": "fee_payments",
  "amount": 10,
  "email": "john@example.com",
  "currency": "PHP",
  "paymentCode": "gcash",
  "depositDetails": {
    "cryptoTicker": "USDC",
    "sendersWalletAddress": "0xcf2888157e35d8595cba5abd7970f94a43f0d2d2"
  },
  "additionalDetails": {
    "firstName": "John",
    "phone": "1234567890"
  },
  "deviceDetails": {
    "ipInfo": { "ip": "186.228.23.255" },
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
  }
}
Response 200 OK
JSON — Response 
{
  "orderId": "OR-250428110808237",
  "cryptoAmount": 0.179142,
  "walletAddress": "0xbd09d65597b27626b23cd2e2d7664943df007293"
}
Deposit Address

The response includes the PayItFast wallet address where the user must send stablecoins. The cryptoAmount field indicates the exact amount of crypto expected.

Order Status Flow (Offramp)

Initiated Asset Deposited Fund Processing Fund Settled
Initiated Asset Deposit Failed
Asset Deposited Fund Processing Fund Failed
Status Description
initiated Order created, waiting for stablecoin transfer from user
asset_deposited Crypto received from user's wallet
asset_deposit_failed Crypto not received
fund_processing Awaiting bank confirmation of fiat transfer
fund_settled Fiat successfully transferred to recipient
fund_failed Fiat payout failed
expired Order expired due to inactivity