Text Overflow Fix

Developer's Guide

Integration Process
SUNRATE is committed to providing global enterprises with safe and efficient global payment and treasury management solutions.

This document is used to illustrate the standard API integration process to ensure your implementation project runs smoothly.

1. Read the Developer's Guide and API Documentation

Before confirming to integrate with SUNRATE API, we recommend that you read the Developer’s Guide and API Documentation to understand the product capabilities and workflow.

2. Talk with us about your business scenarios and requirements

Let us know about your business scenarios and requirements through your dedicated account manager at SUNRATE, or leave your enquiry via [Contact Us] page.

Our Product and Tech team will be happy to set up some time for solution consulting and project planning.

3. Test in the UAT environment

We will provide you with configuration document before setting up for testing. You will need to provide information such as your IP address (for whitelisting), public key, callback address, etc.

UAT configuration will be completed within 1~3 working days after we have received your response. You’ll then be able to start testing the in-scope APIs in the UAT environment.

4. Sign off before going live

Pre-launch testing will be necessary for us to move you into the Production environment.

5. Go live!
After projects are signed off, we will provide you with configuration document for production environment.
Once your production configuration is complete, feel free to make your first live API call!

Technical support will be available throughout your API integration journey with us, even after going live.

1. Security Solution
Randomly generate a 16-character string as an AES private key and encrypt operational parameters using AES encryption in base64 format. Place this under the requestBody parameter and exchange it for RSA public key. Use SUNRATE’s RSA public key to encrypt the AES private key encoded in base64 and place it under the ‘key’ parameter. Lastly, order all public messaging parameters in ascending order, and concatenate using key=value&key=value (excluding null values). Use your own RSA private key to encrypt in base64 and place the signature value under the ‘sign’ field.

Once you’ve received the response parameters, similarly, encrypt them as mentioned above, using the SUNRATE public key to authenticate and using the SUNRATE private key to decode and retrieve the AES private key. Use the AES private key to decode the operational parameters to retrieve the operational parameters.

Note: The RSA private key is 1024-bits.

1.1. Generate AES Private Key
Randomly generate 16-digit AES private key including alphanumeric values. See java sample code as follows:
String ramStr = RandomStringUtils.randomAlphanumeric(16);

1.2. Parameter Encryption
Encrypt AES parameters and encoded in base64. Place it in the request body. See java sample code as follows:

String dataEn = AesUtils.encrypt(data, ramStr);

public static String encrypt(String data, String key) {

byte[] iv = new byte[]{0x0, 0x1, 0x2, 0x3, 0x4, 0x5, 0x6, 0x7, 0x8, 0x9, 0xA, 0xB, 0xC, 0xD, 0xE, 0xF};

byte[] bytes = null;

try {

IvParameterSpec ivSpec = new IvParameterSpec(iv);

Key aKey = new SecretKeySpec(key.getBytes(Charset.forName("UTF-8")), "AES");

Cipher cipher = Cipher.getInstance("AES/CFB/NoPadding");

cipher.init(1, aKey, ivSpec);

bytes = cipher.doFinal(data.getBytes(Charset.forName("UTF-8")));

} catch (Exception e) {

e.printStackTrace();

}

return Base64.encodeBase64URLSafeString(bytes);

}

Vector Processing for non-Java languages，PHP Code Snippets：

// Encryption

base64_encode(openssl_encrypt($str ,'aes-128-cfb', $key, OPENSSL_NO_PADDING, base64_decode('AAECAwQFBgcICQoLDA0ODw==')));

// Decryption

openssl_decrypt(base64_decode($str) ,'aes-128-cfb', $key, OPENSSL_NO_PADDING, base64_decode('AAECAwQFBgcICQoLDA0ODw=='));

Python：

// List Format

[\x00,\x01,\x02,\x03,\x04,\x05,\x06,\x07,\x08,\x09,\x0A,\x0B,\x0C,\x0D,\x0E,\x0F]

// String Format

\x00\x01\x02\x03\x04\x05\x06\x07\x08\x09\x0A\x0B\x0C\x0D\x0E\x0F

1.3. Encrypt AES Key
Use SUNRATE’s RSA public key to encrypt the 16-digit private key and encode it in base64 format before placing it under the ‘key’ field.

1.4. Add Signature
Add a signature to the public messaging parameters. Remove the sign field from all non-empty parameters and order them alphabetically in ascending order, using the key=value&key=value format to generate a string, and use your own RSA private key to add a signature. (Signature algorithm: SHA256WithRSA), encode in base64 and place under the ‘sign’ field. See a sample of the resultant encrypted string as follows:

appId=11111111&ip=127.0.0.1&key=SEdqrTkhxiws3jRggqHSfnLNJqnnhv/6Sq3SvmdK7ROwT9UjSa1NAsoKTL1y6S/ yJ3lLikX31gkoNviZx/A6TlD9aEsQm/a5X3V+ZjrYyZ1iT2ovOoHGSeFYUafxH989JUq8G+WWzFtYlTraGSP/ jYAGwFuSrFUSMJElUbi2lHQ=&msgId=2018081845685246791352 &requestBody=NTRLbW1GNEFXajIxUGpPQ29BbVFUNXlCWVhhem1lSlFTT3BCZldXUVRRSTJtOWZHOXZW Tkw1c1Y0aWo2TTFsQVg0S0F3WkpnR3Zqd1owdlV1OElnc3dTWnN0T2ppTlBORE5qa053 &timestamp=2019-08-13 10:23:01.475&version=1.0

API Overview
1. Network Protocol

Type	Description
Network Protocol	HTTP
Request Method	POST
Data Format	application/json
Character Encoding	UTF-8

2. API List

Module	Name	Endpoint
Onboarding	Submit KYC	/openapi/v3/register/create/
	Receive KYC status update	Provided by client
	Update KYC	/openapi/v3/register/modify/
	Query KYC	/openapi/v3/register/get/
Virtual Accounts	Apply for a virtual account	/openapi/v3/globalCollectionAccount/create/
	Receive virtual account status update	Provided by client
	Update virtual account application	/openapi/v3/globalCollectionAccount/modify/
	Query virtual account	/openapi/v3/virtAcctApply/get/
	Query virtual accounts	/openapi/v3/virtAcctApply/list/
Collections	Receive fund arrival notice	Provided by client
	Receive collection status update	Provided by client
	Query collection details	/openapi/v3/transin/globalCollectionAccount/get/
	Query collections	/openapi/v3/transin/globalCollectionAccount/list/
Recipients	Create a recipient	/openapi/v3/beneficiary/create/
	Receive recipient status update	Provided by client
	Update recipient	/openapi/v3/beneficiary/modify/
	Query recipient	/openapi/v3/beneficiary/get/
	Query recipients	/openapi/v3/beneficiary/list/
Payouts	Query exchange rate	/openapi/v3/trade/queryPrice/
	Create a payout	/openapi/v3/trade/create/
	Create a payout without quote	/openapi/v3/trade/marketOrder/
	Receive payout status update	Provided by client
	Query payout	/openapi/v3/trade/get/
	Query payouts	/openapi/v3/trade/list/
	Download confirmation	/openapi/v3/voucher/transFile/download/
Trade	Get a quote	/openapi/v3/fxquote/getSingleQuote
	Create a trade	/openapi/v3/fxtxn/createFxTxn
	Get a rate	/openapi/v3/fxquote/getSingleRefQuote
	Create a trade without quote	/openapi/v3/fxtxn/marketFxTxn
	Settle a trade	/openapi/v3/fxtxn/dealFxTxn
	Query trade	/openapi/v3/fxtxn/getFxTxn
	Fund for trade	/openapi/v3/acctbal/trans
	Query balance for trade	/openapi/v3/acctbal/listAcctBal
Book Transfers	Create a transfer	/openapi/v3/ transfer/create/
	Query outward transfer	/openapi/v3/ transfer/get/
	Query outward transfers	/openapi/v3/ transfer/listOut/
	Query inward transfers	/openapi/v3/ transfer/listIn/
Reporting	Query balance	/openapi/v3/balance/list/
Reporting	Query statement	/openapi/v3/acctFlow/query/

2. Public Messaging Format

2.1. Access Method

All SUNRATE’s APIs operate based on the HTTP client-server protocol. All API calls can be made by sending form data using the POST method.

2.2. Parameter Label

Label	Description
M	Mandatory
O	Optional
C	Conditional

2.3. Data Format

All request and response are to be of JSON format, encoded in UTF-8, with the content type as application/json

2.4. IP Whitelisting

Both Test and Production environments adopts IP Whitelisting. Please make sure to provide static IP addresses for whitelisting during onboarding phase.

2.5. Public Request Headers

Parameter Name	Type	Max Length	Label	Details
appId	String	21	M	Unique identifier of a client assigned by Sunrate
msgId	String	21	M	The request message ID
bizId	String	21	O	Business ID
ip	String	15	M	User’s browser IP address.
version	String	5	M	Endpoint version. Fixed value “1.0”
callbackUrl	String	256	O
timestamp	String	23	M	Timestamp of request，formatted as "yyyy-MM-ddTHH:mm:ss.SSS" For example, 2008-08-08T08:08:08.888
key	String	16	M	Private key value of 16-digit AES after encryption. The 16-digit AES key is to be generated randomly by merchant.
sign	String		M	Signature value
requestBody	String		M	Encrypted request body. Note: format the request in JSON before encryption. No restriction on max. length

2.6. Public Response Parameters

Parameter Name	Type	Max Length	Label	Details
msgId	String	21	M	Serial number of response message.
code	String	6	M	Response code “000000” indicates a successful request.
msg	String	128	M	Response message
timestamp	String	23	M	Timestamp of response，formatted as "yyyy-MM-ddTHH:mm:ss.SSS" For example, 2008-08-08T08:08:08.888
key	String	16	M	Private key value of 16-digit AES after encryption
sign	String		M	Signature value
responseBody	String		M	Encrypted response body. Refer to response parameters.

API Documentation - Global Payments

Onboarding

This suite of APIs can be used to create a user account within SUNRATE and complete account verification to unlock the payment services SUNRATE provides.

1.1 Submit KYC（Client -> SUNRATE）

Endpoint：/openapi/v3/register/create/

1.1.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	outBizId	String	26	M	Unique registration identifier assigned by client
2.	registerName	String	60	M	Name of registrant
3.	registerEname	String	255	M	Name of registrant in English
4.	userAlias	Array		O	Alias of registrant
5.	registerEmail	String	60	M	Unique email address used for registration. Email address cannot be re-used
6.	registerMobile	String	30	M	Mobile number used for registration
7.	zoneNumber	String	6	O	Default to +86 if not provided
8.	registerType	String	1	M	Used to specify the type of onboarding entity 1：Individual 2：Business
9.	identityType	String	1	M	Used to specify the identity of registrant 1：Legal person 2：Authorised representative
10.	frontFilePath	String	255	C	Mandatory when registrant is authorised representative
11.	behindFilePath	String	255	C	Mandatory when registrant is authorised representative
12.	authFilePath	String	255	C	Mandatory when registrant is authorised representative
13.	remark	String	255	O
14.	companyInfo	JSON		C	Mandatory when type of onboarding entity is business
14.1.	companyName	String	varchar(128)		Business name
14.2.	companyNameEn	String	varchar(128)		Business name in English
14.3.	registerCountryCode	String	2	M	Country code of the country where the business is registered
14.4.	openAddress	String	varchar(255)	M	Business address
14.5.	openAddressEn	String	varchar(255)	M	Business address in English
14.6.	registerFilePath	String	varchar(255)	M	File path for certificate of incorporation
14.7.	registerExtraFilePath	String	varchar(255)	O	File path for any additional business documents
14.8.	payCur	String	255	M	Transaction currencies
14.9.	payMonthAmt	Number		M	Projected monthly volume in USD
14.10.	tradeType	String	1	M	Used to specify the type of business 1: Cross-border e-commerce 2: B2B export 3: Both 1 and 2 4: Logistics services 5: B2B import 6: Travel services 7: Content economy 8: Others (such as information services provider)
14.11.	legalInfoList	Array		O
14.11.1.	legalUserAlias	Array		M	Alias of legal person
14.11.2.	legalCarType	String	1	O	Used to specify the type of ID document 1: National ID 2: Passport
14.11.3.	legalFrontFilePath	String	varchar(255)	M	File path for front page of the ID document specified
14.11.4.	legalBehindFilePath	String	varchar(255)	O	File path for back page of the ID document specified
14.12.	shareholderInfoList	Array		O
14.12.1.	shareholderAlias	Array		M	Alias of shareholder
14.12.2.	shareholderCardType	String	1	O	Used to specify the type of ID document for shareholder 1: National ID 2: Passport
14.12.3.	shareholderFrontFilePath	String	varchar(255)	M	File path for front page of the ID document specified
14.12.4.	shareholderBehindFilePath	String	varchar(255)	O	File path for back page of the ID document specified

1.1.2 Response Parameters

No.	Parameter	Type	Length	Remarks
1.	registerId	String	30	Unique registration reference number assigned by SUNRATE
2.	outBizId	String	26	Unique registration identifier assigned by client
3.	acctId	String	8	Unique 8-digit user account identifier assigned by SUNRATE

1.2 Receive KYC status update（SUNRATE -> Client）

Endpoint：Provided by client

1.2.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	registerName	String	60	M	Name of the registrant
2.	registerEmail	String	60	M	Email address used for registration
3.	registerMobile	String	30	M	Mobile number used for registration
4.	registerStatus	String	1	M	Possible values: 1, 2 1：KYC is complete, account has been verified 2：KYC is incomplete, additional information is required
5.	remark	String	128	O
6.	checkRemark	String	128	C	Compliance review opinion when KYC is incomplete

1.2.2 Response Parameters

None.

1.3 Update KYC（Client -> SUNRATE）

Endpoint：/openapi/v3/register/modify/

1.3.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	outBizId	String	26	M	Unique registration identifier assigned by client
2.	registerName	String	varchar（60）	M	Name of registrant
3.	registerEname	String	varchar(255)	M	Name of registrant in English
4.	registerType	String	1	M	Used to specify the type of onboarding entity 1：Individual 2：Business
5.	identityType	String	1	M	Used to specify the identity of registrant 1：Legal person 2：Authorised representative
6.	remark	String	varchar （255）	O
7.	companyInfo	JSON		C	Mandatory when type of onboarding entity is business
7.1.	companyName	String	varchar(128)	M	Business name
7.2.	companyNameEn	String	varchar(128)	M	Business name in English
7.3.	registerCountryCode	String	2	M	Country code of the country where the business is registered
7.4.	openAddress	String	varchar(255)	M	Business address
7.5.	openAddressEn	String	varchar(255)	M	Business address in English
7.6.	registerFilePath	String	varchar(255)	M	File path for certificate of incorporation
7.7.	registerExtraFilePath	String	varchar(255)	O	File path for any additional business documents
8.	legalInfoList	Array		O
8.1.	legalUserAlias	Array		M	Alias of legal person
8.2.	legalCarType	String	1	O	Used to specify the type of ID document for legal person 1: National ID 2: Passport
8.3.	legalFrontFilePath	String	varchar(255)	M	File path of front page of the ID document specified
8.4.	legalBehindFilePath	String	varchar(255)	O	File path for back page of the ID document specified
9.	shareHolderInfoList	Array		O
9.1.	shareholderAlias	Array		M	Alias of shareholder
9.2.	shareholderCardType	String	1	O	Used to specify the type of ID document for shareholder 1: National ID 2: Passport
9.3.	shareholderFrontFilePath	String	varchar(255)	M	File path for front page of the ID document specified
9.4.	shareholderBehindFilePath	String	varchar(255)	O	File path for back page of the ID document specified

1.3.2 Response Parameters

No.	Parameter	Type	Length	Remarks
1.	outBizId	String	26	Unique registration identifier assigned by client
2.	acctId	String	8	Unique 8-digit user account identifier assigned by SUNRATE

1.4 Query KYC（Client -> SUNRATE）

Endpoint：/openapi/v3/register/get/

1.4.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	outBizId	String	26	M	Unique registration identifier assigned by client

1.4.2 Response Parameters

No.	Parameter	Type	Length	Remarks
1.	outBizId	String	26	Unique registration identifier assigned by client
2.	acctId	String	8	Unique 8-digit user account identifier assigned by SUNRATE
3.	registerName	String	60	Name of registrant
4.	registerEname	String	255	Name of registrant in English
5.	registerMobile	String	30	Mobile number used for registration
6.	zoneNumber	String	6	International dialing code of the mobile number
7.	registerType	String	1	Possible values: 0, 1 1：Individual 2：Business
8.	identityType	String	1	Possible values: 0, 1 1：Legal person 2：Authorised representative
9.	remark	String	255
10.	status	String	1	Possible values: 0, 1 0：KYC is being reviewed 1：KYC is complete, account has been verified
11.	companyInfo	JSON
11.1.	companyName	String	varchar(128)	Business name
11.2.	companyNameEn	String	varchar(128)	Business name in English
11.3.	registerCountryCode	String	2	Country code of the country where business is registered
11.4.	openAddress	String	varchar(255)	Business address
11.5.	openAddressEn	String	varchar(255)	Business address in English
12.	legalInfoList	Array
12.1.	legalUserAlias	Array		Alias of legal person
12.2.	legalCarType	String	1	Possible values: 1, 2 1: National ID 2: Passport
13.	shareHolderInfoList	Array
13.1.	shareholderAlias	Array		Alias of shareholder
13.2.	shareholderCardType	String	1	Possible values: 1, 2 1: National ID 2: Passport

Collections

Receive real-time notification for inward transactions sent into virtual accounts, and retrieve transaction details.

1.5 Receive fund arrival notice（SUNRATE -> Client）

Endpoint: Provided by client

1.5.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	transinNoticeId	String	10	M	Unique inward transaction identifier assigned by SUNRATE
2.	orgCode	String	18	M	Business registration number of client
3.	acctId	String	8	M	Unique 8-digit user account identifier assigned by client
4.	bankCardNo	String	50	M	Virtual account number
5.	sendAccountName	String	50	M	Sender name
6.	transinCur	String	3	M	Currency of fund received
7.	transinAmt	Number	15,2	M	Amount of fund received
8.	availableAmt	Number	15,2	M	New available amount on the user account, equal to the amount of fund received
9.	sysTxnDate	String	10	M	Date when fund is received
10.	noticeStat	String	1	M	Possible values: 2, 3 2: Supporting documents are required for the funds to be credited into the user account 3: Funds have been credited to the user account since the sender has been verified and whitelisted
11.	remark	String	100	O

1.5.2 Response Parameters

None

1.6 Receive collection status update（SUNRATE -> Client）

Endpoint: Provided by client

1.6.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	transinNoticeId	String	10	M	Unique inward transaction identifier assigned by SUNRATE
2.	orgCode	String	18	M	Business registration number of client
3.	acctId	String	8	M	Unique 8-digit user account identifier assigned by SUNRATE
4.	noticeStat	String	1	M	Possible values: 2, 3 2: Supporting documents are required for the funds to be credited into the user account 3: Funds have been credited to the user account since the sender has been verified and whitelisted
5.	transinFileStatus	String	1	M	Possible values: 1, 2 1: Supporting documents are sufficient, noticeStat will be 3 when transinFileStatus is 1 2: Supporting documents are insufficient, noticeStat will be 2 when transinFileStatus is 2
6.	transinFileRemark	String	255	M	transinFileRemark will be compliance review opinion when transinFileStatus is 2

1.6.2 Response Parameters

None

1.7 Query collection details（Client -> SUNRATE）

Endpoint：/openapi/v3/transin/globalCollectionAccount/get/

1.7.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	transinNoticeId	String	10	M	Unique inward transaction identifier assigned by SUNRATE

1.7.2 Response Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	acctId	String	8	M	Unique 8-digit user account identifier assigned by SUNRATE
2.	transinNoticeId	String	10	M	Unique inward transaction identifier assigned by SUNRATE
3.	bankCardNo	String	50	M	Virtual account number
4.	sendAccountName	String	50	M	Sender name
5.	transinCur	String	3	M	Currency of fund received
6.	transinAmt	Number	15,2	M	Amount of fund received
7.	availableAmt	Number	15,2	M	New available amount on the user account, equal to the amount of fund received
8.	feeAmt	Number	15,2	O	Amount of processing fees charged by SUNRATE for the inward transaction
9.	transinDate	String	10	M	Date when fund is received
10.	transinFileStatus	String	1	M	Used to specify the status of supporting documents. Possible values: 0, 1, 2, 3, 9 0: Supporting documents have been submitted 1: Supporting documents are sufficient for the funds to be credited into the user account 2: Supporting documents are insufficient and have to be supplemented 3: Supporting documents are under review 9: Supporting documents have not been provided
11.	status	String	1	M	Used to specify the status of the inward transaction. Possible values: 0, 1, 2, 3, 9 0：Inward transaction has been reported 1：Inward transaction is under review 2：Inward transaction has been reviewed 3：Inward transaction has been approved, fund has been credited into the user account 9：Inward transaction is on-hold, additional supporting documents are required
12.	remark	String	100	O

1.8 Query collections（Client -> SUNRATE）

Endpoint：/openapi/v3/transin/globalCollectionAccount/list/

1.8.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	startDate	Date		M	Date after which fund is received
2.	endDate	Date		M	Date before which fund is received
3.	pageNum	Number	500	M	Count of pages, default to 1 if not provided
4.	pageSize	Number	100	M	Count of records per page. Ranges from 1 to 100. Default to 20 if not provided
5.	cur	String	3	C	Currency code for currency of fund received

1.8.2 Response Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	acctId	String	8	M	Unique 8-digit user account identifier assigned by SUNRATE
2.	totalRecordNum	Number	-	M	Count of total records queried
3.	currentPageNum	Number	500	M	Page number of current page
4.	currentPageSize	Number	100	M	Count of records of current page
5.	list	Array		M
5.1.	transinNoticeId	String	10	M	Unique inward transaction identifier assigned by SUNRATE
5.2.	bankCardNo	String	50	M	Virtual account number
5.3.	sendAccountName	String	50	M	Sender name
5.4.	transinCur	String	3	M	Currency of fund received
5.5.	transinAmt	Number	15,2	M	Amount of fund received
5.6.	availableAmt	Number	15,2	M	New available amount on the user account, equal to the amount of fund received
5.7.	feeAmt	Number	15,2	O	Amount of processing fees charged by SUNRAET for the inward transaction
5.8.	transinDate	String	10	M	Date when fund is received
5.9.	transinFileStatus	String	1	M	Used to specify the status of supporting documents. Possible values: 0, 1, 2, 3, 9 0: Submitted 1: Passed 2: Rejected 3: Under review 9: Not provided
5.10.	status	String	1	M	Used to specify the status of the inward transaction. Possible values: 0, 1, 2, 3, 9 0：Pending 1：Under review 2：Passed 3：Approved 9：Rejected
5.11.	remark	String	100	O

Recipient

This suite of APIs can be used to add, modify and retrieve recipients used in payouts. Once a recipient has been approved by SUNRATE, it cannot be modified, and a payout to this recipient can be initiated.

1.9 Create a recipient（Client -> SUNRATE）

Endpoint：/openapi/v3/beneficiary/create/

1.9.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	countryCode	String	2	M	Country code for country where recipient’s bank is located
2.	bankName	String	128	M	Full name of recipient’s bank, include branch when possible
3.	routeType	String	1	M	Used to specify the necessary recipient’s account information for a payment to be delivered to recipient 1: ABA 2: IBAN 3: SWIFT Code
4.	aba	String	9	C	9-digit ACH routing number, mandatory when routeType is 1
5.	iban	String	34	C	IBAN, mandatory when routeType is 2
6.	swiftcode	String	8、11	C	SWIFT Code, mandatory when routeType is 3
7.	beneficiaryName	String	28	M	Recipient’s full bank account name
8.	beneficiaryAcctNo	String	60	M	Recipient’s bank account number, equal to IBAN when routeType is 2
9.	beneficiaryCountryCode	String	2	M	Country code for country where recipient is registered
10.	cur	String	3	M	Currency code for currency of recipient’s bank account
11.	beneficiaryType	String	1	M	Used to specify type of recipient 0：Own bank accounts 1：Third-party bank accounts
12.	beneficiaryEntityType	String	1	O	Used to specify type of recipient’s bank account 1：Business bank account
13.	beneficiaryAddr	String	55	M	Recipient’s business address or residential address
14.	intermediarySwiftBic	String	8、11	O	Intermediary bank Swift Code
15.	remark	String	255	O

1.9.2 Response Parameters

No.	Parameter	Type	Length	Remarks
1.	beneficiaryId	String	10	Unique recipient identifier assigned by SUNRATE
2.	acctId	String	8	Unique 8-digit user account identifier assigned by SUNRATE
3.	beneficiaryStatus	String	1	Status of recipient, only when beneficiaryStatus is 2, can a payout to recipient be created. Possible values: 0, 1, 2 0：Recipient has been submitted and will be reviewed 1：Recipient has been approved 2：Recipient has been denied, additional information might be required
4.	countryCode	String	2	Country code for country where recipient’s bank is located
5.	bankName	String	128	Full name of recipient’s bank
6.	routeType	String	1	Used to specify the necessary recipient’s account information for a payment to be delivered to recipient 1: ABA 2: IBAN 3: SWIFT Code
7.	aba	String	9	9-digit ACH routing number, mandatory when routeType is 1
8.	iban	String	34	IBAN, mandatory when routeType is 2
9.	swiftcode	String	8、11	SWIFT Code, mandatory when routeType is 3
10.	beneficiaryName	String	28	Recipient’s full bank account name
11.	beneficiaryAcctNo	String	60	Recipient’s bank account number, equal to IBAN when routeType is 2
12.	beneficiaryCountryCode	String	2	Country code for country where recipient is registered
13.	cur	String	3	Currency code for currency of recipient’s bank account
14.	beneficiaryType	String	1	Used to specify type of recipient 0：Own bank accounts 1：Third-party bank accounts
15.	beneficiaryEntityType	String	1	Used to specify type of recipient’s bank account 1：Business bank account
16.	beneficiaryAddr	String	55	Recipient’s business address or residential address
17.	intermediarySwiftBic	String	8、11	Intermediary bank Swift Code
18.	remark	String	255

1.10 Receive recipient status update（SUNRATE -> Client）

Endpoint: Provided by client

1.10.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	beneficiaryId	String	10	M	Unique recipient identifier assigned by SUNRATE
2.	orgCode	String	18	M	Business registration number of client
3.	acctId	String	8	M	Unique 8-digit user account identifier assigned by SUNRATE
4.	beneficiaryStatus	String	1	M	Status of recipient. Possible values: 1, 2 1：Recipient has been approved 2：Recipient has been denied, additional information might be required
5.	remark	String	varchar（100）	C	Reason for denial when beneficiaryStatus is 2

1.10.2 Response Parameters

None

1.11 Update recipient（Client -> SUNRATE)

Endpoint：/openapi/v3/beneficiary/modify/

1.11.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	beneficiaryId	String	char（10）	M	Unique recipient identifier assigned by SUNRATE
2.	countryCode	String	2	M	Country code for country where recipient’s bank is located
3.	bankName	String	128	M	Recipient’s bank name
4.	routeType	String	1	M	Used to specify the necessary recipient’s account information for a payment to be delivered to recipient 1: ABA 2: IBAN 3: SWIFT Code
5.	aba	String	9	C	9-digit ACH routing number, mandatory when routeType is 1
6.	iban	String	34	C	IBAN, mandatory when routeType is 2
7.	swiftcode	String	8、11	C	SWIFT code, mandatory when routeType is 3
8.	beneficiaryName	String	28	M	Recipient’s full bank account name
9.	beneficiaryAcctNo	String	60	M	Recipient’s bank account number, equal to IBAN when routeType is 2
10.	beneficiaryCountryCode	String	2	M	Country code for country where recipient is registered
11.	cur	String	3	M	Currency code for currency of recipient’s bank account
12.	beneficiaryType	String	1	M	Used to specify type of recipient 0：Own bank accounts 1：Third-party bank accounts
13.	beneficiaryEntityType	String	1	O	Used to specify type of recipient’s bank account 1：Business bank account
14.	beneficiaryAddr	String	55	M	Recipient’s business address or residential address
15.	intermediarySwiftBic	String	8、11	O	Intermediary bank Swift Code
16.	remark	String	255	O

1.11.2 Response Parameters

No.	Parameter	Type	Length	Remarks
1.	beneficiaryId	String	10	Unique recipient identifier assigned by SUNRATE
2.	acctId	String	8	Unique 8-digit user account identifier assigned by SUNRATE
3.	beneficiaryStatus	String	1	Status of recipient. Possible values: 0, 1, 2 0: Recipient has been submitted, and will be reviewed 1：Recipient has been approved 2：Recipient has been denied, additional information might be required
4.	countryCode	String	2	Country code for country where recipient’s bank is located
5.	bankName	String	128	Recipient’s bank name
6.	routeType	String	1	Used to specify the necessary recipient’s account information for a payment to be delivered to recipient 1: ABA 2: IBAN 3: SWIFT Code
7.	aba	String	9	9-digit ACH routing number
8.	iban	String	34	IBAN
9.	swiftcode	String	8、11	SWIFT Code
10.	beneficiaryName	String	28	Recipient’s bank account name
11.	beneficiaryAcctNo	String	60	Recipient’s bank account number
12.	beneficiaryCountryCode	String	2	Country code for country where recipient is registered
13.	cur	String	3	Currency code for currency of recipient’s bank account
14.	beneficiaryType	String	1	Used to specify type of recipient 0：Own bank accounts 1：Third-party bank accounts
15.	beneficiaryEntityType	String	1	Used to specify type of recipient’s bank account 1：Business bank account
16.	beneficiaryAddr	String	55	Recipient’s business address or residential address
17.	intermediarySwiftBic	String	8、11	Intermediary bank Swift Code
18.	remark	String	255

1.12 Query recipient（Client -> SUNRATE）

Endpoint: /openapi/v3/beneficiary/get/

1.12.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	beneficiaryId	String	10	M	Unique recipient identifier assigned by SUNRATE

1.12.2 Response Parameters

No.	Parameter	Type	Length	Remarks
1.	beneficiaryId	String	char（10）	Unique recipient identifier assigned by SUNRATE
2.	beneficiaryStatus	String	1	Status of recipient, only when beneficiaryStatus is 2, can a payout to recipient be created. Possible values: 0, 1, 2 0：Recipient has been submitted and will be reviewed 1：Recipient has been approved 2：Recipient has been denied, additional information might be required
3.	orgCode	String	18	Business registration number of client
4.	acctId	String	8	Unique 8-digit user account identifier assigned by SUNRATE
5.	countryCode	String	2	Country code for country where recipient’s bank is located
6.	bankName	String	varchar（128）	Full name of recipient’s bank
7.	routeType	String	1	Used to specify the necessary recipient’s account information for a payment to be delivered to recipient 1: ABA 2: IBAN 3: SWIFT Code
8.	aba	String	9	9-digit ACH routing number
9.	iban	String	varchar （34）	IBAN
10.	swiftcode	String	8、11	SWIFT code
11.	beneficiaryName	String	varchar（128）	Recipient’s bank account name
12.	beneficiaryAcctNo	String	varchar（60）	Recipient’s bank account number
13.	cur	String	3	Currency code for currency of recipient’s bank account
14.	beneficiaryAddr	String	varchar（255）	Recipient’s business address or residential address
15.	remark	String	varchar（255）

1.13 Query recipients（Client -> SUNRATE）

Endpoint: /openapi/v3/beneficiary/list/

1.13.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	pageNum	Number	500	M	Count of pages, default to 1 if not provided
2.	pageSize	Number	100	M	Count of records per page. Ranges from 1 to 100. Default to 20 if not provided

1.13.2 Response Parameters

No.	Parameter	Type	Length	Remarks
1.	acctId	String	8	Unique 8-digit user account identifier assigned by SUNRATE
2.	totalRecordNum	Number	-	Count of total records queried
3.	currentPageNum	Number	500	Page number of current page
4.	currentPageSize	Number	100	Count of records of current page
5.	list	Array
5.1.	beneficiaryId	String	10	Unique recipient identifier assigned by SUNRATE
5.2.	beneficiaryStatus	String	1	Status of recipient, only when beneficiaryStatus is 2, can a payout to recipient be created. Possible values: 0, 1, 2 0：Recipient has been submitted and will be reviewed 1：Recipient has been approved 2：Recipient has been denied, additional information might be required
5.3.	countryCode	String	2	Country code for country where recipient’s bank is located
5.4.	routeType	String	1	Used to specify the necessary recipient’s account information for a payment to be delivered to recipient 1: ABA 2: IBAN 3: SWIFT Code
5.5.	aba	String	9	9-digit ACH routing number
5.6.	iban	String	34	IBAN
5.7.	swiftcode	String	11	SWIFT code
5.8.	beneficiaryName	String	128	Recipient’s bank account name
5.9.	beneficiaryAcctNo	String	60	Recipient’s bank account number
5.10.	beneficiaryAddr	String	255	Recipient’s business address or residential address
5.11.	cur	String	3	Currency code for currency of recipient’s bank account
5.12.	beneficiaryRejectRemark	String	255	Reason for recipient denial when beneficiaryStatus is 2
5.13.	intermediarySwiftBic	String	11	Intermediary bank for recipient’s bank
5.14.	beneficiaryType	String	1	Used to specify type of recipient 0：Recipient’s bank account holder is client themselves 1：Recipient’s bank account holder is not client themselves

Payouts

This suite of APIs can be used to initiate payments to bank accounts with SUNRATE’s global payment network, and to obtain real-time transaction status.

1.14 Query exchange rate（Client -> SUNRATE）

Endpoint：/openapi/v3/trade/queryPrice/

1.14.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	queryNo	String	26	M	Unique query identifier assigned by client
2.	buyCur	String	3	M	Currency to be purchased
3.	sellCur	String	3	M	Currency to be sold
4.	txnMode	String	1	M	Used to specify currency for txnAmt 0：txnAmt is based on currency to be purchased 1：txnAmt is based on currency to be sold
5.	txnAmt	Number	15,2	M	Amount to be purchased when txnMode is 0, amount to be sold when txnMode is 1
6.	tradeType	String	1	C	Used to specify type of transaction, must be 0 if beneficiaryType is 0, must be 1 if beneficiaryType is 1, default to 0 if not provided 0：Payout to third=party recipient 1：FX and payout to client’s own account
7.	feeType	String	3	C	Used to specify the bearer of bank charges, default to SHA if not provided OUR: bank charges will be borne by client SHA: bank charges will be borne by client and recipient

1.14.2 Response Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	queryNo	String	26	M	Unique query identifier assigned by client
2.	orgCode	String	9	M	Business registration number of client
3.	acctId	String	8	M	Unique 8-digit user account identifier assigned by SUNRATE
4.	buyCur	String	3	M	Currency to be purchased
5.	buyAmt	Number	15,2	M	Amount to be purchased
6.	sellCur	String	3	M	Currency to be sold
7.	sellAmt	Number	15,2	M	Amount to be sold
8.	feeCur	String	3	M	Currency of processing fee
9.	feeAmt	Number	15,2	M	Amount of processing fee
10.	payAmt	Number	15,2	M	Total amount to be deducted from user account
11.	txnMode	String	1	M	Possible values: 0,1 0：txnAmt is based on currency to be sent 1：txnAmt is based on currency to be sold
12.	queryRate	Number	9,4	M	Exchange rate for the currency pair
13.	tradeType	String	1	C	Possible values: 0, 1 0：Payout to third=party recipient 1：FX and payout to client’s own account

1.15 Create a payout（Client -> SUNRATE）

Endpoint：/openapi/v3/trade/create/

1.15.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	lockNo	String	26	M	Unique payout identifier assigned by client
2.	queryNo	String	26	M	Unique query identifier assigned by client
3.	buyCur	String	3	M	Currency to be purchased
4.	buyAmt	Number	15,2	M	Amount to be purchased
5.	sellCur	String	3	M	Currency to be sold
6.	sellAmt	Number	15,2	M	Amount to be sold
7.	feeAmt	Number	15,2	M	Amount of processing fee
8.	payAmt	Number	15,2	M	Total amount to be deducted from user account
9.	txnMode	String	1	M	Used to specify the currency for txnAmt 0：txnAmt is based on currency to be purchased 1：txnAmt is based on currency to be sold
10.	queryRate	Number	9,4	M	Exchange rate for the currency pair, obtained from Query exchange rate
11.	valueDate	String	10	C	Format: YYYY-MM-DD
12.	beneficiaryId	String	10	M	Unique recipient identifier assigned by SUNRATE
13.	oboId	String	20	C	Unique obo identifier assigned by SUNRATE, contact SUNRATE for details
14.	remark	String	Varchar(100)	O	Remittance information

1.15.2 Response Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	txnNo	String	10	M	Unique payout identifier assigned by SUNRATE
2.	lockNo	String	26	M	Unique payout identifier assigned by client
3.	queryNo	String	26	M	Unique query identifier assigned by client
4.	orgCode	String	18	M	Business registration number of client
5.	acctId	String	8	M	Unique 8-digit user account identifier assigned by SUNRATE
6.	buyCur	String	3	M	Currency to be purchased
7.	sellCur	String	3	M	Currency to be sold
8.	buyAmt	Number	15,2	M	Amount to be purchased
9.	sellAmt	Number	15,2	M	Amount to be sold
10.	feeCur	String	3	M	Currency of processing fee
11.	feeAmt	Number	15,2	M	Amount of processing fee
12.	payAmt	Number	15,2	M	Total amount to be deducted from user account
13.	txnMode	String	1	M	Possible values: 0, 1 0：txnAmt is based on currency to be purchased 1：txnAmt is based on currency to be sold
14.	finRate	Number	9,4	M	Exchange rate for transaction
15.	oboId	String	20	C	Unique obo identifier assigned by SUNRATE
16.	remark	String	varchar(100)	M	Remittance information
17.	txnStatus	String	2	M	Used to specify status of payout, possible values: 03, 09 03：User account has sufficient balance for payout 09：Payout has been processed by SUNRATE

1.16 Create a payout without quote（Client -> SUNRATE）

Endpoint：/openapi/v3/trade/marketOrder/

1.16.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	lockNo	String	26	M	Unique payout identifier assigned by client
2.	buyCur	String	3	M	Currency to be purchased
3.	sellCur	String	3	M	Currency to be sold
4.	txnMode	String	1	M	Used to specify the currency for txnAmt 0：txnAmt is based on currency to be purchased 1：txnAmt is based on currency to be sold
5.	txnAmt	Number	15,2	M	Amount to be purchased when txnMode is 0, amount to be sold when txnMode is 1
6.	valueDate	String	10	C	Format: YYYY-MM-DD, only T, T+1, T+2 can be accepted
7.	beneficiaryId	String	10	M	Unique recipient identifier assigned by SUNRATE
8.	remark	String	varchar(100)	O	Remittance information
9.	tradeType	String	1	C	Used to specify type of transaction, must be 0 if beneficiaryType is 0, must be 1 if beneficiaryType is 1, default to 0 if not provided 0：Payout to third=party recipient 1：FX and payout to client’s own account
10.	feeType	String	3	C	Used to specify the bearer of bank charges, default to SHA if not provided OUR: bank charges will be borne by client SHA: bank charges will be shared by client and recipient

1.16.2 Response Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	txnNo	String	10	M	Unique payout identifier assigned by SUNRATE
2.	lockNo	String	26	M	Unique payout identifier assigned by client
3.	orgCode	String	9	M	Business registration number of client
4.	acctId	String	8	M	Unique 8-digit user account identifier assigned by SUNRATE
5.	buyCur	String	3	M	Currency to be purchased
6.	buyAmt	Number	15,2	M	Amount to be purchased
7.	sellCur	String	3	M	Currency to be purchased
8.	sellAmt	Number	15,2	M	Amount to be purchased
9.	txnMode	String	1	M	Possible values: 0, 1 0：txnAmt is based on currency to be purchased 1：txnAmt is based on currency to be sold
10.	finRate	Number	9,4	M	Exchange rate for transaction
11.	feeCur	String	3	M	Currency of processing fee
12.	feeAmt	Number	15,2	M	Amount of processing fee
13.	payAmt	Number	15,2	M	Total mount to be deducted from user account
11.	remark	String	varchar(100)	O	Remittance information
14.	txnStatus	String	2	M	Used to specify status of payout, possible values: 03, 09 03：User account has sufficient balance for payout 09：Payout has been processed by SUNRATE

1.17 Receive payout status update（SUNRATE -> Client）

Endpoint: Provided by client

1.17.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	payoutNoticeId	String	26	M	Unique payout notification identifier assigned by SUNRATE
2.	lockNo	String	26	M	Unique payout identifier assigned by client
3.	txnNo	String	10	M	Unique payout identifier assigned by SUNRATE
4.	orgCode	String	18	M	Business registration number of client
5.	acctId	String	8	M	Unique user account identifier assigned by SUNRATE
6.	beneficiaryId	String	varchar（20）	M	Unique recipient identifier assigned by SUNRATE
7.	beneficiaryName	String	varchar（100）	M	Recipient’s full bank account name
8.	beneficiaryAcctNo	String	varchar（30）	M	Recipient’s bank account number
9.	payCur	String	3	M	Currency to be sent
10.	payAmt	Number	15,2	M	Amount to be sent
11.	payStatus	String	1	M	Used to specify status of payer, possible values: 1, 9, 8 9：Payout has not been processed 8：Payout is being processed 1：Payout has been processed by SUNRATE
12.	remark	String	100	O

1.17.2 Response Parameters

None

1.18 Query payout（Client -> SUNRATE）

Endpoint：/openapi/v3/trade/get/

1.18.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	lockNo	String	26	M	Unique payout identifier assigned by client

1.18.2 Response Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	txnNo	String	10	M	Unique payout identifier assigned by SUNRATE
2.	lockNo	String	26	M	Unique payout identifier assigned by client
3.	buyCur	String	3	M	Currency to be purchased
4.	sellCur	String	3	M	Currency to be sold
5.	buyAmt	Number	15,2	M	Amount to be purchased
6.	sellAmt	Number	15,2	M	Amount to be sold
7.	feeAmt	Number	15,2	M	Amount of processing fee
8.	payAmt	Number	15,2	M	Total amount to be deducted from user account
9.	txnMode	String	1	M	Possible values: 0, 1 0：txnAmt is based on currency to be purchased 1：txnAmt is based on currency to be sold
10.	finRate	Number	9,4	M	Exchange rate for transaction
11.	txnDate	String	10	M	Date set for transaction, format: YYYY-MM-DD
12.	remark	String	varchar(100)	O	Remittance information
13.	txnStatus	String	2	M	Used to specify status of payout, possible values: 03, 04, 05, 09, 20 03：User account has sufficient balance for payout 04, 05：Transaction is being processed 09：Payout has been processed by SUNRATE 20：Transaction has been canceled by client

1.19 Query payouts（Client -> SUNRATE）

Endpoint：/openapi/v3/trade/list/

1.19.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	startDate	Date		M	Date after which payout is created
2.	endDate	Date		M	Date before which payout is created
3.	pageNum	Number	500	M	Count of pages, default to 1 if not provided
4.	pageSize	Number	100	M	Count of records per page. Ranges from 1 to 100. Default to 20 if not provided

1.19.2 Response Parameters

No.	Parameter	Type	Length	Remarks
1.	acctId	String	8	Unique 8-digit user account identifier assigned by SUNRATE
2.	totalRecordNum	Number	-	Count of total records queried
3.	currentPageNum	Number	500	Page number of current page
4.	currentPageSize	Number	100	Count of records of current page
5.	list	Array
5.1.	txnNo	String	10	Unique payout identifier assigned by SUNRATE
5.2.	lockNo	String	26	Unique payout identifier assigned by client
5.3.	buyCur	String	3	Currency to be purchased
5.4.	buyAmt	Price	20	Amount to be purchased
5.5.	sellCur	String	3	Currency to be sold
5.6.	sellAmt	Price	20	Amount to be sold
5.7.	feeCur	String	3	Currency of processing fee
5.8.	feeAmt	Price	20	Amount of processing fee
5.9.	payAmt	Price	20	Amount to be sent
5.10.	txnMode	String	1	Possible values: 0, 1 0：txnAmt is based on currency to be purchased 1：txnAmt is based on currency to be sold
5.11.	finRate	Price	20	Exchange rate for transaction
5.12.	txnStatus	String	2	Used to specify status of payout, possible values: 03, 04, 05, 09, 20 03：User account has sufficient balance for payout 04, 05：Transaction is being processed 09：Payout has been processed by SUNRATE 20：Transaction has been canceled by client
5.13.	oboId	String	21	Unique obo identifier assigned by SUNRATE
5.14.	oboName	String	128	Obo name
5.15.	oboCountryCode	String	2	Country code for country where obo is registered
5.16.	oboAddress	String	70	Business address of obo
5.17.	beneficiaryId	String	10	Unique recipient identifier assigned by SUNRATE

1.20 Download confirmation（Client -> SUNRATE）

Endpoint：/openapi/v3/voucher/transFile/download/

1.20.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	txnNo	String	10	M	Unique payout identifier assigned by SUNRATE
2.	lockNo	String	26	M	Unique payout identifier assigned by client
3.	voucherType	String	1	M	Used to specify type of confirmation, must be 1
4.	subType	String	1	M	Used to specify use of confirmation, must be 1

1.20.2 Response Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	orgCode	String	18	M	Business registration number of client
2.	acctId	String	8	M	Unique 8-digit user account identifier assigned by SUNRATE
3.	lockNo	String	26	M	Unique payout identifier assigned by SUNRATE
4.	txnNo	String	10	M	Unique payout identifier assigned by SUNRATE
5.	filePath	String	128	M	Path for document

Trade

This suite of APIs can be used to book FX spot contracts within SUNRATE’s FX Management solutions and to manage the execution of the contracts.

1.21 Get a quote (Client -> SUNRATE)

Endpoint：/openapi/v3/fxquote/getSingleQuoted

1.21.1 Request Parameters

No	Parameter	Type	Length	Required/Optional	Remarks
1.	buyCur	String	3	M	Currency to be purchased
2.	buyAmt	BigDecimal(15,2)		M	Amount to be purchased. Either buyAmt or sellAmt is mandatory
3.	sellCur	String	3	M	Currency to be sold
4.	sellAmt	BigDecimal(15,2)		M	Amount to be sold. Either buyAmt or sellAmt is mandatory
5.	valueDate	String		O	Format: YYYY-MM-DD. Will be the date the request is made if not provided

1.21.2 Response Parameters

No	Parameter	Type	Length	Remarks
1.	prdId	String	6	Currency pair based on market convention
2.	quoteId	String	22	Unique quote identifier assigned by SUNRATE
3.	custRate	String		Exchange rate for the currency pair
4.	tenor	Integer		Count of days between value date and date the request is made
5.	buyCur	String	3	Currency to be purchased
6.	buyAmt	BigDecimal(15,2)		Amount to be purchased
7.	sellCur	String	3	Currency to be sold
8.	sellAmt	BigDecimal(15,2)		Amount to be sold
9.	validTill	String		Time when the quote is expired. Format: YYYY-MM-DDTHH:mm:ss.SSS
10.	valueDate	String		Format: YYYY-MM-DD

1.22 Create a trade（Client -> SUNRATE）

Endpoint：/openapi/v3/fxtxn/createFxTxn

1.22.1 Request Parameters

No.

Parameter

Type

Length

Required/Optional

Remarks

outRefNo

String

Varchar（64）

Unique transaction identifier assigned by client

quoteId

String

Unique quote

identifier assigned by SUNRATE obtained from Get a quote API

1.22.2 Response Parameters

No.	Parameter	Type	Length	Remarks
1.	txnId	String	22	Unique transaction identifier assigned by SUNRATE
2.	prdId	String	6	Currency pair based on market convention
3.	buyCur	String	3	Currency to be purchased
4.	buyAmt	BigDecimal(15,2)		Amount to be purchased
5.	sellCur	String	3	Currency to be sold
6.	sellAmt	BigDecimal(15,2)		Amount to be sold
7.	custRate	String		Exchange rate for the currency pair
8.	txnMode	String	1	Possible values: 0, 1 0：Transaction amount is based on the amount of purchasing currency 1：Transaction amount is based on the amount of selling currency
9.	valueDate	String		Format: YYYY-MM-DD
10.	txnDate	String		Format: YYYY-MM-DD

1.23 Get a rate（Client->SUNRATE）

Endpoint：/openapi/v3/fxquote/getSingleRefQuote

1.23.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	buyCur	String		M	Currency to be purchased
2.	sellCur	String		M	Currency to be sold
3.	valueDate	String		O	Format: YYYY-MM-DD. Will be the date the request is made if not provided

1.23.2 Response Parameters

No.	Parameter	Type	Length	Remarks
1.	prdId	String	6	Currency pair based on market convention
2.	custRate	String		Exchange rate for the currency pair
3.	tenor	Integer		Count of days between value date and date the request is made
4.	buyCur	String	3	Currency to be purchased
5.	sellCur	String	3	Currency to be sold

1.24 Create a trade without quote（Client -> SUNRATE）

Endpoint：/openapi/v3/fxtxn/marketFxTxn

1.24.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	outRefNo	String	Varchar（64）	M	Unique transaction identifier assigned by client
2.	buyCur	String		M	Currency to be purchased
3.	buyAmt	BigDecimal(15,2)	3	M	Amount to be purchased. Either buyAmt or sellAmt is mandatory
4.	sellCur	String		M	Currency to be sold
5.	sellAmt	BigDecimal(15,2)	3	M	Amount to be sold. Either buyAmt or sellAmt is mandatory
6.	valueDate	String		O	Format: YYYY-MM-DD. Will be the date the request is made if not provided

1.24.2 Response Parameters

No.	Parameter	Type	Length	Remarks
1.	txnId	String	22	Unique transaction identifier assigned by SUNRATE
2.	prdId	String	6	Currency pair based on market convention
3.	buyCur	String	3	Currency to be purchased
4.	buyAmt	BigDecimal(15,2)		Amount to be purchased
5.	sellCur	String	3	Currency to be sold
6.	sellAmt	BigDecimal(15,2)		Amount to be sold
7.	custRate	String		Exchange rate for the currency pair
8.	txnMode	String	1	Possible values: 0, 1 0：Transaction amount is based on the amount of purchasing currency 1：Transaction amount is based on the amount of selling currency
9.	valueDate	String		Format: YYYY-MM-DD
10.	txnDate	String		Format: YYYY-MM-DD

1.25 Settle a trade（Client -> SUNRATE）

Endpoint：/openapi/v3/fxtxn/dealFxTxn

1.25.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	outRefNo	String	Varchar（64）	M	Unique transaction identifier assigned by client

1.25.2 Response Parameters

Standard response, trade can be considered as settled once response is received.

1.26 Query trade（Client -> SUNRATE）

Endpoint：/openapi/v3/fxtxn/getFxTxn

1.26.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	outRefNo	String	Varchar（64）	M	Unique transaction identifier assigned by client

1.26.2 Response Parameters

No.	Parameter	Type	Length	Remarks
1.	txnId	String	22	Unique transaction identifier assigned by SUNRATE
2.	quoteId	String	22	Unique quote identifier assigned by SUNRATE
3.	prdId	String	3	Currency pair based on market convention
4.	buyCur	String	3	Currency to be purchased
5.	buyAmt	BigDecimal(15,2)		Amount to be purchased
6.	sellCur	String	3	Currency to be sold
7.	sellAmt	BigDecimal(15,2)		Amount to be sold
8.	custRate	BigDecimal(9,4)		Exchange rate for the currency pair
9.	txnDate	String		Format: YYYY-MM-DD
10.	valueDate	String		Format: YYYY-MM-DD
11.	txnMode	String	1	Possible values: 0, 1 0：Transaction amount is based on the amount of purchasing currency 1：Transaction amount is based on the amount of selling currency
12.	closeTime	String		Time of settlement or transaction cancellation. Format: YYYY-MM-DDTHH:mm:ss.SSS
13.	dealStatus	String	1	Possible values: 0, 1 1：Transaction has been settled；0：Transaction has been canceled
14.	settleOptStatus	String	1	Possible values: 0, 1 1：Transaction can be settled；0：Transaction cannot be settled
15.	unwindOptStatus	String	1	Possible values: 0, 1 1：Transaction can be unwound；0：Transaction cannot be unwound

1.27 Fund for trade（Client -> SUNRATE）

Endpoint：/openapi/v3/acctbal/trans

1.27.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	cur	String	3	M	Currency of the transfer
2.	amt	String	BigDecimal(15,2)	M	Amount of the transfer
3.	transType	String	3	M	Used to specify direction of the transfer 000：Transfer balance from user account into FX Management; 001：Transfer balance from FX Management to user account
4.	outRefNo	String	Varchar（64）	M	Unique transfer identifier assigned by client

1.27.2 Response Parameters

Standard response, transfer can be considered as completed once response is received.

1.28 Query FX Management balance（Client -> SUNRATE）

Endpoint：/openapi/v3/acctbal/listAcctBal

1.28.1 Request Parameters

Standard Request Header

1.28.2 Response Parameters

No.	Parameter	Type	Length	Remarks
1.	list	Array
2.	cur	String	3	Currency with available balance
3.	avlBar	BigDecimal		Available balance of the currency

Book Transfers

This suite of APIs can be used to initiate like-for-like transfers sent to other SUNRATE user accounts and to retrieve details of such transfers. Book transfers can only be created with sufficient balance on user account to cover the transfer.

1.29 Create a transfer（Client -> SUNRATE）

Endpoint：/openapi/v3/ transfer/create/

1.29.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	outBizId	String	26	M	Unique transfer identifier assigned by client
2.	beneAcctId	String	8	M	Unique 8-digit user account identifier of recipient’s user account
3.	beneAcctName	String	128	M	Recipient’s user account name
4.	txnCur	String	3	M	Currency of transfer
5.	txnAmt	Number	15,2	M	Transfer amount
6.	cause	String	1	M	Used to specify purpose of payment 0：Payment to supplier 1：Payment to affiliate
7.	remark	String	128	O	Message to recipient

1.29.2 Response Parameters

No.	Parameter	Type	Length	Remarks
1.	id	String	21	Unique transfer identifier assigned by SUNRATE
2.	txnAmt	Number	15,2	Transfer amount
3.	txnRealAmt	Number	15,2	Amount to be received
4.	txnFee	Number	15,2	Processing fee amount borne by payer
5.	tTxnStatus	String	1	Used to specify transfer status. Possible values: 0, 1, 2, 3, 4, 5 0：Transfer has been submitted 1：Transfer has been approved 2：Transfer has been completed 3：Transfer has been canceled 4：Transfer has been denied 5：Transfer is being processed

1.30 Query outward transfer（Client -> SUNRATE）

Endpoint：/openapi/v3/ transfer/get/

1.30.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	outBizId	String	26	M	Unique transfer identifier assigned by client

1.30.2 Response Parameters

No.	Parameter	Type	Length	Remarks
1.	payId	String	21	Unique transfer identifier assigned by SUNRATE
2.	outBizId	String	26	Unique transfer identifier assigned by client
3.	acctId	String	8	Client’s unique 8-digit user account identifier
4.	acctName	String	128	Client’s user account name
5.	beneAcctId	String	8	Recipient’s unique 8-digit user account identifier
6.	beneAcctName	String	128	Recipient’s user account name
7.	txnCur	String	3	Currency of transfer
8.	txnAmt	Number	15,2	Transfer amount
9.	txnRealAmt	Number	15,2	Amount to be received
10.	txnFee	Number	15,2	Processing fee amount borne by payer
11.	remark	String	128	Message to recipient
12.	txnStatus	String	1	Used to specify transfer status. Possible values: 0, 1, 2, 3, 4, 5 0：Transfer has been submitted 1：Transfer has been approved 2：Transfer has been completed 3：Transfer has been canceled 4：Transfer has been denied 5：Transfer is being processed

1.31 Query outward transfers（Client -> SUNRATE）

Endpoint：/openapi/v3/ transfer/listOut/

1.31.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	beneAcctId	String	8	O	Recipient’s unique 8-digit user account identifier
2.	start	Number		M	Start position of records queried, equal to (page number to query-1) * limit
3.	limit	Number		M	Count of records per page. Ranges from 1 to 100. Default to 20 if not provided
4.	startDate	Date	10	O	Date after which transfer is created
5.	endDate	Date	10	O	Date before which transfer is created

1.31.2 Response Parameters

No.	Parameter	Type	Length	Remarks
1.	payId	String	21	Unique transfer identifier assigned by SUNRATE
2.	outBizId	String	26	Unique transfer identifier assigned by client
3.	acctId	String	8	Client’s unique 8-digit user account identifier
4.	acctName	String	128	Client’s user account name
5.	beneAcctId	String	8	Recipient’s unique 8-digit user account identifier
6.	beneAcctName	String	128	Recipient’s user account name
7.	txnCur	String	3	Currency of transfer
8.	txnAmt	Number	15,2	Transfer amount
9.	txnRealAmt	Number	15,2	Amount to be received
10.	txnFee	Number	15,2	Processing fee amount borne by payer
11.	remark	String	128	Message to recipient
12.	txnStatus	String	1	Used to specify transfer status. Possible values: 0, 1, 2, 3, 4, 5 0：Transfer has been submitted 1：Transfer has been approved 2：Transfer has been completed 3：Transfer has been canceled 4：Transfer has been denied 5：Transfer is being processed
13.	totalCounts	Number		Count of total transfers queried

1.32 Query inward transfers（Client -> SUNRATE）

Endpoint：/openapi/v3/ transfer/listIn/

1.32.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	payAcctId	String	8	O	Payer’s unique 8-digit user account identifier
2.	start	Number		M	Start position of records queried, equal to (page number to query-1) * limit
3.	limit	Number		M	Count of records per page. Ranges from 1 to 100. Default to 20 if not provided
4.	startDate	Date	10	O	Date after which transfer is created
5.	endDate	Date	10	O	Date before which transfer is created

1.32.2 Response Parameters

No.	Parameter	Type	Length	Remarks
1.	beneId	String	21	Unique transfer identifier assigned by SUNRATE
2.	acctId	String	8	Client’s unique 8-digit user account identifier
3.	acctName	String	128	Client’s user account name
4.	payAcctId	String	8	Payer’s unique 8-digit user account identifier
5.	payAcctName	String	128	Payer’s user account name
6.	txnCur	String	3	Currency of transfer
7.	txnAmt	Number	15,2	Transfer amount
8.	txnRealAmt	Number	15,2	Amount to be received
9.	txnFee	Number	15,2	Processing fee amount borne by payer
10.	remark	String	128	Message to recipient
11.	totalCounts	Number		Count of total transfers queried

API Documentation - VCC

2.1 Account

2.1.1 Query Card Wallet Balance

Endpoint：/openapi/v1/acctBal/list

Response Parameters

None, {}

Response Parameters

No.	Parameter Name	Details	Type	Max Length	Label	Remarks
1.	list	List of results	List		M	Refer to “list” for details

List

No.	Parameter Name	Details	Type	Max Length	Label	Remarks
1.	ccy	Currency	String	3	M
2.	acctBal	Account Balance	BigDecimal	15,2	M
3.	creditAmt	Credit Amount	BigDecimal	15,2	C
4.	pendingAmt	Pending Amount	BigDecimal	15,2	M	Funds that have been authorized but not settled.
5.	cardPendingAmt	Pending Amount on card	BigDecimal	15,2	C	Used in mode 3

Note: Available Balance = acctBal + creditAmt – pendingAmt – cardPendingAmt

Response Sample:

{

"list": [

{

"ccy": "USD",

"acctBal": 17595.37,

"creditAmt": 0,

"pendingAmt": 7438.17,

"cardPendingAmt": 445

}

]}

2.6.1 Query Account Records

Endpoint：/openapi/v1/acctJnl/list

Request Parameters

No.

Parameter Name

Details

Type

Max Length

Label

Remarks

txnDate

Transaction Date

Date

yyyy-MM-dd

Supports account records lookup by any specific date

pageInfo

Page information

Object

{

"current": "1",

"size": "100"

}

Response Parameters

No.	Parameter Name	Details		Type	Max Length	Label	Remarks
1.	list	List of results		List		M	Refer to “list” for details
2	pageInfo	Page information	Object			M	{ "current": "1", "size": "100", "total": "1000" }

list

No.	Parameter Name	Details	Type	Max Length	Label	Remarks
1.	jnlId	Record ID	String	21	M
2.	ccy	Currency	String	3	M
3.	txnAmt	Transaction Amount	BigDecimal	15,2	M
4.	preBal	Pre-transaction Balance	BigDecimal	15,2	M
5.	postBal	Post-transaction Balance	BigDecimal	15,2	M
6.	txnType	Transaction Type	String	2	M	00-Transfer-In 01-Transfer-Out 10-Card Fee 11-Txn Fee 12-Refund Fee 13-Auth Fee 14-Chargeback Fee 20-Settlement 21-Refund
7.	cardId	Card UID	String	19	C
8.	refNo	Reference Number	String	64	C	Chargeback ID
9.	createTime	Transaction Time	DateTime		M

Request Sample:

{ "txnDate": "2023-04-25", "pageInfo": { "current": "1", "size": "10" }}

Response Sample:

{ "list": [ { "jnlId": "AJ1650393936172350000", "ccy": "USD", "txnAmt": 10, "preBal": 885340.26, "postBal": 885350.26, "txnType": "00", "cardId": null, "refNo": "IO1650393935824230000", "createTime": "2023-04-24T14:59:11.879" }, { "jnlId": "AJ1650339628999450001", "ccy": "USD", "txnAmt": -1.56, "preBal": 885341.82, "postBal": 885340.26, "txnType": "20", "cardId": "1549952395537170000", "refNo": "F1637755936363580000", "createTime": "2023-04-24T11:23:24.039" } ], "pageInfo": { "total": 2, "size": 10, "current": 1}}

Query Wallet Balance

Endpoint：/openapi/v1/acctBal/listWallet

*Difference between 3.1.3 and 3.1.1 being that SUNRATE Wallet and SUNRATE Card Wallet holds separate balance. In this endpoint, clients are allowed to query the balance of their SUNRATE Wallet.

Request Parameters

None, {}

Response Parameters

No.	Parameter Name	Details	Type	Max Length	Label	Remarks
1.	list	List of Results	List		M	Refer to “list” for details

list

No.	Parameter Name	Details	Type	Max Length	Label	Remarks
1.	ccy	Currency	String	3	M
2.	currBal	Current Balance	BigDecimal	15,2	M
3.	availableBal	Current Available Balance	BigDecimal	15,2	M

Response Sample:

{

"header": {

"msgId": "1658745293799104513",

"code": "000000",

"msg": "Success",

"timeStamp": "2023-05-17T16:04:30.696"

"list": [

{

"ccy": "AUD",

"currBal": 198375.06,

"availableBal": 198375.06

{

"ccy": "CAD",

"currBal": 21023.68,

"availableBal": 2396.68

}

]

}

Commit Transfer-in (From Wallet to Card Wallet)

Endpoint：/openapi/v1/transfer/transIn

Transfer Funds from SUNRATE Wallet into SUNRATE Card Wallet

Request Parameters

No.	Parameter Name	Details	Type	Max Length	Label	Remarks
1.	outTradeNo	Merchant request ID	String	32	M	Internal reference number within requestor’s system. outTradeNo must be unique for each request.
2.	ccy	Currency	String	3	M
3.	amt	Amount	BigDecimal	15，2	M
4.	remark	Remark	BigDecimal	255	M

Response Parameters

No.	Parameter Name	Details	Type	Max Length	Label	Remarks
1.	tioJnlId	Transaction ID	String	21	M	SUNRATE transaction ID
2.	txnCcy	Currency	String	3	M
3.	txnAmt	Amount	String	15，2	M
4.	txnType	Type	String	2	M	00 – Transfer in
5.	txnDesc	Description	String	128	M
6.	txnStatus	Status	String	1	M	9 - Processing, 0 - Failed, 1 - Successful
7.	txnRemark	Transaction Remark	String	255	M
8.	remark	Remark	String	255	M
9.	outTradeNo	Merchant request ID	String	32	O
10.	txnDate	Transaction Date	Date		M	yyyy-MM-dd
11.	createTime	Creation Time	DateTime		M	yyyy-MM-dd HH:mm:ss
12.	lastTime	Last Updated Time	Datetime		M	yyyy-MM-dd HH:mm:ss

list

Request Sample:

{

"header": {

"timeStamp": "2021-11-26T16:22:43.397",

"msgId": "1464147593092804609"

"outTradeNo": "0000000000000000",

"acctId": "95754185",

"ccy": "HKD",

"amt": "10",

"remark": "Transfer-In"

}

Response Sample:

{

"header": {

"msgId": "1658782860334587906",

"code": "000000",

"msg": "Success",

"timeStamp": "2023-05-17T18:33:47.256"

"tioJnlId": "IO1658782846782791681",

"txnCcy": "HKD",

"txnAmt": 10.00,

"txnType": "00",

"txnDesc": "Deposit from Wallet",

"txnStatus": "1",

"txnRemark": "Success",

"remark": "Transfer-In",

"outTradeNo": "0000000000000001",

"txnDate": "2023-05-17",

"createTime": "2023-05-17T18:33:44.026",

"lastTime": "2023-05-17T18:33:46.388"

}

Commit Transfer-out (From Card Wallet to Wallet)

Endpoint：/openapi/v1/transfer/transOut

Transfer Funds from SUNRATE Card Wallet into SUNRATE Wallet

Request Parameters

No.	Parameter Name	Details	Type	Max Length	Label	Remarks
1.	outTradeNo	Merchant request ID	String	32	M	Internal reference number within requestor’s system. outTradeNo must be unique for each request.
2.	ccy	Currency	String	3	M
3.	amt	Amount	BigDecimal	15，2	M
4.	remark	Remark	BigDecimal	255	M

Response Parameters

No.	Parameter Name	Details	Type	Max Length	Label	Remarks
1.	tioJnlId	Transaction ID	String	21	M	SUNRATE transaction ID
2.	txnCcy	Currency	String	3	M
3.	txnAmt	Amount	String	15，2	M
4.	txnType	Type	String	2	M	00 – Transfer in
5.	txnDesc	Description	String	128	M
6.	txnStatus	Status	String	1	M	9 - Processing, 0 - Failed, 1 - Successful
7.	txnRemark	Transaction Remark	String	255	M
8.	remark	Remark	String	255	M
9.	outTradeNo	Merchant request ID	String	32	O
10.	txnDate	Transaction Date	Date		M	yyyy-MM-dd
11.	createTime	Creation Time	DateTime		M	yyyy-MM-dd HH:mm:ss
12.	lastTime	Last Updated Time	Datetime		M	yyyy-MM-dd HH:mm:ss

list

Request Parameters

{

"header": {

"timeStamp": "2021-11-26T16:22:43.397",

"msgId": "1464147593092804609"

"outTradeNo": "1000000000000001",

"acctId": "95754185",

"ccy": "USD",

"amt": "10",

"remark": "API Transfer-Out"

}

Response Parameters

{

"header": {

"msgId": "1658784565189140481",

"code": "000000",

"msg": "Success",

"timeStamp": "2023-05-17T18:40:33.724"

"tioJnlId": "IO1658784561615593473",

"txnCcy": "USD",

"txnAmt": -10.00,

"txnType": "01",

"txnDesc": "Withdraw to Wallet",

"txnStatus": "1",

"txnRemark": "Success",

"remark": "API Transfer-Out",

"outTradeNo": "1000000000000001",

"txnDate": "2023-05-17",

"createTime": "2023-05-17T18:40:32.872",

"lastTime": "2023-05-17T18:40:33.631"

}

Query Transfer Status

Endpoint: /openapi/v1/transfer/ query

Lookup the status of Wallet Transfers

Request Parameters

No.	Parameter Name	Details	Type	Max Length	Label	Remarks
1.	outTradeNo	Merchant request ID	String	32	M	Internal reference number within requestor’s system.

Response Parameters

No.	Parameter Name	Details	Type	Max Length	Label	Remarks
1.	tioJnlId	Transaction ID	String	21	M	SUNRATE transaction ID
2.	txnCcy	Currency	String	3	M
3.	txnAmt	Amount	String	15，2	M
4.	txnType	Type	String	2	M	00 – Transfer in
5.	txnDesc	Description	String	128	M
6.	txnStatus	Status	String	1	M	9 - Processing, 0 - Failed, 1 - Successful
7.	txnRemark	Transaction Remark	String	255	M
8.	remark	Remark	String	255	M
9.	outTradeNo	Merchant request ID	String	32	O
10.	txnDate	Transaction Date	Date		M	yyyy-MM-dd
11.	createTime	Creation Time	DateTime		M	yyyy-MM-dd HH:mm:ss
12.	lastTime	Last Updated Time	Datetime		M	yyyy-MM-dd HH:mm:ss

list

Request Sample:

{

"header": {

"timeStamp": "2021-11-26T16:22:43.397",

"msgId": "1464147593092804609"

"outTradeNo": "1000000000000001"

}

Response Sample:

{

"header": {

"msgId": "1658785242049142785",

"code": "000000",

"msg": "Success",

"timeStamp": "2023-05-17T18:43:15.101"

"tioJnlId": "IO1658767925927985154",

"txnCcy": "HKD",

"txnAmt": 10.00,

"txnType": "00",

"txnDesc": "Deposit from Wallet",

"txnStatus": "1",

"txnRemark": "Success",

"remark": "Transfer-In",

"outTradeNo": "0000000000000000",

"txnDate": "2023-05-17",

"createTime": "2023-05-17T17:34:26.617",

"lastTime": "2023-05-17T17:34:28.76"

}

Card

Issue Card

Endpoint：/openapi/v1/card/createCard

Request Parameters

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	outTradeNo	Merchant request ID	String	32	M	Unique to each card issuance request
2.	productCode	Product code	String	8	M	Please refer to configuration document.
3.	cardBin	Card BIN	String	10	O	Certain products support appointing for a specific BIN. A list of supported card BINs for a particular productCode can be retrieved via “Get card BINs for Card Product” endpoint. BIN will be allocated randomly for those card products if this field is omitted.
3	cardUse	Card Type	String	1	M	S：Single-use M：Multiple-use
4	ccy	Currency	String	3	M	ISO 3-Letter Currency Code
5	activateNow	Activation Mode	String	1	O	0: Card to be activated at a later date 1: Card activated immediately Default set as “1”
6	activateDate	Activation Date	Date		C	Mandatory if “activateNow” is set to “0” Defaults to current date if “activateNow” is set to “1”
7	expDate	Expiry Date	Date		M	yyyy-MM-dd dd has to be the the last day of the month. Card expiry date can range from: Earliest: One month later of issuance date Latest: Within 2 years of issuance date
8	nickName	Card Alias	String	32	O
9	velocityControl	Velocity Control Config	Object		O	1. If not inputted, default configuration will apply. 2. Configuration must follow logic: Per Transaction Limit ≤ Daily Limit ≤ Monthly Limit ≤ Cumulative Limit For details, see velocityControl
10	cardAmt	Amount on Card	BigDecimal	15,2	C	Applicable for some card productCode, contact implementation manager for details
12.	extra1	Additional information	String	32	O
13.	extra2	Additional information	String	32	O
14.	extra3	Additional information	String	32	O
15.	createImage	Image file	String		O	0: Do not generate image 1: Generate image Defaults to “0”
16.	riskCtrl	RIsk Control	List		O	See riskCtrl

Response Parameters

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	outTradeNo	Card order number	String	32	M	Every card issued is assigned a unique order number.
2.	cardId	Card ID	String	19	M
3.	cardUse	Card use type	String	1	M	S：Single-use M：Multiple-use
4.	ccy	currency	String	3	M
5.	cardNo	Card No.	String	20	M	Card number used for transactions.
6.	activateNow	Activation Mode	String	1	O	0: Card to be activated at a later date 1: Card activated immediately Default set as “1”
7.	activateDate	Activation Date	Date		C	Mandatory if “activateNow” is set to “0” Defaults to current date if “activateNow” is set to “1”
8.	expiry	Valid thru date	String	5	M	MM/YY
9.	cvv	cvv	String	3	M
10.	cardStatus	Card Status	String	1	M	0：Deactivated 1：Activated 2：Frozen 3：Expired 4：Locked 9: Inactive
11.	nickName	Card alias	String	32	O
12.	createTime	Date and time of creation	DateTime		M	yyyy-MM-dd HH:mm:ss
13.	extra1	Additional information	String	32	O
14.	extra2	Additional information	String	32	O
15.	extra3	Additional information	String	32	O
16.	cardImage	Image file	String		C	Png format

Request Sample:

{ "outTradeNo": "V2023011520545791400Me10000001", "productCode": "00000000", "cardUse": "M", "ccy": "USD", "expDate": "2023-05-31", "nickName": "abc", "velocityControl": { "perTransactionLimit": { "txnMaxAmt": 999999, "txnMinAmt": 1 }, "velocityList": [ { "period": "D", "maxTrans": 10, "cumulativeAmt": 50000 }, { "period": "C", "maxTrans": 100, "cumulativeAmt": 100000000 } ] }, "riskCtrl": [ { "created": "2024-03-27T10:31:19.319", "name": "txnCcy", "action": "deny", "list": [ "PHP", "GIP", "GBP" ] }, { "created": "2024-03-27T10:31:19.319", "name": "txnDate", "action": "deny", "list": [ "2024-05-01", "2024-05-20" ] }, { "created": "2024-03-27T10:31:19.319", "name": "txnTime", "action": "deny", "list": [ "08:00:00", "20:00:00" ] }

]}

Response Sample:

{ "cvv": "123", "cardUse": "M", "createTime": "2023-04-28T11:20:51.745", "nickName": "abc", "outTradeNo": "V2023011520545791400Me10000001", "cardId": "1651788535293970000", "ccy": "USD", "expiry": "06/23", "cardNo": "0000000000000000", "cardStatus": "1"}

Query Card Information

Endpoint：/openapi/v1/card/getCardInfo

Request Parameters

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	outTradeNo	Card Order No.	String	32	C	Either outTradeNo or cardId should be present
2.	cardId	Card ID	String	19	C	Either outTradeNo or cardId should be present

Response Parameters

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	outTradeNo	Card order number	String	32	M
2.	cardId	Card ID	String	19	M
3.	cardUse	Card Type	String	1	M	S：Single-use M：Multiple-use
4.	ccy	Currency Type	String	3	M
5.	activateNow	Activation Mode	String	1	O	0: Card to be activated at a later date 1: Card activated immediately Default set as “1”
6.	activateDate	Activation Date	Date		O
7.	cardStatus	Card Status	String	1	M	0：Deactivated 1：Activated 2：Frozen 3：Expired 4: Locked 9: Inactive
8.	nickName	Card Alias / Nickname	String	32	C
9.	velocityControl	Card Limit	Object		C	For details, see velocityControl
10.	velocityUsedList	Velocity Control Used	List		M	For details, see velocityList
11.	createTime	Date and time of creation	DateTime		M	yyyy-MM-dd HH:mm:ss
12.	extra1	Additional information	String	32	O
13.	extra2	Additional information	String	32	O
14.	extra3	Additional information	String	32	O
15.	riskCtrl	RIsk Control	List		O	See riskCtrl

Request Sample

{"outTradeNo": "V2023011520545791400Me10000001","cardId": "1651788535293970000"}

Response Sample

{ "outTradeNo": "V2023011520545791400Me10000001", "cardId": "1651788535293970000", "cardUse": "M", "ccy": "USD", "cardStatus": "1", "nickName": "abc", "velocityControl": { "perTransactionLimit": { "txnMaxAmt": 999999, "txnMinAmt": 1 }, "velocityList": [ { "period": "D", "maxTrans": 10, "cumulativeAmt": 50000 }, { "period": "C", "maxTrans": 100, "cumulativeAmt": 100000000 } ] }, "velocityUsedList": [ { "period": "D", "maxTrans": 0, "cumulativeAmt": 0 }, { "period": "C", "maxTrans": 1, "cumulativeAmt": 30 } ], "riskCtrl": [ { "created": "2024-03-27T10:31:19.319", "name": "txnCcy", "action": "deny", "list": [ "PHP", "GIP" ] }, { "created": "2024-03-27T10:31:19.319", "name": "txnDate", "action": "deny", "list": [ "2024-05-01", "2024-05-20" ] }, { "created": "2024-03-27T10:31:19.319", "name": "txnTime", "action": "deny", "list": [ "08:00:00", "20:00:00" ] } ], "createTime": "2023-04-28T11:15:03.527"}

Query Card Sensitive Information

Endpoint：/openapi/v1/card/getCardSensitiveInfo

Request Parameters

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	cardId	Card ID	String	19	M

Response Parameters

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	cardNo	Card Number	String	20	M	Full PAN information
2.	cvv	CVV	String	3	M
3.	expiry	Expiry	String	5	M	MM/YY

Request Sample

{"cardId": "1651788535293970000"}

Response Sample

{ "cvv": "123", "expiry": "06/23", "cardNo": "0000000000000000" }

Update Card Limit

Endpoint：/openapi/v1/card/updateCardLimit

Request Parameters

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	cardId	Card ID	String	19	M
2.	velocityControl	Card limit	Object		M	For details, see velocityControl (3.31)
3.	riskCtrl	RIsk Control	List		O	See riskCtrl

Response Parameters

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	cardId	Card ID	String	19	M
2.	velocityControl	Card limit	Object		M	For details, see velocityControl (3.31)

Request Sample

{ "cardId": "1651788535293970000", "velocityControl": { "perTransactionLimit": { "txnMaxAmt": 100000, "txnMinAmt": 5 }, "velocityList": [ { "period": "D", "maxTrans": 1, "cumulativeAmt": 1000 }, { "period": "C", "maxTrans": 100, "cumulativeAmt": 100000000 } ] }, "riskCtrl": [ { "created": "2024-03-27T10:31:19.319", "name": "txnCcy", "action": "deny", "list": [ "PHP", "GIP" ] }, { "created": "2024-03-27T10:31:19.319", "name": "txnDate", "action": "deny", "list": [ "2024-05-01", "2024-05-20" ] }, { "created": "2024-03-27T10:31:19.319", "name": "txnTime", "action": "deny", "list": [ "08:00:00", "20:00:00" ] } ]}

Response Sample

Update Card Status

Endpoint：/openapi/v1/card/updateCardStatus

Request Parameters

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	cardId	Card ID	String	19	M
2.	cardStatus	Card status	String	1	M	0：Deactivated 1：Activated 2：Frozen
3.	remark	Additional remarks	String	128	O

Response Parameters

No.

Parameter

Details

Type

Max Length

Label

Remarks

cardId

Card ID

String

cardStatus

Card status

String

0：Deactivated

1：Activated

2：Frozen

3：Expired

4：Locked

GET Card Authorization Record

Endpoint：/openapi/v1/card/listCardTxn

Request Parameters

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	cardId	Card ID	String	19	C
2.	txnDateStart	Transaction Date - Start	Date		C	yyyy-MM-dd When card ID is not present, transaction date is mandatory. Transaction Date-Start and Transaction Date-End must be of the same date
3.	txnDateEnd	Transaction Date - End	Date		C	yyyy-MM-dd When card ID is not present, transaction date is mandatory. Transaction Date-Start and Transaction Date-End must be of the same date
4.	pageInfo	Page Information	Object		M	{ "current": "1", "size": "100" }

Response

No.

Parameter

Details

Type

Max Length

Label

Remarks

list

List of results

List

Refer to “list” for details

pageInfo

Page Information

Object

{

"current": "1",

"size": "100",

"total": "1000"

}

list

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	txnId	Transaction ID	String	20	M
2.	originTxnId	Original transaction ID	String	20	C	Original transaction ID used in the event of a reversal
3.	cardId	Card ID	String	19	M
4.	txnType	Transaction Type	String	1	M	A：Authorization D：Reversal
5.	txnStatus	Transaction Status	String	1	M	0：Failed 1：Success
6.	txnCcy	Transaction Currency	String	3	M
7.	txnAmt	Transaction Amount	BigDecimal	15,2	M
8.	billCcy	Bill Currency	String	3	M
9.	billAmt	Bill Amount	BigDecimal	15,2	M
10.	merchName	Merchant Name	String	128	M
11.	merchantCtry	Merchant Country	String	3	M	3-digit ISO Standard Country Code
12.	mcc	Merchant Category Code	String	128	M
13.	rspCode	Response Code	String	2	M	See appendix C
14.	declineReason	Reason for decline	String	128	C
15.	authCode	Authorization Code	String	6	C
16.	txnTime	Transaction Time	DateTime		M	yyyy-MM-dd hh:mm:ss
17.	clearingDate	Clearing Date	DateTime		C	yyyy-MM-dd hh:mm:ss

Request Sample:

{ "txnDateStart": "2023-04-24", "txnDateEnd": "2023-04-24", "pageInfo": { "current": 1, "size": 10 }}

Response Sample:

{ "list": [ { "cardId": "1651788535293970000", "txnId": "A1650337673904330000", "originTxnId": null, "txnType": "A", "txnStatus": "1", "txnCcy": "GBP", "txnAmt": 56.33, "billCcy": "USD", "billAmt": 58.09, "merchName": "Department Store Vegas NV", "merchCtry": "GBR", "mcc": "0780 Landscaping and horticultural services", "rspCode": "00", "declineReason": null, "txnTime": "2023-04-24T11:23:24.015", "clearingDate": "2023-04-24" }, { "cardId": "1651788535293970000", "txnId": "A1650337673904330001", "originTxnId": "A1628643391916802049", "txnType": "D", "txnStatus": "1", "txnCcy": "USD", "txnAmt": -5, "billCcy": "USD", "billAmt": -5, "merchName": "PAYPAL", "merchCtry": "GBR", "mcc": "5999 Miscellaneous Specialty Retail", "rspCode": "00", "declineReason": null, "txnTime": "2023-04-24T11:15:37.987", "clearingDate": null } ], "pageInfo": { "total": 2, "size": 10, "current": 1 }}

GET Clearing Record

Endpoint：/openapi/v1/card/listCardClearing

Request Parameters

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	cardId	CardID	String	19	C
2.	txnDateStart	Transaction Clearing Date - Start	Date		C	yyyy-MM-dd When card ID is not present, transaction date is mandatory. Transaction Date-Start and Transaction Date-End must be of the same date
3.	txnDateEnd	Transaction Clearing Date - End	Date		C	yyyy-MM-dd When card ID is not present, transaction date is mandatory. Transaction Date-Start and Transaction Date-End must be of the same date
4.	pageInfo	Page Information	Object		M	{ "current": "1", "size": "100" }

Response Parameter

No.

Parameter

Details

Type

Max Length

Label

Remarks

list

List of results

List

See list

pageInfo

Page Information

Object

{

"current": "1",

"size": "100",

"total": "1000"

}

list

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	txnId	Transaction ID	String	20	M
2.	authTxnId	Corresponding Authorization ID	String	20	M
3.	cardId	Card ID	String	19	M
4.	txnType	Transaction Type	String	1	M	C：Expense R：Refund
5.	txnCcy	Transaction Currency	String	3	M
6.	txnAmt	Transaction Amount	BigDecimal	15,2	M
7.	billCcy	Bill Currency	String	3	M
8.	billAmt	Bill Amount	BigDecimal	15,2	M
9.	merchName	Merchant Name	String	128	M
10.	merchantCtry	Merchant Country	String	3	M	3-digit ISO Country Code
11.	mcc	Merchant Category Code	String	128	M
12.	authCode	Authorization Code	String	6	C
13.	arn	ARN	String	23	C
14.	clearingDate	Clearing Date	DateTime		M

Request Sample

{ "txnDateStart": "2023-03-20", "txnDateEnd": "2023-03-20", "pageInfo": { "current": 1, "size": 10 }}

Response Sample

{ "list": [ { "cardId": "1628587609561490000", "txnId": "F1637755936363580000", "authTxnId": null, "txnType": "R", "txnCcy": "USD", "txnAmt": -15.22, "billCcy": "HKD", "billAmt": -119.77, "merchName": "RYANAIR PHZ0", "merchCtry": "GBR", "mcc": "3246 RYANAIR", "clearingDate": "2023-03-20" }, { "cardId": "1651788535293970000", "txnId": "F1637728540629794818", "authTxnId": "A1650337673904330000", "txnType": "C", "txnCcy": "GBP", "txnAmt": 56.33, "billCcy": "USD", "billAmt": 58.09, "merchName": "Department Store Vegas NV", "mcc": "0780 Landscaping and horticultural services", "clearingDate": "2023-03-20" } ], "pageInfo": { "total": 2, "size": 10, "current": 1 }}

GET Card BINs for Card Product

*Not used for “E” series products

Endpoint：/openapi/v1/card/getCardBin

Response Parameters

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	list	Results list	List		M	See list

list

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	productCode	Product code	String	8	M	Product code
2.	cardUse	Card use type	String	1	M	S：Single-use M：Multiple-use
3.	ccy	Currency	String	3	M	3-digit standard ISO currency code
4.	cardBinList	List of card BINs	List<String>		M

Response Sample

{ "list": [ { "productCode": "xxx", "cardUse": "M", "ccy": "USD", "cardBinList": [ "51250kkkk" ] }, { "productCode": "xxx", "cardUse": "M", "ccy": "USD", "cardBinList": [ "40854kkkk", "41207kkkk" ] } ]}

Activate Card

Endpoint：/openapi/v1/card/activateCard

Request Parameters

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	cardId	Card ID	String	19	M

Response Parameters

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	cardId	Card ID	String	19	M
2.	cardStatus	Card Status	String	1	M	1: Activated

Request Sample

{"cardId": "1651788535293970000"}

Request Sample

{ "cardId": "1651788535293970000", "cardStatus": "1"}

2.3 Element And Attributes

2.3.1 velocityControl

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	perTransactionLimit	Per Transaction Limit	Object		O	For details, see perTransactionLimit
2.	velocityList	Velocity Control List	List		O	For details, see velocityList

perTransactionLimit

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	txnMinAmt	Minimum Amount per Transaction	BigDecimal	15,2	O
2.	txnMaxAmt	Maximum Amount per Transaction	BigDecimal	15,2	C

velocityList

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	period	Period param	String	1	C	D：Daily M：Monthly C：Cumulative
2.	maxTrans	Maximum No. of Transactions	Integer	10	C	Maximum numbrt of transactions that can be accepted with the card within the period
3.	cumulativeAmt	Cumulative Amount	BigDecimal	15,2	C	Maximum cumulative amount that can be used with the card within the period

riskCtrl

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	name	Risk Contrrol	String	10	M	txnCcy: Transaction currency txnMcc: MCC txnCountry: Merchant Country txnMerchId: Merchant ID txnDate: Transaction Date txnTime: Transaction Time
2.	action	Action Type	String	10	M	allow: Allow list deny: Deny list
3.	list	Control List	List		M	List <String> When setting risk controls with txnDate or txnTime, set the start date and end date and then first and second position of the array. e.g., [“start date” , “end date”]
4.	created	Creation Time	DateTime		M	yyyy-MM-dd HH:mm:ss

2.4 Webhook Notifications

Notification Request Headers

Parameter Name	Type	Max Length	Label	Details
msgId	String	21	M	messageId, the request message ID
timestamp	String	23	M	Timestamp of request，formatted as "yyyy-MM-ddTHH:mm:ss.SSS" For example, 2008-08-08T08:08:08.888
key	String	16	M	Private key value of 16-digit AES after encryption. The 16-digit AES key is to be generated randomly by merchant.
sign	String		M	Signature value
requestBody	String		M	Encrypted request body. Note: format the request in JSON before encryption. No restriction on max. length

Notification Response Headers

Parameter Name	Type	Max Length	Label	Details
msgId	String	21	M	messageId, the request message ID
code	String	6	M	Response Code “000000” signifies a successful request
msg	String	128	M	Response Code description
timestamp	String	23	M	Timestamp of request，formatted as "yyyy-MM-ddTHH:mm:ss.SSS" For example, 2008-08-08T08:08:08.888

Authorization Record Notification

SUNRATE will PUSH authorization records to client’s notification URL. HTTPS Port 443 must be used.

Callback URL: url/callBack/cardAuth

Notification Parameters

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	txnId	Transaction ID	String	20	M
2.	originTxnId	Original transaction ID	String	20	C	Original transaction ID used in the event of a reversal
3.	cardId	Card ID	String	19	M
4.	txnType	Transaction Type	String	1	M	A：Authorization D：Reversal
5.	txnStatus	Transaction Status	String	1	M	0：Failed 1：Success
6.	txnCcy	Transaction Currency	String	3	M
7.	txnAmt	Transaction Amount	BigDecimal	15,2	M
8.	billCcy	Bill Currency	String	3	M
9.	billAmt	Bill Amount	BigDecimal	15,2	M
10.	merchName	Merchant Name	String	128	M
11.	merchantCtry	Merchant Country	String	3	M	3-digit ISO Standard Country Code
12.	mcc	Merchant Category Code	String	128	M
13.	rspCode	Response Code	String	2	M	See appendix C
14.	declineReason	Reason for decline	String	128	C
15.	authCode	Authorization Code	String	6	C
16.	txnTime	Transaction Time	DateTime		M	yyyy-MM-dd hh:mm:ss
17.	clearingDate	Clearing Date	DateTime		C	yyyy-MM-dd hh:mm:ss

Response Parameters

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	msgId	Response messageID	String	21	M
2.	code	Status Code	String	6	M	000000 - Success
3.	msg	Description	String	32	M	success
4.	timestamp	Timestamp	DateTime		M	yyyy-MM-dd hh:mm:ss

Request Sample:

{ "cardId": "1651788535293970000", "txnId": "A1650337673904330000", "originTxnId": null, "txnType": "A", "txnStatus": "1", "txnCcy": "GBP", "txnAmt": 56.33, "billCcy": "USD", "billAmt": 58.09, "merchName": "Department Store Vegas NV", "merchCtry": "NV", "mcc": "0780 Landscaping and horticultural services", "rspCode": "00", "declineReason": null, "txnTime": "2023-04-24T11:23:24.015", "clearingDate": "2023-04-24"}

Response Sample:

{ "msgId": "123456789", "code": "000000", "msg": "success", "timestamp": "2023-04-24T11:23:24.015"}

Clearing Record Notification

SUNRATE will PUSH clearing records to client’s notification URL. HTTPS Port 443 must be used.

Callback URL: url/callBack/cardClearing

Notification Parameters

No.	Parameter	Details	Type	Max Length	Label	Remarks
1.	txnId	Transaction ID	String	20	M
15.	authTxnId	Corresponding Authorization ID	String	20	M
16.	cardId	Card ID	String	19	M
17.	txnType	Transaction Type	String	1	M	C：Expense R：Refund
18.	txnCcy	Transaction Currency	String	3	M
19.	txnAmt	Transaction Amount	BigDecimal	15,2	M
20.	billCcy	Bill Currency	String	3	M
21.	billAmt	Bill Amount	BigDecimal	15,2	M
22.	merchName	Merchant Name	String	128	M
23.	merchantCtry	Merchant Country	String	3	M	3-digit ISO Country Code
24.	mcc	Merchant Category Code	String	128	M
25.	authCode	Authorization Code	String	6	C
26.	arn	ARN	String	23	C
27.	clearingDate	Clearing Date	DateTime		M

Request Sample:

{ "cardId": "1628587609561490000", "txnId": "F1637755936363580000", "authTxnId": null, "txnType": "R", "txnCcy": "USD", "txnAmt": -15.22, "billCcy": "HKD", "billAmt": -119.77, "merchName": "RYANAIR PHZ0", "merchCtry": "GBR", "mcc": "3246 RYANAIR", "clearingDate": "2023-03-20"}

Response Sample:

{ "msgId": "123456789", "code": "000000", "msg": "success", "timestamp": "2023-04-24T11:23:24.015"}

API Documentation - Reporting

This suite of APIs can be used to retrieve account statement for reconciliation.

3.1 Query balance（Client-> SUNRATE）

Endpoint：/openapi/v3/balance/list/

3.1.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	curId	String	3	O	Currency code for currency

3.1.2 Response Parameters

No.	Parameter	Type	Length	Remarks
Array
1.	curId	String	char（3）	Currency code
2.	currBal	Number	15,2	Total balance of the currency, equal to sum of availableBal and frozenBal
3.	availableBal	Number	15,2	Available balance of the currency for transaction creation
4.	frozenBal	Number	15,2	Frozen balance of the currency due to transaction(s) created

3.2 Query statement（Client-> SUNRATE）

Endpoint：/openapi/v3/acctFlow/query/

3.2.1 Request Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	curId	String	3	O	Currency code for currency
2.	startDate	Date	10	O	Date after which transaction is created
3.	endDate	Date	10	O	Date before which transaction is created
4.	start	String		M	Start position of records queried, equal to (page number to query-1) * limit
5.	limit	String		M	Count of records per page. Ranges from 1 to 100. Default to 20 if not provided

3.2.2 Response Parameters

No.	Parameter	Type	Length	Required/Optional	Remarks
1.	orgCode	String	18	M	Business registration number of client
2.	acctId	String	8	M	Unique 8-digit user account identifier
3.	curId	String	char（3）	M	Currency of balance change
4.	txnAmt	Number	15,2	M	Used to specify type of change in balance, possible values: +, - +: Credit -: Debit
5.	initBal	Number	15,2	M	Balance before transaction
6.	closeBal	Number	15,2	M	Balance after transaction
7.	refNo	String	18	M	Unique identifier of balance change
8.	txnType	String	4	M	Used to specify type of transaction that incurs balance change
9.	remark	String	100	O	Used to describe details of transaction
10.	sysTxnDate	String	10	M	Date of balance change
10．	totalCounts	Number		M	Count of total records queried

Share to

Return to list

SUNRATE API Docs: Global Payments & VCC