Welcome to Transafe

Welcome to Transafe. Transafe provides one-stop payment services. This is the technical integration documentation. Please read the required sections carefully. Contact Transafe support if you need help during integration.

Integration can be completed independently without Transafe staff involvement. If you encounter issues, review this documentation first.

Best Practices

1. WARNING

   For create-payout APIs, always check the HTTP status code. If it is not 200, confirm the order status with operations before resubmitting.

2. For collection callbacks, always verify the actual paid amount.
3. Add your server IPs to the merchant console IP allowlist.
4. Allowlist Transafe callback IPs on your callback endpoints.
5. Avoid repeatedly calling the collection API for the same user and amount within a short interval.

Conventions & Notes

1. When asking for support, provide: request URL, request parameters, response HTTP status code, and response body. For signature issues, provide the pre-sign string, environment, and the signature received/generated.
2. All POST requests must use Content-Type: application/json.
3. Collection/payout platform callbacks must return HTTP 200. Otherwise the platform retries up to 5 times within 12 hours, then stops.
4. Character encoding: UTF-8.
5. Data format: JSON for both request and response.
6. Signature algorithm: OPENSSL_ALGO_SHA256 (merchant private key signs; platform public key verifies).
7. Evaluation order: protocol fields → business fields → transaction status.
8. Amounts use major currency units. Avoid unnecessary trailing zeros: 100.00 ❌, 100.20 ❌, 100 ✅, 100.2 ✅.
9. Sandbox supports automatic callbacks: odd last digit of phone → success, even → failure.
10. Name + phone + email + amount identify customers. Do not hard-code all of them. Use a stable name + phone + email per customer to avoid risk-control false positives.
11. All responses include a status field. Non-200 means failure. Map status enums for user messaging; do not expose raw msg (it may contain sensitive information).
12. Request payloads must not contain Chinese characters.

Next Steps

• Quick Start
• Signature & Verification
• Sandbox Configuration
• Global Payments