Create Order

Other Description

We provide two ways to create orders:

1. Merchant server-side signature order creation, which is introduced in this document.
2. Using the webui component, where the payment component creates orders with server-side signatures. Please refer to the demo page for details.

API description

The unified order interface is merchant to create order.

Interface Information

• Interface URL: POST /v2/createOrder
• Content-Type: application/json
• Authentication: Need to pass app-id and signature verification in Header

Request Header Parameters

Parameter	Type	Required	Description
app-id	string	Yes	Merchant Application ID
Content-Type	string	Yes	application/json

Request Parameters

Parameter	Type	Required	Description
payChannel	string	Yes	Payment channel name
sign	string	Yes	Request signature
outTradeNo	string	Yes	Merchant order number, must be unique
amount	string	Yes	Payment amount
currency	string	Yes	Currency type
currencyId	string	Yes	Currency ID
timestamp	string	No	Timestamp
timeExpire	string	No	Order expiration time
payAddress	string	No	Payment address (Required for settlement channel to enable refunds)
extra	object	No	Extended parameters, see below for details

Request Data Structure

The following is the Go structure definition for the create order request:

type CreateOrderRequest struct { 
	PayChannel string                 `json:"payChannel" form:"payChannel"` 
	Sign       string                 `json:"sign" form:"sign" binding:"required"` 
	OutTradeNo string                 `json:"outTradeNo" form:"outTradeNo" binding:"required"` 
	Amount     string                 `json:"amount" form:"amount" binding:"required"` 
	Currency   string                 `json:"currency" form:"currency"` 
	CurrencyId string                 `json:"currencyId"  form:"currencyId" ` 
	Timestamp  string                 `json:"timestamp" form:"timestamp"` 
	TimeExpire string                 `json:"timeExpire" form:"timeExpire"` 
	PayAddress string                 `json:"payAddress" form:"payAddress"` 
	Extra      map[string]interface{} `json:"extra" form:"extra"` 
} 

Extra Parameter Description

Parameter	Type	Required	Default Value	Description
description	string	No	"buy something"	Order description
attach	string	No	"chainpay-support"	pay desc
channel_pay_type	string	No	"qrcode"	Payment type, options: "qrcode", "cards"

about length:

1. attach length must be less than 60
2. description length must be less than 60

Response Parameters

Success Response

{
    "code": 0,
    "data": {
        "extra": {
            "abapay_deeplink": "",
            "paymentURL": "",
            "qrimage": "",
            "qrstring": ""
        },
        "orderNo": "1754377439308531400",
        "qrcode": "",
        "scheme": ""
    },
    "msg": "success"
}

Error Response

{
    "code": 7,
    "data": {},
    "msg": "payment processing failed: "
}

Request Examples

cURL Example

curl -X POST "/v2/createOrder" \
  -H "Content-Type: application/json" \
  -H "app-id: your-app-id" \
  -d '{
    "payChannel": "demo",
    "sign": "generated_signature",
    "outTradeNo": "ORDER_20240101_001",
    "amount": "100.00",
    "currency": "USDT",
    "currencyId": "USDT",
    "timestamp": "1704067200",
    "timeExpire": "1704070800",
    "payAddress": "0x1234567890abcdef",
    "extra": {
      "channel_pay_type": "qrcode",
      "description": "buy something",
      "attach": "chainpay-support",
    }
  }'

Cards Payment Order Example

Request Parameters

{
    "payChannel": "payway",
    "sign": "generated_signature",
    "outTradeNo": "ORDER_20240101_001",
    "amount": "100.00",
    "currency": "USDT",
    "currencyId": "USDT",
    "timestamp": "1704067200",
    "timeExpire": "1704070800",
    "payAddress": "0x1234567890abcdef",
    "extra": {
      "channel_pay_type": "cards",
      "description": "buy something",
      "attach": "chainpay-support",
    }
}

Response Parameters

{
    "code": 0,
    "data": {
        "extra": {
            "data": {
                "additional_params": "",
                "amount": "20.00",
                "cancel_url": "",
                "continue_success_url": "",
                "currency": "USD",
                "custom_fields": "",
                "description": "buy something",
                "email": "",
                "firstname": "",
                "google_pay_token": "",
                "hash": "dbBRKH+Tud7qhQRMWGU9bvtwqx2yPQccSXX34lXOxVWJlSqzE8k1xEg3RwpBwnKYtfM+q9OPWVknPxpl9WEjHQ==",
                "items": "",
                "lastname": "",
                "lifetime": "",
                "merchant_id": "ec000262",
                "payment_gate": "0",
                "payment_option": "cards",
                "payout": "",
                "phone": "",
                "req_time": "20250806055806",
                "return_deeplink": "",
                "return_params": "",
                "return_url": "",
                "shipping": "",
                "skip_success_page": "1",
                "tran_id": "1754459886204383900",
                "type": "purchase",
                "view_type": ""
            },
            "requestUrl": "https://checkout-sandbox.payway.com.kh/api/payment-gateway/v1/payments/purchase"
        },
        "orderNo": "1754459886204383900",
        "qrcode": "",
        "scheme": ""
    },
    "msg": "success"
}

Remark

You need to submit the returned requestUrl and the data parameter from extra via a POST request to the requestUrl. After form submission, you will be redirected to the payment page. Alternatively, you can embed it into your page using an iframe.

Order Callback

After the payment is completed, the merchant needs to configure the callback address to receive the payment notification.

30 seconds after creating an order, ChainPay will send the order information to the merchant's configured callback address via a POST request.

Notification strategy:

• Retry after notification failure
• Retry interval increases (0s, 10s, 20s...)
• Maximum 10 retries
• Stop notification when any notification succeeds (returns "success")

callback request parameter

The callback request parameter is a JSON object.

{
    "appId": "merchant_app_id",
    "outTradeNo": "merchant_order_123",
    "attach": "custom_data",
    "nonce": "random_nonce",
    "hash": "tx_hash_123",
    "transactionId": "platform_tx_123",
    "status": "DONE_PAYMENT",
    "timestamp": "1683123456",
    "sign": "generated_signature"
}

callback parameter description

Parameter	Type	Required	Default Value	Description
appId	string	Yes	Merchant app ID
outTradeNo	string	Yes	Merchant order number
attach	string	No	Custom data
nonce	string	Yes	Random nonce
hash	string	Yes	Transaction hash
transactionId	string	Yes	Platform transaction ID
status	string	Yes	Payment status
timestamp	string	Yes	Timestamp
sign	string	Yes	Signature

Signature Description

The signature is the same as the create order signature.

Signed with the merchant's private key. After receiving, the merchant needs to verify the signature with the public key.

Signature Verification

Merchants need to verify the signature with the public key to ensure it is correct.