tencent cloud

All product documents
Tencent Cloud Super App as a Service
Decrypt Callback Messages
Last updated: 2025-04-03 11:36:38
Decrypt Callback Messages
Last updated: 2025-04-03 11:36:38
To ensure security, the superapp's payment encrypts critical information using AES-256-GCM in the callback notification API. Upon receiving the message, merchants need to decrypt it to obtain the plaintext. The APIv3 key is the symmetric key used for decryption. This document describes the format of the encrypted message and the decryption process.

1. Encrypted message format

AES-GCM is a NIST standard authenticated encryption algorithm that ensures data confidentiality, integrity, and authenticity. It is most widely used in TLS connections.
The encryption key used for certificates and callback messages is the APIv3 key. For details, see Development Parameter Application and Configuration.
For the encrypted data, we use a separate JSON object to represent it. For ease of reading, the example is pretty-formatted and includes comments.
{
"original_type": "transaction", // The type of object before encryption
"algorithm": "AEAD_AES_256_GCM", // Encryption algorithm
// Base64-encoded ciphertext
"ciphertext": "...",
// Random string initialization vector used for encryption
"nonce": "...",
// Additional data packet (may be empty)
"associated_data": ""
}

2. Decryption

For details of the algorithm API, see RFC 5116.
Most programming languages (newer versions) support AEAD_AES_256_GCM. You can refer to the following examples to understand how to implement decryption in your programming language.
JAVA:
import java.io.IOException;
import java.security.GeneralSecurityException;
import java.security.InvalidAlgorithmParameterException;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;
import javax.crypto.Cipher;
import javax.crypto.NoSuchPaddingException;
import javax.crypto.spec.GCMParameterSpec;
import javax.crypto.spec.SecretKeySpec;
public class AesUtil {
static final int KEY_LENGTH_BYTE = 32;
static final int TAG_LENGTH_BIT = 128;
private final byte[] aesKey;
public AesUtil(byte[] key) {
if (key.length != KEY_LENGTH_BYTE) {
throw new IllegalArgumentException("Invalid ApiV3Key. The length must be 32 bytes.");
}
this.aesKey = key;
}
public String decryptToString(byte[] associatedData, byte[] nonce, String ciphertext)
throws GeneralSecurityException, IOException {
try {
Cipher cipher = Cipher.getInstance("AES/GCM/NoPadding");
SecretKeySpec key = new SecretKeySpec(aesKey, "AES");
GCMParameterSpec spec = new GCMParameterSpec(TAG_LENGTH_BIT, nonce);
cipher.init(Cipher.DECRYPT_MODE, key, spec);
cipher.updateAAD(associatedData);
return new String(cipher.doFinal(Base64.getDecoder().decode(ciphertext)), "utf-8");
} catch (NoSuchAlgorithmException | NoSuchPaddingException e) {
throw new IllegalStateException(e);
} catch (InvalidKeyException | InvalidAlgorithmParameterException e) {
throw new IllegalArgumentException(e);
}
}
}
Python:
from cryptography.hazmat.primitives.ciphers.aead import AESGCM
import base64
def decrypt(nonce, ciphertext, associated_data):
key = "Your32Apiv3Key"
key_bytes = str.encode(key)
nonce_bytes = str.encode(nonce)
ad_bytes = str.encode(associated_data)
data = base64.b64decode(ciphertext)
aesgcm = AESGCM(key_bytes)
return aesgcm.decrypt(nonce_bytes, data, ad_bytes)
GO:
// DecryptGCM decrypts ciphertext using AES-256-GCM
func DecryptGCM(ciphertext []byte, key []byte, nonce []byte, additionalData []byte) ([]byte, error) {
block, err := aes.NewCipher(key)
if err != nil {
return nil, err
}
gcm, err := cipher.NewGCM(block)
if err != nil {
return nil, err
}


plaintext, err := gcm.Open(nil, nonce, ciphertext, additionalData)
if err != nil {
return nil, err
}
return plaintext, nil
}


Was this page helpful?
You can also Contact Sales or Submit a Ticket for help.
Yes
No

Feedback

Contact Us

Contact our sales team or business advisors to help your business.

Technical Support

Open a ticket if you're looking for further assistance. Our Ticket is 7x24 available.

7x24 Phone Support
Hong Kong, China
+852 800 906 020 (Toll Free)
United States
+1 844 606 0804 (Toll Free)
United Kingdom
+44 808 196 4551 (Toll Free)
Canada
+1 888 605 7930 (Toll Free)
Australia
+61 1300 986 386 (Toll Free)
EdgeOne hotline
+852 300 80699
More local hotlines coming soon