Message encoding prevents errors and ambiguity caused by special characters during transmission. Proper encoding ensures data integrity across all API communications.
Encoding Requirements
Byte Data (Signatures & Encrypted Content)
All binary data including signatures and encrypted content must be Base64 encoded before transmission.
Method: Base64 encoding
// Encoding a signature
const signature = crypto.sign('RSA-SHA256', data, privateKey);
const encodedSignature = signature.toString('base64');
// For URL-safe contexts, use base64url
const base64UrlSignature = signature
.toString('base64')
.replace(/\+/g, '-')
.replace(/\//g, '_')
.replace(/=/g, '');
import base64
# Encoding a signature
signature = sign_data(data, private_key)
encoded_signature = base64.b64encode(signature).decode('utf-8')
# For URL-safe contexts
url_safe_signature = base64.urlsafe_b64encode(signature).decode('utf-8').rstrip('=')
HTTPS URL Data
URLs must be percent-encoded before transmission to handle special characters correctly.
Method: URL encoding (percent-encoding)
| Original | Encoded |
|---|
https://www.merchant.com/callback?order=123 | https%3A%2F%2Fwww.merchant.com%2Fcallback%3Forder%3D123 |
https://example.com/path with spaces | https%3A%2F%2Fexample.com%2Fpath%20with%20spaces |
// URL encoding
const callbackUrl = 'https://www.merchant.com/authorizationResult';
const encodedUrl = encodeURIComponent(callbackUrl);
// Result: https%3A%2F%2Fwww.merchant.com%2FauthorizationResult
from urllib.parse import quote
callback_url = 'https://www.merchant.com/authorizationResult'
encoded_url = quote(callback_url, safe='')
# Result: https%3A%2F%2Fwww.merchant.com%2FauthorizationResult
Character Sets
Request Body
- Encoding: UTF-8
- Content-Type:
application/json; charset=UTF-8
All JSON request bodies should be UTF-8 encoded. Special characters in string values are automatically handled by JSON serialization.
const requestBody = {
orderDescription: "Café latté × 2", // UTF-8 characters
extendInfo: JSON.stringify({ note: "特殊字符" })
};
// Send with proper content-type
fetch(url, {
headers: { 'Content-Type': 'application/json; charset=UTF-8' },
body: JSON.stringify(requestBody)
});
Signature Calculation
When calculating signatures, the content to be signed must be properly encoded:
Construct String
Build the string to sign from HTTP method, URI, headers, and body
Encode to Bytes
Convert the string to UTF-8 bytes
Sign
Apply RSA-SHA256 signature algorithm
Base64 Encode
Encode the binary signature as Base64
// Complete signature flow
const contentToSign = [
'POST',
'/api/open/v2/payments/pay',
clientId,
requestTime,
JSON.stringify(body)
].join('\n');
// Convert to bytes (UTF-8)
const bytes = Buffer.from(contentToSign, 'utf-8');
// Sign
const signer = crypto.createSign('RSA-SHA256');
signer.update(bytes);
const signature = signer.sign(privateKey);
// Base64 encode
const encodedSignature = signature.toString('base64');
Common Encoding Scenarios
| Data Type | Encoding Method | Example Use Case |
|---|
| Signature | Base64 | Signature header value |
| Encrypted data | Base64 | Sensitive field encryption |
| Callback URLs | URL encoding | paymentNotifyUrl parameter |
| JSON body | UTF-8 | Request body transmission |
| Extended info | JSON string | extendInfo field |
Best Practices
Double Encoding: Be careful not to encode data twice. If you URL-encode a value and then include it in a JSON body that gets URL-encoded again, you’ll have double-encoded data that won’t decode correctly.
