# Get started

The Solidgate API lets you send bank payments via SEPA and SWIFT, track their status, and
retrieve account statements for reconciliation, all through a single integration.

## OpenAPI specification

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:

div
a
svg
g
path
YAML
    
a
svg
g
path
JSON
    
## Use cases

**Send payments** 
Choose a payment method (SEPA or SWIFT), add the beneficiary's details, and create the transfer.
Payments routed to a recipient on this platform settle internally instead of over the external rail.

**Track payment status** 
Confirm a created payment to authorize the transfer of funds, then retrieve it at any time to follow
its progress from `AWAITING_CONFIRMATION` through `PROCESSING` to `COMPLETED` or `DECLINED`.

**Payout to cards** 
Automate payouts to Visa and Mastercard cards with a single integration into your systems.

**Reconcile with account statement** 
Retrieve the ledger transactions of an account on demand, for periodic reconciliation and reporting.

## Authentication and security

The API uses a **Bearer token** authentication model. Include the key in the `Authorization` header of every request:

```text
Authorization: Bearer your_secret_here
```

br
**Account-bound keys**

An API key can be scoped to one or more specific accounts (IBANs), instead of an entire legal entity. Endpoints that require this binding always take an explicit `account_id`, and the platform authorizes it against the key's granted accounts.

## API structure and conventions

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

br
**Endpoint format**

All operations use the **POST** method.

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

- **Host:** `https://api.solidgate.com/treasury`
- **Version:** `v2`
- **Resources:** Plural form of the domain model, for example, `bank-transfers`, `accounts`.
- **Action:** Operation name, for example, `create`, `confirm`, `get`, or `get-statement`.


br
**Data formatting**

- **Body:** JSON
- **Property names:** `snake_case`
- **Enum values:** `UPPER_CASE`


## Scopes and permissions

Fine-grained access control follows the principle of least privilege. Keys carry scopes in the form `domain:action`, for example `bank-transfers:read`, `bank-transfers:manage`, or `accounts:read`. A key without the required scope for an operation gets `403 PERMISSION_DENIED`.

## Error handling

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

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

Some responses include a `context` object with structured details.

| Status | Code | Description |
|  --- | --- | --- |
| `400` | `VALIDATION` | Malformed JSON or invalid field constraints. `context.constraints` lists per-field failures. |
| `401` | `UNAUTHENTICATED` | Invalid or missing API key. |
| `403` | `PERMISSION_DENIED` | Key lacks the required scope, or the account isn't in its granted set. |
| `404` | `NOT_FOUND` | Resource or endpoint does not exist. |
| `422` | domain-specific | Request conflicts with current business or system state (e.g., `INSUFFICIENT_FUNDS`, `INCOMPATIBLE_STATUS`). |
| `429` | `RATE_LIMIT` | Quota exhausted. Check `context.next_try_at`. |
| `500` | `INTERNAL` | Server-side failure. |


## 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 results in a `429 Too many requests` error response.

A widely used approach for handling rate limit error responses is implementing exponential backoff with jitter.

## API key management

Manage API keys via **Solidgate Hub**, in the **Developers** section. Each key can be scoped to specific accounts (IBANs) or to the whole legal entity, and to a specific set of scopes.

## Backward compatibility

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

| Category | Change |
|  --- | --- |
| **Operation removal** | Removing an API operation. |
| **Request** | Remove or rename a field, make optional fields required, remove `oneOf`. |
| **Response** | Remove or rename a field, change HTTP status code, remove `oneOf`. |
| **Type changes** | Change request or response data types. |
| **HTTP headers** | Add required headers or remove existing ones. |
| **Enum updates** | Remove enum values. |
| **Errors** | Change existing error codes. |
| **Validation rules** | Add stricter or new rules. |
| **Authentication and authorization** | Change requirements. |


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

| Category | Change |
|  --- | --- |
| **Request** | Add new optional fields, change required fields to optional. |
| **Response** | Add new optional fields, change optional fields to required. |
| **HTTP headers** | Add new optional headers, change header case. |
| **Field length** | Expand maximum length. |
| **Identifier format** | Change prefixes or formatting. |
| **Rate limiting** | Changes communicated at least one month in advance. |


For help, contact us.