Authentication and IP whitelist

Order of checks

Each request is checked in the following order. If any check fails, an error is returned:

  1. Signature: api_identity must be an active credential, and sign must be correct. If not, invalid_signature (HTTP 401) is returned.
  2. Timestamp: timestamp is required, in the format yyyy-MM-dd HH:mm:ss (UTC+8), and must not differ from the ST Pay server time by more than 5 minutes. If it is missing, missing_parameter is returned; if the format is invalid, invalid_parameter; if it differs by more than 5 minutes, timestamp_expired (HTTP 400). The timestamp is checked only after the signature passes, so a tampered timestamp returns invalid_signature.
  3. Source IP: The source IP must be on the merchant's API whitelist. If the whitelist is empty, all requests are rejected. If not, ip_not_allowed (HTTP 403) is returned.
  4. Merchant status (checked only when creating an order): A disabled merchant cannot create orders, and merchant_disabled (HTTP 403) is returned. You can still query orders while disabled.

Keeping your secret key safe

  • Keep the secret key only on your server. Never put it in web pages, apps, or any program distributed to end users.
  • If your secret key is leaked or lost, contact ST Pay immediately to create a new credential and disable the old one.

Key rotation

A merchant can have multiple active credentials at the same time, and each of them can be used to call the API. Callbacks are always signed with the secret key of the most recently created active credential, so we recommend rotating your key in the following order:

  1. First, make your Callback signature verification able to accept two keys at the same time. (You will only receive the new key after step 2, but you can prepare the place where it will be configured in advance.)
  2. Ask ST Pay to create a new credential, and add the new key to your Callback signature verification. As soon as the new credential is created, Callbacks are signed with the new key. Callbacks received before you add the new key will fail signature verification; confirm those orders with an order query, or ask ST Pay to resend them.
  3. Switch your API calls to the new api_identity and secret key.
  4. After confirming that no requests use the old credential anymore, ask ST Pay to disable the old credential, and remove the old key from your Callback signature verification.