---
title: "Create Order"
method: POST
path: "/v3/orders"
tags: ["Orders"]
---

# Create Order

`POST /v3/orders`

Create a new order (onramp, offramp, payin, payout, prefund, swap).

## Headers

- `MID` string, required

## Request body

- object
  - `partnerId` string — Optional; This field can be used to reference your own transaction Id with TransFi's order Id.
  - `userId` string — Required for onramp, offramp, payin, payout, swap, gaming. For offramp, this field must be omitted when using the user-user (third-party) flow — in that case, provide source.userId and destination.userId instead.
  - `invoiceId` string — Can be obtained from the /v3/invoices/create endpoint. Relevant for payin and payout orderTypes.
  - `customerMetaData` object — Optional; This field can be used to pass additional customer metadata to the order.
  - `settlementAccountId` string — Optional. Only applicable for orderType payin and gaming. This is the account where you want your funds to be paid out. The settlementAccountId's currency should match with the destination.currency passed.
  - `purposeCode` string, required — Purpose of the Payment. Enum values for purposeCode can be found [here](https://docs.transfi.com/v3.0/docs/purpose-code-for-transactions).
  - `sourceUrl` string, uri — Merchant website URL from where the traffic is flowing to TransFi. Must include https:// protocol.
  - `successRedirectUrl` string, uri — URL to redirect the user after a successful transfer. Must include the https:// protocol. This field is not required if a default redirectUrl is configured in the Displ-AI dashboard [https://qa-displai.transfi.com/settings/integration]. Providing a value in this field will override the default redirectUrl configured in the dashboard. If a redirectUrl is not configured in the dashboard, this field is required for: - Gaming orders - Cases where headlessMode is false and the orderType is one of: onramp, offramp, payin, swap
  - `failureRedirectUrl` string, uri — URL to redirect the user after a failed transfer. Must include the https:// protocol. This field is not required if a default redirectUrl is configured in the Displ-AI dashboard [https://qa-displai.transfi.com/settings/integration]. Providing a value in this field will override the default redirectUrl configured in the dashboard. If a redirectUrl is not configured in the dashboard, this field is required for: - Gaming orders - Cases where headlessMode is false and the orderType is one of: onramp, offramp, payin, swap
  - `deviceDetails` object — Optional; This field can be used to pass device details of the user.
    - `userAgent` string
    - `ipInfo` object
      - `ip` string — Client IP address (IPv4 or IPv6 format).
      - `countryCode3` string — 3-letter country code. Automatically populated based on IP address lookup.
  - `customization` object — Optional.
    - `locale` 'en' | 'id' | 'zh' | 'pt' | 'es' | 'vi' | 'tl' | 'bn' — Locale code to display in the payment widget. Supported locales: - en (English) - id (Bahasa) - zh (Mandarin) - pt (Portuguese) - es (Español) - vi (Vietnamese) - tl (Tagalog) - bn (Bengali)
  - `headlessMode` boolean — Optional; defaults to false. When true, enables headless mode for the payment flow: the user is not redirected to a payment page. All required additional payment details for the source object must be provided in this API payload. NOte: This field is relevant for payin, swap, onramp, offramp orderTypes.
  - `orderType` 'onramp' | 'offramp' | 'payin' | 'payout' | 'fiat_prefund' | 'crypto_prefund' | 'swap' | 'gaming', required
  - `source` object, required
    - `currency` string, required — Source currency code. Must be a supported deposit currency in the system. Can be obtained from the /v3/config/supported-currencies or /v3/config/list-tokens endpoint.
    - `userId` string — Source user ID for the user-user (third-party) offramp flow. When provided together with destination.userId, the root-level userId is not required. Currently only supported for orderType: offramp.
    - `amount` number
    - `paymentCode` string — Payment code for the source payment method. Can be obtained from the /v3/payment-methods endpoint. Relevant if type of source.currency is fiat.
    - `paymentType` 'bank_transfer' | 'card' | 'local_wallet' — Type of payment method. Relevant if type of source.currency is fiat.
    - `additionalPaymentDetails` object — Optional. Use this field to supply extra payment details for the source, when required. If the source.currency is fiat and headlessMode is true, obtain these fields from the /v3/payment-methods endpoint. NOTE- This object is required for fiat_prefund orderType.
    - `sendersWalletAddress` string — Sender's wallet address for crypto transactions. Relevant if type of source.currency is crypto.
    - `walletAddress` string — Sender's wallet address. Alternative to sendersWalletAddress.
  - `destination` object, required
    - `currency` string, required — Destination currency code. Must be a supported withdraw currency in the system. Can be obtained from the /v3/config/supported-currencies or /v3/config/list-tokens endpoint.
    - `holdingCurrency` string — Optional. Only applicable for orderType payin and gaming. The currency in which the balance will be held. If not passed, the balance will be held in destination.currency itself.
    - `userId` string — Destination user ID for the user-user (third-party) offramp flow. When provided together with source.userId, the root-level userId is not required. Currently only supported for orderType: offramp.
    - `amount` number
    - `paymentCode` string — Payment code for the destination payment method. Can be obtained from the /v3/payment-methods endpoint. Relevant if type of destination.currency is fiat.
    - `paymentType` 'bank_transfer' | 'card' | 'local_wallet' — Type of payment method. Relevant if type of destination.currency is fiat.
    - `additionalPaymentDetails` union — Optional. Use this field to supply extra payment details for the destination, when required.
      - object — Fiat flow object. If destination.currency is fiat and headlessMode is true, obtain these fields from the /v3/payment-methods endpoint.
      - object — Required when orderType is payout with destination.currency as crypto, or when orderType is onramp.
        - `walletOwner` 'exchange' | 'self', required — Required for crypto flows. Declares whether the destination wallet is exchange-hosted or self-custodied.
        - `exchangeName` string — Optional. Name of the exchange hosting the wallet.
        - `userConfirmed` boolean — Confirms the end user owns the wallet when walletOwner is self.
    - `walletAddress` string — Destination wallet address for crypto transactions. Relevant if type of destination.currency is crypto.
    - `qrCode` string — Optional Field, Only needed for QR Payouts Flow.

## Response `200`

Order created successfully

- object
  - `status` string
  - `data` object
    - `flow` string
    - `orderId` string
    - `amount` number
    - `payUrl` string
    - `paymentsData` object
      - `accountDetails` object
        - `iban` string
        - `name` string
        - `address` string
        - `bic` string
      - `type` string
    - `feeData` object
      - `depositAmount` number
      - `withdrawAmount` number
      - `exchangeRate` number
      - `totalFee` number
  - `traceId` string, uuid

## Other responses

- `400` — Validation error
- `500` — Internal server error

---

[API](https://skmtc.net/transfi/apis/transfi-single-integrated-api.md) · [All operations](https://skmtc.net/transfi/apis/transfi-single-integrated-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/transfi/transfi-single-integrated-api/revisions/adb1b62e58cf/schema)