Fiat API Specification

Merchants can download offline QR codes in the back office for customers to scan and make payments in-store using Alipay or WeChat. We also provide an API to create online fiat orders for customers to make payments online using Alipay or WeChat.

Create Fiat Order

Used to generate online fiat orders for customers to make payments with Alipay or WeChat.

Endpoint

POST https://test-order.airswift.io/docking/fiat-order/create

Request Headers

Content-Type: application/x-www-form-urlencoded

Request Parameters

Parameter	Type	Requirement	Description
signStr	string	M	Encrypted signature.
bizContent	object (JSON)	M	Business parameters.

Required Fields in bizContent

Note: M = Mandatory, O = Optional

Field	Type	M	Description
amount	string	M	amount to pay
appKey	string	M	The app key obtained from the email.
clientOrderSn	string	M	The Airswift order ID.
currency	string	M	USD, CAD, etc.
note	string	O	order note
remarks	string	O	product description

Example Request

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d '{
  "signStr": "weqweqe21312dada",
  "bizContent": {
    "amount": "10.01",
    "appkey": "1231231",
    "clientOrderSn": "1658909065813",
    "currency": "USD",
    "note": "orer note",
    "remarks": "product desc"
  }
}' https://test-order.airswift.io/docking/fiat-order/create

signStr

Before signing the bizContent, keys of bizContent must be sorted in alphabetical order, excluding null or empty values, and then concatenated using the Merchant Private Key for signing. In this case:

// concat non-null and non-empty values in alphabetical order of keys
let dataToSign = 
  bigContent['amount']+
  bigContent['appKey']+
  bigContent['clientOrderSn']+
  bigContent['currency']+
  bigContent['note']+
  bigContent['remarks'];

// sign with RSA-SHA256 using merchant private key
sign(privateKey:any, dataToSign: string) {
    const signer = crypto.createSign('RSA-SHA256');
    signer.write(dataToSign);
    signer.end();

    let signature = signer.sign(privateKey, 'base64');

    return signature;
}

Response Details

{
    "code": 200,
    "message": "success",
    "data": "https://test-cashier.airswift.io/index.html?orderSn=813342999522623488&channel=fiat&currency=USD&amount=0.01",
    "count": null,
    "responseString": "200~success",
    "url": null,
    "cid": null
}

Upon receiving the response, the merchant can redirect to the URL of the checkout page found in the data field.

Order Query

This interface aims to provide a method for checking the payment status of a specific order.

Endpoint

GET https://test-order.airswift.io/docking/fiat-order/detail/[orderSn]

Request Parameters

The orderSn can be located in the response of order creation.

Example Request

curl -X GET https://test-order.airswift.io/docking/fiat-order/detail/813342999522623488

Response Details

Field	Type	Description
merchantId	string	Merchant ID
merchantName	string	Merchant Name
appId	string	App ID
appName	string	App Name
memberId	string	Member ID
memberName	string	Member Name
orderSn	string	Order number
clientOrderSn	string	Store APP ID for distinguishing customer orders
tradeType	string	Transaction type. 0 for prepaid orders
amount	number	order amount
currency	string	USD, CAD, etc
remarks	string	Remark
status	string	Order status. 0: pending, 1: success, 2: fail, 3: cancel
autoResendNum	string	The number for auto resend callback
createTime	string	The timestamp for creating the order
payTime	string	The timestamp for when the order was paid
cancelTime	string	The timestamp for when the order was canceled
payAmount	string	The actual paid order amount
payStatus	string	The payment status. 0: pending, 1: fully paid, 2: canceled, 3: insufficient pay, 4: overpay
pushStatus	string	The push status. 0: fail, 1: success

{
    "code": 200,
    "message": "SUCCESS",
    "data": {
        "id": 13,
        "merchantId": 46,
        "merchantName": "airswifttest",
        "appId": 36,
        "appName": "test",
        "memberId": null,
        "memberName": null,
        "orderSn": "813342999522623488",
        "clientOrderSn": "FIAT1000021",
        "tradeType": 0,
        "amount": 0.01000000,
        "currency": "USD",
        "remarks": "product desc",
        "status": 0,
        "autoResendNum": 0,
        "createTime": "2024-02-13T01:34:42.000+0000",
        "payTime": null,
        "cancelTime": null,
        "payAmount": null,
        "payStatus": 0,
        "pushStatus": null,
        "createTimeStr": null,
        "payTimeStr": null,
        "refundAmount": 0E-8
    },
    "count": null,
    "responseString": "200~SUCCESS",
    "url": null,
    "cid": null
}

Fiat Payment Notification

After the fiat order is either fully paid or times out, we will notify the merchant of the order status. The merchant needs to set up the callbackUrl in the Merchant Backoffice at https://test-merchant.airswift.io.

Response Details

{
    "data": {
        "amount": "0.01000000",
        "orderSn": "808982039538221056",
        "createTime": "1706748348000",
        "payTime": "1702493477000",
        "cancelTime": null,
        "clientOrderSn": "FIAT1000005",
        "currency": "USD",
        "id": "4",
        "tradeType": "0",
        "remarks": "product desc",
        "status": "1"
    },
    "sign": "LujtfZzvmwGxmonhUgTDYFeO3mQbVdrWuG9pEfY7tKLxwsSd0kgUck2fEawl26s1joTgxYg8Hcb5idqgj2D5Aq+LZR8dLV1wKUWNonrDAeTn1w3eXe8pA0xplxWtMT5GvXEwUAajIfKGrKfen0yfwvjUJ1IjWSfF9/OdS8MNkavB/qLCFo3DRQj3StBLGgb9+WzNb8iGSDTbM8tbPC+UnI6yRlj6XgkxSaMKdVIWtjfdX27UZwImPhdnu/lrBtuKNQ+UNJVizG8HUKPUI6Jxn21w4dWOjaOgQPs90FoH1Ka9+A49T0lUQ4TB3+YmfEcJLJ7uX6goG028SZ/IiDuA3A=="
}

verification of sign

After receving payment notification from Airswift, merchant needs to verify the sign in the response using public key of Application in Merchant back office. The logic to build the string to be signed is same in the part of Create Fiat Order, in this case:

let sortedKeys = Object.keys(response.data).sort();
// sortedKeys = ['amount', 'cancelTime', 'clientOrderSn', 'createTime', 'currency', 'id', 'orderSn', 'payTime', 'remarks', 'status', 'tradeType']

// concat non-null and non-empty values
let dataToSign = '';
for(let key of sortedKeys){
  if(response.data[key])
    dataToSign += response.data[key];
}

// verify signature ...