Union Gateway Payment API of Dinpay

Dinpay / User-Centered; Growing with Merchants
Dinpay WeiXin Payment Api / Security Classification: Public

Union Gateway Payment API of Dinpay

Writer / Updated
Technical Support Dept / 2017-12-29

DinpayPayment Co.,LTD

All Rights Reserved, Violators will be Prosecuted

1. Introduction

1.1. Purpose

1.2. Terms and Abbreviations

1.3. The sequence diagram

2. Interface definition

2.1. Bank payment transaction interface

2.1.1. Description

2.1.2. Definition of interface parameters

2.2. Payment result notification interface

2.2.1. Description

2.2.2. Definition of interface parameters

2.3. Single transaction query interface

2.3.1. Description

2.3.2. Definition of query parameters

2.3.3. Definition of response parameters

2.4. Appendix

2.4.1. Payment type list

2.4.2. Supported bank code

2.4.3. Definition of error code

1.Introduction

1.1. Purpose

This file defines the following API: China Bank payment API ,payment result notice API , and order query API .

1.2. Terms and Abbreviations

1）merchant Code: The unique ID for the Dinpay platform registered by a merchant.

2）bank_code:When a user in the use of Internetbank Direct, according to the merchants bank code submitted jump to the corresponding bank page,saves to the cashier choose bank pag.

3）return_url:Page synchronous notification. Several seconds after Dinpay processes the dataobtained(or after the user clicks the button), the Dinpay payment page will jump to the ruturn_url address designated by the merchant, carrying the feedback after the processing is finished.Example:

4）notfiy_url: Server asynchronous notification. After Dinpay processes the data obtained, the Dinpay server will positively send a notice to the notify_url address designated onthe merchant’s website, carrying the order information processed. Example:

1.3. The sequence diagram

2.Interface definition

2.1. Bank payment transaction interface

2.1.1. Description

This section is description of bank payment transaction interface which between merchant's website and Dinpay's gateway.Transaction order data submitted (in form of HTTPS POST) to Dinpay shall be base on this definition of interface specification.

2.1.2. Definition of interface parameters

Transaction request address: character set of parameter}

For example:

The coded charecter is in consistency with the value of the input_charset request parameter, UTF-8 or GBK.

Parameter / Type / Required / Notes
merchant_code / String(10) / √ / Parameter Name: Merchant ID
Dinpay assigned to the merchant's identity when they establish the cooperation relations.
For example：1111110166
service_type / String(10) / √ / Parameter Name: Service type
It has a fixed value: direct_pay，b2b_pay
notify_url / String(200) / √ / Parameter Name: The address of server asynchronous notification.
After payment is made successfully,Dinpay will actively notice to merchant via this URL.Please make sure that it's effective.
interface_version / String(10) / √ / Parameter Name: Interface version
Fixed value: V3. 0 (Capital)
input_charset / String(5) / √ / Parameter Name: Coded character set of parameter
Value: UTF-8 or GBK (Capital)
sign_type / String(10) / √ / Parameter Name: Signature type
support value: RSA or RSA-S, not participate in signature,please choose one from them
RSA: encrypt data by certification
RSA-S:encrypt data by String Keys
sign / String / √ / Parameter Name: Signature
Dinpay sample code will tell you how to get the value of it
return_url / String(200) / × / Parameter Name: The address of page synchronous notification
After payment is made successfully, return to merchant’s website in form of page return.
pay_type / String(10) / × / Parameter Name: Pay type
Values are as follows（The value must be lowercase, when multiple selections separated by commas）
b2c,plateform,dcard,express,weixin
client_ip / String(15) / × / Parameter Name: Client IP
The IP of machine used by user during creating transaction, for example: 183.62.225.12, the maximal length includes 15 characters.
client_ip_check / Int(1) / Parameter Name:Whether to check the client IP
The duty of 1 check the client IP;
The duty of 0 don't check the client IP;
order_no / String(100) / √ / Parameter Name: Merchant's order No.
1.This order number is generated by merchant’s website,which should be uniqueness.
2.It's composed of letters, numbers or underscores,which shall be no
more than 64 characters.
order_time / Date / √ / Parameter Name: Order time of merchant
Format: yyyy-MM-dd HH:mm:ss 2013-11-01 12:34:58
order_amount / Number(13,2) / √ / Parameter Name: Total amount of merchant orders
The total amount of such order shall be in unit of RMB, and to two digits after the decimal point
For example: 12.01
bank_code / String(10) / × / Parameter Name: Bank code
By using it ,merchant website can be redirected to bank page directly.
redo_flag / Int(1) / × / Parameter Name: Whether to allow repeat orders
The value 1 are not allowed to repeat submit merchant order number;
The value 0 or empty when allowed to repeat submit order number
product_name / String(100) / √ / Parameter Name: Product name
No more than 100 characters
product_code / String(60) / × / Parameter Name: Product code
No more than 60 characters
product_num / Number(10) / × / Parameter Name: Product number
Must be number
product_desc / String(300) / × / Parameter Name: Product description
No more than 300 characters
extra_return_param / String(100) / × / Parameter Name: Public use return parameter
If such parameter is delivered in payment request, then such parameter will be returned when notifying the merchant that the payment is successfully made.
extend_param / String / × / Parameter Name: Public use service extend parameter
Format of parameter: parameter name1^parameter
value|parameter name2^parameter value2
Multiple data shall be separated with"|"
For example: name^ZhangSan|sex^Male
show_url / String(200) / × / Parameter Name: Product show URL
No more than 200 characters
orders_info / String(4000) / × / Related information storage sub-orders,limit 20 products
usr_id / String(20) / × / Merchant user id (only the 4.0 gateway shortcut merchants must pass parameters)

The public use service extend parameters are defined as follows(extend_param):

Parameter / Parameter Name / Type / Required
Information of receiver
ship_to_name / Name of receiver / String(50) / ×
ship_to_email / E-mail of receiver / String(60) / ×
ship_to_phone / Telephone of receiver / String(20) / ×
ship_to_state / Province of receiving address / String(100) / ×
ship_to_city / City of receiving address / String(100) / ×
ship_to_street / Detailed address of receiver / String(200) / ×
ship_to_zip / Zip code of receiving address / String(20) / ×
Information of Customer
customer_email / Customer e-mail / String(100) / ×
customer_name / Customer name / String(50) / ×
customer_phone / Customer telephone or cell phone number / String(20) / ×
customer_state / Province of customer / String(100) / ×
customer_city / City of customer / String(100) / ×
customer_street / Detailed address of customer / String(200) / ×
customer_zip / Zip code of address / String(20) / ×
customer_cardNumber / Consumer Card / String(50) / ×
customer_idNumber / Consumer ID number / String(30) / ×

2.2. Payment result notification interface

2.2.1. Description

When the consumer finished the transaction,both return_url and notfiy_url(you can find them on request parameters) will receive notice from Dinpay server.

Dinpay server won’t send notice if transaction failed.Merchants also can set up the return_url and notify_url on Dinpay merchant system as flows:

It means the setting up will take effect when you see “OFF” and Dinpay server will send notice to the url adderess if you have set up on admin panel.Admin panel have the priority than the request.

2.2.2. Definition of interface parameters

Parameter / Type / required / Notes
Basic parameter
merchant_code / String(10) / √ / Parameter Name: Merchant ID
Dinpay assigned to the merchant's identity when they establish the cooperation relations.for example:1111110166
notify_type / String(14) / √ / Parameter Name: Notification type
1. Page return notification: page_notify
2. Asynchronous notification of server: offline_notify
notify_id / String(100) / √ / Parameter Name: Notify ID
This parameter is no longer used for verified, but still retained.
It'll return the data in form of 32 characters,which as shown below:
e722dceae317466bbf9cc5f1254b8b0a
interface_version / String(10) / √ / Parameter Name: Interface version
Fixed value: V3. 0 (Capital)
sign_type / String(10) / √ / Parameter Name: Signature type
support value: RSA,RSA-S,not participate in signature
sign / String / √ / Parameter Name: Signature
Dinpay sample code will tell you how to use it
Service parameter
order_no / String(64) / √ / Parameter Name: Merchant's order No.
1.This order number is generated by merchant’s website,which should be uniqueness.
2.It's composed of letters, numbers or underscores,which shall be no
more than 64 characters.
order_time / Date / √ / Parameter Name: Order time of merchant
Format: yyyy-MM-dd HH:mm:ss 2013-11-1 12:34:58
order_amount / Number(13,2) / √ / Parameter Name: Total amount of merchant orders
The total amount of such order shall be in unit of RMB, and to two digits after the decimal point
For example: 12.01
extra_return_param / String(100) / × / Parameter Name: Public use return parameter
If such parameter is delivered in payment request, then such parameter will be returned when notifying the merchant that the payment is successfully made.
trade_no / String(30) / √ / Parameter Name: Dinpay transaction order code
For example: 1649737937
trade_time / Date / √ / Parameter Name: Dinpay transaction order time
Format: yyyy-MM-dd HH:mm:ss 2013-11-1 12:34:58
trade_status / String(7) / √ / Parameter Name: Transaction status
SUCCESS, the transaction is successful
bank_seq_no / String / × / Parameter Name: Internet bank transaction sequence number
For example: 2013060911235456

2.3. Single transaction query interface

2.3.1. Description

Merchants can use this API to query the order detail ,including failed and successful orders.At present,just supporting the orders within 12 hours from order_time.

2.3.2. Definition of query parameters

The request address:

Parameter / Type / required / Notes
Basic parameter
service_type / String(18) / √ / Parameter Name: Service type
It has a fixed value: single_trade_query
merchant_code / String(10) / √ / Parameter Name: Merchant ID
Dinpay assigned to the merchant's identity when they establish the cooperation relations
interface_version / String(10) / √ / Parameter Name: Interface version
Fixed value: V3. 0 (Capital)
sign_type / String(10) / √ / Parameter Name: Signature type
support value: RSA or RSA-S, not participate in signature,please choose one from them
RSA: encrypt data by certification
RSA-S:encrypt data by String Keys
sign / String / √ / Parameter Name: Signature
Dinpay sample code will tell you how to get the value of it
Service parameter
order_no / String(64) / √ / Parameter Name: Merchant's order No.
1.This order number is generated by merchant’s website,which should be uniqueness.
2.It's composed of letters, numbers or underscores,which shall be no
more than 64 characters.
trade_no / String(30) / × / Parameter Name: Dinpay transaction order code
For example: 1649737937

2.3.3. Definition of response parameters

Parameter / Type / required / Notes
Basic parameter
is_success / String(1) / √ / This parameter just means whether the query is successful:
If query is successful, is_success = 'T'
If query is unsuccessful, is_success = 'F'
sign_type / String(10) / √ / Parameter Name: Signature type
support value:RSA,RSA-S, not participate in signature
sign / String / √ / Parameter Name: Signature
participate in signature
error_code / string / × / Only return error code when query is failed.
Service parameter
merchant_code / String(10) / √ / Parameter Name: Merchant ID
Dinpay assigned to the merchant's identity when they establish the cooperation relations
For example:1111110166
order_no / String(64) / √ / Parameter Name: Merchant's order No.
1.This order number is generated by merchant’s website,which should be uniqueness.
2.It's composed of letters, numbers or underscores,which shall be no
more than 64 characters
order_time / Date / √ / Parameter Name: Order time of merchant
Format: yyyy-MM-dd HH:mm:ss 2013-11-1 12:34:58
order_amount / Number(13,2) / √ / Parameter Name: Total amount of merchant orders
The total amount of such order shall be in unit of RMB, and to two digits after the decimal point
For example: 12.01
trade_no / String(30) / √ / Parameter Name: Dinpay transaction order code
For example: 1649737937
trade_time / Date / √ / Parameter Name: Dinpay transaction order time
Format: yyyy-MM-dd HH:mm:ss 2013-11-1 12:34:58
trade_status / String(7) / √ / Parameter Name: Transaction status
1. SUCCESS, the transaction is successful
2. UNPAY, the transaction is failed

The xml data which Dinpay returns is as shown below:

In the case of successful query:

version="1.0" encoding="UTF-8" ?>
<dinpay>
<response>
<is_success>T</is_success>
<sign_type>RSA-S</sign_type>
<sign>56ae9c3286886f76e57e0993625c71fe</sign>
<trade>
<merchant_code>2181230245</merchant_id>
<order_no>210023569</order_no>
<order_time>2013-05-10 11:18:00</order_time>
<order_amount>100.00</order_amount>
<trade_no>128600</trade_no>
<trade_time>2013-05-10 11:20:01</trade_time>
<trade_status>SUCCESS</trade_status>
</trade>
</response>
</dinpay>

In the case of unsuccessful query:

<?xml version="1.0" encoding="UTF-8" ?>
<dinpay>
<response>
<is_success>F</is_success>
<error_code>TRADE_IS_NOT_EXIST</error_code>
</response>
</dinpay>

2.4. Appendix

2.4.1. Payment type list

Payment type / Abbreviation
Bank Payment / B2C
Business Bank Payment / B2B
Bank Payment(WAP interface) / wap_pay
DCard payment / dcard
Dinpay wallet payment / plateform
Alipay scan payment / alipay_scan
Wechat scan payment / weixin
QQ wallet scan payment / qq_scan
Unionpay qr code scan payment / upop_scan
JingDong scan payment / jd_scan
Quick payment(PC) / express

2.4.2. Supported bank code

bank code comparison table is as follows:

bank name / bank code
Agricultural Bank of China / ABC
Industrial and Commercial Bank of China / ICBC
China Construction Bank / CCB
Bank of Communication / BCOM
Bank of China / BOC
China Merchants Bank / CMB
China Minsheng Bank / CMBC
China Ever Bright Bank / CEBB
Bank of Beijing / BOB
Bank of Shanghai / SHB
Bank of Ningbo / NBB
Hua Xia Bank / HXB
China Industrial Bank / CIB
Postal Saving Bank of China / PSBC
Shenzhen Ping An Bank / SPABANK
Shanghai Pudong Development Bank / SPDB
China Citic Bank / ECITIC
Bank of HangZhou / HZB
China Guangfa Bank / GDB
Unionpay / UPOP_ORG_Y

2.4.3. Definition of error code

Error code / Notes
ILLEGAL_SIGN / Meaning:the signature is incorrect,signature data is inconsistent
Possible reason:
1)Some requierd parameters don’t paticipate in singnature.
2)The sequence of signature section is incorrect,it must be in the sequence of a~z
1）3)Wrong private key or the private key is inconsistent of the public key saved in Dinpay merchant system
CHECK_URL_NOT_MATCH / Meaning: the business domain name verification does not pass
Reason: merchant number corresponding website domain name not in Dinpay merchant system for binding, please login in Dinpay merchant system "business applications" - "to increase binding domain name" top-level domain binding,after the approval of the relevant departments(about 1 working day), you can use this domain name
TRANSACTION_REJECTED_001 / Meaning: the transaction request is rejected
The Dinpay payment system detects the transaction risk of the consumer payment environment, please change the network environment to pay
ILLEGAL_URL_FORMAT / Meaning: Format of notification url is incorrect
Reason: The format of the value of payment parameter notify_url is incorrect
Correct example:
csp.orderService.order-is-already-exist / Meaning:order already exists
Reason:order_no is submitted repeatedly
csp.orderService.prepay-create-order-failure / Meaning:generate the order failed
Reason:System fails to generate order
ILLEGAL_REQUEST / Reason:parameter error
ILLEGAL_PAY_BUSINESS / Meaning:unknown payment business
Reason:the payment business is not open,please contact our salesman
SYSTEM_ERROR / Reason:something is wrong with the system,like network timeout and so on
NOTIFY_URL_IS_NULL / Reason:it cannot be null with the notify_url
NOTIFY_URL_IS_TOO_LONG / Reason:the length of notify_url is too long
ORDER_NO_IS_NULL / Reason:it cannot be null with the order_no
ORDER_NO_IS_TOO_LONG / Reason:the length of order_no is too long
ORDER_TIME_IS_NULL / Reason:it cannot be null with the order_time
ILLEGAL_ORDER_TIME_FORMAT / Reason:the format of order_time is incorrect
Correct example:2013-12-01 12:23:34
ORDER_AMOUNT_IS_NULL / Reason:it cannot be null with the order_amount
ILLEGAL_ORDER_AMOUNT_FORMAT / Reason:the format of order_amount is incorrect
Correct example:12.01
ORDER_AMOUNT_IS_TOO_LARGE / Reason:the length of order_amount cannotexceed 13 figures
PRODUCT_NAME_IS_NULL / Reason:it cannot be null with the product_name
PRODUCT_NAME_IS_TOO_LONG / Reason:the length of procuct_name cannotexceed 100 characters
ILLEGAL_PRODUCT_NUM_FORMAT / Reason:the format of product_num is incorrect
correct example:10
PRODUCT_CODE_IS_TOO_LONG / Reason:the length of procuct_code cannotexceed 60 characters
PRODUCT_DESC_IS_TOO_LONG / Reason:the length of procuct_desc cannotexceed 300 characters
EXTRA_RETURN_PARAM_IS_TOO_LONG / Reason:the length of extra_return_param cannotexceed 100 characters
ILLEGAL_EXTEND_PARAM_FORMAT / Reason:the format of extend_param is incorrect
correct example:name Zhang San|sex^Male
ILLEGAL_SERVICE_TYPE / Reason: incorrect service_type or service_type is null
MERCHANT_CODE_IS_NULL / Reason:it cannot be null with the merchant_code
INTERFACE_VERSION_IS_NULL / Reason:it cannot be null with the interface_version
ILLEGAL_INTERFACE_VERSION / Reason:incorrect interface_version,it must be V3.0
SIGN_TYPE_IS_NULL / Reason:it cannot be null with the sign_type
ILLEGAL_SIGN_TYPE / Reason:unsupported sign_type,it must be RSA-S or RSA
SIGN_IS_NULL / Reason:it cannot be null with the sign
ILLEGAL_PARAMS / Reason:your request parameter contains illegal characters
CONCUMER_NAME_IS_NULL / It cannot be null with consumer name
CONCUMER_IDNO_IS_NULL / It cannot be null with consumer idno
CONCUMER_IDNO_IS_INVALID / Wrong consumer idno
ILLEGAL_CONCUMER_IDNO / Consumer idno is wrong format or invalid
INVALID_ID_CARD / The Card ID does not pass the verification
RECEIVER_IDNO_IS_INVALID / Wrong consignee idno
ILLEGAL_RECEIVER_IDNO / Consignee idno is wrong format or invalid
ILLEGAL_CLIENT_IP / Meaning: illegal client IP, not the IP that the consumer uses when creating a transaction
Reason: the client IP value is tampered with, and the IP of the machine used to create the transaction with the consumer is inconsistent

1