QFPay API in Japanese Business

Index

● 1. Business Process

● 1.1 Merchant registration

● 1.2 Payment Process

○ 1.2.1 Barcode payment

○ 1.2.2 Query transaction

○ 1.2.3 Cancel transaction

○ 1.2.4 Response code description

● 1.3 Reconciliation

● 2. API

● 2.1 Scan barcode interface

● 2.2 Dynamic QR code pay interface   

● 2.3 Refund interface

● 2.4 Query interface

● 2.5 Close interface

● 2.6 Download reconciliation interface

● 2.7 Parameter Description

● 3. Developer Guide

● 3.1 Environment Description

● 3.2 Signature Algorithm

● 3.3 Request Description

● 3.4 Verifying the Signature

● 3.5 Notification Callback

● 3.6 Sample code

1. Business Process

1.1 Merchant registration

Merchants have to register to the QFPay services.

After registration, merchants will receive their app-code, key for integration, and the unique merchant ID (mchid) for each store.

Example:

AppCode: <32_character_MD5_string_qfpay>

Key: <32_character_MD5_string_qfpay>

1.2 Payment Process

Now, we provide an example about how merchants can use the API to do a barcode payment.

Note: There are limitations to the payment amount (depending on bank). Please refer to kf.qq.com/touch/sappfaq/151210NZzmuY151210ZRj2y2.html?platform=15&ADTAG=veda.weixinpay.wenti

1.2.1 Barcode payment

After receiving the code, key and mchid, merchants are ready to use the QFPay services. By using code scanner, Merchant can scan consumer's Wechat/Alipay QR code to get the auth_code, cash will be deducted from consumer's Wechat/Alipay account. The whole process is shown as the following flow chart

Process:

Step 1, using code scanner to scan consumer's Wechat/Alipay QR code, send the transaction request to QFPay system. (The detail of the barcode payment interface can be found at API 2.1)

1a, if get response code as 0000 from the QFPay system, then the transaction is successful.

1c, if get response code which is not 0000, 1143 or 1145, then the transaction is failed.

1b, if get response code as 1143, 1145 from the QFPay system, then the transaction is still in processing.

1.2.2 Query transaction

Step 2, call the query interface to QFPay system and check the status of the transaction again.

 (The detail of the query interface can be found at API 2.4)

2a, if get response code as 0000 from the QFPay system, then the transaction is successful.

2c, if get response code which is not 0000, 1143 or 1145, then the transaction is failed.

2b, if get response code as 1143, 1145 from the QFPay system, then the transaction is still in processing. Go back to Step 2.

1.2.3 Cancel transaction

After calling query interface for more than 2 minutes, if the response code is still 1143 or 1145, please cancel the transaction and place the order again.

 (The detail of the cancel interface can be found at API 2.5)

1.2.4 Response code description

2. API

2.1 Barcode Payment

2.1.1 Interface Description

In this scenario, merchant can scan consumer's Wechat/Alipay QR code via scanning gun to get auth_code, cash will be deducted from consumer's Wechat/Alipay account

2.1.2 Process Flow

2.1.3 Request Information

2.1.4 Request Parameters

2.1.5 Request Example

2.1.6 Response Parameters

2.1.7 Response Example

2.2 Merchant QR Code Payment

2.2.1 Interface Description

Merchant enter the price of product and call QFPay’s interface to generate a dynamic QR code, consumer scan the QR code by using Wechat or Alipay app to finish the payment. The dynamic QR code will expire in 30 minutes.

2.2.2 Request Information

2.2.3 Request Parameters

2.2.4 Request Example

2.2.5 Response Parameters

2.2.6 Response Example

2.2.7 Notification callback

Merchants receive the notification callback when the payment is successfully made

Note: The notification callback may be delayed due to external factors. Therefore, please use query interface for the scene with real-time processing requirements. For security reasons, notification callback only supports ports 80 and 443, and custom port assignments are not supported. For more detail, please see Developer Guide 3.5.

2.3 Refund interface

2.3.1 Interface Description

The merchant and partner can use this interface to refund an existing payment. A refund can be partial and a transaction can have multiple refunds as long as the total refund amount is no greater than the original transaction amount.

2.3.2 Request Information

2.3.3 Request Parameters

2.3.4 Request Example

2.3.5 Response Parameters

2.3.6 Response Example

2.4 Query interface  

2.4.1 Interface Description

When the transaction is in processed, call the query interface to acquire the status of transaction. Using the start-time and end-time to check the status of transactions in multiple months. Or, using QFPay order number(syssn) to check the status of specific transaction.

2.4.2 Request Information

2.4.3 Request Parameters

2.4.4 Request Example

2.4.5 Response Parameters

Description of parameter <data>:

The parameter respcd=0000 inside the data_list stands for the transaction is complete.

The respcd=0000 outside of the data_list stands for the order has been placed.

2.4.6 Response Example

2.5 Cancel interface

2.5.1 Interface Description

1. What’s kind of order can be closed?

If the payment is unsuccessful, the order can always be canceled. If  the cancel interface is called while the payment is successful made, which actually stands for calling the WeChat revoke API, and the payment for this order will be returned.

2. Scenarios of canceling the transaction

Cancel interface is only applicable at the time,which is mainly used to avoid double payments.
In order to avoid causing various unknown problems, please do not use the cancel interface as a refund interface.

2.5.2 Request Information

2.5.3 Request Parameters

2.5.4 Request Example

2.5.5 Response Parameters

2.5.6 Response Example

Note: Cancel transaction is non-generic supported, there may be cases that do not support canceling the transaction. If the cancel interface response return code is "1297" or the returned content has no syssn field (note: not orig_syssn), the transaction does not support canceling the order. If the user Successfully paid, the refund interface can be called for a refund.

2.6 Parameter Description

2.6.1 out_trade_no

The merchant’s order number is custom generated by the merchant. It only supports the combination of alphanumeric characters, such as alphanumeric, underline _, vertical bar|, and asterisk *. Do not use special characters such as Chinese characters or full-width characters. The merchant order number is required to be unique (it is recommended to be generated based on the current system time plus a random sequence). To re-initiate a payment, use the original order number to avoid double payment; the order number that has been paid or has been called, and the cancelled order number cannot be reused for a new payment.

Notice: If not using, please not input this parameter to request parameters as the form of none.

2.6.2 goods_name

no longer than 20 characters, special characters are not allowed. Note: special characters include full-width characters and symbols (★☆★$ & ¤ § | °゜ ¨ ± · × ÷ ˇ ˉ ˊ ˋ ˙ Γ Δ Θ Ξ Π Σ Υ Φ Ψ Ω α β γ δ ε ζ η θ ι κ λ μ ν ξ π ρ σ τ υ φ ψ ω Ё Б Г Д Е Ж З ИЙ К Л Ф У Ц Ч Ш Щ Ъ Ы Э Ю Я а б в г д ж з и й к л ф ц ч ш щ ъ ы ю я ａｂｃｄｅｆｇｈｉｊｋｌｍｎｏｐｑｒｓｔｕｖｗｘｙｚ - ― ‖ ‥ … ‰ ′ ″ ※ ℃ ℅ ℉ № ℡)

3. Developer Guide

3.1 Environment Description

QFPay provides two environment for using our services:

3.1.1 Test Environment:

Request Url: https://openapi-test.qfpay.com

1. During test, the money will not be operated. Please use little amount.

2. Mchid can be found in the channel system, which will be provided when formally applying the app-code and key.

3. Merchants under the same channel system can use the same app-code and key.

3.1.2 Formal Environment:

Request Url: https://openapi.qfpay.com

Please use your formal information including the mchid, code and key.

3.2 Signature Algorithm

When there is no special statement, the signature in all request interfaces uses the format below:

How to make the interface parameter signature:

Step 1: Ascending order all parameters by parameter name。

Parameter list :abc=value1 bcd=value2 bad=value3

The ascending result:abc=value1 bad=value3 bcd=value2

Step 2:Connect all parameters with & to get the string to be signed.

abc=value1&bad=value3&bcd=value2

Step 3:Splice the string to be signed with the developer's Key.

abc=value1&bad=value3&bcd=value2Key

Step 4:Apply  MD5 for the spliced string.

MD5(abc=value1&bad=value3&bcd=value2Key)

Step 5:Use signature to request the interface.

Store the signed results into the X-QF-SIGN in the HTTP head.

Python Sample:

3.3 Request Description

When requesting API interface, parameters have to be set up as follows in the HTTP head.

3.4 Verifying the Signature

Description: after successfully requesting the interface, a JSON format buffer will be received and to be verified.

The response HTTP head is set up as follows’

3.4.1 Head Signature sample

3.4.2 Public response parameters:

3.4.3 Response Signature sample

3.5 Notification Callback

3.5.1 Note 

The notification callback address has to be provided to the technical support of QFPay through channel system. Each notification callback  address can only be configured with one set of code and key, which can be modified.

If the order is successfully paid, the result of the notification callback will be returned. However, the notification callback may be delayed due to external factors. Therefore, please use query interface for the scene with real-time processing requirements. It is recommended that the notification callback can be used together with the query interface. For security reasons, notification callback only supports ports 80 and 443, and custom port assignments are not supported.

3.5.2 Notification Callback Rules

1. The address of the notification callback has to be provided to the technical support of QFPay by setting up in the channel  system.

2. After the transaction succeeds, the QFPay will POST the notification data (JSON format) to the configured notification callback address.

3. After receiving the notification callback and verifying the signature, the developer needs to return the SUCCESS string to the QFPay, indicating that it has been processed.

4. If the developer returns other data to the QFPay, or if there is no return, then the QFpay will send the notification callback again with a certain strategy. The time interval is configured as 1m, 5m, 10m, 60m, 2h, 6h, 15h. Once the SUCCESS string is sent back to QFPay, the follow-up callback notices will not be continued.

3.5.3 Verifying the signature in Callback:

Step 1: Get the signature from X-QF-SIGN in HTTP head.

Step 2: Connect the body of the HTTP response with Key to get the string to be verified.

Step 3: Apply MD5 for the spliced string. (SIGN = MD5(body + key))

Step 4: Compare the computing result with the signature from X-QF-SIGN to verify whether they are identical. If they are identical, the verification is successful and return SUCCESS string to QFPay.

3.5.4 Sample Code

import hashlib
unicode_to_utf8 = lambda s: s.encode('utf-8') if isinstance(s, unicode) else s
def make_resp_sign(data, key):
    unsign_str = unicode_to_utf8(data) + unicode_to_utf8(key)
    s = hashlib.md5(unsign_str).hexdigest()
    return s.upper()

3.5.5 Callback Response Parameter

3.5.6 Response Callback sample

3.6 Python Sample code

#!/usr/bin/env python

#encoding=utf8

import urllib, urllib2, hashlib

import json

import argparse

import random

import qrcode

from datetime import datetime

from PIL import ImageFile

import hashlib

parser = argparse.ArgumentParser(description="Simulate Payment Process for QFPay and CIL")

parser.add_argument('--txamt', default=1, help='Payment Amount')

parser.add_argument('--type', default='wechat', help='Payment Type')

parser.add_argument('--cur', default='CNY', help='Payment Currency')

parser.add_argument('--authcode', help='Auth Code')

parser.add_argument('--syssn', help='Syssn Code')

parser.add_argument('--tradeno', help='Out Trade No')

parser.add_argument('--query', action='store_true', help='Perform Query')

parser.add_argument('--refund', action='store_true', help='Perform Refund')

parser.add_argument('--txdtm', help='Transaction Time')

parser.add_argument('--starttime', default=None)

parser.add_argument('--endtime', default=None)

parser.add_argument('--close', action='store_true')

parser.add_argument('--reconcile', action='store_true')

parser.add_argument('--tradedate', default=None)

unicode_to_utf8 = lambda s: s.encode('utf-8') if isinstance(s, unicode) else s

def make_req_sign(data, key):

    keys = data.keys()

    keys.sort()

    p = []

    for k in keys:

        k = unicode_to_utf8(k)

        v = unicode_to_utf8(data[k])

        p.append('%s=%s'%(k,v))

    unsign_str = '&'.join(p) + unicode_to_utf8(key)

    s = hashlib.md5(unsign_str).hexdigest()

    return s.upper()

def main():

    pay_type = {

        'wechat': '800201', #dynamic QR code generation

        'alipay': '800101',

        'wechat_app': '800208', #scan from user's app

        'alipay_app': '800108', #scan from user's app

        'general': '800008',

    }

    d = datetime.now()

    # mchid = None

    args = parser.parse_args()

    txamt = args.txamt

    txcurrcd = args.cur

    pay_type = pay_type[args.type]

    out_trade_no = random.randint(10**11, 10**12)

    txdtm = d.strftime("%Y-%m-%d %H:%M:%S")

    # goods_name = '商品名１:缶コーヒー'

    goods_name = 'test'

    limit_pay = 'no_credit'

    udid = 'xxxxxxxx'

    auth_code = args.authcode

    start_time = args.starttime

    end_time = args.endtime

    mchid = 'xxxxxxxxx'

    app_code = 'xxxxxxxxxxxxxxxxxxxxxxxxxxx'

    key = 'xxxxxxxxxxxxxxxxxxxxxxxxxxx'

    is_pay = True

    url = 'https://openapi.qfpay.com/trade/v1/payment'

    data ={'txamt': txamt, 'txcurrcd': txcurrcd, 'pay_type': pay_type, 'out_trade_no': out_trade_no, 'txdtm': txdtm, 'goods_name':goods_name,'limit_pay':limit_pay,'udid':udid}

    if mchid: data['mchid'] = mchid

    if args.type in ['wechat_app', 'alipay_app', 'general']:

        data['auth_code'] = auth_code

    if args.query:

        is_pay = False

        url = 'https://openapi.qfpay.com/trade/v1/query'

        data = { 'pay_type': pay_type, 'mchid': mchid, 'page_size': 1, 'Page': 2}

        if start_time: data['start_time'] = start_time

        if end_time: data['end_time'] = end_time

    elif args.refund:

        is_pay = False

        url = 'https://openapi.qfpay.com/trade/v1/refund'

        data = { 'syssn': args.syssn, 'out_trade_no': args.tradeno, 'pay_type': pay_type,'mchid': mchid, 'txamt': txamt, 'txdtm': args.txdtm}

    elif args.close:

        is_pay = False

        url = 'https://openapi.qfpay.com/trade/v1/close'

        data = {'txamt': txamt, 'txdtm': args.txdtm, 'mchid': mchid }

        if args.syssn is not None: data['syssn'] = syssn

        if args.tradeno is not None: data['out_trade_no'] = args.tradeno

    elif args.reconcile:

        url = 'https://openapi.qfpay.com/download/v1/trade_bill'

        data = { 'trade_date': args.tradedate }

    print(data)

    req = urllib2.Request(url, urllib.urlencode(data))

    req.add_header('X-QF-APPCODE', app_code)

    req.add_header('X-QF-SIGN', make_req_sign(data, key))

    resp = urllib2.urlopen(req)

    output = json.loads(resp.read())

    print resp.info()

    print output

    print output['respcd']

    print output['resperr'].encode("utf-8")

    if output['respcd'] == '0000' and args.type in ['wechat', 'alipay'] and is_pay:

        img = qrcode.make(output['qrcode'])

        img.save('qrcode.png')

if __name__ == '__main__':

    main()