Signing Requests

---

All BasicEx Payment API requests that require authentication need to be signed. Use this guide to understand the process.

Merchant API Certificate

A merchant API certificate is obtained by the merchant and includes the merchant's merchant ID, company name, and public key information.

BasicEx Payment API uses certificates issued by BasicEx CA. Merchants can apply for and download their API certificate information through the merchant platform. The private key file in the downloaded certificate information must be securely stored.

Merchant API Private Key

The merchant's API certificate information, obtained and downloaded through the merchant platform, contains the private key file. The private key file is stored with the filename merchant_number.key. The private key information is also present in the config.json file. Do not disclose these two files to prevent unauthorized use of the private key.

Platform Certificate

The platform certificate is issued by BasicEx CA and used by the BasicEx Payment platform. In Webhook requests, BasicEx uses the private key associated with this platform certificate to sign the Webhook request. Merchants can use this platform certificate to verify that the Webhook request is initiated by BasicEx Payment.

Request Signature

If you are using the BasicEx Payment SDK, you don't need to consult this section. The data signing part is already encapsulated in the BasicEx Payment SDK. You only need to introduce the private key information and public key information during SDK initialization.

Merchants need to use the private key information to sign the API URL, as well as the combination of critical data such as the message body, using SHA-256 with RSA. The signature information is passed through the HTTP header: X-Signature. See the section Request Signature Generation for details. When BasicEx fails to verify the signature, it returns a 401 Unauthorized status error.

Additionally, when calling an API that requires authentication, you need to pass your certificate information in the HTTP header: X-Identity. Due to the limitations of newline characters in the header fields, you need to remove the newline characters from the certificate file content and place them. Here's a complete example:

X-Identity: -----BEGIN CERTIFICATE-----MIIFiTCCA3GgAwIBAgIUcNxzIbh9cRGZ5lNyyOctEMM2kJYwDQYJKoZIhvcNAQELBQAwPzELMAkGA1UEBhMCQ04xEDAOBgNVBAoTB0Jhc2ljRXgxHjAcBgNVBAMTFUJhc2ljRXggU2VydmVyIEVDQyBDQTAeFw0yMzA4MjQwOTExMTNaFw0yMzA5MjUwOTExNDNaMBoxGDAWBgNVBAMTDzgxMTMyNDA1MTU5NTI2NTCCASIwDQYJKoZIhvcNAQEBBQADggEPADCCAQoCggEBALdORJj7ZhFWTzgnzf9xIlOST5pVDRwyYYSNgwNKOnNO4VnsoSRGje/5QRwFsRx58TYEBMSgoZRKL4m+JXVNdA9KMaNwKZm6SPYeUsbR7el1sRvCay8/7qPt0DhDaxGmic/aWMjxLAVb7280RW6gjvTt/zZC04m9hoffWwuSUQr8UB3ZX8LNH0cp/vht497dk8CECGEURpP46FN0yXQwr8UbueE8Yk73EkGf/BpQsmxWZiwvsjSW1naFXwCxfRdeS3Nw3YGHmqLQr/D63dVkkofPZ/2x5BYMSFXyxCfa3FQ6SrlNDSqfLBxk66lEKGZS7rqPewv9EWUjk1V2TksfNZ8CAwEAAaOCAaAwggGcMA4GA1UdDwEB/wQEAwIDqDAdBgNVHSUEFjAUBggrBgEFBQcDAQYIKwYBBQUHAwIwHQYDVR0OBBYEFDKNo7RhqLsE36RVQrCSVsSZqmLQMB8GA1UdIwQYMBaAFO4lJSiwmdhLS3nRqW6L2ceACPB7MIGlBggrBgEFBQcBAQSBmDCBlTAzBggrBgEFBQcwAYYnaHR0cHM6Ly8xOTIuMTY4LjMxLjIyNTo4MjAwL3YxL3BraS9vY3NwMF4GCCsGAQUFBzAChlJodHRwczovLzE5Mi4xNjguMzEuMjI1OjgyMDAvdjEvcGtpL2lzc3Vlci80OWE4YmNjYi0wYzAzLTNjOGItZTQ4NS1hMzlhODY2MjZmNmEvZGVyMBoGA1UdEQQTMBGCDzgxMTMyNDA1MTU5NTI2NTBnBgNVHR8EYDBeMFygWqBYhlZodHRwczovLzE5Mi4xNjguMzEuMjI1OjgyMDAvdjEvcGtpL2lzc3Vlci80OWE4YmNjYi0wYzAzLTNjOGItZTQ4NS1hMzlhODY2MjZmNmEvY3JsL2RlcjANBgkqhkiG9w0BAQsFAAOCAgEAGdJV5hoKk0/hYxgdIVOzanIfV3MsixLyBo0VUU46mAUnHBdzyoDTpguDLLHScCUZMA7R23TZxJH2+2wh4MQyYnqXfTNrW0ENipUIXi/j0YGHMF6VhJSfFhkh3qmLoSZxJa2yt+QwxjWdETUp9wgAIFLOSNL9D2a7KBZiNR8aZO4aPR0Fy/OIXxWRkc6VihlJeKIQz3u0dgZ1P9fJEb9mHmz4qwAMOX2R/n9jUitwFf5HpID8ou+21zFZaERf6/Mg6aTWwvYCGjrUq7G0EhTwr8xQ+I+94apBVteUujYP7XhWiT/KxTZMFbztNj+/dwyMeL1KqEBG8mYkxm5fdFbkSySQZWqKVj9988TLGNEW0hCgOyYoWS6Bf7tkd3IGCAsfaAaU3T0h0MvtzvWg2IzIjqoV0svEBN8AmRZUkPjrPX8Qkx3dE5qe7L5pKHZCH4l23x46+Fbk3ywQsXPnD4WLC1Cn7xDO76HCXxz8q3+MTMgdpDFHH02w2f8o02zWDaajB39bpbfESInAGz+1vkm0bykABjig8Hrcl40hezxSIdW6/M41/0Ghh8KRhnt29SeRBFXO0V2fimRSLPvMxVmbrWUNJBK0JJpLKNfZ1S7MGLPLWJWNyvH6hG2PBJsF3yVp+JBNYyO5bFYw5P5YSpP9WEOUmKFScPXZUVvPedy8PgY=-----END CERTIFICATE-----
X-Signature: G8iDi8OsMVC5G7mOmwQ+tIrU7UrcsPgb5/w25kBL/g6VoTQVdpGzJoGqYtYm3ZKICIe8ax07TBKmyDQD4Z6bw7Ta2Iy64wxcZyI9Uy6EsCxxM8au2bmk/Qm7bsqV0mbv7iLyMKUTjYeTOLvtKNxv3rZ35JAdBYQ6YONBW01Un/R1C9I5uxL7M4N6TtIhjPGNr+PTxQM6f1MA5+pkMAy98A1SZqVeb2lwZJu1eJNzNOY9VcuU9P+6POkToNm2sj/KvOktw6d1p6uJ4aTRZ3FA7knz9A4nbWym/N6nRGyUiGa31RTXCeg/INgE0MTcWeUnJGRV19UePbZ69gN9jVbhIg==

Request Signature Generation

Build Signature String

We expect the technical developers of the merchant to construct the signature string according to the rules specified in this document. BasicEx Payment will construct the signature string in the same way. If the merchant constructs the signature string incorrectly, it will result in signature verification failure.

The signature string is composed of the request URL and the request data body directly concatenated. For example:

https://openapi.basicex.com/v2/test{"t": "123"}

For GET requests or similar requests without a request data body, the signature string is composed of the request URL alone. For example:

https://openapi.basicex.com/v2/invoices/40620230828091249764130683289837

Calculate Signature Value

Most programming languages provide signature functions that support signing of signature data. It is strongly recommended that merchants call such functions, sign the signature string with their private key using SHA-256 with RSA, and base64 encode the result to obtain the signature value.

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

Set Signature Request Header

BasicEx Payment API requires the signature to be passed through: X-Signature, and the certificate information to be passed through: X-Identity. Due to the limitations of newline characters in the header fields, you need to remove the newline characters from the certificate file content and place them. See the Request Signature section for a specific example.