1. Description of The Document

API Document for IBS Payment Gateway

1.1. Version

  • 2017-09-05
    Version 1.0.0

1.2. Global Planning

  • Server address: https://api.payingcloud.cn

  • Data Format: json

  • The asynchronous notification interface must return "success" when it was completed.

1.3. Signature Rules

HTTP requests should add a Authorization' Header to include ‘Signature’that the message has been authorized.

Signature
 HmacUtils.hmacSha1Hex(               (1)
                key,                  (2)
                verb + "\n" +         (3) (4)
                resource + "\n" +     (5)
                body + "\n" +         (6)
                timestamp + "\n");    (7)
1 Using hmacSha1 algorithm to get the M-16.
2 key——Signature required keys that is generated in the console.
3 verb——HTTP request Method that include PUT, GET, POST, HEAD, DELETE.
4 \n——newline
5 resource——Stitching parameter string is used for the request interface. path+?+query
6 body——Content of the request body
7 timestamp——Said the operation time, and must be in GMT format,like "Sun, 22 Nov 2015 08:16:38 GMT". This timestamp will also be added to * Header *,and the key is * Date *.
Remark

The signature body of the HttpMethod without the request body is represented by an empty string.

For Example:
HmacUtils.hmacSha1Hex("3zKciJOwhWE4SSRUxXzCsABcIhJWd5Gb",
                      "POST" + "\n" +
                      "/charges?a=a&b=b&c=c" + "\n" +
                      "{"a":"a","b":"b","c":"c"}" + "\n" +
                      "Sun, 22 Nov 2015 08:16:38 GMT" + "\n"

Add your signature to accessKeyId,then base64 encoding.Add the result to the Basic+blank to compose Authorization.

Authorization
"Basic " + Base64.encodeBase64String((accessKeyId + ":" + signature).getBytes()));
Final Header
Content-Type:application/json; charset=UTF-8
Authorization:Basic NTgzMTM1NDZlZjE5MGM1MWMwYmVhYzZmOjA2NzY2NTUwMzdhOTQyZDc5M2JjOGM5YzRmNzE5M2QzZTRhYjY5YjE=
Date:Tue, 13 Dec 2016 03:22:13 GMT

1.4. Checking Steps

In order to prevent damage caused by hackers fake transaction results,all asynchronous notification using RSA signatures were sent to the merchant.And put the signature with Base64 encoding in Http request headers kbd: [sign].Developers need to use SHA1WithRSA algorithm and IBS provides RSA public key to validate it.

For Example:
// Gets a signature from asynchronous notification request headers.
String sign = request.getHeader("sign");
// Using base64 decoding the signature String to bytes.
byte[] signBytes = Base64.decodeBase64(sign)
//Gets the asynchronous notification request body.
String content = ...
// Using UTF-8 character to decode the request body.
byte[] contentBytes = content.getBytes("UTF-8")
// SHA1WithRSA algorithm is used to validate it.
KeyFactory keyFactory = KeyFactory.getInstance("RSA");
byte[] encodedKey = Base64.decodeBase64(PayingCloud.DEFAULT_PUBLIC_KEY); // 使用PayingCloud提供的RSA公钥
PublicKey key = keyFactory.generatePublic(new X509EncodedKeySpec(encodedKey));
Signature signature = Signature.getInstance("SHA1WithRSA"); // 验签算法SHA1WithRSA
signature.initVerify(key);
signature.update(contentBytes);
return signature.verify(signBytes);
IBS RSA Public Key
MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQCPymtLbRkHgvVfUT933LrwWns6YZHLPpT1pP9TKJ+cgIZiQwZ4mtqoqPHSVtiT5HA8fwFzWuJ/6qWaQhER7TOISUFUHZlHyBjNK/Z5px6PNB7rT4OrLP0KuZ7nuX5qdnOKuAbrj1MBLSinOHQ8tDJhPrPKxuZlKw3SeL5auHlKWwIDAQAB

2. OPEN API

2.1. Payment Interface

2.1.1. Interfaces Overview

Payment process shown in the following figure:

payment flowchart

2.1.2. Request Method

POST /charges

2.1.3. Request Parameters

Parameters Required Type Example Description

mer_order_no

Yes

String(32)

20150806125346

Vendor Order Number,Lengths from 4 to 32 characters.

subject

Yes

String(128)

iPhone7-32G

Item Details

total

Yes

Int

888

The total amount charged or refunded. The units are expressed in cents and must be an integer.

currency

Yes

String(16)

GBP

ISO-4217 standard compliant and be described by three characters based code. For more information, see Currency Type Form.

channel

YES

Enum

UMF_CREDIT_CARD

Channel Type. For more information, see Channel Type.

external_customer_id

NO

String

oUpF8uMuAJO_M2pxb1Q9zNjWeS6o

The customer unique id in merchant system.Lengths from 1 to 32 characters.

user_ip

YES

String(16)

123.12.12.123

This is the IP address when a customer makes a payment request.

extra

YES

Map<String, Object>

{"returnUrl": "https://api.payingcloud.cn/returnUrl"}

Channel Extra Parameters.Map of key-value pairs store between the different channels of Channel Extra Parameters.

notifyUrl

YES

String(100)

https://api.payingcloud.cn/callback

Specifies the callback address for receiving payment notifications.

2.1.4. Synchronized Return Parameters

To be continued.

2.1.5. Asynchronous Notification Parameters

To be continued.

2.2. Submit Refund API

To be continued.

2.2.1. Request Parameters

To be continued.

2.2.2. Return Parameters

To be continued.

2.2.3. Asynchronous Notification Parameters

To be continued.

2.3. Query Order

To be continued.

2.3.1. Request Parameters

To be continued.

2.3.2. Return Parameters

To be continued.

2.4. Query Refund

To be continued.

2.4.1. Request Parameters

To be continued.

2.4.2. Return Data

To be continued.

3. Remark

3.1. Channel Type

Name Description

UMF_CREDIT_CARD

UMF_Pay by credit card.

UMF_DEBIT_CARD

UMF_ Pay by debit card.

UMF_WECHAT_SCAN

UMF return a QR-Code String. The customer may use their WeChat scan the QR-Code to pay.

UMF_WECHAT_WEB

UMF_The customer may pay for the order inside the WeChat browser.

UMF_WECHAT_IN_APP

UMF_The customer may pay for the order inside a native app.

UMF_ALIPAY_SCAN

UMF returns a QR-Code String. The customer may use their Alipay to scan the QR-Code to pay.

WX_CODE

The Vendor generates a transaction QR Code according to the WeChat Payment Protocol and the Payer goes to "Scan QR Code" in their WeChat in order to complete payment.

WX_APP

In-App payment also refers to a mobile-based payment in which the Vendor calls the WeChat payment module by using the open SDK integrated in their mobile-based app to pay for transactions.

WX_JSAPI

The Payer opens the Vendor’s HTML5 pages on their WeChat and calls the WeChat payment module via the JSAPI interface to pay their transaction.

3.2. Transaction Credential Sample

"url":"<form name=\"punchout_form\"method=\"post\" action=\"https://pay.yizhifubj.com/prs/user_payment.checkit?v_md5info=b00a57dc732366cbfed3da03fe064af5&v_orderstatus=1&v_rcvname=9466&v_moneytype=0&v_oid=20161222-9466-585b77b5ab5c986f049a0faa&v_ymd=20161222&v_url=http%3A%2F%2F127.0.0.1%3A9000%2Forder%2Fcharge%2Freturn&v_rcvaddr=9466&v_ordername=9466&v_rcvtel=9466&v_mid=9466&v_amount=0.01&v_rcvpost=9466\">\n<input type=\"submit\" value=\"[0xe7][0xab][0x8b][0xe5][0x8d][0xb3][0xe6][0x94][0xaf][0xe4][0xbb][0x98]\" style=\"display:none\" >\n</form>\n<script>document.forms[0].submit();</script>"

3.3. Transaction Credential Details

  • BDPAY_WEB

  • BDPAY_WAP

    • Get: url from credentials

servletResponse.sendRedirect(charge.getCredentials().get("url"));
  • ALIPAY_DIRECT

  • BJPAY_WEB

  • CHINAPAY_WEB

  • JDPAY_WEB

  • JDPAY_WAP

  • YEEPAY_WAP

  • ALIPAY_WAP

    • Get html(utf-8) from credentials

servletResponse.setContentType("text/html;charset=UTF-8");
servletResponse.getWriter().write(charge.getCredentials().get("html"));
  • YEEPAY_WEB

    • Get html(gbk) from credentials

servletResponse.setContentType("text/html;charset=gbk");
servletResponse.getWriter().write(charge.getCredentials().get("html"));
  • BDPAY_QR

    • Get url from credentials

  • WXPAY_NATIVE

  • BJPAY_WX

  • ALIPAY_QR

  • KFTPAY_WX

  • KFTPAY_ALI

  • JDPAY_QR

  • CMBCPAY_T0_ALI

  • CMBCPAY_T1_ALI

  • CMBCPAY_T0_WX_QR

  • CMBCPAY_T1_WX_QR

  • CMBCPAY_T0_QQ

  • CMBCPAY_T1_QQ

  • WEBANKPAY_WX_QR

    • Get codeUrl from credentials

  • WXPAY_JSAPI

  • CMBCPAY_T0_WX_JSAPI

  • CMBCPAY_T1_WX_JSAPI

  • WEBANKPAY_WX_JSAPI

    • Get form credentials:

      • appId

      • timeStamp

      • nonceStr

      • package

      • signType

      • paySign

3.4. Channel Extra Parameters

Table 1. UMF_CREDIT_CARD
Parameter Required Description Constraints

sub_orders

YES

Each sub_order can only have same type goods.

Object Array.For more information, see sub_order.

goods_type

YES

Category of commodities

ENUM:0 virtual goods;1 physical goods

receiver_name

YES

Name of the recipient

String.When goods_type is either 1 , it is required to send this field.

receiver_moblie_id

YES

Phone number of the recipient

String.When goods_type is either 1 , it is required to send this field.

shipping_address

YES

Address of the recipient

String.When goods_type is either 1 , it is required to send this field.

real_name

YES

Real name purchase

ENUM.0 not real name system ;1 real name system

phone

YES

The phone number registered in the bank card issuer.

String

card_holder

YES

The name of card holder.

String

citizen_id_number

YES

Citizen id number.

String

bank_code

YES

The abbreviation of bank.

String.

number

YES

The card number.

String

valid_date

YES

The valid date of bank card.

String

cvv2

YES

CVV2 of bank card.

String

Table 2. UMF_DEBIT_CARD
Parameter Required Description Constraints

sub_orders

YES

Each sub_order can only have same type goods.

Object Array.For more information, see sub_order.

goods_type

YES

Category of commodities

ENUM:0 virtual goods;1 physical goods

receiver_name

YES

Name of the recipient

String.When goods_type is either 1 , it is required to send this field.

receiver_moblie_id

YES

Phone number of the recipient

String.When goods_type is either 1 , it is required to send this field.

shipping_address

YES

Address of the recipient

String.When goods_type is either 1 , it is required to send this field.

real_name

YES

Real name purchase

ENUM.0 not real name system ;1 real name system

phone

YES

The phone number registered in the bank card issuer.

String

card_holder

YES

The name of card holder.

String

citizen_id_number

YES

Citizen id number.

String

bank_code

YES

The abbreviation of bank.

String.

number

YES

The card number.

String

Table 3. UMF_WECHAT_WEB
Parameter Required Description Constraints

sub_orders

YES

Each sub_order can only have same type goods.

Object Array.For more information, see sub_order.

goods_type

YES

Category of commodities

ENUM:0 virtual goods;1 physical goods

receiver_name

YES

Name of the recipient

String.When goods_type is either 1 , it is required to send this field.

receiver_moblie_id

YES

Phone number of the recipient

String.When goods_type is either 1 , it is required to send this field.

shipping_address

YES

Address of the recipient

String.When goods_type is either 1 , it is required to send this field.

real_name

YES

Real name purchase

ENUM.0 not real name system ;1 real name system

phone

YES

The payer’s phone number.

String

name

YES

The name of payer.

String

citizen_id_number

YES

Citizen id number.

String

open_id

YES

The OpenID is a unique encrypted WeChat ID for each user of an official account, and users can have separate OpenIDs corresponding to different official accounts.

String.

Table 4. UMF_WECHAT_SCAN 、UMF_ALIPAY_SCAN、UMF_WECHAT_IN_APP
Parameter Required Description Constraints

sub_orders

YES

Each sub_order can only have same type goods.

Object Array.For more information, see sub_order.

goods_type

YES

Category of commodities

ENUM:0 virtual goods;1 physical goods

receiver_name

YES

Name of the recipient

String.When goods_type is either 1 , it is required to send this field.

receiver_moblie_id

YES

Phone number of the recipient

String.When goods_type is either 1 , it is required to send this field.

shipping_address

YES

Address of the recipient

String.When goods_type is either 1 , it is required to send this field.

real_name

YES

Real name purchase

ENUM.0 not real name system ;1 real name system

phone

YES

The payer’s phone number.

String

name

YES

The name of payer.

String

citizen_id_number

YES

Citizen id number.

String

Table 5. sub_order
Parameter Required Description Constraints

mer_sub_reference_id

YES

The ID of sub_order object.

Lengths from 4 to 16 characters.

sub_total

YES

The amount of sub_order.

Maximum length is 12 digits including 2 decimal places.

rans_code

YES

The transaction code of goods. 

ENUM

is_customs

YES

If the merchant needs UMF to submit the payment information to customs.

TRUE FALSE

invoice_id

YES

This receipt of sub_order.

Lengths from 1 to 20 characters.

mer_item_id

YES

The ID in merchant system.

Lengths from 1 to 32 characters.

type

YES

The type of goods.

ENUM

name

NO

The goods name.

Lengths from 1 to 256 characters.

description

NO

The description of goods.

Lengths from 1 to 64 characters.

mer_total

YES

The amount object. The price of goods.

Maximum length is 12 digits including 2 decimal places.

quantity

YES

Number. The quantity of goods.

Maximum length is 2

Table 6. WX_CODE、WX_APP、WX_JSAPI

Parameter

Required

Type

Example

Description

attach

NO

String(128)

Additional description

Allow vendors an additional field to be returned in the payment notification after submitting a payment to the Query Order API.

detail

NO

String(6000

{ "goods_id":"iphone6s_32G", "wxpay_goods_id":"1002", "goods_name":"iPhone6s 32G", "quantity":1,"price":608800, "goods_category":"123789", "body":"iPhones" }

Detailed product list described in JSON format.

goods_tag

NO

String(32)

WXG

Specifies the label of goods, which is a parameter in the coupon feature for businesses.

product_id

NO

String(32)

1.22354E+22

This field is only required when trade_type is NATIVE. This ID contains the product ID as set by the Vendor.

3.5. Currency Type Form

Parameter Name Description

GBP

Great Britain pound

HKD

Hong Kong dollar

USD

United States dollar

JPY

Japanese yen

CAD

Canadian dollar

AUD

Australian dollar

EUR

Euro

NZD

New Zealand Dollar

KRW

South Korean won

THB

Thailand baht

Notes: The currency type for payment and refund must be identical.