API overview
WorldFirst offers a set of Application Programming Interfaces (APIs) that provides the ability for integration. You can use POST
method to send HTTPS requests and receive responses accordingly.
Versioning
WorldFirst APIs are backward compatible. Earlier clients are adaptable to newer API releases.
Message structure
Request structure
An API Request is composed of the following structure:
Name | Description |
Request URL |
|
Request Method |
|
Request header | Composed of :
Refer to the table down below for more details. |
Request body | Request body is in JSON format. Sample:
|
A request header contains the following fields:
Name | Sample | Description |
Signature | signature: algorithm=RSA256, keyVersion=2, signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGRrWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrTpMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3JrbRFvcowQwt0lP1XkoPmSLGpBevDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD%2FFYDAwSd%2B6%2FEOFo9UbdlKcmodJwjKlQoxZZIzmF8w%***** |
|
Content-Type | Content-Type: application/json; charset=UTF-8 |
|
Client-Id | Client-Id: **** | Identify a client that is associated with the keys that are used for signature and encryption. |
Request-Time | Request-Time: 2019-04-04T12:08:56+08:00 | Specifies the time when the request is sent, as defined by ISO 8601. |
The following curl example depicts the general structure of a message:
curl -X POST \
http://xxx.com/amsin/api/v1/payments/inquiryQuotes \
-H 'Content-Type: application/json; charset=UTF-8' \
-H 'Client-Id: 5J5Y307NSG5GB7*****' \
-H 'Request-Time: 2019-04-04T12:08:56+05:30' \
-H 'Signature: algorithm=RSA256, keyVersion=2, signature=KEhXthj4bJ801Hqw8kaLvEKc0Rii8KsNUazw7kZgjxyGSPuOZ48058UVJUkkR21iD9JkHBGRrWiHPae8ZRPuBagh2H3qu7fxY5GxVDWayJUhUYkr9m%2FOW4UQVmXaQ9yn%2Fw2dCtzwAW0htPHYrKMyrTpMk%2BfDDmRflA%2FAMJhQ71yeyhufIA2PCJV8%2FCMOa46303A0WHhH0YPJ9%2FI0UeLVMWlJ1XcBo3JrbRFvcowQwt0lP1XkoPmSLGpBevDE8%2FQ9WnxjPNDfrHnKgV2fp0hpMKVXNM%2BrLHNyMv3MkHg9iTMOD%2FFYDAwSd%2B6%2FEOFo9UbdlKcmodJwjKlQoxZZIzmF8w%*****' \
-d '{
"quoteBizScene": "REF_QUOTES"
}'
The following figure illustrates the request structure:
Figure 1. Request structure
Response structure
An API Response is composed of the following structure:
Name | Description |
Request header | Composed of :
Refer to the table down below for more details. |
Request body | In JSON format.
|
HTTP Response Status | Sample: |
The following figures illustrate the response structure:
Figure 2. Response structure
Procedures to make an API call
The following figure illustrates the message transmission workflow from Partner to WorldFirst:
Figure 3. Message transmission workflow
Step 1. Construct a request
- Properly construct a request with matching structures.
- Sign the request.
- Enable the Base64 encoding.
Step 2. Send a request
Assemble the request and send it to the WorldFirst server.
Step 3. Check the response
Validate the signature of the response after receiving the response message.
Step 4. Check the status code
In the event that an error occurs, an error response is returned, in which the result object indicates the error code and error message for the purpose of troubleshooting.