Skip to main content

Security

Authentication Mechanism​

Every request to Baokim API requires client identity authentication before processing. Baokim uses OAuth2 with JWT Bearer Token:

  1. Merchant calls /b2b/auth-service/api/oauth/get-token API with merchant_code, client_id, client_secret.
  2. Baokim returns access_token (JWT) with validity period (expired_at).
  3. Merchant attaches token to each request header: Authorization: Bearer <access_token>.

If token expires or is invalid, Baokim returns authentication error and request is rejected.

Request Signing​

In addition to token authentication, Baokim requires digital signature on entire request body to ensure data integrity during transmission.

Signing process:

  1. Get the data to sign:
    • For POST: get the entire raw JSON string of the request body.
    • For GET: get the query string sorted alphabetically (there is no request body).
  2. Sign using SHA256withRSA (or SHA1withRSA for VA direct) with merchant's private key.
  3. Base64 encode the signature string.
  4. Place in header: Signature: <base64 encoded string>

Baokim uses merchant's public key (exchanged during integration) to verify the signature. If signature is invalid, request is rejected with signature verification error.

In reverse direction, Baokim also signs response and webhook sent to merchant — merchant should verify Baokim's signature to ensure data integrity.

Idempotency​

In unstable network environments, a request may be sent multiple times. To prevent duplicate transactions, Baokim uses Idempotency via request_id field:

  • Each request must have a unique request_id (generated by merchant).
  • If Baokim receives two requests with same request_id, Baokim processes only the first one and returns old result for subsequent ones — no new transaction created.
  • Recommended format: {merchant_code}_{YYYYMMDDHHIISS}_{unique_id}.

⚠️ Important: For order creation / transaction creation APIs, request_id must be unique for each new creation. Do not reuse request_id from old transactions when creating new ones.