Connect to PayAPI
BBMSL Online Payment Service provides various APIs, which are named PayAPI for processing payment requests from the merchant. The APIs allow sensitive payment data to be exchanged between the merchant's backend and BBMSL accurately and securely.
While there are number of APIs available under different integration models, they are all standardized with the following characteristics,
Identification
Every onboarded merchant will be assigned to a merchant account with a unique merchant ID. The merchant is required to provide the merchant ID in every PayAPI request.
Connection Security
All APIs are protected by Transport Layer Security (TLS) protocol and whitelisting strategy. The request can only function properly over HTTPS connection, HTTP connection should not work.
Authentication and Message Security
Each message request to PayAPI is signed by the RSA key pair for verification. BBMSL authenticates the integrity of the merchant request by its digital signature. The signing details are included in the next section.
#
Signing PayAPI requestEach PayAPI request should include a signature signed by the merchant. Before performing any API request, the merchant needs to generate its own RSA key pairs (public and private key) and share the public key with BBMSL. The merchant should use the private key to sign the request message, and BBMSL will verify the signature with the shared public key.
Signature is not an independent API. It is a cryptographic measure to ensure integrity and non-repudiation.
About the signing
- Signing algorithm: 2048 bits RSA
- Hashing algorithm: SHA256
#
Key Generation using OpenSSLYou are not limited to use OpenSSL, you can use any tools to generate the key pair.
- Generate a new RSA keys pair
- Export public key
#
Exchange Public KeyAfter the RSA key pair is generated, you must exchange the public key with the BBMSL for signature verification by completing the following steps:
- Remove the public key header, footer and all line break
\n
from the following key string.
- Upload the processed key string below to BBMSL Merchant Portal and activate the key.
- Obtain BBMSL public key. Use the BBMSL public key to verify the notification signature. See Verify notification signature.
note
Please contact your relationship manager for the public key
#
Signing the RequestPrepare the request parameters in JSON format, and perform the following steps to sign the message,
- Prepare the content to be signed like the following,
Hash the JSON content by using SHA256withRSA algorithm. Then use the merchant's RSA private key to sign it as the signature. The length of the RSA key must be 2048 bits.
Base64 encode the signature, a sample result is shown below,
- Use the obtained string as the value of the
signature
parameter. The following sample shows a whole API request,
signing the request
The value of request
key must be in JSON string with backslash \
instead of JSON object.
#
Example Code#
Code Snippet for signing- Java
- PHP
To use above Java code, you need to perform same public key manual edit on the private key PEM file.