Skip to content

Callback Signature and Encryption ​

Introduction ​

This document describes the signature and encryption requirements for callback APIs (SUD OP SVR → APP server). For key configuration, algorithm parameters, calculation examples and the complete calling-direction flow, see Server API Signature and Encryption.

No additional keys are involved in the callback direction. Callback requests are verified with the SUD OpenPaaS certificate and decrypted with the symmetric key configured in Chapter 2 of Server API Signature and Encryption; callback responses are signed with the application private key and encrypted with the symmetric key.

Mandatory: Callback APIs have no plaintext mode. Every callback request must be verified and then decrypted. If either step fails, reject the request immediately without entering business logic.

I. Roles and keys ​

In the calling direction the APP server encrypts and signs the request, then verifies and decrypts the response; in the callback direction it is the other way round — the same key set, with the signer and verifier swapped.

StepKey or certificateHow the peer validates
Verify callback requestPublic key in the SUD OpenPaaS certificate—
Decrypt callback requestSymmetric key—
Encrypt callback responseSymmetric keySUD OP SVR decrypts with the symmetric key
Sign callback responseApplication private keySUD OP SVR verifies with the application public key

II. Callback request processing ​

Process in the order verify → decrypt → business checks. If verification or decryption fails, return a non-200 status code instead of a business result.

2.1 Request headers ​

HeaderRequiredDescription
X-Sud-AppIdYesCurrent AppId, which must match _appid in the decrypted plaintext
X-Sud-TimestampYesTimestamp when the platform generated the callback request (seconds)
X-Sud-SignatureYesPlatform signature, Base64 encoded

The formula, delimiter and the way data is obtained are defined in 3.2.1 of Server API Signature and Encryption. In the callback direction only urlpath differs:

  • urlpath is the full URL of the callback address itself (including scheme and host, excluding the query string) and must match the value configured in the SUD OP console character by character;
  • data is the raw bytes of the HTTP body (the ciphertext payload); never re-serialize it after parsing.

2.2 Decryption and verification ​

Follow Chapter 3 of Server API Signature and Encryption for decrypting and verifying the request body.

III. Signing callback responses ​

Responses must also be encrypted and signed; the verifier is SUD OP SVR. All signature-related response headers carry the APP server's own values.

3.1 Response headers ​

HeaderRequiredDescription
X-Sud-AppIdYesApp ID
X-Sud-TimestampYesTimestamp when the APP server generated the response (seconds)
X-Sud-SerialYesApplication asymmetric key serial number, used by the platform to select the application public key
X-Sud-SignatureYesSignature produced with the application private key over the response payload, Base64 encoded
X-Sud-Serial-DeprecatedNoApplication key serial number about to expire (returned during application key rotation)
X-Sud-Signature-DeprecatedNoSignature made with the expiring application key, Base64 encoded (returned during rotation)

These headers share their names with open API responses but come from a different source: open API responses are signed by SUD OP SVR with the platform certificate, whereas callback responses are signed by the APP server with the application key. Do not reuse the certificate serial or the platform signature just because the names match.

3.2 Encryption and signing ​

Follow Chapter 3 of Server API Signature and Encryption for encrypting and signing the response body.