Signature & Merchant API

SoPay merchant APIs use REST JSON with RSA2 headers (not legacy appId / bizContent).

Base URL prefix

/api/v1/merchant

Response envelope

{ "code": 0, "msg": "ok", "data": {} }

code = 0 means success.

Required headers

Header	Description
X-Merchant-No	Merchant id, e.g. M42
X-Timestamp	Unix time in seconds
X-Nonce	Unique random string
X-Sign	Base64 RSA2 signature

POST also requires Content-Type: application/json.

RSA2 sign string

1. GET: all query parameters
2. POST: flatten top-level JSON body fields
3. Add timestamp and nonce from headers
4. Exclude sign and empty values
5. Sort keys ASCII ascending
6. Join: key1=value1&key2=value2&...
7. Sign with merchant private key; encode Base64 → X-Sign

Callback verification

Platform signs callbacks with its private key. Merchants verify with the platform public key (same flatten + sort rules). The body is plaintext JSON — verify signature, do not decrypt.

Numeric fields: When completedAt is a JSON number (Unix seconds), flatten to a decimal integer string (e.g. 1782121882), not scientific notation. Amount fields are strings. See Webhook guide.

ACK success: HTTP 200 and body exactly OK.

See Webhook guide for worked examples, code, retries, and troubleshooting.