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
generateSignature
function, 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_7b197……..ba108f842 |
signature |
Request signature allows verification of the merchant's authenticity on the payment gateway server. | MjNiYFdSdjVj……..hYmNiZDY |
Solidgate uses a similar
Subscribe for events on your Solidgate account so your integration can automatically trigger actions.
authentication method
for webhooks, with merchant and signature parameters included in the headers.
|
|
Outgoing requests for IP addresses
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.
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 |
Handling 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.
-
Check the full URL
Confirm that the full URL used in your API request aligns with the valid endpoints provided in the Solidgate API reference. -
Verify endpoint-base URL pairing
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 https://pay.solidgate.com/api/v1 , you may encounter a Blocked by WAF error. The correct base URL for subscription actions is https://subscriptions.solidgate.com/api/v1 .
Rate limits
Rate limiting is a crucial technique to control the frequency at which requests are made to services. It aims to prevent resource abuse, ensure fair usage, and protect servers from overloads. Rate limiting serves several purposes:
- Manage resource utilization: Helps ensure servers maintain optimal performance, preventing overloads that can lead to service disruptions.
- Improve user experience: Controlling request rates reduces delays, ensuring a smoother experience, especially for real-time services.
- Reduce costs: Avoids unnecessary resource consumption that could lead to higher operational costs.
A standard method limits users to a set number of requests per time unit. Once exceeded, the system returns a 429 Too Many Requests response. If requests exceed the set threshold value, further requests are delayed to prevent system overload.
Configuration
Solidgate suggests rate limits for live systems and staging environments. Slight delays are introduced before returning a 429 error to ensure legitimate merchant traffic flow.
Test mode: 25 read/write operations per second
Requests to different APIs, such as payments and reports, share the same rate limit. For instance, 50 write operations to the payment API will reduce available requests for other APIs by the same amount.
Handling 429/503 status code
When rate limits are exceeded, systems return 429 Too Many Requests or 503 Service Unavailable responses, to handle this:
- Retry mechanism: If a 429 response is received, pause and retry after a delay.
- Delay logic: The Retry-After header in the response specifies the delay before retrying. It is very important to observe a delay of 1-5 seconds.
|
|
In practice, with proper delay handling, the chances of encountering a 429 error are minimal if the rate is kept under ~100 RPS. However, Solidgate does not require merchants to implement additional traffic management, as they receive 429 status feedback when action is needed.