API Signature

Overview

This document describes the signature verification mechanism for TocoPay API. All API requests require signature verification to ensure the security and integrity of requests.

Signature Algorithm

Signature Steps

1. Collect Parameters: Collect all request parameters (including URL query parameters and request body parameters)
2. Remove Signature Field: If the request contains a sign field, remove it first
3. Add Timestamp: Add a timestamp field (Unix timestamp in seconds)
4. Sort Parameters: Sort all parameters alphabetically by key name (A -> Z)
5. Build Signature String: Concatenate parameters in key=value& format
6. Add Secret Key: Append &key=your_api_secret to the end of the signature string
7. Generate Signature: Perform MD5 encryption on the signature string and convert to uppercase

Signature String Format

param1=value1&param2=value2&timestamp=1234567890&key=your_api_secret

Important Notes

• Empty value parameters (null, undefined, empty strings) will be ignored
• Object and array type parameters will be converted to JSON strings
• Signature result must be in uppercase format
• Timestamp uses Unix timestamp (in seconds)

Multi-Language Implementation Examples

JavaScript (Node.js)

const crypto = require('crypto');

function generateSignature(params, apiSecret) {
    // Remove existing sign field
    delete params.sign;
    
    // Add timestamp
    params.timestamp = Math.floor(Date.now() / 1000);
    
    // Sort by key name
    const keys = Object.keys(params).sort();
    
    // Build signature string
    let dataString = '';
    keys.forEach(key => {
        const value = params[key];
        if (value !== null && value !== undefined && value !== '') {
            // Convert objects or arrays to JSON
            const stringValue = (typeof value === 'object') ? JSON.stringify(value) : value;
            dataString += key + '=' + stringValue + '&';
        }
    });
    
    // Add secret key
    dataString += 'key=' + apiSecret;
    
    // Generate MD5 signature and convert to uppercase
    const sign = crypto.createHash('md5').update(dataString).digest('hex').toUpperCase();
    
    return sign;
}

// Usage example
const params = {
    uid: 'your_merchant_id',
    amount: 100.00,
    currency: 'USD',
    order_id: 'ORDER123456'
};

const apiSecret = 'your_api_secret';
const signature = generateSignature(params, apiSecret);
params.sign = signature;

console.log('Signature result:', signature);
console.log('Complete parameters:', params);

Request Examples

Complete API Request Example

curl -X POST "https://api.tocopay.com/pay" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "your_merchant_id",
    "amount": 100.00,
    "currency": "USD",
    "order_id": "ORDER123456",
    "timestamp": 1640995200,
    "sign": "A1B2C3D4E5F6G7H8I9J0K1L2M3N4O5P6"
  }'

Error Handling

Common Error Codes

• 20041: Missing signature parameter
• 20042: Signature verification failed
• 20005: Missing merchant ID
• 30001: Merchant does not exist

Debugging Tips

1. Check Parameter Completeness: Ensure all required parameters are included
2. Verify Timestamp: Ensure timestamp format is correct (Unix timestamp in seconds)
3. Check Parameter Sorting: Ensure parameters are sorted alphabetically
4. Verify Signature Algorithm: Ensure MD5 encryption is used and converted to uppercase
5. Check Secret Key: Ensure the correct API secret key is used

Security Considerations

1. Protect API Secret: API secrets should be stored securely and not exposed in client-side code
2. Use HTTPS: All API requests should be made over HTTPS
3. Timestamp Validation: Consider validating request timestamps to prevent replay attacks
4. IP Whitelist: Consider configuring IP whitelist for enhanced security

Support

If you encounter any issues while implementing signature verification, please contact our technical support team.