API Specification

Order Query

The purpose of this interface is to provide a means of checking the payment status for a specific order.

Endpoint

POST https://order.airswift.io/docking/order/detail

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
appKey string M The app key obtained from the email.
orderSn string M The Airswift order ID.
timestamp string M The current timestamp in milliseconds. Example: 1658909065813.
nonce string M A randomly generated 6-digit string.

Example Request

    
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d '{
  "signStr": "weqweqe21312dada",
  "bizContent": {
    "appKey": "1231231",
    "orderSn": "1231231",
    "timestamp": "1658909065813",
    "nonce": "123123"
  }
}' https://order.airswift.io/docking/order/detail

Response Details

Field Type Description
id string Order ID
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
coinUnit string The digital currency used in the transaction. Currently supports USDT, USDC, ETH
address string The wallet address to receive the transaction
amount string The amount for cryptocurrency
fee string The transaction fee. Order amount multiplied by the merchant transaction fee rate
merchantFee string The actual transaction fee paid
memberFee string The customer fee (currently not required)
cnyAmount string The amount in fiat currency
rate string The exchange rate for the transaction
remark string Remark
status string Order status. 0: pending, 1: success, 2: fail, 3: cancel, 4: callback fail
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
floatingRatio string The rate for actual payment and required payment
payStatus string The payment status. 0: pending, 1: received, 2: canceled, 3: not enough payment, 4: overpay
pushStatus string The push status. 0: fail, 1: success

Example Response

    
{
  "id": "123456",
  "merchantId": "789",
  "merchantName": "Example Merchant",
  "appId": "567",
  "appName": "Example App",
  "memberId": null,
  "memberName": null,
  "orderSn": "ABC123",
  "clientOrderSn": "XYZ789",
  "tradeType": "0",
  "coinUnit": "USDT",
  "address": "0xAbCdEfGhIjKlMnOpQrStUvWxYz",
  "amount": "10.5",
  "fee": "1.05",
  "merchantFee": "0.5",
  "memberFee": null,
  "cnyAmount": "100.00",
  "rate": "10.00",
  "remark": "Payment received",
  "status": "1",
  "autoResendNum": "0",
  "createTime": "1658909065813",
  "payTime": "1658910000000",
  "cancelTime": null,
  "payAmount": "10.00",
  "floatingRatio": "0.95",
  "payStatus": "1",
  "pushStatus": "1"
}

Create Order

The purpose of this interface is to create and submit the payment.

Endpoint

POST https://order.airswift.io/docking/order/create

Request Headers

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

Request Parameters

Note: M = Mandatory, O = Optional
Parameter Type Requirement Description
signStr string M Encrypted signature.
bizContent object (JSON) M Business parameters.

Required Fields in bizContent

Note: M = Mandatory, O = Optional
Parameter Type M Description
appKey string M The app_key obtained from the email.
nonce string M Randomly generated 6-digit string.
timestamp string M Current timestamp in milliseconds (e.g., 1658909065813).
clientOrderSn string M Your store APP order ID used to distinguish customer orders.
tradeType string M Transaction type. Set to 0 for prepaid orders.
coinUnit string M The digital currency used in the transaction. Currently supports USDT, USDC, ETH.
basicsType string M Fiat currency types. Set to 1 for USD.
amount string M Transaction amount in fiat currency.
remarks string M Remark for the transaction.

Example Request

    
curl -X POST -H "Content-Type: application/x-www-form-urlencoded" \
  -d '{
    "signStr": "weqweqe21312dada",
    "bizContent": {
      "appKey": "1231231",
      "coinUnit": "USDT",
      "timestamp": "1658909065813",
      "nonce": "123123",
      "amount": "0.1",
      "clientOrderSn": "123123",
      "basicsType": "1",
      "tradeType": "0",
      "appSecret": "123123",
      "remarks": "remark"
    }
  }' \
  https://order.airswift.io/docking/order/create

Respnse Details

Field Type Description
code string The response code indicating the status of the request.
message string A descriptive message accompanying the response code.
data string The URL for accessing the order details.
count string Not applicable in this response.
responseString string The concatenated string of the response code and message.
url string Not applicable in this response.
cid string Not applicable in this response.

Example Response

    
jsonCopy code{
  "code": 200,
  "message": "success",
  "data": "https://order.airswift.io/order/index.html?orderSn=orderSn:627037162681450496&amount=10.00000000&fee=0E-8",
  "count": null,
  "responseString": "200~success",
  "url": null,
  "cid": null
}

Remark: Please note that for the data field in the response sample, the provided URL contains additional fields appended to it. Within this URL, the orderSn field represents the unique order number associated with the transaction. The amount field indicates the precise transaction amount in fiat currency, while the fee field denotes the corresponding transaction fee for the order.

Callback (Webhook)

Introduction

The callback feature, also known as a webhook, allows you to receive payment status updates from the Airswift API. To enable this functionality, follow these steps:

  1. Set up a pre-established RESTful backend for your "APP."
  2. Specify the callback URL in the Airswift console, which will receive payment status updates.

Whenever there is a payment status update in Airswift, the system will make a POST request to your specified callback URL, providing the relevant data in the request payload.

Example

    
plaintextCopy codePOST {your_callback_url}
Content-Type: application/json

{
  "data": {
    "id": "3",
    "orderSn": "347746481850597376",
    "clientOrderSn": "12345678",
    "tradeType": "1",
    "coinUnit": "USDT",
    "address": "0x3e3ca52c88c17a67b8c3e28365c00c68aa48a73e",
    "amount": "10.00000000",
    "fee": "1",
    "cnyAmount": "69.65",
    "rate": "6.96500000",
    "remarks": "test",
    "status": "1",
    "createTime": "1596781222000",
    "payTime": "1596781222000",
    "cancelTime": null
  },
  "sign": "5p9q9299WPjG0Ew2gMW5lnsSzncf8abWZgwtMZTgOB+TOBNpmSP1nDbfZfvBA0KBQy+OrfjW"
}

Please ensure that your RESTful backend is properly configured to receive this POST request and process the payment status update accordingly. If the reception and processing are successful, respond with the success message "SUCCESS."

Callback (Offline Business)

Introduction

This webhook is designed for offline transaction scenarios. When consumers make payments by scanning the wallet QR code, the Airswift server will notify the merchant of the payment result.

To enable this functionality, please follow these steps:

  1. Establish a pre-configured RESTful backend for your "APP."
  2. Define the callback URL in the Airswift console, which will receive updates on payment status.

Upon a successful scan by the consumer using the wallet to make a payment, the system will initiate a POST request to your specified callback URL, delivering the pertinent data in the request payload.

Respnse Details

Field Type Description
amount string The amount for cryptocurrency
address string Merchant receiving address
payTime string Order placement time
fromAddress string Consumer address
txHash string The hash for consumer-initiated on-chain transfer
coinUnit string Coint type
status string Payment status; 1 SUCCESS

Example

    
plaintextCopy codePOST {your_callback_url}
Content-Type: application/json

{
  "data": {
    "amount": "0.03",
    "address": "TQY77nr1TzjT14kGMry7KjnSt89bX8zUwC",
    "payTime": "Thu Feb 22 20:07:28 UTC 2024",
    "fromAddress": "TQY77nr1TzjT14kGMry7KjnSt89bX8zUwD",
    "txHash": "0xcefec11a83a7e254f3f8301ed84364883d15e332102983292bc80ee27d100006",
    "coinUnit": "USDT",
    "status": "1"
  },
  "sign": "KF341NZkB9Rl44eRE25ER09BuZ6Y7ho4HYoaxe8FIah3favq7L07BIM4EfSGs/x6ReZMnExpRj79qhcESpSEL+wsKqTNKb1UxY8HmQf9825mhUxZeDcH5hYMd7tSdZ68a10tcaCmCwGcGRBhO7OJRX1fuGO0fo0gFw3q+UFwKLCV8gETKnBbW3QlqFTWywu1AcrWQfZ4F1VCl9YDCDF8wPPyvLUkyupA9ljcN/1mBqqkh46XeNOforhGnn3dKTJ8ukx3KMBuBQ7xsIwNpKmXi5P5W6HxZXceP6+/ZbKZ6roace6FbpYnWgLNMmKlh34icvmrPqr1smTWoS0AWkotRg=="
}

Note: Ensure that your RESTful backend is correctly configured to receive and process this POST request in order to update the payment status accordingly. In the event of successful reception and processing, respond with the success message "SUCCESS."