API Request

API Request

The merchant needs to obtain a token before using the API normally

Send Request Use different Service Parameters to access the API

• Serialize all business parameters into json to generate bizContent

• Use the merchant's private key to sign bizContent

• AES encryption of bizContent

Common Request

POST {{ base_url }}/api/v2/pay

Method: POST

Headers

Name	Type	Description
Authorization*	String	Bearer token

Request Body

Name	Type	Description
service*	String	Sample: createPayer
bizContent*	String	AES encrypted containing all business parameters
sign*	String	Signature

200 OK

{
    "statusCode": 0,
    "bizContent": "ZXlKcGRpSTZJbTgyUzA1cmJscDZha2xVVEdkNmRVWlRiSGRsZVdjOVBTSXNJblpoYkhWbElqb2lPRzVVY1RseFEyWkNSbVF4VEVacGJpOXBVemg0UlVwdlN6Rm1lbk5tZW14U2RVOTZhRFJ3TW1GcGJ6MGlMQ0p0WVdNaU9pSTFaR1kzWWpWaE5XUTFZV05rT0Rjek9UQmpNMk15WlRBME0yUm1aV1EwTlRoaE0yUTVOekpsTkRObE16SmpORE01WkdKak9UUmhNMk5rWWpnMk4yTTNJaXdpZEdGbklqb2lJbjA9",
    "sign": "J4079QgEUJdqZtx/9/L8m2ZCEcs/18un2w+vL9SNmM7EaxrWX3lEA6CObv3FLpRNKadtkdekCavy0MK3tL+vb95MAX7nDQakeYhBk0oVfIyQYhYCtskxSHFy9ZO+Ys8f2MCbPNwl489SnrskXOE0Azxvtsk22C6GmWuRMA4gbO7xoneg/lMlxyiu/mVkoHZ8E1bBQBdYK0G14M/XzU/Xchn6VzPCydW9t7+epVEKgz3dO9qKJk6Gz1P/3ui+s84gWn1jUToaHR23BGjEg9wZln1K/1x5CF6/kUjHhSfq1bAvD5ctsajKvYTaspv65dVh7untNLl5K1WAI7EZ1YFGog==",
    "timestamp": "2023-09-12 14:26:30 GMT+8"
}

401 Unauthorized

400: Bad Request

403: Forbidden

500: Internal Server Error

API Request Sample

Important：Service parameters are case sensitive, please refer to the Service List

PHP - Guzzle

<?php
$client = new Client();
$headers = [
  'Authorization' => 'Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9yZWxvYWQudGVzdFwvYXBpXC92MlwvbG9naW4iLCJpYXQiOjE2OTQ1MTI3ODgsImV4cCI6MTY5NDUxNjM4OCwibmJmIjoxNjk0NTEyNzg4LCJqdGkiOiJxMWlTQTdZbnROZ2U1bnA3Iiwic3ViIjoxMDAsInBydiI6IjIzYmQ1Yzg5NDlmNjAwYWRiMzllNzAxYzQwMDg3MmRiN2E1OTc2ZjcifQ.CfhtwYhBRmzusPH3EOOnQLO0XySNY7T_e90sDEkZ3IA',
  'Content-Type' => 'application/x-www-form-urlencoded'
];
$options = [
'form_params' => [
  'service' => 'createPayer',
  'bizContent' => 'AgAv0CCKyfxCCX3Ou907purhD5Bs93AV2NzELRn6GWxwxhv6aMsAT3YM3q1sSu+SNQrJNh2s2RuduUgB/bnlU9OK6UbSNVEGN2sASha6NuuS/phda4vG/ihPTguEgmYrsrS5ukYJ2gOiShrvthGLH9fsemAQnGZS4+AOuB2U0DZvbQfIkjweE8E1xuVu15DzFDzbM+1dFO/Uc8gngiTzeCipNLMl4sGzjc/+r30j+5ZbyGQP67DBo9i2hMyCiApGrAbhnTLQ3QCi8CNAGyt1Cme6NC1lnjhigj/QNkR/f3CJAm+lz5hKOQZ6O1KnY5WYtawNHQcST+38Vi3lO6BV/tkI6R/n7twEEnxtHPoV6GJyuebFAbzrTX3tyq0ibJ5lB8xFM8I1t7qMOepEu6Dj8gcThQwRRTBLx3kWBz0BA3lLRwbxkfYsqqOksrCnLvrycQATlLUcrOJ7vuOxqiDpnsZpcd57wZo2gPc68AdLs9kTSP2criGpEAcD5mGQZH7YUHRc2LnB93U8WU22fI81xATNJ+e++D9RtjaIeCOScNKnE9g7PjasOYy0riMbQgSJPOR9V5Zvc3aEYQ+VRQePa44XDg5sTbmGLbev8BKqlAYupmzUL898mEGF8NxBVwMB9qw2HQh0Kmg8PjIqrRdADTtmABLf2OvL+WZTgufIGUQ=',
  'sign' => 'UD26CyfptzTq9GQnRZLl530BsU/Gje7v69wm6UeBuJ9+htqg225UFkjyWE/homEHD2G9h6TXcjJezfZPfJkJZgY/0JMYV2AxbClKnowOceiVBn1Vzh0YsmEtAed98U5aPgEIRxOWyN+5zUv3ZSFBhajHlm5sBEo6VBLskTg9UCYTp3pm3jGcLE6jZ6xdsjTmLEjnUKFCdg4uNJj7AEs3WtsLJ4qQ1Ul76OTRts9X9Dm+d0QfVi6RhmoOhFiHGVPfb3kouHO8zSHesSnNohyXemlzTv2CKx32wSbH/giqHWeLl3lHE548a/rcA+nBX7WseiEQQMwu1sKR91g81FqpXA=='
]];
$request = new Request('POST', 'https://sandbox-app/api/v2/pay', $headers);
$res = $client->sendAsync($request, $options)->wait();
echo $res->getBody();

Java - OkHttp

API Response

The API returns in json format. When statusCode=0, it means the API request is successful. The specific business return parameters are in bizContent.

{
    "statusCode": 0,
    "bizContent": "ZXlKcGRpSTZJbTgyUzA1cmJscDZha2xVVEdkNmRVWlRiSGRsZVdjOVBTSXNJblpoYkhWbElqb2lPRzVVY1RseFEyWkNSbVF4VEVacGJpOXBVemg0UlVwdlN6Rm1lbk5tZW14U2RVOTZhRFJ3TW1GcGJ6MGlMQ0p0WVdNaU9pSTFaR1kzWWpWaE5XUTFZV05rT0Rjek9UQmpNMk15WlRBME0yUm1aV1EwTlRoaE0yUTVOekpsTkRObE16SmpORE01WkdKak9UUmhNMk5rWWpnMk4yTTNJaXdpZEdGbklqb2lJbjA9",
    "sign": "J4079QgEUJdqZtx/9/L8m2ZCEcs/18un2w+vL9SNmM7EaxrWX3lEA6CObv3FLpRNKadtkdekCavy0MK3tL+vb95MAX7nDQakeYhBk0oVfIyQYhYCtskxSHFy9ZO+Ys8f2MCbPNwl489SnrskXOE0Azxvtsk22C6GmWuRMA4gbO7xoneg/lMlxyiu/mVkoHZ8E1bBQBdYK0G14M/XzU/Xchn6VzPCydW9t7+epVEKgz3dO9qKJk6Gz1P/3ui+s84gWn1jUToaHR23BGjEg9wZln1K/1x5CF6/kUjHhSfq1bAvD5ctsajKvYTaspv65dVh7untNLl5K1WAI7EZ1YFGog==",
    "timestamp": "2023-09-12 14:26:30 GMT+8"
}

Handling Return Parameters

• Decrypt the bizContent field by using AES

• Verify the signature by decrypted bizContent

The API returns responses in a standard JSON format that includes the following properties in response payload:

1. status: An integer representing the status of the response.

2. errors: A list of error objects that provide additional information about any errors that occurred during processing.

3. data: The actual data payload of the response, which can be of any type.

bizContent Business Data Sample

{
    "status": "0",
    "data":
    {
        "firstName": "Peter",
        "lastName": "Pan",
        "email": "[email protected]",
        "areaCode": "852",
        "phone": "98765432",
        "address": "Hong Kong",
        "city": "Hong Kong",
        "country": "China",
        "payerID": "9007199254740991"
    }
}

Important：To ensure business security, please verify the signature of the returned parameters

The table below shows the property name, data type, possible values (for the status property), and a description of what each property means.

PROPERTY	TYPE	VALUES	DESCRIPTION
status	integer	0 or -1	Status of the response: 0 indicates success, -1 indicates failure.
errorCode	String		Application specific error code about any error that occurred during processing.
errorMessage	String		Error Description
data	any	Any	The actual data payload of the response, which can be of any JSON-compatible type

Successful Response:

A successful response payload will have:

• Status property with a value of 0

• Error Code property as null

• Error Message property as null

• Data property containing the requested data (JSON-compatible)

For example, a successful response to a request for getting cardholders might look like this:

{
    "status": "0",
    "data":
    {
        "firstName": "Peter",
        "lastName": "Pan",
        "email": "[email protected]",
        "areaCode": "852",
        "phone": "98765432",
        "address": "Hong Kong",
        "city": "Hong Kong",
        "country": "China",
        "payerID": "9007199254740991"
    }
}

Unsuccessful Response:

An unsuccessful response will have:

• Status property with a value of -1

• Error Code property with a value

• Error Code property with a description

• Data property as null

If there is no associated error code for the error, a default error code value of -1 will be returned.

For example, an unsuccessful response with an invalid userID might look like this:

{
    "status": -1,
    "errorCode": "120",
    "errorMsg": "Invalid userId or apiKey"
}