Troubleshooting & Other Resources

Common Issues

SDK calls fail / staging payments not appearing

If initTeyaBlocks() succeeds but element submissions return unexpected errors, or if successful test payments never show up in your staging Business Portal, you are most likely calling production with a staging session token.

• Set developmentMode: true in the initTeyaBlocks() options object - see SDK Initialization
• Confirm your server is calling https://api.teya.xyz (not api.teya.com) when creating the session
• Confirm you are not setting developmentMode: true in your production build

API calls return 403 Forbidden as an HTML page

If an API call returns a plain HTML 403 Forbidden page instead of a JSON error, the request is being blocked before it reaches our API. Our API always returns errors as JSON, for example:

{ "code": "FORBIDDEN", "message": "..." }

The most common cause is a missing User-Agent header. Always send one identifying your integration.

This catches PHP integrations in particular, because curl does not send a User-Agent unless you set it explicitly:

curl_setopt($ch, CURLOPT_USERAGENT, 'YourCompany-Integration/1.0');

Note that the user_agent setting in php.ini does not apply here - it only affects PHP's HTTP stream wrapper (file_get_contents, fopen), not curl.

Webhook / Callback URL not received

1. Check firewall settings
   a. It is common for CDNs like Cloudflare to block requests suspected of being bots. We recommend allowing the Teya IPs to prevent this.
2. Verify the SSL certificate
3. Test webhook URL accessibility
4. Check signature verification
5. Whitelist Teya IPs

Token Expiration

• Verify the token refresh mechanism
• Check system clock synchronization
• Implement proper error handling
• Use appropriate cache duration

API invocation failures

• Verify API credentials
• Check request format
• Validate currency conversion
• Test with different amounts

Signature Verification Fails

For Payment Webhooks:

• Ensure the correct key is used. The public key is created by Teya when the merchant creates the webhook via the Teya Business Portal, and it is unique per webhook.
• Verify SHA256withRSA algorithm implementation

Teya Outgoing (public) IP addresses to whitelist in the firewall

API usage Best Practices

• Always send a User-Agent header identifying your integration
• Always implement retry logic for network failures
• Use exponential backoff to avoid overwhelming the API in case of errors
• Handle 401 (unauthorized) by refreshing tokens
• Handle 429 (rate limited) by waiting before retry
• Log errors for debugging, but don't expose sensitive data

Security Best Practices

1. Credential Storage

• Store merchant credentials safely and avoid sharing them
• Use environment variables for sensitive data
• Implement proper access controls

2. Webhook Security

• Always verify webhook signatures
• Use timing-safe comparison functions
• Implement replay attack protection
• Log security events

3. API Security

• Use HTTPS for all communications
• Implement proper timeout handling
• Validate all input data
• Use idempotency keys for critical operations

4. Data Protection

• Never store sensitive payment data
• Use secure session management
• Audit data access logs