Payment Methods

warning

Verify that your API credentials allow for the selected pay_type.

PayType

Code	Description
800008	Consumer Present QR Code Mode (CPM) for WeChat, Alipay, UNIONPAY Quick Pass
800101	Alipay Merchant Presented QR Code Payment in store (MPM) (Overseas Merchants)
800108	Alipay Consumer Presented QR Code Payment (CPM) (Overseas & HK Merchants)
801101	Alipay Online WEB (in browser Chrome etc.) Payment (Overseas Merchants) **
801107	Alipay Online WAP (in mobile browser Chrome etc.) Payment (Overseas Merchants)
801110	Alipay in-APP Payments (Overseas Merchants)
800107	Alipay Service Window H5 Payment (in Alipay APP H5 payments)
801501	Alipay Merchant Presented QR Code (MPM) Payment (HK Merchants)
801510	Alipay In-App Payment (HK Merchants)
801512	Alipay Online WAP Payment (HK Merchants)
801514	Alipay Online WEB Payment (HK Merchants)
800201	WeChat Merchant Presented QR Code Payment (MPM) (Overseas & HK Merchants)
800208	WeChat Consumer Presented QR Code Payment (CPM) (Overseas & HK Merchants)
800207	WeChat JSAPI Payment - WeChat Official Account Payment (in Wechat App)(Overseas & HK Merchants)
800212	WeChat H5 Payment (In mobile browser)
800210	WeChat in-APP Payment (Overseas & HK Merchants)
800213	WeChat Mini-Program Payment (Overseas & HK Merchants)
801008	WeChat Pay HK Consumer Presented QR Code Payment (CPM) (Direct Settlement, HK Merchants)
801010	WeChat Pay HK In-App Payment (Direct Settlement, HK Merchants)
805801	PayMe Merchant Presented QR Code Payment in store (MPM) (HK Merchants)
805808	PayMe Consumer Presented QR Code Payment (CPM) (HK Merchants)
805814	PayMe Online WEB (in browser Chrome etc.) Payment (HK Merchants)
805812	PayMe Online WAP (in mobile browser Chrome etc.) Payment (HK Merchants)
800701	UNIONPAY Quick Pass Merchant Presented QR Code Payment (MPM)
800708	UNIONPAY Quick Pass Consumer Presented QR Code Payment (CPM)
800712	UNIONPAY WAP Payment (HK Merchants)
800714	UNIONPAY PC-Web Payment (HK Merchants)
802001	FPS Merchant Presented QR Code Payment (MPM) (HK Merchants)***
803701	Octopus dynamic QRC Payment - Merchant Present Mode (MPM) (HK Merchants)
802801	Visa / Mastercard Online Payments
802808	Visa / Mastercard Offline Payments
806527	ApplePay Online Payments
806708	UnionPay Card Offline Payments
806808	American Express Card Offline Payments

note

*

1. Differently from Public Payment Parameters, return_url is a mandatory request parameter.
2. web_url parameter in response contains the payment url.

**

1. Transaction amount must be greater than 1 HKD.

***

1. Payment method does not support refunds.

****

1. Please refer to this section for payment request and response.

Currencies

The below listed currencies are currently available in our payment network. Please consult technical.support@qfpay.com to verify that your API credentials and selected pay_type support your desired currency.

Code	Description
AED	Arab Emirates Dirham
CNY	Chinese Yuan
EUR	Euro
HKD	Hong Kong Dollar
IDR	Indonesian Rupiah
JPY	Japanese Yen
MMK	Myanmar Kyat
MYR	Malaysian Ringgit
SGD	Singapore Dollar
THB	Thai Baht
USD	United States Dollar
CAD	Canadian Dollar
AUD	Australian Dollar

API Endpoint for Payments

warning

Remember to immediately refund transactions that were made in the sandbox environment.

If you would like to quickly test the payment function in Postman we provide a collection that includes a pre-request script to generate the signature, download the file from here: Payment Request in Postman

Request Header:

{
  Content-Type: application/x-www-form-urlencoded;
  X-QF-APPCODE: D5589D2A1F2E42A9A60C37**********
  X-QF-SIGN: 6FB43AC29175B4602FF95F8332028F19
}

Request Body:

{
  mchid=ZaMVg*****&out_trade_no=01234567890123&pay_type=800101&txamt=10&txcurrcd=EUR&txdtm=2019-12-25 14:21:28
}

Python

#coding=utf8
import urllib.request, urllib.parse, urllib.error, urllib.request, urllib.error, urllib.parse, hashlib
import requests
import datetime
import string

# Enter Client Credentials
environment = 'https://test-openapi-hk.qfapi.com'
app_code = 'D5589D2A1F2E42A9A60C37*********'
client_key = '0E32A59A8B454940A2FF39**********'


# Create parameter values for data payload
current_time = datetime.datetime.now().replace(microsecond=0)                                

print(current_time)

# Create signature
def make_req_sign(data, key):
    keys = list(data.keys())
    keys.sort()
    p = []
    for k in keys: 
        v = data[k]
        p.append('%s=%s'%(k,v))
    unsign_str = ('&'.join(p) + key).encode("utf-8")
    s = hashlib.md5(unsign_str).hexdigest()
    return s.upper()


# Body payload
txamt = '10' #In USD,EUR,etc. Cent
txcurrcd = 'HKD'
pay_type = '800101' # Alipay CPM = 800108 , MPM = 800101
auth_code='283854702356157409' #CPM only
out_trade_no = '01234567890123'
txdtm = current_time
goods_name = 'test1'   
auth_code = '280438849930815813'
mchid = 'ZaMVg*****'
notify_url = 'https://xxx.com/notify/success'
key = client_key


#data ={'txamt': txamt, 'txcurrcd': txcurrcd, 'pay_type': pay_type, 'out_trade_no': out_trade_no, 'txdtm': txdtm, 'goods_name': goods_name, 'udid': udid, 'auth_code': auth_code, 'mchid': mchid, 'notify_url': notify_url}
data ={'txamt': txamt, 'txcurrcd': txcurrcd, 'pay_type': pay_type, 'out_trade_no': out_trade_no, 'txdtm': txdtm, 'mchid': mchid}

r = requests.post(environment+"/trade/v1/payment",data=data,headers={'X-QF-APPCODE':app_code,'X-QF-SIGN':make_req_sign(data, key)})

print(r.json())

Java

import java.text.SimpleDateFormat;
import java.util.Date;
import java.util.HashMap;
import java.util.Map;

public class TestMain {
    public static void main(String args[]){
        String appcode="D5589D2A1F2E42A9A60C37*********";
        String key="0E32A59A8B454940A2FF39*********";
        String mchid="ZaMVg*****";

        String pay_type="800101";
        String out_trade_no= "01234567890123";
        SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
        String date=df.format(new Date());
        String txdtm=date;
        String txamt="10";
        String txcurrcd="EUR";

        Map<String, String> unsortMap = new HashMap<>();
        unsortMap.put("mchid", mchid);
        unsortMap.put("pay_type", pay_type);
        unsortMap.put("out_trade_no", out_trade_no);
        unsortMap.put("txdtm", txdtm);
        unsortMap.put("txamt", txamt);
        unsortMap.put("txcurrcd", txcurrcd);
        //unsortMap.put("product_name", product_name);
        //unsortMap.put("valid_time", "300");

        String data=QFPayUtils.getDataString(unsortMap);
        System.out.println("Data:\n"+data+key);
        String md5Sum=QFPayUtils.getMd5Value(data+key);
        System.out.println("Md5 Value:\n"+md5Sum);

        String url="https://test-openapi-hk.qfapi.com";
        String resp= Requests.sendPostRequest(url+"/trade/v1/payment", data, appcode,key);
        System.out.println(resp);
    }
}

Javascript

// Enter Client Credentials
const environment = 'https://test-openapi-hk.qfapi.com'
const app_code = 'D5589D2A1F2E42A9A60C37*********'
const client_key = '0E32A59A8B454940A2FF39*********'

// Generate Timestamp
var dateTime = new Date().toISOString().replace(/T/, ' ').replace(/\..+/, '')
console.log(dateTime)

// Body Payload
const key = client_key
var tradenumber = String(Math.round(Math.random() * 1000000000))
console.log(tradenumber)

var payload = {
'txamt': '10', // In USD,EUR,etc. Cent
'txcurrcd': 'HKD',
'pay_type': '800101', // Alipay CPM = 800108 , MPM = 800101
'out_trade_no': tradenumber,
'txdtm': dateTime,
'mchid': 'ZaMVg*****'
};

// Signature Generation
const ordered = {};
Object.keys(payload).sort().forEach(function(key) {
ordered[key] = payload[key] });
console.log(ordered)

var str = [];
for (var p in ordered)
if (ordered.hasOwnProperty(p)) {
str.push((p) + "=" + (ordered[p]));
}
var string = str.join("&")+client_key;
console.log(string)

const crypto = require('crypto')
var hashed = crypto.createHash('md5').update(string).digest('hex')
console.log(hashed)


// API Request
var request = require("request");
request({
uri: environment+"/trade/v1/payment",
headers: {
    'X-QF-APPCODE': app_code,
    'X-QF-SIGN': hashed
},
method: "POST",
form: payload,
}, 
function(error, response, body) {
console.log(body);
});

Php

<?php
ob_start();
function GetRandStr($length){
    $str='abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789';
    $len=strlen($str)-1;
    $randstr='';
    for($i=0;$i<$length;$i++){
        $num=mt_rand(0,$len);
        $randstr .= $str[$num];
    }
    return $randstr;
}

$url = 'https://test-openapi-hk.qfapi.com';
$api_type = '/trade/v1/payment';
$pay_type = '800101';
//$mchid = "MNxMp11FV35qQN"; //Only agents must provide this parameter
$app_code = 'FF2FF74F2F2E42769A4A73*********'; //API credentials are provided by QFPay
$app_key = '7BE791E0FD2E48E6926043B*********'; //API credentials are provided by QFPay
$now_time = date("Y-m-d H:i:s"); //Get current date-time

$fields_string = '';
$fields = array(
    //'mchid' => urlencode($mchid),
'pay_type' => urlencode($pay_type),
    'out_trade_no' => urlencode(GetRandStr(20)),
'txcurrcd' => urlencode('HKD'),
    'txamt' => urlencode(2200),
    'txdtm' => $now_time
);
ksort($fields); //Ascending dictionary sorting A-Z
print_r($fields);
    
foreach($fields as $key=>$value) { 
    $fields_string .= $key.'='.$value.'&' ;
}
$fields_string = substr($fields_string , 0 , strlen($fields_string) - 1);

$sign = strtoupper(md5($fields_string . $app_key));

//// Header ////
$header = array();
$header[] = 'X-QF-APPCODE: ' . $app_code;
$header[] = 'X-QF-SIGN: ' . $sign;

//Post Data
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url . $api_type);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $header);
curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, false);
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $fields_string);
$output = curl_exec($ch);
curl_close($ch);    

$final_data = json_decode($output, true);
print_r($final_data);

ob_end_flush();
?>

The above command returns JSON structured like this:

{
    "txdtm": "2019-12-25 14:21:28",
    "qrcode": "https://qr.alipay.com/bax01781r3pu4fjaqazt4091",
    "pay_type": "800101",
    "resperr": "success",
    "out_trade_no": "01234567890123",
    "syssn": "20191225000200020060996533",
    "sysdtm": "2019-12-25 14:22:37",
    "paydtm": "2019-12-25 14:22:37",
    "txcurrcd": "EUR",
    "respmsg": "",
    "cardcd": "",
    "udid": "qiantai2",
    "txamt": "10",
    "respcd": "0000",
    "chnlsn": ""
}

HTTP Request

POST ../trade/v1/payment

Listed below are the most common parameters for the payment endpoint. Please refer to the payment scenario applicable to you for additional parameters.

Public Payment Request Parameters

Attribute	Mandatory	Type	Description
txamt	Yes	Int(11)	Amount of the transaction. Unit in cents (i.e. 100 = $1)
txcurrcd	Yes	String(3)	Transaction currency. View the Currencies table for a complete list of available currencies
pay_type	Yes	String(6)	Please refer to the section Payment Codes for a complete list of payment types
out_trade_no	Yes	String(128)	External transaction number / Merchant platform transaction number: This parameter must be unique for each payment and refund request under the same merchant account in the system.
txdtm	Yes	String(20)	Transaction time format： YYYY-MM-DD hh:mm:ss
auth_code	Yes (CPM only)	String(128)	Specifies the authorization code for scanning a barcode/QR Code. The auth_code returned is unique in each authorization. Each auth_code can be used only once and will automatically expire in one day. For testing CPM with Alipay and WeChat Pay the auth_code can be extracted with any QRC reader or manually found in the consumer wallet below the barcode.
expired_time	No (MPM only)	String(3)	QRC expiration time in unit minutes. The default expiration time is 30 minutes. The parameter can manually be adjusted to a minimum of 5 minutes, and up to a maximum of 120 minutes. Available for: 800201 - WeChat scan code 800101 - Alipay scan code 801512 - Alipay Hong Kong WAP payment 801501 - Alipay Hong Kong scan code 801107 - Alipay overseas WAP payment 801101 - Alipay overseas scan code 801010 - WeChat Hong Kong APP 801510 - Alipay Hong Kong APP
goods_name	No	String(64)	Goods Name / Marking: Cannot exceed 20 alphanumeric or contain special characters. Cannot be empty for app payment. Parameter needs to be UTF-8 encoded if it is written in Chinese characters.
mchid	No	String(16)	May or may not be given to merchant. If MCHID is given, it is mandatory to provide the MCHID .On the contrary, if MCHID is not provided, merchants shall not pass in the MCHID parameter in the API request.
txzone	No	String(5)	Transaction Time zone. Default time zone is Beijing time UTC+8 (+0800).
udid	No	String(40)	Unique transaction device ID displayed on the merchant portal.
notify_url	No	String(256)	URL where asynchronous notificiations will be sent to upon payment completion.

Public Payment Response Parameters

Attribute	Type	Description
pay_type	String(6)	Please refer to the section Payment Codes for a complete list of payment types
sysdtm	String(20)	Format：YYYY-MM-DD hh:mm:ss This parameter value is used as the cut-off time for settlements.
txdtm	String(20)	Format：YYYY-MM-DD hh:mm:ss
resperr	String(128)	Request result description
txamt	Int(11)	Amount of the transaction
respmsg	String(128)	Supplementary response description
out_trade_no	String(128)	External transaction number
syssn	String(40)	QFPay internal transaction number (unique)
chnlsn	String	Wallet/Channel transaction number
respcd	String(4)	0000 = Request successful. 1143/1145 = merchants are required to continue to query the transaction result. All other return codes indicate transaction failure. Please refer to the page Transaction Status Codes for a complete list of response codes.

Transaction Status Codes

Return code	Description
0000	Transaction successful
1100	System under maintenance (1100)
1101	Reversal error (1101)
1102	Duplicate request (1102)
1103	Request format error (1103)
1104	Request parameter error (1104)
1105	Device not activated (1105)
1106	Invalid device (1106)
1107	Device not allowed (1107)
1108	Signature error (1108)
1125	Transaction has been refunded already (1125)
1136	The transaction does not exist or is not operational (1136)
1142	Order already closed (1142)
1143	The order has not been paid for, the password is currently being entered (1143)
1145	Please wait while processing (1145)
1147	Wechat pay transaction error (1147)
1150	Your billing method is T0 and does not support canceling transactions. (1150)
1155	Refund request denied (1155)
1181	Order expired (1181)
1201	Insufficient balance, please use a different payment method (1201)
1202	Incorrect or expired payment code, please show the correct payment code or refresh the payment code and retry (1202)
1203	Merchant account error, confirm that the payment account is configured correctly (1203)
1204	Bank error, confirm that the payment wallet is functionable (1204)
1205	The transaction failed. Please try again later (1205)
1212	Please use the UnionPay overseas payment code (1212)
1241	The store does not exist or the status is incorrect. Do not conduct payments (1241)
1242	The store has not been configured correctly, unable to conduct payments (1242)
1243	The store has been disabled. Do not conduct payments, contact the owner to confirm (1243)
1250	The transaction is forbidden. For more information please contact QFPay Customer Service Team (1250)
1251	The store has not been configured correctly, we are currently working to fix this problem (1251)
1252	System error when making the order request (1252)
1254	A problem occured. We are currently resolving the issue (1254)
1260	The order has already been paid for, please confirm the transaction result before conducting more transactions (1260)
1261	The order has not been paid for, please confirm the transaction result before conducting more transactions (1261)
1262	The order has been refunded, please confirm the order status before conducting more transactions (1262)
1263	The order has been cancelled, please confirm the order status before conducting more transactions (1263)
1264	The order has been closed, please confirm the order status before conducting more transactions (1264)
1265	The transaction cannot be refunded. Refunds for transactions between 11:30pm to 0:30am and special promotions cannot be processed. (1265)
1266	The transaction amount is wrong, please confirm the order status (1266)
1267	The order information does not match, please confirm the order status (1267)
1268	The order does not exist, please confirm the order status (1268)
1269	Today's unsettled transaction amount is insufficient. Refunds cannot be processed. Please confirm that the balance is sufficient (1269)
1270	This currency does not support partial refunds (1270)
1271	The selected transaction does not support partial refunds (1271)
1272	The refund amount is greater than the maximum amount that can be refunded for the original transaction (1272)
1294	The transaction may be non-compliant and has been prohibited by the bank (1294)
1295	The connection is slow, waiting for a network response (1295)
1296	The connection is slow, waiting for a network response. Please try again later or use other payment methods (1296)
1297	The banking system is busy. Please try again later or use other payment methods (1297)
1298	The connection is slow, waiting for a network response. In case you have already paid, do not repeat the payment. Please confirm the result later (1298)
2005	The customer payment code is incorrect or has expired, please refresh and restart the transaction process (2005)
2011	Transaction serial number repeats (2011)