QFPay POS API ECR Integration

https://sdk.qfapi.com/docs/in-store/pos-api/ECR/
Admin
Provides technical specifications for integrating Electronic Cash Registers (ECR) with the QFPay POS...
Tokens:62,509
Snippets:228
Trust Score:5.3
Update:1 year ago
Show doc for...
Tokens:
Raw
### Payment Object Initialization Example

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/paymentelement

An example demonstrating the initialization of both the QFPay global object and the subsequent payment object, which is necessary before performing payment operations.

```JavaScript
const qfpay = QFpay.config()
const payment = qfpay.payment()
```

--------------------------------

### Example API Response for Payment Intent

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/paymentelement

An example JSON structure showing the response parameters for a successful payment intent operation, including transaction details, system date and time, and intent expiry.

```JSON
{
    "respcd": "0000",
    "txamt": "123",
    "txcurrcd": "123",
    "sysdtm": "2022-11-14 16:15:16",
    "out_trade_no": "501871840",
    "payment_intent": "38aec7cef8564f309ea2265a454b8ca5",
    "intent_expiry": "2022-11-15 12:34:34"
}
```

--------------------------------

### Java Example for QFPay Trade Query

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/common-api/transaction-enquiry

This Java example illustrates how to query trade information using the QFPay API. It includes steps for setting up API credentials, constructing the request map, generating the MD5 signature, and sending a POST request to the trade query endpoint.

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

public class Enquiry {
    public static void main(String args[]){
        String appcode="D5589D2A1F2E42A9A60C37**********";
        String key="0E32A59A8B454940A2FF39*********";
        String mchid="ZaMVg*****"; // Only Agents must provide the mchid

        SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
        String date=df.format(new Date());
        String txdtm=date;

        String syssn="20191227000300020061662295";
        String start_time = "2019-12-27 00:00:00";
        String end_time = "2019-12-27 23:59:59";

        Map<String, String> unsortMap = new HashMap<>();
        unsortMap.put("mchid", mchid);
        unsortMap.put("syssn", syssn);

        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/query", data, appcode,key);
        System.out.println(resp);
    }
}
```

--------------------------------

### Initiate QFPay In-Store Payment Request (PHP)

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/in-store/CPM

This PHP example demonstrates how to set up the necessary parameters for an in-store payment request, including payment type, authorization code, and generating a random `out_trade_no`. It also shows how to get the current timestamp and prepare the fields for the API call.

```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 = '800108'; //Alipay CPM = 800108, WeChat Pay CPM = 800208
     $auth_code = '280438849930815813';
     //$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),
      'auth_code' => urlencode($auth_code),
      'out_trade_no' => urlencode(GetRandStr(20)),
      'txcurrcd' => urlencode('HKD'),
```

--------------------------------

### Python Example for Asynchronous Notification Signature Verification Setup

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/common-api/asynchronous-notification

This Python code snippet demonstrates the initial setup for verifying the integrity of asynchronous notification messages from QFPay. It shows how to import necessary libraries like `hashlib` and `json`, and how to define the `client_key` which is crucial for the MD5 hashing process used in signature verification. The full verification process involves appending this key to the raw request body and then hashing.

```Python
import hashlib
import json

# Client Credentials
client_key = "3ABB1BFFE2E0497BB9270978B0BXXXXX"
```

--------------------------------

### Create Payment Intent API Overview

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/paymentelement

High-level overview of the Create Payment Intent API, outlining its structure including required headers, request parameters, and expected response parameters.

```APIDOC
Create Payment Intent API:
  Header: API request headers.
  Request Parameters: Parameters required for creating a payment intent.
  Response Parameters: Parameters returned upon successful payment intent creation.
```

--------------------------------

### GET WeChat OAuth Code Request URL Example

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/wechat/wechat-pay-jsapi

Example of the direct URL for initiating the WeChat OAuth code request, showing the required app_code, sign, and redirect_uri parameters.

```HTTP
GET WeChat oauth_code request:

{
  https://test-openapi-hk.qfapi.com/tool/v1/get_weixin_oauth_code?app_code=5D81D64E602043F7AF51CEXXXXXXXXXX&sign=F4D8FB00894F213993B33116BC1B4E10&redirect_uri=https://sdk.qfapi.com
}
```

--------------------------------

### Example API Response JSON Structure

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/preparation/introduction

This snippet shows a simplified example of a JSON response from the API, illustrating a single string value as the response body. This is likely an example of a successful signature verification response or a unique identifier returned by the API.

```JSON
{
"B3B251B202801388BE4AC8E5537B81B1"
}
```

--------------------------------

### JavaScript Example for QFPay Payment Request (Node.js)

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/alipay/alipay-service-window-h5

This JavaScript (Node.js) example details the process of making a QFPay payment request. It covers setting up client credentials, generating a timestamp and a unique trade number, constructing the payload, sorting parameters for signature generation, calculating an MD5 hash, and sending the POST request using the 'request' module.

```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. Suggest value > 200 to avoid risk control
'txcurrcd': 'HKD',
'pay_type': '801107', // Alipay Wap Payment = 801107
'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);
});
```

--------------------------------

### Java Example for QFPay API Refund/Reversal

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/common-api/reversal-cancel

This Java example illustrates how to prepare the parameters for a refund or reversal transaction, including merchant ID, transaction amount, system serial number, and transaction date. It shows the use of 'QFPayUtils' (assumed utility class) for data string generation and MD5 signature calculation, followed by sending the POST request to the QFPay API.

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

public class Refund {
    public static void main(String args[]){
        String appcode="3F504C39125E4886AB4741**********";
        String key="5744993FBC034DBBB995FA**********";
        String mchid="MNxMp11FV35qQN"; // Only Agents must provide the mchid

        SimpleDateFormat df = new SimpleDateFormat("yyyy-MM-dd HH:mm:ss");
        String date=df.format(new Date());

        String txdtm="2020-03-05 16:50:30";
        String txamt="2500";
        String syssn="20200305066100020000977812"; //only syssn or out_trade_no must be provided
        String out_trade_no="4MDGEJ7L496LAAU1V1HBY9HMOGWZWLXQ"; //only syssn or out_trade_no must be provided

        Map<String, String> unsortMap = new HashMap<>();
        unsortMap.put("mchid", mchid);
        unsortMap.put("txamt", txamt);
        unsortMap.put("syssn", syssn);
        unsortMap.put("out_trade_no", out_trade_no);
        unsortMap.put("txdtm", txdtm);

        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);

         //如果是国内钱台，网址是：https://test-openapi-hk.qfapi.com.
        String url="https://test-openapi-hk.qfapi.com";
        String resp= Requests.sendPostRequest(url+"/trade/v1/reversal", data, appcode,key);
        System.out.println(resp);
    }
}
```

--------------------------------

### Import QFPay Element SDK JavaScript Library

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/paymentelement

Provides script tags to import the QFPay Element SDK JS library for sandbox, live test, and production environments. Choose the appropriate URL based on your deployment stage.

```javascript
// sanbox environment
<script src="https://cdn-int.qfapi.com/qfpay_element/qfpay.js"></script>
// live test environment
<script src="https://test-cdn-hk.qfapi.com/qfpay_element/qfpay.js"></script>
// production environment
<script src="https://cdn-hk.qfapi.com/qfpay_element/qfpay.js"></script>

```

--------------------------------

### Prerequisites for QFPay Element SDK Integration

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/paymentelement

Outlines the necessary prerequisites for integrating the QFPay Element SDK. The primary requirement is to import the SDK library (qfpay.js) based on the specific environment and purpose of the integration.

```text
Prerequisites:
import SDK library (qfpay.js) according to your environment and purpose

```

--------------------------------

### QFPay Global Object API Reference

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/paymentelement

Documentation for the global QFPay object and its core methods for SDK configuration, payment intent retrieval, and various payment processing functionalities.

```APIDOC
QFPay Global Object:
  QFpay.config(params): Configures the QFPay SDK with provided parameters.
  qfpay.retrievePaymentIntent(): Retrieves a payment intent.
  qfpay.element(appearance): Creates an element object for UI integration based on appearance settings.
  qfpay.payment(): Initiates a payment process.
  qfpay.confirmPayment(): Confirms a payment.
  qfpay.confirmWalletPayment(): Confirms a wallet payment.
```

--------------------------------

### CPM API Request Header and Body Example

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/in-store/CPM

Illustrates the required HTTP headers and the structure of the request body for initiating a Consumer Present Mode (CPM) payment.

```APIDOC
Request Header:

{
  Content-Type: application/x-www-form-urlencoded;
  charset=UTF-8,
  Content-Length: 218,
  Chunked: false
  X-QF-APPCODE:A6A49A66B4C********94EA95032
  X-QF-SIGN:3b020a6349646684ebeeb0ec2cd3d1fb
}

Request Body:

{
  auth_code=13485790*******88557&goods_name=qfpay&mchid=R1zQrTdJnn&out_trade_no=Native201907221520536a25477909&pay_type=800208&txamt=10&txcurrcd=HKD&txdtm=2019-07-22 15:20:54&udid=AA
}
```

--------------------------------

### Payment Object API Reference

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/paymentelement

Documentation for the payment object methods, including direct payment, wallet payment, and inquiry functionalities for transaction status.

```APIDOC
Payment Object:
  payment.pay(params1, params2): Processes a payment with specified parameters.
  payment.walletPay(params1, params2): Processes a wallet payment with specified parameters.
  payment.inquiry(params1, params2): Inquires about a payment status with specified parameters.
```

--------------------------------

### Initialize and Display Credit Card Payment Form (Visa/Mastercard)

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/paymentelement

Initializes QFPay SDK, sets parameters for credit card transactions, and generates a Visa/Mastercard payment form. Demonstrates triggering form submission and receiving payment responses.

```javascript
// initialize qfpay object
const qfpay = QFpay.config()

// initialize payment object
const payment = qfpay.payment()

// set payment related parameters
payment.pay({
  goods_name: "goods",
  paysource: "payment_element"
}, "e487a02e3e1143e482db765ccec63d58")

// initialize element object and generate card form
const elements = qfpay.element()
elements.createEnhance({
  selector: "#container"
})

// trigger card form submission and receive payment response
const response = qfpay.confirmPayment({
  return_url: 'https://xxx.xxx.com'
})

```

--------------------------------

### PHP Example for QFPay Trade Query

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/common-api/transaction-enquiry

This PHP example shows how to query trade information from the QFPay API. It includes functions for generating random strings (though not used in the main query logic), setting up API credentials, preparing and sorting request parameters, generating the MD5 signature, and sending the POST request using cURL.

```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/query';
$syssn = '20200311066100020000977841';
//$out_trade_no = 'zCvo0IqTg0SaQkGnHd6w';
//$mchid = "MNxMp11FV35qQN"; //Only agents must provide this parameter
$app_code = 'FF2FF74F2F2E42769A4A73*********'; //API credentials provided by QFPay
$app_key = '7BE791E0FD2E48E6926043B*********'; //API credentials provided by QFPay
$now_time = date("Y-m-d H:i:s"); //Get the current date-time

$fields_string = '';
$fields = array(
//'mchid' => urlencode($mchid),
'syssn' => urlencode($syssn),
//'out_trade_no' => urlencode($out_trade_no),
//'start_time' = '2020-03-01 00:00:00',
//'end_time' = '2020-03-04 23:59:59'
);
ksort($fields); //Sort parameters in ascending order from A to 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();
?>
```

--------------------------------

### Example JSON Response Format

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/in-store/pos-api/ECR

Illustrates the basic structure of a successful API response, including response code, data, and messages.

```json
{\"respcd\": \"6000\",\"data\": \"{\\\"aaaaaa\\\"}\",\"respmsg\": \"xxxxxxxxxx\",\"resperr\":\"xxxxxxxxxx\"}
```

--------------------------------

### Python Example: Generating X-QF-SIGN for MPM API

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/in-store/MPM

This Python code snippet provides a practical example for generating the `X-QF-SIGN` signature required for authenticating requests to the MPM API. It demonstrates how to sort request parameters, concatenate them with the client key, and apply MD5 hashing to produce the signature. It also shows how to set up client credentials and generate dynamic values for transaction parameters.

```Python
#coding=utf8
import urllib.request, urllib.parse, urllib.error, urllib.request, urllib.error, urllib.parse, hashlib
import requests
from hashids import Hashids
import datetime
import string
import random

# Enter Client Credentials
environment = 'https://test-openapi-hk.qfapi.com'
app_code = 'FADB8A87E0674012979F5443AA81ECF1'
client_key = 'F644B1389AD24C25BEFE8BE10C31C878'

# Create parameter values for data payload
current_time = datetime.datetime.now().replace(microsecond=0)
random_string = ''.join(random.choices(string.ascii_uppercase + string.digits, k=32))

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")
    print(unsign_str)
    s = hashlib.md5(unsign_str).hexdigest()
    return s.upper()
```

--------------------------------

### Example JSON Response for Payment API

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/preparation/paycode

Illustrates a typical successful JSON response received from the QFPay payment API, including transaction details, QR code, payment type, and various status and identification codes. This example helps developers understand the expected data structure upon a successful API call.

```JSON
{
    "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": ""
}
```

--------------------------------

### Configure QFPay Global Object

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/paymentelement

Initializes the QFPay global object. Allows configuration of region ('hk', 'qa') and environment ('prod', 'test', 'qa') settings. Returns the configured QFPay object for further API calls.

```JavaScript
/**
 * parameters: optional, Object, default valie: {region: 'hk', env: 'prod'},
 *      region possible values：
 *        'hk' 		- live/live test
 *        'qa' 		- sandbox
 *
 *      env possible values:
 *        'prod' 	- live environment
 *        'test' 	- live test environment
 *        'qa' 		- sandbox environment
 * return: qfpay object
 * purpose: generate qfpay global object
 */
const qfpay = QFpay.config()
```

--------------------------------

### QFPay API Payment Response Example

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/alipay/alipay-in-app-payments

Example of a successful JSON response from the QFPay API, detailing transaction status, payment parameters, and system identifiers. The `pay_params` object contains information relevant for subsequent Alipay SDK calls.

```JSON
{
  "pay_type": "801510",
  "sysdtm": "2021-05-27 11:57:02",
  "paydtm": "2021-05-27 11:57:02",
  "udid": "qiantai2",
  "txcurrcd": "HKD",
  "txdtm": "2021-05-27 11:57:00",
  "txamt": "1",
  "resperr": "交易成功",
  "respmsg": "",
  "out_trade_no": "052711570017898",
  "syssn": "20210527154100020004180921",
  "pay_params": {
    "body": "goods_info",
    "forex_biz": "FP",
    "seller_id": "2088231067382451",
    "secondary_merchant_id": "1000007081",
    "service": "mobile.securitypay.pay",
    "payment_inst": "ALIPAYHK",
    "it_b_pay": "30m",
    "secondary_merchant_name": "IFlare Hong Kong Limited (external) - online",
    "_input_charset": "UTF-8",
    "sign": "iU1yXUnsCK7rJAu0DoN61arVexbIfo3GLR5jr3QzjkZ29INSPhcA4e%2F2%2BdPrsf5huzQAkxVKP0CTfvaGPMYqNkxmhoaJWUH0ZhgYDgKugMvtweBvRqOX2W0h3A%2F%2FIdJuxeyOAuh7bHiuazSB3ZH%2BEQwRGP%2Bkk8Jpha930gHwPtw%3D",
    "currency": "HKD",
    "out_trade_no": "20210527154100020004180921",
    "payment_type": "1",
    "total_fee": 0.01,
    "sign_type": "RSA",
    "notify_url": "https://test-o2-hk.qfapi.com/trade/alipay_hk/v1/notify",
    "partner": "2088231067382451",
    "secondary_merchant_industry": "5941",
    "product_code": "NEW_WAP_OVERSEAS_SELLER",
    "return_url": "https://www.qfpay.global/",
    "subject": "goods_name"
  },
  "respcd": "0000",
  "chnlsn": "",
  "cardcd": ""
}
```

--------------------------------

### Initialize QFPay Payment Object

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/paymentelement

Generates a payment object from the QFPay instance. This object is essential for initiating and confirming payment transactions. It requires a previously configured QFPay global object.

```JavaScript
/**
 * parameters: N/A
 * return： payment object
 * purpose: generate payment object
 */
const qfpay = QFpay.config()
const payment = qfpay.payment()
```

--------------------------------

### Example JSON Response for Transaction Query

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/common-api/transaction-enquiry

Illustrates the structure of a successful JSON response returned by the API for a transaction query, containing details for multiple transactions.

```json
{
"respmsg": "",
"resperr": "请求成功",
"respcd": 0,
"data":
[{
"cardtp": "5",
"cancel": "0",
"pay_type": "800101",
"order_type": "payment",
"clisn": "038424",
"txdtm": "2019-12-27 10:39:39",
"goods_detail": "",
"out_trade_no": "CHZ7D61JN1ANJF2R2K1I7TXP2JTCEWBL",
"syssn": "20191227000200020061752831",
"sysdtm": "2019-12-27 10:40:24",
"paydtm": "2019-12-27 10:42:18",
"goods_name": "",
"txcurrcd": "EUR",
"chnlsn2": "",
"udid": "qiantai2",
"userid": "2605489",
"txamt": "10",
"chnlsn": "2019122722001411461404119764",
"respcd": "0000",
"goods_info": "",
"errmsg": "success"
}],
"page": "1",
"page_size": "10"
}
```

--------------------------------

### Element Object API Reference

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/paymentelement

Documentation for the element object methods used to create payment input fields, supporting various card types and payment methods like ApplePay, as well as token creation.

```APIDOC
Element Object:
  elements.create(params1, params2, params3, params4): Creates payment elements, supporting Visa/Mastercard card payment only.
  elements.createEnhance(params): Creates enhanced payment elements, supporting Visa Mastercard card payment, ApplePay payment, and token creation in payment mode.
```

--------------------------------

### Example JSON Response for QFPay API Transaction

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/common-api/reversal-cancel

Illustrates the typical JSON structure returned by QFPay API calls, showing various transaction details such as surcharge fees, response codes, transaction amounts, and timestamps.

```JSON
{
    "surcharge_fee": "0",
    "resperr": "success",
    "txdtm": "2020-03-05 16:50:30",
    "syssn": "20200305066100020000977814",
    "sysdtm": "2020-03-05 16:54:38",
    "txcurrcd": "EUR",
    "respmsg": "",
    "chnlsn2": "",
    "cardcd": "",
    "udid": "qiantai2",
    "txamt": "2500",
    "orig_syssn": "20200305066100020000977813",
    "surcharge_rate": "0",
    "respcd": "0000",
    "chnlsn": ""
}
```

--------------------------------

### GET WeChat OpenID Request URL Example

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/wechat/wechat-pay-jsapi

Example of the direct URL for requesting the WeChat OpenID. This request requires the 'code' parameter obtained from the OAuth code redirect.

```HTTP
HTTP Request:

{
  https://test-openapi-hk.qfapi.com/tool/v1/get_weixin_openid?code=011QipnO1yMIla1VJdoO1FUrnO1Qipnv
}
```

--------------------------------

### Initialize and Display Complete Wallet Payment Form (Multi-Payment Types)

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/paymentelement

Sets up a comprehensive payment flow supporting various wallet types like Alipay, WeChat Pay, and UnionPay. Initializes SDK, validates intent, sets parameters, customizes appearance, and creates a wallet list for selection.

```javascript

// initialize qfpay object
const qfpay = QFpay.config()

// initialize payment object
const payment = qfpay.payment()

// validate payment intent valye
qfpay.retrievePaymentIntent()

// set payment parameters
payment.walletPay(
{
  lang:  'zh-cn',
  goods_info:  'goods_info',
  goods_name:  "goods_name",
  paysource:  "payment_element_checkout",
  out_trade_no: intentParams.out_trade_no,
  txamt:  intentParams.txamt,
  txcurrcd:  intentParams.txcurrcd,
  support_pay_type: ['Alipay', 'WeChat', 'UnionPay', 'AlipayHK',
  'FPS', 'VisaMasterCardPayment', 'ApplePay', 'VisaMasterCardPreAuth']
},intentParams.payment_intent);
// initalize element object and create wallet list
const  appearance = {
variables: {
	colourComponentText:  'black',
	colorQRCodeTopPromptContent:  '#000000',
	colorQRCodeBottomPromptContent:  '#000000',
	fontWeightQRCodeTopPrompt:  '900',
	fontWeightQRCodeBottomPrompt:  '300'
},
billingAddressDisplay: {
	city:  true,
	address1:  true,
	address2:  true,
}
}
const elements = qfpay.element(appearance)
elements.createWallet({
	selector:  "#container"
})

//trigger submission and retrieve payment response
const response = qfpay.confirmWalletPayment({
return_url:  'https://xxx.xxx.com'
})

```

--------------------------------

### Initiate QFPay In-Store Payment Request (Java)

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/in-store/CPM

This Java example shows how to prepare the payment request parameters, generate the signature using `QFPayUtils`, and send a POST request to the QFPay `/trade/v1/payment` API. It covers setting up transaction details, merchant ID, and handling date formatting.

```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="800108";
        String auth_code="280438849930815813";
        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("auth_code", auth_code);
        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);
    }
}
```

--------------------------------

### Process Refund with QFPay API in PHP

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/common-api/refunds

This PHP example demonstrates how to send a refund request to the QFPay API. It includes a helper function to generate a random string for the trade number, setting up API credentials, getting the current timestamp, constructing and sorting the request parameters, generating an MD5 signature, and finally making the API call using cURL.

```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/refund';
     $syssn = '20200311066100020000977840';
     //$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 the currend date-time

     $fields_string = '';
     $fields = array(
	  //'mchid' => urlencode($mchid),
    'syssn' => urlencode($syssn),
	  'out_trade_no' => urlencode(GetRandStr(20)),
	  'txamt' => urlencode(2200),
	  'txdtm' => $now_time
    );
    ksort($fields); //Sort parameters in ascending order from A to 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);
```

--------------------------------

### Preparing QFPay API Payment Request in PHP

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/preparation/introduction

This PHP snippet demonstrates how to set up the necessary parameters for a QFPay payment API request. It includes defining API credentials, generating a random string for 'out_trade_no', and constructing an associative array of payment fields. The snippet also shows how to sort these parameters alphabetically, a common step before signature generation.

```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 the 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); //Sort parameters in ascending order from A to Z
print_r($fields);
```

--------------------------------

### Example QFPay API Response Body

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/wechat/wechat-in-app-payments

An example of the JSON response returned by the QFPay API after a successful transaction, including payment details and system information.

```JSON
{
  "sysdtm": "2019-09-13 12:53:04",
  "paydtm": "2019-09-13 12:53:04",
  "txcurrcd": "HKD",
  "respmsg": "",
  "pay_params":
        {
        "package": "Sign=WXPay",
        "timestamp": 1568350384,
        "sign": "XwFjohEKWdkhhT4ueg7BxeDn8tT9LcqoZYdXzifTMYyDGe3/tRchpii6vWgOn21tPSaAtqo766gvifXgDEOwR+ILKN8t97r624IJlrH0EkvSUSLh9E/cga9scXGVy0jPWHM/oVvVzJIvXew79CwZFCNTSJok2KmpSm9X9oPg7PGXbqvNMHltf+YlIOsuiz391qVmFtTE5A/cpA50+06T7iW8GYsOJQTTJed75VY+aSzNo5C6ju6WSgJKpAJJ0ocl+ONtmOp6GLVBSQXaMC4PitQcebcoP2J6fFgQ+YcPwHXasCYEnn4LaFN7zT/AjGg3E3gdCx3ksGNBOazYBRVz+g==",
        "partnerid": "316525492",
        "appid": "wx3c6896fa9b351f2a",
        "prepayid": "wx131253044253463a81dc336e1254149882",
        "noncestr": "7786db42d9a245c2b1cfc717ac59376e"
        },
  "pay_type": "800210",
  "cardcd": "",
  "udid": "AA",
  "txdtm": "2019-09-13 04:53:03",
  "txamt": "10",
  "resperr": "交易成功",
  "out_trade_no": "O5DNgEgL1XpvbvQSfPhN",
  "syssn": "20190913152100020001567741",
  "respcd": "0000",
  "chnlsn": ""
}
```

--------------------------------

### WeChat Pay H5: Example Request Body for extend_info

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/wechat/wechat-pay-h5

Provides a concrete JSON example for the extend_info parameter, demonstrating the structure for scene_info and spbill_create_ip.

```JSON
extend_info:
{
  "scene_info":{ //场景类型
    "h5_info": { // h5支付固定传"h5_info"
      "type": "Wap", //场景类型
      "wap_url": "https://qfpay.global/h5/pay", //WAP网站URL地址
      "wap_name": "qfpay" //WAP 网站名
    }
  },
  "spbill_create_ip": "192.168.1.10"// 用户真实ip地址获取指引 https://pay.weixin.qq.com/wiki/doc/api/H5.php?chapter=15_5
}
```

--------------------------------

### Steps to Create a Recurring Payment Subscription

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/qfpay-recurring-payment

Outlines the sequential steps required to establish a new subscription, from configuring notifications to creating customer, product, and subscription objects using various API calls.

```APIDOC
1. Config your notification address, you will receive notification to get token_id and track the state change of subscription.
2. Create customer object and get customer_id
3. Integrate with our element service and use elements.createEnhance() and payment.pay() for token creation page. Then use customer_id and card information to create token and get token_id
4. Create product object and get product_id, your subscription transaction amount for each billing cycle and the interval between two billing cycles will be defined in product object.
5. Create subscription object using customer_id, product_id and token_id, your subscription start time and total billing cycles will be defined in subscription object.
```

--------------------------------

### Example QFPay API Request Body

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/wechat/wechat-in-app-payments

An example of the request body format for QFPay API calls, showing key-value pairs for transaction details. Note that this is a URL-encoded string, not a JSON object.

```Text
{ goods_info=test_app&goods_name=qfpay&out_trade_no=O5DNgEgL1XpvbvQSfPhN&pay_type=800210&txamt=10&txcurrcd=HKD&txdtm=2019-09-13 04:53:03&udid=AA }
```

--------------------------------

### WeChat OpenID Response JSON Example

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/wechat/wechat-pay-jsapi

Example of the JSON response returned after a successful WeChat OpenID request. The 'openid' field contains the unique identifier for the WeChat user.

```JSON
{
  "resperr": "",
  "respcd": 0000,
  "respmsg": "",
  "openid": "oo3Lss8d0hLOuyTuSJMVwLTk68JE"
}
```

--------------------------------

### WeChat OAuth Code Redirect URL Example

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/wechat/wechat-pay-jsapi

Example of the URL to which the user is redirected after a successful WeChat OAuth code request. This URL contains the 'code' parameter, which is then used to obtain the OpenID.

```HTTP
{
  "http://xg.fshop.top/index.php/wap/pay/wxredirect?showwxpaytitle=1&code=011QipnO1yMIla1VJdoO1FUrnO1Qipnv"
}
```

--------------------------------

### Java Payment API Integration Example

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/preparation/paycode

Illustrates how to prepare payment parameters, generate an MD5 signature, and send a POST request to the QFPay payment API using Java. It includes setting up credentials, formatting the date, constructing a map of parameters, and utilizing utility methods for data string and MD5 generation.

```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="D5589D2A1F2E42A9A60C
```

--------------------------------

### QFPay API Request Body Example

Source: https://sdk.qfapi.com/docs/in-store/pos-api/ECR/online-shop/alipay/alipay-in-app-payments

Example of a URL-encoded request body for a QFPay payment API call, including transaction details, payment type, and merchant information. This payload is sent to the QFPay API.

```Plain Text
txamt=1&txcurrcd=HKD&pay_type=801510&out_trade_no=052711570017898&txdtm=2021-05-27+11%3A57%3A00&goods_name=goods_name&goods_info=goods_info&mchid=nDB64h9qJ1An&trade_name=trade_name&goods_detail=goods_detail&return_url=https%3A%2F%2Fwww.qfpay.global%2F&pay_tag=ALIPAYHK&seller_id=testoverseas9191%40alipay.com
```
Tokens:
Raw