Request and Response

The HTTP method of open API are all POST;
The Accept of Header is always set to application/json, same for Content-Type;
he format of Body is JSON;
UTF-8 is being used by the system.

Request structure

Each request contains Request URL, Method, Header and Body.

URL

The format of the request URL is https://{domain name}/api/{version}/{endpoint}, which consist of the following parts:

domain name: AlphaPay Open API domain, e.g. openapi.alphapay.ca.
version: API version number, e.g. v1.0 or v2.0.
endpoint: refers to the particular interface, e.g. /{version}/payments/pay. Each endpoint uniquely identifies an API, e.g. /v1.0/payments/pay is a different interface from /v2.0/payments/pay. An example of a complete URL for reference: https://openapi.alphapay.ca/api/v2.0/payments/pay.

Method

HTTP methods are all POST

Request Header

Request Header should contain the following fields：
Note: the field name is case sensitive.

Header field	Required	Description	Code sample
`Signature`	Yes	Signature information	`Signature: algorithm=RS256, keyVersion=1, signature={generatedSignature}`
`Merchant-Code`	Yes	Merchant code provided by AlphaPay	`Merchant-Code: CXVJIU`
`Request-Time`	Yes	Specifies the time when a request is sent, as defined by ISO 8601. This field must be accurate to milliseconds.	`Request-Time: 2019-04-04T12:08:56+05:30`
`Nonce`	Yes	Random String with length of 32	`Nonce: b111bcf0dfb54d4e8bae68c293d85e2e`
`Content-Type`	Yes	Media types for each request	`Content-Type: application/json; charset=UTF-8`
`Accept`	Yes	Media types that can be accepted	`Accept: application/json`

Signature

Signature consists of multiple key-value pairs, each pair can be formatted as {key}={value}, e.g. algorithm=RS256; 2 different key-value pairs should be separated by a comma ,, e.g. algorithm=RS256,keyVersion=1.

For the keys required by the Signature, please see below:

algorithm: Specifies the signature algorithm used for generating the signature, which defaults to RS256.
keyVersion: Specifies the version number of the key used for generating and verifying the signature for the current request, currently the version number is 1.
signature: Please reference the Sign a Request for the generation method.

An example of a completed Signature:

Signature details in the Header

Signature: algorithm=RS256, keyVersion=1, signature=d%2FqFC126U57guKgRRXnd4colw5Ed5tpq3NDh2M5JOtfDivAze4X%2BYEaUCWHNW7h02sSed7hsnsDtM2rjtYe8kqAJTV9fMLzraeUZvWBh4j8Sf2D%2Bcz4bJ23S4F7VtoWaxMWjySwWuS0nMQweg%2BM7MY1HQFz2EXZjAa4CVflxU1I61NuEURfiYJGW%2BLEf%2FPVPEgzBLO8LopYMovmgO7Fl97E9UVFZnFW37bSaEdkNCffJlBU00AYWKaXbsARLarETkY9NA8nTJ5yDwjKm4rH3O%2FUhwGYnwLAvozKKjfWLU4m15LoAUF30Tap6d7IGFfewnLxdY34sVYG3Nx6m0Mit%2Bg%3D%3D

Merchant-Code

Merchant-Codeis a unique ID assigned by AlphaPay to the merchant and is used for generating the signature of the request.The length of the Merchant-Code is between 4 to 6 digits and can be looked up in the merchant dashboard. E.g. Merchant-Code: CXVJIU.

Request-Time

Specifies the time when a request is sent, as defined by ISO 8601. This field must be accurate to milliseconds.
E.g. Request-Time: 2019-04-04T12:08:56+05:30.

Nonce

Random-generated String with length of 32. E.g. Nonce: b111bcf0dfb54d4e8bae68c293d85e2e.

Content-Type

Content-Typespecifies the media types for each request body. E.g. Content-Type: application/json; charset=UTF-8.

Accept

Accept specifies the media types that can be accepted. E.g. Accept: application/json.

Request Body

Requestbody is formatted with JSON，which includes detailed request information. For specific information, please refer to the corresponding API specifications.

Response Structure

Each Request contains the Header, Body and response status.

Response Header

Response Header should contain the following fields：
Note: Field name is case sensitive.

Header field	Required	Description	Code sample
`Signature`	Yes	Signature information	`Signature: algorithm=RS256, keyVersion=1, signature={generatedSignature}`
`Merchant-Code`	Yes	Merchant code provided by AlphaPay	`Merchant-Code: CXVJIU`
`Response-Time`	Yes	Specifies the time when a request is sent, as defined by ISO 8601. This field must be accurate to milliseconds.	`Response-Time: 2019-04-04T12:08:56+05:30`
`Nonce`	Yes	Random String with length of 32	`Nonce: b111bcf0dfb54d4e8bae68c293d85e2e`
`Content-Type`	Yes	Media types for each request	`Content-Type: application/json; charset=UTF-8`

Signature, Merchant-Code, Response-Time, Nonce and Content-Type have the same specification as them in the request header.

Response Body

The Response Body contains the message that needs to be sent back to the client. The fields may vary depending on the specific service being requested, but the result field, which indicates the result of the API call, is returned by every interface.

In case of a failed API call, the resultCode will return an error code, and the resultMessage will return an error message, which can be used to diagnose the error.

Field	Date type	Description
`resultCode`	String	Result code for each payment, please see resultCode for more details
`resultStatus`	String	Result status for each payment, please see resultStatus for more details
`Response-Time`	String	Detailed error message

Request Flow

1. Construct a request

Please follow the Request Structure for constructing a request.

To ensure the security and authenticity of the request, all requests need to be signed as required, please refer to Sign a Request for more details.

2. Send a request

Sending the request constructed from step 1.

3. Receive and validate the response

The response will be returned in JSON format, please refer to the Response Structure for more details.

To ensure the security and authenticity of the response, all responses should be accompanied by a signature, please see Handle a Response for more details.

4. Checking and processing the result

The response will be returned with different information based on request to each specific interface, whereas the result field that indicating the result of the API call should be returned by every interface.

If API call fails, the resultCode field typically returns an error code, resultMessage will be returned with an error message, which could be used for debugging the API calling process.
If there is no error occurred, business processing can be continued.

Secure Sockets Layer

Currently support TLS 1.2