Get started

Learn about authentication, permissions, 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 v2 uses a simplified Bearer token authentication model for outbound API calls. You no longer need to manage request signatures or multiple key sets when calling the API. Incoming webhook deliveries still require HMAC signature verification.

API key

• Format: Key IDs use the prefix akey_xxx, secrets use the prefix asec_xxx.
• Method: Include the key in the Authorization header of every request.

Example header

Authorization: Bearer your_secret_here

Key flexibility

API keys are decoupled from channels.

• Account level: By default, keys exist at the account level with access to all channels.
• Channel-bound: A key that can be restricted to one or many specific channels.

The API follows a strict structural pattern to keep behavior predictable.

Endpoint format

All operations use the POST method.

POST {host}/{version}/{resources}/{action}

• Host: https://api.solidgate.com
• Version: v2
• Resources: Plural form of the domain model, for example, api-keys, payments.
• Action: Operation name, for example, create, list, or rotate.

Data formatting

• Body: JSON
• Property names: snake_case
• Enum values: UPPER_CASE

Fine-grained access control follows the principle of least privilege. Keys can be restricted by channel and permission.

Manage keys via Solidgate Hub or API v2. Hub access is available to Merchant Admin and Developer roles. Navigate to the Developers section and then select API v2.

Key rotation with zero downtime

To maintain security without service interruption, use Rotation.

1. Initiate
   • API: Call /rotate and set the rotation period in seconds
   • Hub: Click Rotate for the API key
2. Overlap
   During this period, both old and new secrets remain valid
3. Expiry
   After the period ends, the old secret is automatically deactivated

API key operations

All operations require an account-level API key marked in Hub as Applies to all channels.

The API uses standard HTTP status codes. All errors return the same JSON envelope, for example:

{"code": "PERMISSION_DENIED", "message": "Permission denied"}

Some responses include a context object with structured details. Every response carries a request-id header, share it with support when reporting issues.

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

Webhook event security uses a Base64-encoded HMAC-SHA256 signature generated with your webhook endpoint secret. Each notification includes a signature value in the headers.

• signature – a Base64-encoded HMAC-SHA256 digest of the raw request body, signed with your webhook endpoint secret.

Unlike v1, webhook deliveries do not include a public key in the headers. Identify the correct webhook endpoint secret using the endpoint that received the webhook.

1. Determine which endpoint received the webhook, and look up that endpoint's secret.
2. Generate a signature from the raw request body using the generateSignature function, which must return the Base64-encoded digest.
3. 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.

Every v2 webhook payload includes the following fields.

Unlike v1, this metadata is sent in the payload rather than the headers. signature is the only header v2 sends.

• Prevent replay attacks: Check the occurred_at field in the payload. Reject deliveries with a timestamp older than 5 minutes.
• Process asynchronously: Return a 200 OK response immediately after signature verification, then 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 event_id. Store processed event IDs for at least one week, and skip any duplicate.

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.