By understanding the Solidgate validation and authentication process for API requests, you can gain access to the API and effectively handle validation error messages. Obtain the required credentials, including public and secret keys, and follow the signature creation and webhook validation steps to enable secure payment processing, proper authentication, and error management.
Retrieve your credentials
To start accepting payments, even in the sandbox environment, you require credentials. These credentials are the Public
publicKey
and Secret
secretKey
keys, which should be applied for direct API calls and to check the webhook signature.
Obtain the keys from the personal account in the Solidgate Hub by navigating to the Developers > Channel details page:
- API keys have the prefix
api_pk_/api_sk_ - Webhook keys have the prefix
wh_pk_/wh_sk_
The Public and Secret keys are applied to calculate the signature, verifying both the source and the integrity of the request details transmitted between the merchant and gateway.
Generate signature
The signature value is a base64-encoded string, which is a hexadecimal representation of the SHA-512 hash function. The encryption key used for this is the Secret key.
Use the string resulting from the concatenation to create a signature: publicKey + jsonString + publicKey
publicKey + publicKey
| Field | Description | Test data |
|---|---|---|
| publicKey | Public key. | api_pk_8f8a8k8e8k8e8y8 |
| jsonString | Request body in JSON string. | {“amount”: “100”, “currency”: “USD”} |
| secretKey | Secret key. | api_sk_8f8a8k8e8k8e8y8 |
| *Public and Secret keys, provided during merchant registration, are essential for generating secure signatures used in authentication and verification. | ||
- Use the
generateSignaturefunction, which takes the data and the Secret key as parameters. - Generate the HMAC-SHA512 hash using the Secret key and data.
- Get the hexadecimal representation of the hash.
- Encode the hexadecimal representation of the hash directly to Base64.
| Expected signature with test data | ||
|---|---|---|
| MjFkZGE3ZTZjODc0YjY5YTczOTlmOTBlYjk0MDY1NThiODJiZmE3ZTgxOGJjMWUxYjNkNTFjMDNjZmUzOGRlMTBhZGEzMmYxMGY3NTBlOTBlMGZkNDUwZTRiNmI5YTBiYTVmZWM5NzcxMjU3OWM0MGU5Mzg1NTljOTE1NTVlNzA= | ||
Authenticate your API request
To authenticate, add the following headers to each request:
| Field | Description | Example |
|---|---|---|
merchant |
Unique Public key is provided upon registration and must be shared for identification purposes. | api_pk_7b197xxxxxxxxba108f842 |
signature |
Request signature allows verification of the merchant's authenticity on the payment gateway server. | MjNiYFdSdjVjxxxxxxhYmNiZDY |
Solidgate uses a similar authentication method for webhooks, with merchant and signature parameters included in the headers.
If you receive an incorrect signature response, verify your API keys and encryption value, then contact the Solidgate support team for further assistance.Outgoing requests for IPs
Specific IP addresses are used for outbound requests to external services for secure and effective communication. Allowing traffic from these IP addresses in your system is crucial to ensure uninterrupted service and data exchange.
Security Configure your security systems to accept these IPs to prevent service interruptions. Monitoring Stay informed about any changes to these IP addresses for continuous service.| IP addresses |
|---|
| 3.74.184.6 / 3.121.136.242 |
| 18.156.25.95 / 18.157.254.13 / 18.157.119.243 / 18.184.24.146 / 18.192.168.222 / 18.195.90.222 |
| 35.157.172.91 / 35.165.202.104 |
| 44.224.79.149 |
| 52.10.37.135 / 52.88.195.65 |
Handle WAF errors
The Blocked by WAF error indicates that a Web Application Firewall (WAF) has prevented an API request due to a security and legal policy violation. This error often arises from mismatched endpoints and base URLs in API requests.
Ensure that the endpoint and base URL used in your API requests are correctly paired to avoid this error. Verify that the endpoint matches the intended action and follows the Solidgate API reference.
- Confirm that the full URL used in your API request aligns with the valid endpoints provided in the Solidgate API reference.
- Ensure that the endpoint corresponds to the appropriate base URL.
For example, if you attempt to cancel a subscription using the endpoint /subscription/cancel-by-customer at the base URL pay.solidgate.com/api/v1 , you may encounter a Blocked by WAF error. The correct base URL for subscription actions is subscriptions.solidgate.com/api/v1 .
The WAF is configured to block IP addresses from sanctioned countries to increase security and ensure compliance with international regulations. To avoid this issue, ensure your IP address is not from a sanctioned country.Rate limits
Rate limiting controls the frequency at which requests are made to API endpoints within specific time periods. It helps protect against service overload while ensuring consistent performance for all clients. Exceeding limits leads to a 429 Too many requests error response.
API usage limits
Solidgate returns the 429 error response when necessary to protect legitimate merchant traffic.
Rate limits differ by endpoint based on operational and reliability needs. The Solidgate team continuously monitors system performance and may adjust these limits as needed to maintain optimal service quality.
For endpoint-specific rate limit information, visit the Developers section in the Solidgate Hub , which is updated as changes occur.
Handle rate limits
You can handle rate limiting by monitoring for the 429 Too many requests error response. Effective handling combines retries and overall request flow control.
A widely used approach for handling rate limit error responses is implementing exponential backoff Wiki with jitter. This method retries requests using short initial delays that increase after each failure. Introducing randomization, or jitter, helps avoid conflicts caused by multiple clients retrying simultaneously.
While retries are useful, a significant improvement comes from regulating request flow across the entire application. The token bucket Wiki algorithm is standard practice for this purpose. It allows short bursts of requests while enforcing an average request rate over time, reducing traffic spikes and improving overall stability. Token bucket implementations exist in many programming languages and can be applied client-side to reduce failed requests and maintain consistent performance.
By following these practices, your application can handle rate limits smoothly, avoid unnecessary request failures, and maintain reliable performance when interacting with the Solidgate APIs.