1. Introduction#
The following content of this guide includes instructions on how to implement foreign exchange collection and settlement technology through the Whalet platform, divided into Public Message , Business API and Webhook Notification.1.1 Purpose#
The main purpose of this guide is to assist technology developers in mastering the cross-border foreign exchange collection and settlement methods and the use of payment platforms, and integrating them into existing systems.1.2 Target#
The target audience of this guide is product managers, system designers, technical developers, and testers of partners.1.3 Copyright#
The copyright of this document belongs to Xiamen Yijing Information Technology Co., Ltd. (hereinafter referred to as "Whalet"). As the end user of this system (hereinafter referred to as "Partner"), you may have the right to use this document, but without the written permission of Whalet, you shall not lend, assign or publish this document to any third party.1.4 Technical support#
If you have any questions about the connectivity and debugging of the APIs, please contact the relevant technical support staff according to the following methods during working hours.
product@whalet.com
Please alse browse this document with Demo. Demo will be synchronized with the changes of the document. Please ask the technical staff for the latest Demo and document if necessary.2. Public Message#
Use HTTPS communication protocol, and all use POST submission method.Use JSON as the common format for request and response messages, and use UTF-8 encoding format uniformly.
Message Mandatory Flag: M (Mandatory Option) O (Optional Option) C (Conditional Mandatory, specific conditions must be filled first).Request Message#
1.
The request message consists of two parts: the request message header and the request message body. The request message header information is within the header (head) node, and the request message body information is within the body (body) node.
2.
The message header is the same for every transaction. Please refer to the Public Request Message Header section for the filling standard of the request message header information.
3.
The message body of the request varies according to the interface definition of each transaction. Please refer to the Business API chapter for the definition of the request message body. The request message body needs to be assembled and parsed according to the interface definition of each transaction.
Response Message#
1.
The transaction response message consists of two parts: the response message header and the response message body. The response message header information is within the header (head) node, and the response message body information is within the body (body) node.
2.
The header of the message is the same for every transaction. Please refer to the Public Response Message Header section for the filling standard of the response message header information.
3.
The message format varies depending on the interface definition of each transaction. Please refer to the Business API chapter for the definition of the response message format. The response message format needs to be assembled and parsed according to the interface definition of each transaction.
4.
When the response message of the transaction is successful, the code in the header of the message is "SUCCESS", and the detail is "Successful". At this time, the node of the message body (body) can be empty or not empty according to the actual business needs.
5.
When the response message of the transaction is filded, error codes and error messages are filled in the code (return code) and detail (return description) fields of the message header, with the body node (body) being empty.
2.3 Encryption and Signature Methods#
To ensure the security of data, all transaction message transmissions need to be encrypted, signed, and verified.1.
Message encryption algorithms: AES/ECB/PKCS5Padding
2.
Session key generation: KeyGenerator
3.
Session Key Encryption Algorithm: RSA/ECB/PKCS1Padding
4.
Signature Algorithm：SHA1withRSA
Generating RSA key pairs#
For the partner, it is necessary to generate its own RSA key pair (including public and private keys), where the private key is kept by the partner and the public key is provided to WHALET.
For WHALET, it is necessary to generate a corresponding key pair for partner. Where the private key is kept by WHALET and the public key needs to be provided to the partner.Message Encryption and Signature#
1.
Use the KeyGenerator generator to generate an AES encryption session key SK.
2.
Use SK to encrypt the JSON plaintext (AES/ECB/PKCS5Padding), and convert the encrypted result to a HEX string to obtain the encrypt field.
3.
Base64 encoded the SK and Encrypt using the recipient's public key (RSA/ECB/PKCS1Padding), and converted the result to a HEX string to obtain the keyEnc field. Sign the requested "string to be signed" (UTF-8 encoded) using the sender's private key (SHA1withRSA), and convert the signature result to a HEX string to obtain the sign field.
Message Decryption and Verification#
1.
Convert the keyEnc field to a binary byte array, and use the private key of the recipient to decrypt the session key to obtain the plaintext SK;
2.
Base64 decoded the SK, Convert encrypt to a binary byte array, decrypt it using the session key SK obtained in the previous step, and obtain the plaintext json;
3.
Use the obtained "unsigned string", the sender's public key, and the sign field data to verify the signature's validity.
Request for Signature String#
All fields are concatenated in the following order using "|" symbol.partnerId，apiCode，version，requestNo from the corresponding field in the request header.
encrypt comes from request body encrypt field.Response to be Signed String#
All fields are concatenated in the following order using "|" symbol.partnerId，apiCode，version，requestNo，code and detail from the corresponding field in the response header.
encrypt from finally response encrypt field，where message(body) is empty,encrypt will be empty and not participate in the connection of the string to be signed.| field | type | length | required | description |
|---|
| partnerId | String | 30 | M | Partner id provided by Whalet |
| apiCode | String | 30 | M | API code |
| requestNo | String | 30 | M | Request serial number, unique |
| version | String | 3 | M | API version, fixed as 1.0 |
| sign | String | | M | Request message signature |
| keyEnc | String | | M | Session key |
| field | type | length | required | description |
|---|
| partnerId | String | 30 | M | Response as Request header Partner id provided by Whalet |
| apiCode | String | 30 | M | Response as Request header API code |
| requestNo | String | 30 | M | Response as Request header Request serial number, unique |
| version | String | 3 | M | Response as Request header API version, fixed as 1.0 |
| code | String | 32 | M | Response code SUCCESS indicates successful request |
| detail | String | 256 | M | Description |
| sign | String | | O | Response message signature |
| keyEnc | String | | O | Session key ciphertext |
2.6 Error Response Code#
| code | description | remark |
|---|
| SUCCESS | Success | |
| PROCESSING | Processing | Waiting for notification |
| FAILURE | Failed | Find the specific failure content in the detail’s attribute |
| TOO_MANY_REQUESTS | Too frequently | |
| PARTNER_NOT_EXIST | Partner not exists | |
| INTERNAL_ERROR | Internal error | |
| PARAM_FORMAT_ERROR | Parameter format error | |
| PARAMETER_ERROR | Parameter error | |
| IDEMPOTENT_ERROR | Idempotent error | |
| REQUEST_NO_NOT_UNIQUE | Duplicated request number | |
| UNAUTHORIZED | Unauthorized | |
| UNAUTHENTICATED_ERROR | Unauthorized error | |
| INTERFACE_UNAUTHORIZED | Unauthorized api | |
2.7 Webhook Notification#
For some APIs that cannot return results synchronously (the synchronization result status is PROCESSING), Whalet will send messages of different notification types (differentiated by ApiCode) to the notification URL provided by the partner through asynchronous notification after the service processing is completed, and the partner can handle its own business when receiving the notification and completing the corresponding message decryption and verification.
The partner needs to return the result within the specified time (which must meet the requirements of the public response format and requirements), and if the request times out, Whalet will retry according to the following rules:2.
The interval time is 1s, 2s, 4s, 8s, and 16s
3.
If it still fails after 5 attempts, Whalet will notify the partner offline
2.8 Message Example#
Request Definition#
ConnectivityGuideRequestBody
Request Example#
Response Definition#
ConnectivityGuideResponseBody
Response Example#
3 File Upload#
Use HTTPS and POST method to submit.The request format is multipart/form-data, and the response format is JSON.3.3 Token#
String to be signed#
Concatenate the fields with the "|" symbol in the following order.partnerId is the ID of parter, and timestamp is the current timestamp (milliseconds, 13 digits).Signature#
The signature string (UTF-8 encoding) is signed with the sender's private key (SHA1withRSA), and the signature result is converted to a HEX string as a token.Expiration#
Whalet will verify the token and check the validity period of the token according to timestamp, which is valid for 30 minutes and can be reused during the validity period.3.4 Request Example#
curl request#
postman request#
3.5 Sample Response#
Success Reponse#
{
"code": "SUCCESS",
"detail": "Success",
"info": {
"fileId": "202405011245158834940001",
"fileName": "demo.jpg",
"fileUrl": "https://test-file.whalet.com/2024-05-01/75ab32a9-cc98-46cb-9e8f-5c055fd9e4b5.jpg"
}
}
Error Response#
{
"code": "UNAUTHENTICATED_ERROR",
"detail": "invalid token",
"info": null
}
Notes#
1.
The supported file types: jpeg, jpg, png, gif, bmp, pdf, doc, docx, xls, xlsx, csv, txt, zip, rar
2.
The size limit for single file: 10M
Modified at 2025-04-22 06:07:09
