# 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](/partners/online-payments/embedded-components/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:

```json
{ "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:

```php
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

| Environment | Static IP |
|-------------|-----------|
| Production | 63.35.101.166<br>63.34.233.45<br>34.252.138.105 |
| Development | 34.248.215.221<br>34.247.185.175<br>52.19.244.188 |

## 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