Signing & Notifications
Request Specification & Signing
Request Domain
The Feishu API reference confirms this Singapore endpoint. Obtain the test endpoint, credentials and charging scope separately; do not assume this URL is a sandbox.
Request Specification
Signing Method
All platform APIs only support JSON-formatted requests. Ensure Content-Type: application/json is included in the HTTP request header.
All request bodies must use UTF-8 encoding. All responses will use the same encoding.
All platform API calls require signature verification.
Sign the exact UTF-8 bytes sent. Serialize JSON once before signing; changes to order, whitespace, escaping or a trailing newline require a new signature.
Authorization contains the caller serial number and signature. For transaction APIs it must match terminal_sn in the body.
Signature Algorithm (V2):
Concatenate the raw HTTP body bytes with the secret: vendor_key for activation, terminal_key for the other business APIs on this page.
Where HASH supports both MD5 and SHA256:
- Use
MD5by default - Alternatively use
SHA256for enhanced security - Specify the algorithm via
Authorization-Typeheader (md5 or sha256) - If
Authorization-Typeis omitted, defaults to md5
Signature Header Format:
Use one ASCII space between serial number and signature. Algorithm names are lowercase md5 / sha256; hex comparison is case-insensitive. This is HASH(body + key), not HMAC.
All response parameters are in JSON format.
Respect field types: result_code and amounts are commonly strings; biz_response / data / extended are objects, collections are arrays, and error fields may be null or absent.
Represent SGD amounts as integer-cent strings, for example SGD 1.00 = "100", without floating-point arithmetic. Merchant/channel configuration determines currency.
Credential Tiers
Request Example
Local Signature Test Vector
Fictional credentials for byte/encoding verification only, not API credentials. The body has no trailing newline. The complete example uses this SHA256 vector for selftest.
The cURL snippets illustrate request shape; compute <sign> from the final body. Use the complete Python example first to avoid signing different JSON from what is sent.
Callback Verification
Callback Signature Verification
Gateway V2 payment notifications use SHA256withRSA; cancellation payloads are described separately. Verify the raw request body before processing business data.
- Use the entire
Authorizationheader as the RSA signature, without aterminal_snprefix. - Read and retain the exact UTF-8 body bytes; do not parse and reserialize before verification.
- Use the platform public key for the environment; confirm distribution and rotation before launch.
- Verify with the platform public key using SHA256withRSA, then parse JSON and validate the order and amount.
- After durably recording a valid notification, return HTTP 2xx and plain-text
success. Invalid signatures must not update orders.
Response Signature Verification
Normal business responses use V2 signatures over the exact response bytes. Early authentication errors may lack a valid signature; treat them as diagnostics, not trusted business outcomes.
Use the request algorithm and matched terminal_key for ordinary responses. Activation responses use vendor_sn / vendor_key. A successful check-in response uses the newly returned terminal_key.
Callback Notification
The payment platform pushes payment results to the merchant system via HTTP POST. Must implement, but should not be the sole method of result confirmation.
API Information
- Direction: Payment Platform → Merchant Server
- Method: POST Content-Type: application/json
- Verification: RSA SHA256WithRSA — obtain sign from Header Authorization, verify with public key
Callback Parameters (Core)
Verification Flow
- Retain raw body bytes and the full
Authorizationsignature - Verify SHA256withRSA using the environment public key
- Parse JSON and check order, amount, transaction type and state
- Durably record the event; process business effects idempotently
- Return HTTP 2xx with plain-text
success(no quotes/newline)
Required Response
Return HTTP 2xx with exactly lowercase success, without quotes, spaces or newline, after verification and durable storage.
- Make effects idempotent by transaction type, tsn and state within the merchant/order scope; permanent deduplication by sn alone would drop later refunds.
- Never skip signature verification before processing business logic.
- Use callbacks alongside proactive query polling — never rely on callbacks alone. Requery the same order and transaction on conflicts. Do not overwrite newer state with an old notification; escalate persistent inconsistencies.
Notification Delivery and Handling
Payment Notification Example
This is a minimal example with fictional values. The real payload is a direct JSON object, without a biz_response wrapper. tsn/type/status identify the transaction and state; client_tsn is its external identifier. A refund event is not a new payment.
Node.js Verification Function
Uses the Node.js standard library. rawBody must be the original Buffer before JSON middleware modifies it. This function uses the Base64 encoding found in the local SDK; validate an authentic target-environment notification with Chinese text before launch. See verification scope.
Delivery and Acknowledgment
The checked gateway sends immediately, then retries after 1, 5, 30 and 600 seconds , at most four retries (five total attempts). Non-2xx, network failure, empty bodies, or quoted/newline-terminated success trigger retries. Delivery is not indefinite; compensate with queries and reconciliation. Verify and durably store first, acknowledge promptly, then perform slower business work asynchronously. No universal receiver timeout SLA is confirmed.
Cancellation Has a Different Payload
The verified pre-cancel path, when no order exists and pre-cancel is allowed, can send the following payload to cancel_notify_url. It has no payment sn/type/order_status and does not prove that funds were refunded. Delivery scope depends on device/routing and must be tested. /mis/close accepts an explicit cancellation URL.
In the checked Allinpay/KPay pre-cancel route, the proxy replaces the request terminal_sn with the target payment terminal ID, which the gateway includes in the notification. In this example, the caller is 2101107140290972547 and the target payment terminal under the same merchant is 2101107140290972548; the payload contains the latter. After signature verification, correlate out_trade_no using verified merchant/device mappings. Do not require the notification terminal ID to equal the caller ID.
Apply the gateway RSA verification and plain-text acknowledgment rules. Deduplicate the cancellation operation within the original order and query the final outcome. Do not require cancellation events to contain payment transaction fields.
Signature Summary
All API calls use the V2 signing mechanism. The signature is computed as HEX(HASH(request_body_bytes + secret_key)), where HASH supports both MD5 and SHA256. Specify the algorithm via the Authorization-Type header (defaults to md5).
