Get started

Learn about authentication, signature creation, error handling, and API key management.

The complete API schema is available as a single bundled file. It includes all endpoints, request and response structures, and field definitions. To integrate programmatically, download the specification in the preferred format, instead of parsing the rendered API reference:

The Solidgate API v1 uses a signature-based authentication model. Each request must carry two headers that are computed from your Public and Secret key pair.

API keys

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.

• Format: Public keys use the prefix api_pk_, secret keys use the prefix api_sk_.
• Source: Get both keys from the Solidgate Hub by navigating to Developers > Channel details.
• Webhook keys are a separate pair with the prefixes wh_pk_ / wh_sk_, used exclusively for validating webhook payloads.

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.

Never expose your Secret key in client-side code or public repositories. Use it only in secure server-side environments.

Required headers

Every request must include two custom headers.

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 support for further assistance.

Fail response authentication

{
  "error": {
    "code": "1.01",
    "messages": [
      "Authentication failed"
    ]
  }
}

The signature value is a Base64-encoded string of the hexadecimal representation of an HMAC-SHA512 hash, created using the Secret key.

Signature data

Concatenate the following string and use it as the HMAC input publicKey + jsonString + publicKey

For GET requests that do not have a body, the signature data is simply publicKey + publicKey.

Steps

1. Use the generateSignature function, which takes the data and the Secret key as parameters.
2. Generate the HMAC-SHA512 hash using the Secret key and data.
3. Get the hexadecimal representation of the hash.
4. Encode the hexadecimal representation of the hash directly to Base64.

Expected signature with the test data above

MjFkZGE3ZTZjODc0YjY5YTczOTlmOTBlYjk0MDY1NThiODJiZmE3ZTgxOGJjMWUxYjNkNTFjMDNjZmUzOGRlMTBhZGEzMmYxMGY3NTBlOTBlMGZkNDUwZTRiNmI5YTBiYTVmZWM5NzcxMjU3OWM0MGU5Mzg1NTljOTE1NTVlNzA=

Code examples

class SignatureGenerator
{
        public static function generateSignature(string $publicKey, string $jsonString, string $secret_key): string
    {
        $text = $publicKey . $jsonString . $publicKey;
        $hashedBytes = hash_hmac('sha512', $text, $secret_key);
        return base64_encode($hashedBytes);
    }
    public static function main(array $args): void
    {
        $public_key = 'api_pk_8f8a8k8e8k8e8y8';
        $json_string = '{"amount": "100", "currency": "USD"}';
        $secret_key = 'api_sk_8f8a8k8e8k8e8y8';
        $signature = self::generateSignature($public_key, $json_string, $secret_key);
        echo $signature . "\n";
    }
}

SignatureGenerator::main([]);

The v1 API uses domain-specific base URLs, except for endpoints for managing webhooks and files. Select the correct host for the resource you are working with.

Base URLs

Endpoint format

Endpoints use the action name directly after the base URL. The HTTP method depends on the operation.

{method} {host}/{action}

For example, to initiate a card payment:

POST https://pay.solidgate.com/api/v1/charge

Data formatting

• Body: JSON
• Content-Type: application/json

For the complete list of endpoints, methods, and parameters, see the Solidgate API reference.

Using an action with the wrong base URL results in a Blocked by WAF error. For example, the endpoint /subscription/cancel-by-customer must be called on subscriptions.solidgate.com, not pay.solidgate.com.

The API uses standard HTTP status codes. All errors return a consistent JSON structure.

Error response structure

{
  "error": {
    "code": "3.02",
    "messages": [
      "The user's card balance has insufficient funds."
    ],
    "recommended_message_for_user": "Please try a different payment method."
  }
}

For the full list of error codes, see the error codes reference.

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 results in 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 apply per merchant account and differ between environments. In the Live environment, the limit is 25 requests per second, distributed per merchant account. In the Sandbox test environment, the limit is 10 requests per second, across all endpoints per merchant account. When the rate limit is exceeded, the API returns HTTP 429 with error code 5.07.

Rate limits may also 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 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 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.

Webhook event security works like API authentication. Each notification includes merchant and signature values in the headers.

• merchant – your webhook Public key (wh_pk_).
• signature – an HMAC-SHA512 hash of the request body, signed with your webhook Secret key.

Verify a signature

1. Retrieve the merchant value from the request headers and confirm it matches one of your webhook Public keys.
2. Look up the Secret key paired with that Public key.
3. Generate a signature from the raw request body using the same generateSignature function you use for API requests.
4. Compare your generated signature to the signature header value. Reject the request if they do not match.

Use the raw JSON body exactly as received, with no changes. Serializers, URL encoding, or reformatting can change the byte structure and produce a different hash, causing a valid webhook to fail verification.

Delivery headers

Every v1 webhook delivery includes the following headers.

Best practices

• Process asynchronously: Verify the signature, durably store the event, then return a 200 OK immediately, and handle the payload in a background queue. This avoids timeout failures during traffic spikes.
• Ensure idempotency: Delivery order is not guaranteed and the same event may arrive more than once with the same solidgate-event-id, including retries spanning up to 24 hours after the first attempt. Store processed event IDs for at least one week and skip any duplicate.

Subscribe to event types when you create or update a webhook endpoint. Full payload contracts stay on each event page in this reference. For endpoint setup, retries, and delivery headers, see the webhooks guide.

Specific IP addresses are used for outbound requests from Solidgate to your systems (for example, webhooks). Allow traffic from these IPs in your firewall or security configuration to ensure uninterrupted service.

Configure your security systems to accept these IPs to prevent service interruptions. Stay informed about any changes to these IP addresses for continuous service.

The Blocked by WAF error indicates that a Web Application Firewall (WAF) has prevented your request due to a policy violation. The most common cause is sending a request to the wrong base URL. This error often arises from mismatched endpoints and base URLs in API requests.

1. Confirm that the full URL matches a valid endpoint in the Solidgate API reference.
2. Ensure that the endpoint corresponds to the correct base URL for that domain.

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 receive 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.

API logs capture API request and response records for operations.

This helps developers and integrators troubleshoot issues, monitor traffic, and investigate suspicious or unintended API usage.

To view API log entries in the Solidgate Hub:

1. Go to Developers > API logs.
2. Find the log entry you need and click on it.
3. View log entry details, including Status, Method, Path, Host, IP address, and Date (UTC).
4. Expand Request body and Response body to see the JSON payloads sent and received.

Changes to the Solidgate APIs are aimed at minimizing the impact on existing integrations. However, depending on the type of change, actions may be required.

Any API change that requires client-side adjustments will be communicated by the Solidgate team. These changes include preparation time and clear guidance.

When a field or feature is marked as deprecated and a deprecation notice is added to the changelog, it serves as an early notice. Deprecated fields or features are not removed immediately.

Breaking changes can impact existing integrations and require adjustments. These are marked with a breaking changes badge in the changelog and include:

Non-breaking changes modifications do not affect existing integrations and ensure backward compatibility:

For help, contact us. Stay informed with the Changelog.