Introduction
You can use the provided APIs to integrate various payment services like Alipay, WeChat Pay, Credit Card, Apple Pay & Google Pay etc. Our APIs accepts JSON-encoded request bodies, return JSON-encoded responses and uses standard HTTP response codes, authentication.
Demo / Testing Endpoint: https://218.255.14.34 / https://demo.ipayasia.com
Production API Endpoint: https://payment.ipayasia.com
Version: 1.0.0
Authentication
Server API Key: To authorize, use this code:
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
-H "Authorization: bearer server_api_key"
Make sure to replace
server_api_keywith your API key.
We expects for the API key to be included in all API requests to the server in a header that looks like the following:
Authorization: bearer sk_qkn6wgb8nfnadd63dyapxpfire
Apart of API key, you will have a verify secret for verify the payment status notification to your endpoint.
e.g.: y4atnxtrsbggdrq6aehzy89pchs7asjh
WeChat Pay / Alipay
Create Order
curl "https://demo.ipayasia.com/api/v1/payment/pay"
-X POST
-H "Authorization:bearer sk_qkn6wgb8nfnadd63dyapxpfire"
-H "content-type: application/json"
The request payload JSON structured like this:
{
"app_id":"1000343",
"app_key": "PqSpdmuyErQwbGPK2dmwGJYIIXElV0fa",
"mer_id":"1000258",
"mer_key": "NuOpbWyKYV9scy9CclISR1kHLANqyVlL",
"method": "alipay.qrcode",
"amount": 10,
"notify_url": "http://www.example.com",
"provider": "",
"discount": 0,
"code": "",
"reference_no": "",
"sub_open_id": "oxoPW5SUhI5l_Szaef2Rfd4qE57w",
"sub_app_id": "wx6f4b43e962dbb48c",
"sub_mch_id": "",
"store_id": "",
"body": "",
"redirect_url": "",
"wallet": "HK",
"api_region": ""
}
This API creates an order / payment
HTTP Request
POST /api/v1/payment/pay
JSON Payload
| Parameter | Type | Compulsory | Requirement | Default | Description |
|---|---|---|---|---|---|
| app_id | String | Yes | n/a | App ID. Get from the management background, or log in to get. | |
| app_key | String | Yes | n/a | App Key. Get from the management background, or log in to get. | |
| mer_id | String | Yes | n/a | Merchant ID. Get from the management background, or log in to get. | |
| mer_key | String | Yes | n/a | Merchant Key. Get from the management background, or log in to get. | |
| method | String | Yes | refer to supported methods | n/a | Payment method. |
| amount | Integer | Yes | 10-999999999999 | n/a | A positive integer representing how much to charge in unit "Cent". Minimum amount is 10 cents. |
| notify_url | String | Yes | Up to 128 characters | n/a | URL provided by Merchant for returning status used by Payment Notification API |
| provider | String | No | wechat / alipay | If the method is micropay and specified provider, server will check the provider of payment authorization code is matched not. | |
| discount | Integer | No | 0-999999999999 | 0 | Discount amount Unit "Cent" |
| code | String | Conditional | Required when payment method equal to "micropay" | ||
| reference_no | String | No | Up to 32 characters | start and end with alphanumeric, can contain underscore and hyphen | If merchants have their own order system, they can generate their own order number, otherwise they are recommended to be automatically generated by vendor. |
| sub_open_id | String | Conditional | Required if wechat.jsapi, openid retrieved from WeChat "mini program" / "official account" |
||
| sub_app_id | String | Conditional | Required if wechat.jsapi or wechat.app. AppId of WeChat "mini program" / "official account" |
||
| sub_mch_id | String | No | Sub merchant Id | ||
| store_id | String | No | Store Id | ||
| body | String | Conditional | Required when payment method equal to "alipay.wappay". Name / description of goods. | ||
| redirect_url | String | No | The redirect URL for wechat.jsapi / alipay.wappay. | ||
| wallet | String | No | HK / CN | The region of payment wallet allowed | |
| api_region | String | No | ["", "HK", "US", "AU", "UK"] | HK | Use different endpoints in different business areas |
Supported Methods
| Name | Value | Description |
|---|---|---|
| Alipay QR Code | alipay.qrcode | Alipay QR Code. Buyers can scan the QR code to finish the transaction. |
| Alipay WAP Pay | alipay.wappay | Alipay for mobile website payment |
| WeChat QR Code | wechat.qrcode | WeChat QR Code. Buyers can scan the QR code to finish the transaction. |
| WeChat JSAPI / 小程序支付 | wechat.jsapi | 公眾號、小程序支付 |
| WeChat APP支付 | wechat.app | 微信APP支付 |
| Micropay | micropay | Quick Pay. Buyers can present the pay code, sellers will scan the code to finish the transaction. |
The above API returns the following JSON when success.
{
"app_id": "1000343",
"attach": "",
"bank_type": "",
"body": "",
"cash_amount": 0,
"cash_currency": "HKD",
"create_at": 1560739118000,
"detail": "",
"currency": "HKD",
"discount": 0,
"id": "1102129",
"is_subscribe": "N",
"merchant_name": "ABC Company",
"reference_no": "11201906171038384828568541651",
"open_id": "",
"jsapi": "",
"provider": "alipay",
"qr_code": "https://qr.alipay.com/bax08307hkhaqxxvyezc6054",
"refundable": 0,
"serial_number": "11201906171038384828568541651",
"paid_at": 0,
"pay_amount": 10,
"order_amount": 10,
"total_refund_amount": 0,
"trade_state": "NOTPAY",
"trade_type": "NATIVE",
"transaction_id": "",
"wallet": "HK"
}
JSON Response
| Parameter | Type | Possible Values / Specification | Description |
|---|---|---|---|
| app_id | String | Returning back app_id for identification. | |
| attach | String | ||
| bank_type | String | The code of payment bank | |
| body | String | Returning back the body of payment | |
| cash_amount | String | Buyer paid amount, unit cent | |
| cash_currency | String | Buyer paid currency | |
| create_at | Integer | unix timestamp | timestamp of payment create |
| detail | String | ||
| currency | String | Display currency | |
| discount | Integer | ||
| id | String | Payment / order ID | |
| is_subscribe | String | "Y" / "N" | |
| merchant_name | String | ||
| reference_no | String | Returning back reference_no for identification. | |
| open_id | String | openid | |
| jsapi | String | The value for using wechat.jsapi, . | |
| provider | String | Payment provider | |
| qr_code | String | The text for generate QR Code | |
| refundable | Integer | ||
| serial_number | String | ||
| paid_at | Integer | The timestamp of payment finish | |
| pay_amount | Integer | ||
| amount | Integer | ||
| total_refund_amount | Integer | ||
| trade_state | String | refer to Appendix B | The status of payment |
| trade_type | String | Type of payment method | |
| transaction_id | String | up to 28 characters | Transaction identifier from payment provider |
| wallet | String | HK / CN | The region of wallet |
Refund Payment
curl "https://demo.ipayasia.com/api/v1/payment/refund"
-X POST
-H "Authorization:bearer sk_qkn6wgb8nfnadd63dyapxpfire"
-H "content-type: application/json"
The request payload JSON structured like this:
{
"app_id":"1000343",
"app_key": "PqSpdmuyErQwbGPK2dmwGJYIIXElV0fa",
"serial_number": "",
"reference_no": "",
"refund_amount": 2,
"refund_desc": "cancelled order",
"password": "",
"api_region": ""
}
When a refund is required due to the buyer or seller within a period of time after the transaction occurs, the seller can refund the payment to the paying user through the refund interface. The payment provider (Alipay, WeChat, etc.) will receive the refund request and verify the success, and will refund the payment according to the refund rule according to the original payment user account.
HTTP Request
POST /api/v1/payment/refund
JSON Payload
| Parameter | Type | Compulsory | Requirement | Default | Description |
|---|---|---|---|---|---|
| app_id | String | Yes | n/a | App ID. Get from the management background, or log in to get. | |
| app_key | String | Yes | n/a | App Key. Get from the management background, or log in to get. | |
| serial_number | String | Conditional (Select one of reference_no and serial_number, serial_number take priority over reference_no ) | n/a | Vendor's unique identifier, Can be used for queries, closes, refunds, etc. | |
| reference_no | String | Conditional | n/a | Unique identifier, Can be used for queries, closes, refunds, etc. | |
| refund_amount | Integer | No | Optional parameter, the default is the total order amount, which means full refund (Alipay does not support partial refund). | ||
| refund_desc | String | No | Refund Description | ||
| password | String | No | Refund password | ||
| api_region | String | No | ["", "HK", "US", "AU", "UK"] | HK | Use different endpoints in different business areas |
The above API returns the following JSON when success.
{
"app_id": "1000343",
"attach": "",
"bank_type": "",
"body": "",
"cash_amount": 0,
"cash_currency": "HKD",
"create_at": 1561188922000,
"detail": "",
"currency": "HKD",
"discount": 0,
"id": "1117287",
"is_subscribe": "N",
"merchant_name": "ABC Company",
"reference_no": "11201906221535224043397371377",
"open_id": "",
"jsapi": "",
"provider": "alipay",
"qr_code": "",
"refundable": 0,
"serial_number": "11201906221535224043397371377",
"paid_at": 1561188925000,
"pay_amount": 100,
"amount": 100,
"total_refund_amount": 100,
"trade_state": "REFUND",
"trade_type": "MICROPAY",
"transaction_id": "2019062222001467120540782993",
"wallet": "",
"out_refund_no": "11201906191148509924596305391",
"refund_desc": "",
"refund_amount": 100,
"refund_status": "SUCCESS",
"refund_time": 1561188952000
}
JSON Response
| Parameter | Type | Possible Values / Specification | Description |
|---|---|---|---|
| app_id | String | Returning back app_id for identification. | |
| attach | String | ||
| bank_type | String | The code of payment bank | |
| body | String | Returning back the body of payment | |
| cash_amount | String | Buyer paid amount, unit cent | |
| cash_currency | String | Buyer paid currency | |
| create_at | Integer | unix timestamp | timestamp of payment create |
| detail | String | ||
| currency | String | Display currency | |
| discount | Integer | ||
| id | String | Payment / order ID | |
| is_subscribe | String | ||
| merchant_name | String | ||
| reference_no | String | Returning back reference_no for identification. | |
| open_id | String | openid | |
| jsapi | String | The value for wechat.jsapi. | |
| provider | String | Payment provider | |
| qr_code | String | The text for generate QR Code | |
| refundable | Integer | ||
| serial_number | String | ||
| paid_at | Integer | The timestamp of payment finish | |
| pay_amount | Integer | ||
| order_amount | Integer | ||
| total_refund_amount | Integer | ||
| trade_state | String | refer to Appendix B | The status of payment |
| trade_type | String | Type of payment method | |
| transaction_id | String | up to 28 characters | Transaction identifier from payment provider |
| wallet | String | HK / CN | The region of wallet |
| out_refund_no | String | The reference refund number for identification | |
| refund_desc | String | ||
| refund_amount | String | Refunded amount | |
| refund_status | String | Status of refund | |
| refund_at | String | The refund processing time |
Operate Order (Query, Close, Reverse)
Possible Actions: query, close, reverse
curl "https://demo.ipayasia.com/api/v1/payment/{action}"
-X POST
-H "Authorization:bearer sk_qkn6wgb8nfnadd63dyapxpfire"
-H "content-type: application/json"
The request payload JSON structured like this:
{
"app_id":"1000343",
"app_key": "PqSpdmuyErQwbGPK2dmwGJYIIXElV0fa",
"reference_no": "",
"serial_number": "11201906171038384828568541651",
"api_region": ""
}
This API operate order such as query, close and reverse.
HTTP Request
POST /api/v1/payment/{action}
Possible action: query, close and reverse
JSON Payload
| Parameter | Type | Compulsory | Requirement | Default | Description |
|---|---|---|---|---|---|
| app_id | String | Yes | n/a | App ID. Get from the management background, or log in to get. | |
| app_key | String | Yes | n/a | App Key. Get from the management background, or log in to get. | |
| serial_number | String | Conditional (Select one of reference_no and serial_number, serial_number take priority over reference_no ) | n/a | Vendor's unique identifier, Can be used for queries, closes, refunds, etc. | |
| reference_no | String | Conditional | n/a | Merchant's unique identifier, Can be used for queries, closes, refunds, etc. | |
| api_region | String | No | ["", "HK", "US", "AU", "UK"] | HK | Use different endpoints in different business areas |
The above API returns the following JSON when success.
{
"app_id": "1000343",
"attach": "",
"bank_type": "",
"body": "",
"cash_amount": 0,
"cash_currency": "CNY",
"create_at": 1561604164000,
"detail": "",
"currency": "HKD",
"discount": 0,
"id": "1131467",
"is_subscribe": "N",
"merchant_name": "ABC Company",
"reference_no": "11201906271056039151391853068",
"open_id": "oxoPW5SUhI5l_Szaef2Rfd4qE57w",
"jsapi": "",
"provider": "alipay",
"qr_code": "https://qr.alipay.com/bax09940kacxvcnqce5y4096",
"refundable": 0,
"serial_number": "11201906271056039151391853068",
"paid_at": 0,
"pay_amount": 10,
"amount": 10,
"total_refund_amount": 0,
"trade_state": "NOTPAY",
"trade_type": "NATIVE",
"transaction_id": "",
"wallet": "CN"
}
JSON Response
| Parameter | Type | Possible Values / Specification | Description |
|---|---|---|---|
| app_id | String | Returning back app_id for identification. | |
| attach | String | ||
| bank_type | String | The code of payment bank | |
| body | String | Returning back the body of payment | |
| cash_amount | String | Buyer paid amount, unit cent | |
| cash_currency | String | Buyer paid currency | |
| create_at | Integer | unix timestamp | timestamp of payment create |
| detail | String | ||
| currency | String | Display currency | |
| discount | Integer | ||
| id | String | Payment / order ID | |
| is_subscribe | String | ||
| merchant_name | String | ||
| reference_no | String | Returning back reference_no for identification. | |
| open_id | String | openid | |
| jsapi | String | The value for wechat.jsapi. | |
| provider | String | Payment provider | |
| qr_code | String | The text for generate QR Code | |
| refundable | Integer | ||
| serial_number | String | ||
| paid_at | Integer | The timestamp of payment finish | |
| pay_amount | Integer | ||
| order_amount | Integer | ||
| total_refund_amount | Integer | ||
| trade_state | String | refer to Appendix B | The status of payment |
| trade_type | String | Type of payment method | |
| transaction_id | String | up to 28 characters | Transaction identifier from payment provider |
| wallet | String | HK / CN | The region of wallet |
List Order
curl "https://demo.ipayasia.com/api/v1/payment/list"
-X POST
-H "Authorization:bearer sk_qkn6wgb8nfnadd63dyapxpfire"
-H "content-type: application/json"
The request payload JSON structured like this:
{
"app_id":"1000343",
"app_key": "PqSpdmuyErQwbGPK2dmwGJYIIXElV0fa",
"provider": "",
"page": 1,
"limit": 10,
"trade_state": "",
"start_date": "",
"end_date": "",
"start_at": 0,
"end_at": 0,
"sub_mch_id": "",
"store_id": ""
}
This API to list the order / payment.
HTTP Request
POST /api/v1/payment/list
JSON Payload
| Parameter | Type | Compulsory | Requirement | Default | Description |
|---|---|---|---|---|---|
| app_id | String | Yes | n/a | App ID. Get from the management background, or log in to get. | |
| app_key | String | Yes | n/a | App Key. Get from the management background, or log in to get. | |
| provider | String | No | alipay, wechat | will not filter by default | |
| page | Integer | No | 1 | Pagination parameter | |
| limit | Integer | No | 10 | Pagination Limit | |
| trade_state | String | No | NOTPAY, SUCCESS, REFUND, CLOSED, REVOKED, USERPAYING, PAYERROR | Trade State , refer to Appendix B | |
| start_date | String | No | Format: yyyy-MM-dd, e.g 2019-01-01 | Find orders by creation time (start from) | |
| end_date | String | No | Format: yyyy-MM-dd, e.g 2019-12-31 | Find orders by creation time (end to) | |
| start_at | Integer | No | unix timestamp | Find orders by creation time (start from) | |
| end_at | Integer | No | unix timestamp | Find orders by creation time (end to) | |
| sub_mch_id | String | No | Sub merchant Id | ||
| store_id | String | No | Store Id |
The request return JSON structured when success:
{
"page": 1,
"limit": 10,
"total": 3819,
"items": [
{
"attach": "{\"storeId\":\"0\"}",
"body": "pay",
"create_at": 1560828311000,
"discount": 0,
"currency": "HKD",
"id": "1104713",
"reference_no": "a2401b41002064420190618112502438",
"pay_amount": 2,
"provider": "wechat",
"refundable": 0,
"serial_number": "11201906181125101108945770340",
"paid_at": 1560828318000,
"amount": 2,
"total_refund_amount": 2,
"trade_state": "REFUND",
"trade_type": "MICROPAY",
"transaction_id": "4200000335201906187397414528",
"wallet": "CN",
"sub_mch_id": "1000258",
"store_id": "0",
"finish_time": 1560828328000
}
]
}
JSON Response
| Parameter | Type | Possible Values / Specification | Description |
|---|---|---|---|
| page | Integer | the page number of responded results. | |
| limit | Integer | The limit number applied. | |
| items | Array | refer to item schema |
Item Schema
| Parameter | Type | Possible Values / Specification | Description |
|---|---|---|---|
| attach | String | ||
| body | String | Description of goods | |
| create_at | unix timestamp | timestamp of payment create | |
| discount | Integer | ||
| currency | String | Display currency | |
| id | String | Payment / order ID | |
| reference_no | String | Returning back reference_no for identification. | |
| pay_amount | Integer | ||
| provider | Integer | ||
| refundable | Integer | ||
| serial_number | String | ||
| paid_at | Integer | The timestamp of payment finish | |
| amount | Integer | ||
| total_refund_amount | Integer | ||
| trade_state | String | refer to Appendix B | The status of payment |
| trade_type | String | Type of payment method | |
| transaction_id | String | up to 28 characters | Transaction identifier from payment provider |
| wallet | String | HK / CN | The region of wallet |
| sub_mch_id | String | ||
| store_id | String | ||
| finish_time | Integer | unix timestamp |
List Refund
curl "https://demo.ipayasia.com/api/v1/payment/refund/list"
-X POST
-H "Authorization:bearer sk_qkn6wgb8nfnadd63dyapxpfire"
-H "content-type: application/json"
The request payload JSON structured like this:
{
"app_id":"1000343",
"app_key": "PqSpdmuyErQwbGPK2dmwGJYIIXElV0fa",
"provider": "",
"page": 1,
"limit": 10,
"refund_status": "",
"start_date": "",
"end_date": "",
"start_at": 0,
"end_at": 0,
"sub_mch_id": "",
"store_id": ""
}
This API to list the refund.
HTTP Request
POST /api/v1/payment/refund/list
JSON Payload
| Parameter | Type | Compulsory | Requirement | Default | Description |
|---|---|---|---|---|---|
| app_id | String | Yes | n/a | App ID. Get from the management background, or log in to get. | |
| app_key | String | Yes | n/a | App Key. Get from the management background, or log in to get. | |
| provider | String | No | alipay, wechat | ||
| page | Integer | No | 1 | Pagination parameter | |
| limit | Integer | No | 10 | Pagination Limit | |
| refund_status | String | No | refer to Appendix C | Refund status | |
| start_date | String | No | Format: yyyy-MM-dd, e.g 2019-01-01 | Find orders by creation time (start from) | |
| end_date | String | No | Format: yyyy-MM-dd, e.g 2019-12-31 | Find orders by creation time (end to) | |
| start_at | Integer | No | unix timestamp | Find orders by creation time (start from) | |
| end_at | Integer | No | unix timestamp | Find orders by creation time (end to) | |
| sub_mch_id | String | No | Sub merchant Id | ||
| store_id | String | No | Store Id |
The request return JSON structured when success:
{
"page": 1,
"limit": 10,
"total": 3819,
"items": [
{
"discount": 0,
"currency": "HKD",
"id": "925515",
"reference_no": "11201906171310078870606359430",
"refund_reference_no": "11201906171310078870606359430",
"pay_amount": 100,
"provider": "alipay",
"refundable": 0,
"amount": 100,
"refund_id": "2019061722001463700563966487",
"refund_amount": 100,
"refund_status": "SUCCESS",
"refund_desc": "",
"refund_at": 1560748228000,
"transaction_id": "2019061722001463700563966487",
"total_refund_amount": 100,
"wallet": "CN",
"sub_mch_id": "1000258",
"store_id": "1000260"
}
]
}
JSON Response
| Parameter | Type | Possible Values / Specification | Description |
|---|---|---|---|
| page | Integer | the page number of responded results. | |
| limit | Integer | The limit number applied. | |
| items | Array | refer to item schema |
Item Schema
| Parameter | Type | Possible Values / Specification | Description |
|---|---|---|---|
| discount | Integer | ||
| currency | String | Display currency | |
| id | String | Payment / order ID | |
| reference_no | String | Returning back reference_no for identification. | |
| refund_reference_no | String | ||
| pay_amount | Integer | ||
| provider | Integer | ||
| refundable | Integer | ||
| amount | Integer | ||
| refund_id | String | ||
| refund_amount | Integer | ||
| refund_status | String | Status of refund | |
| refund_desc | String | ||
| refund_at | Integer | unix timestamp | |
| transaction_id | String | up to 28 characters | Transaction identifier from payment provider |
| total_refund_amount | Integer | ||
| wallet | String | HK / CN | The region of wallet |
| sub_mch_id | String | ||
| store_id | String |
Payment Status Notification
curl "https://{your_endpoint}"
-X POST
The above command contain the JSON payload structured like this:
{
"mer_id": "1000258",
"amount": 10,
"bank_type": "BALANCE",
"cash_amount": 10,
"cash_currency": "HKD",
"currency": "HKD",
"reference_no": "11201907021042441172037290701",
"transaction_id": "4200000330201907029279686378",
"transaction_time": 1562035515000,
"trade_type": "NATIVE",
"timestamp": 1562039362304,
"signature": "AFE6C08C18611CF8773B692348CA2A86"
}
Expected JSON response:
{
"status": "SUCCESS"
}
Gateway will send a request to your defined endpoint when the payment confirmed. If cannot receive the expected JSON response with http status code 200, retry mechanism will be triggered.
HTTP Request
POST https://{your_endpoint}
JSON Structure
| Parameter | Type | Possible Values / Specification | Description |
|---|---|---|---|
| mer_id | String | Merchant ID | |
| amount | Integer | 1-999999999999 | Returning back payment amount. A positive integer representing how much to charge in unit "Cent". |
| bank_type | String | The code of payment bank | |
| cash_amount | String | Buyer paid amount, unit cent | |
| cash_currency | String | Buyer paid currency | |
| currency | String | displayed currency | |
| reference_no | String | Returning back reference number. | |
| trade_type | String | refer to Appendix A | The type of payment |
| timestamp | Integer | UNIX timestamp | Timestamp of processing signature before request send. |
| transaction_id | String | Up to 32 characters | Transaction ID provided by vendor. |
| transaction_time | Integer | UNIX timestamp | The timestamp of processing transaction. |
| signature | String | base64 encoded string | MD5 signature |
Credit cards / Apple Pay / Google Pay
Load Stripe.js
<script src="https://js.stripe.com/v3/"></script>
// Create a Stripe client.
var stripe = Stripe('pk_test_nX7oXrKzw5fmNxfMaX38nAfB');
Create Charge
curl "https://demo.ipayasia.com/api/v1/payment/stripe/charge"
-X POST
-H "Authorization:bearer sk_qkn6wgb8nfnadd63dyapxpfire"
-H "content-type: application/json"
The request payload JSON structured like this:
{
"account":"acct_1DqBaFIaeFCPR5JY",
"amount": 200,
"currency": "hkd",
"reference_no": "Testing1234567890",
"notify_url": "http://www.example.com",
"token": "",
"source": "",
"statement_descriptor": ""
}
This API creates an order / payment
HTTP Request
`POST /api/v1/payment/stripe/charge
JSON Payload
| Parameter | Type | Compulsory | Requirement | Default | Description |
|---|---|---|---|---|---|
| account | String | Yes | n/a | App ID. Get from the management background, or log in to get. | |
| amount | Integer | Yes | 10-99999999 | n/a | A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge $1.00 or 100 to charge ¥100, a zero-decimal currency). |
| currency | String | Yes | Three-letter ISO currency code (lowercase) | n/a | Please refer to supported currencies. |
| reference_no | String | No | Up to 32 characters | start and end with alphanumeric, can contain underscore and hyphen | A unique string to reference the Checkout Session. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the session with your internal systems. |
| notify_url | String | Yes | Up to 128 characters | n/a | URL provided by Merchant for returning status used by Payment Notification API |
| token | String | Conditional | Required if wechat.jsapi, openid retrieved from WeChat "mini program" / "official account" |
||
| source | String | Conditional | A payment source to be charged. | ||
| statement_descriptor | String | No |
The above API returns the following JSON when success.
{
"amount": 8000,
"amount_refunded": 0,
"application_fee_amount": 507,
"captured": true,
"create_at": 1563440778000,
"currency": "hkd",
"description": "",
"failure_code": "",
"failure_message": "",
"id": "ch_1ExVZ8KOsaXiOK9JxiBRh60k",
"method": "visa",
"wallet": "",
"paid": true,
"refunded": false,
"status": "succeeded"
}
JSON Response
| Parameter | Type | Possible Values / Specification | Description |
|---|---|---|---|
| amount | Integer | amount | |
| amount_refunded | Integer | Amount in cents refunded (can be less than the amount attribute on the charge if a partial refund was issued). | |
| application_fee_amount | Integer | The amount of the application fee (if any) for the charge. | |
| captured | Boolean | Represents whether it is still uncaptured or has since been captured | |
| create_at | Integer | unix timestamp | timestamp of charge created |
| currency | String | Charge currency | |
| description | String | ||
| failure_code | String | Error code explaining reason for charge failure if available | |
| failure_message | String | Message to user further explaining reason for charge failure if available. | |
| id | String | Charge ID | |
| method | String | Payment method | |
| wallet | Strong | The card wallet. | |
| paid | Boolean | true if the charge succeeded, or was successfully authorized for later capture. | |
| refunded | Boolean | Whether the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false. | |
| status | String | The status of the payment is either succeeded, pending, or failed. |
Create Charge by Using Checkout (Redirect)
curl "https://demo.ipayasia.com/api/v1/payment/stripe/checkout"
-X POST
-H "Authorization:bearer sk_qkn6wgb8nfnadd63dyapxpfire"
-H "content-type: application/json"
The request payload JSON structured like this:
{
"account": "acct_1DqBaFIaeFCPR5JY",
"items": [
{
"amount": 400,
"currency": "hkd",
"description": "product1 description",
"name": "product21",
"quantity": 2
},
{
"amount": 1000,
"currency": "hkd",
"description": "product2 description",
"name": "product2",
"quantity": 3
}
],
"success_url": "https://payment.ipayasia.com/success",
"cancel_url": "https://payment.ipayasia.com/cancel",
"notify_url": "https://payment.ipayasia.com/notify",
"reference_no": "TESTB000-000-000-0001",
"locale": "en",
"statement_descriptor": "TESTING"
}
This API creates an order / payment
HTTP Request
`POST /api/v1/payment/stripe/checkout
JSON Payload
| Parameter | Type | Compulsory | Requirement | Default | Description |
|---|---|---|---|---|---|
| account | String | Yes | n/a | App ID. Get from the management background, or log in to get. | |
| items | Item Array | Yes | n/a | A list of items the customer is purchasing. | |
| reference_no | String | No | Up to 32 characters | start and end with alphanumeric, can contain underscore and hyphen | A unique string to reference the Checkout Session. This can be a customer ID, a cart ID, or similar, and can be used to reconcile the session with your internal systems. |
| success_url | String | Yes | Up to 128 characters | n/a | The URL to which vendor should send customers when payment is complete. |
| cancel_url | String | Yes | Up to 128 characters | n/a | The URL the customer will be directed to if they decide to cancel payment and return to your website. |
| notify_url | String | Yes | Up to 128 characters | n/a | URL provided by Merchant for returning status used by Payment Notification API |
| locale | String | No | auto | The IETF language tag of the locale Checkout is displayed in. If blank or auto, the browser’s locale is used. Supported values are auto, da, de, en, es, fi, fr, it, ja, nb, nl, pl, pt, sv, or zh. | |
| statement_descriptor | String | No | Extra information about a charge. This will appear on your customer’s credit card statement. It must contain at least one letter. |
Item Structure
| Parameter | Type | Compulsory | Requirement | Default | Description |
|---|---|---|---|---|---|
| amount | Integer | Yes | smallest currency unit | n/a | unit price |
| currency | String | Yes | Three-letter ISO currency code (lowercase) | n/a | Please refer to supported currencies. |
| name | String | Yes | n/a | Product name | |
| quantity | Integer | Yes | quantity purchased | n/a | |
| description | String | No | The description for the line item. | ||
| images | String Array | No | URL | n/a | A list of images representing the line item. |
The above API returns the following JSON when success.
{
"session_id": "cs_test_oFe4PlH6pTwvpD5ErGim6rETgTDHGwiZmra16Y7rNiHYxbds7WI3eE8y",
"reference_number": "TEST000-000-000-0013"
}
JSON Response
| Parameter | Type | Possible Values / Specification | Description |
|---|---|---|---|
| session_id | String | String for redirect. | |
| reference_no | String | Returning back reference_no for identification. |
Refund Charge
curl "https://demo.ipayasia.com/api/v1/payment/stripe/refund"
-X POST
-H "Authorization:bearer sk_qkn6wgb8nfnadd63dyapxpfire"
-H "content-type: application/json"
The request payload JSON structured like this:
{
"account": "acct_1DqBaFIaeFCPR5JY",
"reference_no":"",
"amount": 0
}
Creating a new refund will refund a charge that has previously been created but not yet refunded. Funds will be refunded to the credit or debit card that was originally charged.
You can optionally refund only part of a charge. You can do so multiple times, until the entire charge has been refunded.
Once entirely refunded, a charge can’t be refunded again. This method will return an an error when called on an already-refunded charge, or when trying to refund more money than is left on a charge.
HTTP Request
POST /api/v1/payment/stripe/refund
JSON Payload
| Parameter | Type | Compulsory | Requirement | Default | Description |
|---|---|---|---|---|---|
| account | String | Yes | n/a | The identifier of account | |
| reference_no | String | Yes | n/a | The reference number to identify of the charge to refund. | |
| amount | Integer | Yes | n/a | A positive integer in cents representing how much of this charge to refund. Can refund only up to the remaining, unrefunded amount of the charge. |
The above API returns the following JSON when success.
{
"amount": 8000,
"amount_refunded": 8000,
"application_fee_amount": 507,
"captured": true,
"create_at": 1563440778000,
"currency": "hkd",
"description": "",
"failure_code": "",
"failure_message": "",
"id": "ch_1ExVZ8KOsaXiOK9JxiBRh60k",
"method": "visa",
"wallet": "",
"paid": true,
"refunded": true,
"status": "succeeded"
}
JSON Response
| Parameter | Type | Possible Values / Specification | Description |
|---|---|---|---|
| amount | Integer | amount | |
| amount_refunded | Integer | Amount in cents refunded (can be less than the amount attribute on the charge if a partial refund was issued). | |
| application_fee_amount | Integer | The amount of the application fee (if any) for the charge. | |
| captured | Boolean | Represents whether it is still uncaptured or has since been captured | |
| create_at | Integer | unix timestamp | timestamp of charge created |
| currency | String | Charge currency | |
| description | String | ||
| failure_code | String | Error code explaining reason for charge failure if available | |
| failure_message | String | Message to user further explaining reason for charge failure if available. | |
| id | String | Charge ID | |
| method | String | Payment method | |
| wallet | Strong | The card wallet. | |
| paid | Boolean | true if the charge succeeded, or was successfully authorized for later capture. | |
| refunded | Boolean | Whether the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false. | |
| status | String | The status of the payment is either succeeded, pending, or failed. |
Query Charge
curl "https://demo.ipayasia.com/api/v1/payment/stripe/query"
-X POST
-H "Authorization:bearer sk_qkn6wgb8nfnadd63dyapxpfire"
-H "content-type: application/json"
The request payload JSON structured like this:
{
"account": "acct_1DqBaFIaeFCPR5JY",
"reference_no":""
}
Retrieves the details of a charge that has previously been created.
HTTP Request
POST /api/v1/payment/stripe/query
JSON Payload
| Parameter | Type | Compulsory | Requirement | Default | Description |
|---|---|---|---|---|---|
| account | String | Yes | n/a | The identifier of account | |
| reference_no | String | Yes | n/a | The reference number to identify of the charge. |
The above API returns the following JSON when success.
{
"amount": 8000,
"amount_refunded": 8000,
"application_fee_amount": 507,
"captured": true,
"create_at": 1563440778000,
"currency": "hkd",
"description": "",
"failure_code": "",
"failure_message": "",
"id": "ch_1ExVZ8KOsaXiOK9JxiBRh60k",
"method": "visa",
"wallet": "",
"paid": true,
"refunded": true,
"status": "succeeded"
}
JSON Response
| Parameter | Type | Possible Values / Specification | Description |
|---|---|---|---|
| amount | Integer | amount | |
| amount_refunded | Integer | Amount in cents refunded (can be less than the amount attribute on the charge if a partial refund was issued). | |
| application_fee_amount | Integer | The amount of the application fee (if any) for the charge. | |
| captured | Boolean | Represents whether it is still uncaptured or has since been captured | |
| create_at | Integer | unix timestamp | timestamp of charge created |
| currency | String | Charge currency | |
| description | String | ||
| failure_code | String | Error code explaining reason for charge failure if available | |
| failure_message | String | Message to user further explaining reason for charge failure if available. | |
| id | String | Charge ID | |
| method | String | Payment method | |
| wallet | Strong | The card wallet. | |
| paid | Boolean | true if the charge succeeded, or was successfully authorized for later capture. | |
| refunded | Boolean | Whether the charge has been fully refunded. If the charge is only partially refunded, this attribute will still be false. | |
| status | String | The status of the payment is either succeeded, pending, or failed. |
Charge Notification
curl "https://{your_endpoint}"
-X POST
The above command contain the JSON payload structured like this:
{
"account": "acct_1DwpMDIMLnBC2UgJ",
"amount": 10,
"method": "visa",
"currency": "hkd",
"reference_no": "TESTB000-000-000-0001",
"transaction_id": "ch_1ExWYvKOsaXiOK9JYdKE3gqz",
"transaction_time": 1562035515000,
"timestamp": 1563444609000,
"signature": "F5648B89E50FB7D8F30DF36502D5175F"
}
Expected JSON response:
{
"status": "SUCCESS"
}
Gateway will send a request to your defined endpoint when the payment confirmed. If cannot receive the expected JSON response with http status code 200, retry mechanism will be triggered.
HTTP Request
POST https://{your_endpoint}
JSON Structure
| Parameter | Type | Possible Values / Specification | Description |
|---|---|---|---|
| account | String | Returning back account | |
| amount | Integer | 10-99999999 | Returning back payment amount |
| method | String | The payment method used by payer | |
| currency | String | Returning back currency | |
| reference_no | String | Returning back reference number. | |
| timestamp | Integer | UNIX timestamp | Timestamp of processing signature before request send. |
| transaction_id | String | Up to 32 characters | Transaction ID provided by vendor. |
| transaction_time | Integer | UNIX timestamp | The timestamp of processing transaction. |
| signature | String | base64 encoded string | MD5 signature |
Verification
Verify Payment Status Notification
The request payload JSON structured of Payment Status Notification API:
{
"mer_id": "1000258",
"amount": 10,
"bank_type": "BALANCE",
"cash_amount": 10,
"cash_currency": "HKD",
"currency": "HKD",
"reference_no": "11201907021042441172037290701",
"transaction_id": "4200000330201907029279686378",
"transaction_time": 1562035515000,
"trade_type": "NATIVE",
"timestamp": 1562039362304,
"signature": "AFE6C08C18611CF8773B692348CA2A86"
}
Convert the JSON object to query parameters in alphabetical order like this:
amount=10&bank_type=BALANCE&cash_amount=10&cash_currency=HKD¤cy=HKD&key=NuOpbWyKYV9scy9CclISR1kHLANqyVlL&mer_id=1000258&reference_no=11201907021042441172037290701×tamp=1562039362304&trade_type=NATIVE&transaction_id=4200000330201907029279686378&transaction_time=1562035515000
Developers can apply one of the options to make sure getting the original data of payment status.
Option 1
Developers are required to verify the data when receive payment status notification.
Convert the JSON object to query parameters string (exclude signature parameter) and add &key=xxxxxxx (verify secret) in the query string and sort by alphanumeric order.
You will get a string like example.
Then generate the MD5 signature for the query string and verify the generated hash with the signature in payload .
Option 2
Developers can submit an enquiry API to retrieve the status of payment without handling signature verification.
Errors
General Error Structure
The request payload JSON structured like this:
{
"message": "Invalid merchant ID.",
"request_id": "f4sgwi1ohbd87eaq8b7mrsnpio",
"status_code": 400,
"type": "invalid_request_error",
"code": "invalid_parameter",
"param": "merchant_id"
}
JSON Parameters
| Parameter | Type | Compulsory | Description |
|---|---|---|---|
| request_id | String | Yes | Unique ID of the request for tracing |
| message | String | Yes | A human-readable message providing more details about the error. |
| status_code | Integer | Yes | HTTP Status Code |
| type | String | Yes | The type of error |
| code | String | Yes | For some errors that could be handled programmatically |
| param | String | Yes | The parameter related to the error. |
Error Types
FPS API uses the following error types:
| Types | Meaning |
|---|---|
| invalid_request_error | Invalid request errors arise when your request has invalid parameters. |
| rate_limit_error | Too many requests hit the API too quickly. |
| authentication_error | Failure to properly authenticate yourself in the request. |
| api_error | API errors cover any other type of problem (e.g., a temporary problem with servers), and are extremely uncommon. |
Error Codes
FPS API uses the following error codes:
| Types | Meaning |
|---|---|
| invalid_parameter | Invalid request errors arise when your request has invalid parameters. |
| invalid_merchant_id | Invalid merchant ID / not found. |
| invalid_reference_number | Invalid reference number / not found. |
| payment_method_not_available | The payment method is not available with the corresponding merchant. |
| currency_not_match | Payment currency and settlement currency is not matched. |
| duplicate_reference_number | Duplicate reference number. |
HTTP Status Code
| Error Code | Status | Meaning |
|---|---|---|
| 400 | Bad Request | The request was unacceptable, often due to missing a required parameter. |
| 401 | Unauthorized | No valid API key / client code provided. |
| 403 | Forbidden | The API requested is hidden for administrators only. |
| 404 | Not Found | The specified resource could not be found. |
| 405 | Method Not Allowed | You tried to access a resource with an invalid method. |
| 406 | Not Acceptable | You requested a format that isn't json. |
| 429 | Too Many Requests | You're requesting too many requests! Slow down! |
| 500 | Internal Server Error | We had a problem with our server. Try again later. |
| 503 | Service Unavailable | We're temporarily offline for maintenance. Please try again later. |
Appendixes
Appendix A: Trade Type
Trade Type
| Type | Description |
|---|---|
| NATIVE | |
| QRCODE | |
| MICROPAY | |
| WAPPAY | |
| JSAPI | |
| APP |
Appendix B: Trade Status
Trade Status
| Status | Description |
|---|---|
| NOTPAY | Not pay |
| SUCCESS | Payment succeeded |
| REFUND | Payment refunded |
| CLOSED | Payment closed |
| REVOKED | The payment is revoked |
| USERPAYING | Paying |
| PAYERROR | Error occurs when pay |
Appendix C: Refund Status
| Status | Description |
|---|---|
| PROCESSING | Processing |
| SUCCESS | Refund succeeded |
| REFUNDCLOSE | Refund closed |
| CHANGE | Change |
Appendix D: WeChat JSAPI reference
Use JSON.parse(data.jsapi) to change the value in data.jsapi to JSON object
and refer to WeChat official development document
Step 1: import wechat js
<script src="http://res.wx.qq.com/open/js/jweixin-1.2.0.js"></script>
Step 2: inject the required API component in config
<script type="text/javascript">
wx.config({
beta : true,
debug: true, // is debug model, if true, the response of API will be alerted in client side. (the request parameters will be displayed in pc console)
appId: '', // compulsory, the unique appId
timestamp: , // compulsory, timestamp for generate signature
nonceStr: '', // compulsory, random string for generate signature
signature: '',// compulsory, generate signature reference：https://mp.weixin.qq.com/wiki?t=resource/res_main&id=mp1421141115
jsApiList: ["getH5PrepayRequest"] // compulsory, the list of required JS interface
});
</script>
Step 3: pass the parameters
<script type="text/javascript">
wx.ready(function(){
// use the parsed value which retrieved from create payment
var payConfig = {
"appId" : "",
"timeStamp" : "",
"nonceStr" : "",
"package" : "",
"signType" : "",
"paySign" : ""
};
wx.invoke('getH5PrepayRequest', payConfig,function(res) { // callback function
var msg = res.errMsg || res.err_msg; // the attribute naming may vary based on version
if(!msg){}
if(-1 != msg.indexOf("ok")) {
// call successfully
} else if(-1 != msg.indexOf("cancel")){
// payer cancelled
} else{
// fail
}
});
});
</script>