Fiat Pay-in

TIP

Fiat Pay-in allows end users to pay in local fiat currency using familiar payment methods such as bank transfers and local wallets, while AIO and its fiat infrastructure partner handle the conversion and crypto settlement in the background.

Unlike standard crypto Pay-in, Fiat Pay-in requires basic KYC before payment. You must first create a KYC profile and obtain a fiat_kyc_id, then use that fiat_kyc_id when creating the fiat pay-in order. Note that name on the KYC must match the Bank title of the sender otherwise payment will fail.

Fiat Pay-in Transaction

Main API Endpoints: /v2/fiat/kyc, /v2/fiat/pay-in/quote, /v2/fiat/pay-in

Supports local fiat payments for supported currencies and payment methods.

Before creating a fiat order, you must first complete basic KYC through POST /v2/fiat/kyc.

The KYC creation response returns fiat_kyc_id, which is required by POST /v2/fiat/pay-in.

After the fiat order is created successfully, AIO returns a fiat_payment_url.

The end user must be redirected to fiat_payment_url to complete the payment.

If the amount is high enough to trigger enhanced compliance checks, the payment page will ask the user to complete advanced KYC, including liveness verification and proof of identity through Sumsub.

Fiat Capability Discovery

API Endpoints: /v2/fiat/supported-fiat, /v2/fiat/payment-methods, /v2/fiat/fiat-limits

Use GET /v2/fiat/supported-fiat to discover supported fiat currencies.

Use GET /v2/fiat/payment-methods to list available payment methods and their payment_code.

Use GET /v2/fiat/fiat-limits to validate the allowed minimum and maximum fiat amount before creating a quote.

These endpoints help you build the correct frontend flow before creating the fiat order.

Basic KYC Creation

API Endpoint: /v2/fiat/kyc

Before any fiat payment, merchants must collect and submit the user's basic KYC information.

Sample Request Body:

{
  "email": "user@example.com",
  "firstName": "Alice",
  "lastName": "Doe",
  "date": "01-01-1990",
  "country": "US",
  "gender": "female",
  "phone": "1234567890",
  "address": {
    "city": "New York",
    "postalCode": "10001",
    "street": "Main Street",
    "state": "NY"
  }
}

Important conditions when creating KYC:

date must be in dd-mm-yyyy format.

The user must be at least 18 years old.

country must be a 2-letter uppercase ISO country code such as US, AE, or IN.

gender must be either "male" or "female".

phone must contain 8 to 15 digits, without symbols and without the + prefix.

KYC Response:

{ "fiat_kyc_id": "KYC_xxx" }

This fiat_kyc_id is required when creating the fiat pay-in order.

Fiat Quote

API Endpoint: /v2/fiat/pay-in/quote

Use this endpoint to calculate the fiat-to-token conversion before creating the fiat order.

fiat_amount and token_amount are mutually exclusive. You must send only one of them.

The response also returns fields such as min_limit, max_limit, can_transact, and message.

The quoted fiat amount already includes the fiat processing fee.

Sample Request Bodies:

{
  "fiat_currency": "EUR",
  "token": "USDT",
  "token_amount": 100
}

{
  "fiat_currency": "EUR",
  "token": "USDT",
  "fiat_amount": 500
}

Create Fiat Pay-in Order

API Endpoint: /v2/fiat/pay-in

Requires a valid AIO txid from a normal pay-in transaction.

Requires a valid fiat_kyc_id from POST /v2/fiat/kyc.

Supports restricting available payment methods through fiat_payment_type and payment_code.

Returns the payment page URL that the end user must open to continue the payment flow.

Typical fields include:

txid

fiat_kyc_id

fiat_currency

fiat_payment_type

fiat_purpose_code

fiat_redirect_url

fiat_source_url (optional)

payment_code (optional)

Sample Request Body:

{
  "txid": "Ixxxxxxxxxxxxxxxxxxxx",
  "fiat_kyc_id": "UX_xxx",
  "fiat_currency": "EUR",
  "fiat_payment_type": "bank_transfer",
  "fiat_purpose_code": "service_charges",
  "fiat_redirect_url": "https://merchant.example/success",
  "payment_code": "sepa_bank"
}

Sample Response:

{
  "txid": "Ixxxxxxxxxxxxxxxxxxxx",
  "fiat_order_id": "OR-xxxx",
  "fiat_payment_url": "https://..."
}

After receiving this response, redirect the end user to fiat_payment_url.

Advanced KYC on Payment Page

After the fiat order is created and the user opens the returned fiat_payment_url:

the user continues the payment on the hosted payment page

if the amount is within the normal range, the user proceeds with the standard payment flow

if the amount roughly goes beyond 25,000 USD equivalent, the payment page may require advanced KYC

this advanced KYC may include liveness verification and additional proof of identity through Sumsub

WARNING

Important notes for Fiat Pay-in:

Basic KYC must be completed before any fiat payment order is created.

POST /v2/fiat/pay-in requires fiat_kyc_id, so KYC creation is mandatory for this flow.

fiat_amount and token_amount in the quote request are mutually exclusive.

Use fiat_payment_type and payment_code to control which payment methods the user sees.

If payment_code is omitted, the user can choose from all available methods within the specified fiat_payment_type.

Always redirect the user to fiat_payment_url after the fiat order is created.

Always verify the callback signature before marking funds as settled.

If the callback status becomes fund_failed or expired, create a new fiat order and redirect the user again.

Fiat Pay-in Transaction#

Fiat Capability Discovery#

Basic KYC Creation#

Fiat Quote#

Create Fiat Pay-in Order#

Advanced KYC on Payment Page#

Fiat Pay-in Integration Sequence Diagram#