Signed Request Guide

All BasicEx Payment API requests that require authentication need to be strictly signed. This guide will walk you through the specifics of the underlying network encryption and signing process.

TIP

If you are using the BasicEx Payment SDK in various language environments, you do not need to consult this section. The SDK already encapsulates all signing logic and network request header configurations at the underlying layer. You simply need to provide the correct key or certificate.

When you must use a native HTTP request library to interact with the BasicEx API due to system limitations or special reasons, please follow the scheme of your choice on this page to complete the signature.

1. Common Rules for Signed Data (Building the Signature String)

Regardless of the encryption method you use, the concatenation logic for the "string to be signed" required by the algorithm is unified and fixed.

You need to concatenate: the complete request URL and the request data body (Body) directly. This is the core to ensuring data integrity and preventing tampering.

Extremely Important: Strict Consistency of Data Body

The request data body (Body) participating in the concatenation MUST be exactly identical, word for word (including spaces, line breaks, and field order), to the raw text body you actually send in the HTTP request. This is because our gateway performs verification by directly intercepting and extracting the raw byte text stream of the request. If, after calculating the signature, you format the JSON via some HTTP library (e.g., changing the field order, removing line breaks, or adding/deleting extra spaces), it will invariably cause the strings to be signed on both ends to mismatch, thereby leading to a signature verification failure!

Example of POST/PUT requests with a Body:

text

String to be signed = https://openapi.basicex.com/v2/invoices{"t": "123"}

Example of GET/DELETE requests without a Body: Composed solely of the request URL. Do not append any whitespace or line breaks.
text
```
String to be signed = https://openapi.basicex.com/v2/invoices/40620230828091249764130683289837
```

2. Choose Your Signature Algorithm

Depending on your configuration in the merchant portal, you can generate your X-Signature using either API Key (HMAC) or API Certificate (RSA).

Option A: Using API Key Signature (HMAC-SHA512)

This is a simpler and more lightweight integration method. In the merchant portal, you will obtain a pair of (ApiKey, SecretKey).

Calculate Signature: Use the HMAC module from the standard library of most programming languages. Use your Secret Key as the key to calculate the HMAC-SHA512 hash of the string to be signed mentioned above.
Encode Output: Encode the resulting binary data as a Hexadecimal string (Hex String). Make sure it is converted to all lowercase.
Set Request Headers: Place the ApiKey in the request header X-Api-Key. Place the aforementioned hexadecimal string signature in the request header X-Signature.
http
```
X-Api-Key: a48f12c...
X-Signature: c81a9f0322ba2e89b... (Hex encoded value)
```

Option B: Using Merchant API Certificate Signature (RSA)

This is a more rigorous and stricter authentication method. The API certificate issued by the merchant portal contains a public-private key pair. The private key is saved as a merchant_number.key file or in config.json. Please keep it extremely secure.

Calculate Signature: Extract your private key and execute an asynchronous signature using SHA-256 with RSA on the string to be signed.

Encode Output: Because the byte stream generated by the RSA signature is not composed of printable characters, the result must be Base64 encoded.

bash

# CLI test signature example
$ echo -n -e \
 "https://openapi.basicex.com/v2/invoices/40620230822134552202883210445009" \
 | openssl dgst -sha256 -sign 813161626275841.key \
 | openssl base64 -A

Set Request Headers: Since the certificate is needed to prove identity, you must also extract the public key certificate (the portion starting with -----BEGIN CERTIFICATE----- in a .cer, .crt, or .pem file).
- Note: Due to the HTTP Header specification's restriction on line breaks, you must remove all actual line breaks in the certificate file content to form a single line and place it in X-Identity!
- Next, place the Base64 encoded signature string into X-Signature.
http
```
X-Identity: -----BEGIN CERTIFICATE-----MIIFiTCCA3Gg... (single-line ultra-long string with newlines removed) ...DaxGmic/aWMjxLAVb7280RW6g=-----END CERTIFICATE-----
X-Signature: G8iDi8OsMVC5G7mOmwQ+tIrU7UrcsPgb... (Base64 encoded value)
```

3. Platform-Level Verification of Webhooks

When your backend passively receives a push from the BasicEx Payment system, you also need to verify the reliability of the data.

Because the verification instructions for BasicEx notifications are crucial and flow in the opposite direction of active API requests, we have extracted them into a dedicated Webhook Guide single page. 👉 If your service needs to respond to asynchronous funds notifications, it is strongly advised to review: Webhook Receiving and Signature Verification Principles

If your request encounters a 401 Unauthorized error status code response, please focus on checking the encoding conversion logic of the string to be signed or the HTTP Headers mentioned above.

Signed Request Guide ​

1. Common Rules for Signed Data (Building the Signature String) ​

2. Choose Your Signature Algorithm ​

Option A: Using API Key Signature (HMAC-SHA512) ​