XiaoNiuPay API Documentation

Fast, Secure, and Reliable Payment Solution

API Features

RESTful API design, simple and easy to use
Supports PHP, Python, Golang and more
Complete payment flow: payment, query, disbursement, etc.
Real-time callback notification
RSA signature verification

Basic Rules

Request URL

Production Environment:

https://api.xiaoniupay.com/xnpay-api

Request Method

POST

Content-Type

application/json

Payment API

API URL: /payment

Create new payment order

POST

Request Parameters

Parameter Name	Description	Type	Required	Example
merchantCode	Merchant Code	String	Y	test
orderNumber	Order Number	String	Y	1604384758793
amount	Amount	Integer	Y	40000
phone	Phone	String	Y	08123456789
email	Email	String	Y	test@test.com
userName	Name	String	Y	John Doe
walletNumber	Wallet Number	String	N	08821900000 (Required for DANA, format 08********; Required for OVO cashier with real number, otherwise optional)
channelCode	Channel Code	String	Y	M1 (If CASH, will use cashier payment. See channel code table for other codes)
returnUrl	Return URL	String	N	http://test/return
callbackUrl	Callback URL	String	Y	http://test/callback
signType	Signature Type	String	Y	RSA
sign	Signature	String	Y	RSA(...)

Signature Rule

RSA(amount + callbackUrl + channelCode + merchantCode + orderNumber)

Response Parameters

Parameter Name	Description	Type	Example
code	Response Code	String	000
message	Response Message	String	success
orderNumber	Order ID	String	O3915CB3C93E445C9
accountNumber	Bank Account	String	TEST0001 (VA only)
paymentUrl	Payment URL	String	http://xxx.xxx/
qrcode	QR Code	String	Returned for QRIS payment
merchantCode	Merchant Code	String	test

Request Example

{
  "merchantCode": "test",
  "orderNumber": "1604384758793",
  "amount": 40000,
  "phone": "08123456789",
  "email": "test@test.com",
  "userName": "John Doe",
  "channelCode": "M1",
  "returnUrl": "http://test/return",
  "callbackUrl": "http://test/callback",
  "sign": "a1b2c3d4e5f6..."
}

Response Example

{
  "code": "000",
  "message": "success",
  "orderNumber": "O3915CB3C93E445C9",
  "paymentUrl": "http://xxx.xxx/",
  "qrcode": "data:image/png;base64,..."
}

Code Examples

package com.customer.demo;

import cn.hutool.http.HttpUtil;
import com.alibaba.fastjson.JSON;

import java.util.HashMap;
import java.util.Map;

public class ZkpayPaymentDemo {

 public static void main(String[] args) {

 String url = "https://api.xiaoniupay.com/xnpay-api/payment";

 String merchantCode = "test";
 String privateKey = "Gjon5exBp34mkNUU0r4wk2delkbclF4i";
 String orderNumber = System.currentTimeMillis() + "";
 Integer amount = 40000;
 String phone = "08123456789";
 String email = "test@test.com";
 String userName = "John Doe";
 String walletNumber = "08821900000";
 String channelCode = "M1";
 String returnUrl = "http://test/return";
 String callbackUrl = "http://test/callback";
 
 String signOrigin = amount + callbackUrl + channelCode + merchantCode + orderNumber;
 String sign = RSAUtil.sign(signOrigin, privateKey);
 System.out.println(sign);
 Map<String, Object> param = new HashMap<>();
 param.put("merchantCode", merchantCode);
 param.put("orderNumber", orderNumber);
 param.put("amount", amount);
 param.put("phone", phone);
 param.put("email", email);
 param.put("userName", userName);
 param.put("walletNumber", walletNumber);
 param.put("channelCode", channelCode);
 param.put("returnUrl", returnUrl);
 param.put("callbackUrl", callbackUrl);
 param.put("signType", "RSA");
 param.put("sign", sign);

 String sendParam = JSON.toJSONString(param);
 System.out.println("request==> " + sendParam);

 String result = HttpUtil.post(url, sendParam, 10000);

 System.out.println("response==> " + result);

 }

}

Payment Query

API URL: /checkPayment

Query payment order status

POST

Request Parameters

Parameter Name	Description	Type	Required	Example
merchantCode	Merchant Code	String	Y	test
orderNumber	Order Number	String	Y	1604384758793
signType	Signature Type	String	Y	RSA
sign	Signature	String	Y	RSA(...)

Signature Rule

RSA(merchantCode + orderNumber)

Response Parameters

Parameter Name	Description	Type	Example
code	Response Code	String	000
message	Response Message	String	complete
userOrderNumber	User Order Number	String	1604384968942
orderNumber	Platform Order Number	String	test16043849702603
amount	Payment Amount	Integer	40000
merchantCode	Merchant Code	String	test
phone	Phone	String	Hidden (00)
email	Email	String	Hidden (00)
userName	Name	String	John Doe
channelCode	Channel Code	String	M1
status	Payment Status	int	0 Pending, 1 Success, 2 Failed
createTime	Order Create Time	Date	2020-11-03 13:29:30
payTime	Payment Time	Date	2020-11-03 13:39:30 (Returned on success)

Request Example

{
  "merchantCode": "test",
  "orderNumber": "1604384758793",
  "sign": "a1b2c3d4e5f6..."
}

Response Example

{
  "code": "000",
  "status": 1,
  "amount": 40000
}

Code Examples

package com.customer.demo;

import cn.hutool.http.HttpUtil;
import com.alibaba.fastjson.JSON;

import java.util.HashMap;
import java.util.Map;

public class ZkpayCheckPaymentDemo {

 public static void main(String[] args) {

 String url = "https://api.xiaoniupay.com/xnpay-api/checkPayment";

 String merchantCode = "test";
 String privateKey = "Gjon5exBp34mkNUU0r4wk2delkbclF4i";
 String orderNumber = "1604384758793";

 String signOrigin = merchantCode + orderNumber;
 String sign = RSAUtil.sign(signOrigin, privateKey);
 Map<String, Object> param = new HashMap<>();
 param.put("merchantCode", merchantCode);
 param.put("orderNumber", orderNumber);
 param.put("signType", "RSA");
 param.put("sign", sign);

 String sendParam = JSON.toJSONString(param);
 System.out.println("request==> " + sendParam);

 String result = HttpUtil.post(url, sendParam, 10000);

 System.out.println("response==> " + result);

 }

}

Disbursement API

API URL: /disbursement

Initiate Disbursement Request

POST

Request Parameters

Parameter Name	Description	Type	Required	Example
merchantCode	Merchant Code	String	Y	test
orderNumber	Order Number	String	Y	1604384758793
amount	Amount	Integer	Y	40000
bankAccount	Bank Account	String	Y	100100100
bankCode	Bank Code	String	Y	PERMATA
phone	Phone	String	Y	08123456789
email	Email	String	Y	test@test.com
userName	Recipient Name	String	Y	John Doe
channelCode	Channel Code	String	Y	ALL
returnUrl	Return URL	String	N	http://test/return
callbackUrl	Callback URL	String	Y	http://test/callback
signType	Signature Type	String	Y	RSA
sign	Signature	String	Y	RSA(amount + bankAccount + bankCode + channelCode + email + merchantCode + orderNumber + phone + userName)

Signature Rule

RSA(amount + bankAccount + bankCode + channelCode + email + merchantCode + orderNumber + phone + userName)

PS

channelCode available: ALL for all channels, ID IDN US ZH for different countries, use ALL if not specified

Request Example

{
  "merchantCode": "test",
  "orderNumber": "1604384758793",
  "amount": 50000,
  "bankAccount": "1234567890",
  "bankCode": "BCA",
  "phone": "08123456789",
  "email": "test@test.com",
  "userName": "John Doe",
  "channelCode": "ALL",
  "returnUrl": "http://test/return",
  "callbackUrl": "http://test/callback",
  "sign": "a1b2c3d4e5f6..."
}

Response Example

{
  "code": "000",
  "message": "success",
  "amount": 40000,
  "merchantCode": "test"
}

Code Examples

package com.customer.demo;

import cn.hutool.http.HttpUtil;
import com.alibaba.fastjson.JSON;

import java.util.HashMap;
import java.util.Map;

public class ZkpayDisbursementDemo {

 public static void main(String[] args) {

 String url = "https://api.xiaoniupay.com/xnpay-api/disbursement";

 String merchantCode = "test";
 String privateKey = "3d5AjiDLYQbpspsEpF1AJrBbaVYNmZsf";
 String orderNumber = System.currentTimeMillis() + "";
 Integer amount = 40000;
 String bankAccount = "100100100";
 String bankCode = "PERMATA";
 String phone = "08123456789";
 String email = "test@test.com";
 String userName = "John Doe";
 String channelCode = "ALL";
 String returnUrl = "http://test/return";
 String callbackUrl = "http://test/callback";
 String signOrigin = amount + bankAccount + bankCode + callbackUrl + channelCode + merchantCode + orderNumber;
 String sign = RSAUtil.sign(signOrigin, privateKey);
 System.out.println(sign);
 Map<String, Object> param = new HashMap<>();
 param.put("merchantCode", merchantCode);
 param.put("orderNumber", orderNumber);
 param.put("amount", amount);
 param.put("phone", phone);
 param.put("email", email);
 param.put("bankAccount", bankAccount);
 param.put("bankCode", bankCode);
 param.put("userName", userName);
 param.put("channelCode", channelCode);
 param.put("returnUrl", returnUrl);
 param.put("callbackUrl", callbackUrl);
 param.put("signType", "RSA");
 param.put("sign", sign);

 String sendParam = JSON.toJSONString(param);
 System.out.println("request==> " + sendParam);

 String result = HttpUtil.post(url, sendParam, 10000);

 System.out.println("response==> " + result);

 }

}

Disbursement Query

API URL: /checkDisbursement

Query disbursement order status

POST

Request Parameters

Parameter Name	Description	Type	Required	Example
merchantCode	Merchant Code	String	Y	test
orderNumber	Order Number	String	Y	1604384758793
signType	Signature Type	String	Y	RSA
sign	Signature	String	Y	RSA(...)

Signature Rule

RSA(merchantCode + orderNumber)

Request Example

{
  "merchantCode": "test",
  "orderNumber": "1604384758793",
  "sign": "a1b2c3d4e5f6..."
}

Response Example

{
  "code": "000",
  "message": "complete",
  "userOrderNumber": "1604384968942",
  "orderNumber": "test16043849702603",
  "amount": 40000,
  "merchantCode": "test",
  "phone": "00",
  "email": "00",
  "userName": "John Doe",
  "bankCode": "PERMATA",
  "bankAccount": "100100100",
  "channelCode": "M1",
  "status": 1,
  "createTime": "2020-11-03 13:29:30",
  "payTime": "2020-11-03 13:39:30"
}

Code Examples

package com.customer.demo;

import cn.hutool.http.HttpUtil;
import com.alibaba.fastjson.JSON;

import java.util.HashMap;
import java.util.Map;

public class ZkpayCheckDisbursementDemo {

 public static void main(String[] args) {

 String url = "https://api.xiaoniupay.com/xnpay-api/checkDisbursement";

 String merchantCode = "test";
 String privateKey = "Gjon5exBp34mkNUU0r4wk2delkbclF4i";
 String orderNumber = "1604384758793";
 String signOrigin = merchantCode + orderNumber;
 String sign = RSAUtil.sign(signOrigin, privateKey);
 Map<String, Object> param = new HashMap<>();
 param.put("merchantCode", merchantCode);
 param.put("orderNumber", orderNumber);
 param.put("signType", "RSA");
 param.put("sign", sign);

 String sendParam = JSON.toJSONString(param);
 System.out.println("request==> " + sendParam);

 String result = HttpUtil.post(url, sendParam, 10000);

 System.out.println("response==> " + result);

 }

}

Available Channels

API URL: /queryChannel

Query available payment channels

Signature Rule: RSA(merchantCode + timestamp)

Balance Query

API URL: /checkBalance

Query merchant balance

Signature Rule: RSA(merchantCode + timestamp)

Async Callback

Payment Callback

After payment is completed, the system will send a POST request to your configured callbackUrl

Callback Parameters

Parameter Name	Description	Type	Example
code	Response Code	String	000
message	Response Message	String	complete
orderNumber	Merchant Order Number	String	1604384758793
amount	Payment Amount	Integer	40000
merchantCode	Merchant Code	String	test
phone	Phone (hidden as 00)	String	00
email	Email (hidden as 00)	String	00
userName	User Name	String	John Doe
channelCode	Channel Code	String	M1
status	Status: 0 Pending, 1 Success	Integer	1
createTime	Order Create Time (timestamp)	Long	1617695193459
payTime	Payment Time (timestamp, returned on success)	Long	1617695193459
signType	Signature Type	String	RSA
sign	RSA(amount + channelCode + email + merchantCode + orderNumber + phone + userName)	String	a1b2c3d4e5f6

Callback Example

{
  "code": "000",
  "message": "complete",
  "orderNumber": "1604384758793",
  "amount": 40000,
  "merchantCode": "test",
  "phone": "00",
  "email": "00",
  "userName": "John Doe",
  "channelCode": "M1",
  "status": 1,
  "createTime": 1617695193459,
  "payTime": 1617695193459,
  "sign": "a1b2c3d4e5f6"
}

Response: Please return HTTP 200 status code to confirm receipt of callback

Disbursement Callback

After disbursement is completed, the system will send a POST request to your configured callbackUrl

Callback Parameters

Parameter Name	Description	Type	Example
code	Response Code	String	000
message	Response Message	String	complete
orderNumber	Merchant Order Number	String	1604384758793
amount	Disbursement Amount	Integer	40000
merchantCode	Merchant Code	String	test
phone	Phone (hidden as 00)	String	00
email	Email (hidden as 00)	String	00
userName	Recipient Name	String	John Doe
bankCode	Bank Code	String	PERMATA
bankAccount	Bank Account	String	100100100
channelCode	Channel Code	String	M1
status	Status: 1 Success, 2 Failed	Integer	1
createTime	Order Create Time (timestamp)	Long	1617695193459
payTime	Payment Time (timestamp, returned on success)	Long	1617695193459
signType	Signature Type	String	RSA
sign	RSA(amount + bankAccount + bankCode + channelCode + email + merchantCode + orderNumber + phone + userName)	String	a1b2c3d4e5f6

Callback Example

{
  "code": "000",
  "message": "complete",
  "orderNumber": "1604384758793",
  "amount": 40000,
  "merchantCode": "test",
  "phone": "00",
  "email": "00",
  "userName": "John Doe",
  "bankCode": "PERMATA",
  "bankAccount": "100100100",
  "channelCode": "M1",
  "status": 1,
  "createTime": 1617695193459,
  "payTime": 1617695193459,
  "sign": "a1b2c3d4e5f6"
}

Response: Please return HTTP 200 status code to confirm receipt of callback

Payment Channel Code Reference

🇮🇩 Indonesia

channel_code	channel_name	Type
QRIS	QRIS	Collection
VC	Credit Card (Visa / Master)	Collection
BK	BCA KlikPay	Collection
BCA	BCA Virtual Account	Collection
BBC	BCA BC	Collection
M1	Mandiri Virtual Account	Collection
ME	Mandiri eCash	Collection
MP	Mandiri PC	Collection
BT	Permata Bank Virtual Account	Collection
PN	Permata Net	Collection
A1	ATM Bersama	Collection
B1	CIMB Niaga Virtual Account	Collection
I1	BNI Virtual Account	Collection
VA	Maybank Virtual Account	Collection
M2U	Maybank2U	Collection
FT	Ritel	Collection
OV	OVO	Collection
LA	LINKAJA	Collection
DANA	DANA	Collection
SP	Shopee Pay	Collection
SA	Shopee Pay Apps	Collection
AG	Bank Artha Graha	Collection
S1	Sahabat Sampoerna	Collection
NI	Bank Negara Indonesia	Collection
RI	Bank Rakyat Indonesia	Collection
RIE	BRI ePay	Collection
IN	INDOMARET	Collection
AL	ALFAMART	Collection
DOB	Danamon Online Banking	Collection
DVA	Danamon Virtual Account	Collection
AI	Alto iDebit	Collection
JIB	Jenius IB	Collection
JA	JAKONE	Collection
OC	Octo Clicks	Collection
SK	Sakuku	Collection
ALF	Alfagroup	Collection
KR	Kredivo	Collection
BL	BTNONLINE	Collection
SVA	Sinarmas Virtual Account	Collection
CASH	Cashier Payment	Collection
ALL	Indonesia Disbursement All Channel	Disbursement

🇵🇰 Pakistan

channel_code	channel_name	Type
PK_JAZZ	JAZZ Wallet	Collection
PK_EASY	EASY Wallet	Collection
PK_ALL	Pakistan Disbursement All Channel	Disbursement

🇧🇷 Brazil

channel_code	channel_name	Type
BR_BRL	QR Code Payment	Collection
BR_ALL	PIX Disbursement Channel	Disbursement

🇹🇭 Thailand

channel_code	channel_name	Type
TH_QR	Thailand QR Code Payment	Collection
TH_ALL	Thailand Disbursement Channel	Disbursement

Bank Code Reference

Bank Code List

🇮🇩 Indonesia

bank_code	bank_name
BCA	Bank BCA
BRI	Bank BRI
MANDIRI	BANK MANDIRI
BNI	BANK BNI 46
CIMB	BANK CIMB NIAGA
PERMATA	BANK PERMATA
BJB	Bank BJB
DANAMON	BANK DANAMON INDONESIA
BTN	Bank BTN
MAYBANK	BANK MAYBANK INDONESIA
SINARMAS	BANK SINARMAS
PANIN	BANK PANIN
BNI_SYR	BANK BNI SYARIAH
MANDIRI_SYR	BANK SYARIAH MANDIRI
DKI	BPD DKI JAKARTA
MEGA	BANK MEGA
BSI	BSI (Bank Syariah Indonesia)
BTPN	Bank BTPN
BRI_SYR	BANK BRI SYARIAH
MUAMALAT	BANK MUAMALAT INDONESIA
OCBC	BANK OCBC NISP
OVO	OVO
SHOPEEPAY	SHOPEEPAY
DANA	DANA
GOPAY	GOPAY

🇵🇰 Pakistan

bank_code	bank_name
PK_EASY	EASY Wallet
PK_JAZZ	JAZZ Wallet

🇧🇷 Brazil

bank_code	bank_name
BR_CPF	CPF Number
BR_PHONE	Phone Number
BR_EMAIL	Email

🇹🇭 Thailand (Thailand)

bank_code	bank_name_en	bank_name_th
TH_BAAC	BANK FOR AGRICULTURE AND AGRICULTURAL COOPERATIVES	ธ. เพื่อการเกษตรและสหกรณ์การเกษตร
TH_BAY	BANK OF AYUDHYA PUBLIC COMPANY LIMITED	ธ. กรุงศรีอยุธยา จำกัด (มหาชน)
TH_BBL	BANGKOK BANK PUBLIC COMPANY LTD.	ธ. กรุงเทพ จำกัด (มหาชน)
TH_CIMBT	CIMB THAI BANK PUPBLIC COMPANY LTD.	ธ. ซีไอเอ็มบีไทย จำกัด (มหาชน)
TH_CITI	CITIBANK, N.A.	ธ. ซิตี้แบงก์
TH_GHB	THE GOVERNMENT HOUSING BANK	ธ. อาคารสงเคราะห์
TH_GSB	THE GOVERNMENT SAVINGS BANK	ธ. ออมสิน
TH_ISBT	ISLAMIC BANK OF THAILAND	ธ. อิสลามแห่งประเทศไทย
TH_ICBCT	INDUSTRIAL AND COMMERCIAL BANK OF CHINA (THAI) PUBLIC COMPANY LIMITED	ธ. ไอซบีซี (ไทย) จำกัด (มหาชน)
TH_KBANK	KASIKORNBANK PUBLIC COMPANY LTD.	ธ. กสิกรไทย จำกัด (มหาชน)
TH_KK	KIATNAKIN BANK PUBLIC COMPANY LIMITED	ธ. เกียรตินาคิน จำกัด (มหาชน)
TH_KTB	KRUNG THAI BANK PUBLIC COMPANY LTD.	ธ. กรุงไทย จำกัด (มหาชน)
TH_LHBANK	LAND AND HOUSES BANK PUBLIC COMPANY LIMITED	ธ. แลนด์แอนด์เฮ้าส์ จำกัด (มหาชน)
TH_MIZUHO	MIZUHO CORPORATE BANK, LTD.	ธ. มิซูโฮ คอร์ปอเรต จำกัด
TH_PROMPTPAY	PromptPay	พร้อมเพย์
TH_SCB	SIAM COMMERCIAL BANK PUBLIC COMPANY LTD	ธ. ไทยพาณิชย์ จำกัด (มหาชน)
TH_SCBT	STANDARD CHARTERED BANK (THAI) PUBLIC COMPANY LIMITED	ธ. สแตนดาร์ดชาร์เตอร์ด (ไทย) จำกัด (มหาชน)
TH_SMBC	SUMITOMO MITSUI BANKING CORPORATION	ธ. ซูมิโตโม มิตซุย แบงกิ้ง คอร์ปอเรชั่น
TH_TBANK	THANACHART BANK PUBLIC COMPANY LTD.	ธ. ธนชาต จำกัด (มหาชน)
TH_TCR	THE THAI CREDIT RETAIL BANK PUBLIC COMPANY LIMITED	ธ. ไทยเครดิต เพื่อรายย่อย จำกัด (มหาชน)
TH_TISCO	TISCO BANK PUBLIC COMPANY LIMITED	ธ. ทิสโก้ จำกัด (มหาชน)
TH_TMB	TMB BANK PUBLIC COMPANY LIMITED	ธ. ทหารไทย จำกัด (มหาชน)
TH_TTB	TMBTHANACHART BANK PUBLIC COMPANY LIMITED	ธ. ทหารไทยธนชาต จำกัด (มหาชน)
TH_UOBT	UNITED OVERSEAS BANK (THAI) PUBLIC COMPANY LIMITED	ธ. ยูโอบี จำกัด (มหาชน)