> This page is for North America.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://amer.developers.trustly.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://amer.developers.trustly.com/_mcp/server.

# API reference

The Trustly API is organized around [REST](https://en.wikipedia.org/wiki/Representational_state_transfer). Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

You can use the Trustly API in [sandbox mode](https://sandbox.trustly.one) to test your integration without affecting live data or processing real bank transactions. Your provisioned `accessId` and `accessKey` credentials determine whether requests are processed against sandbox or production environments.

#### [Just getting started?](/integrate/core-concepts/integrate-client-sdk)

Learn how to set up your first Trustly integration and
process a test transaction.

#### [Client-side SDK](/sdks)

Integrate the Select Bank Widget or Trustly Lightbox using our native SDKs, or use our mobile web integration for cross-platform frameworks like Flutter and MAUI.

## Base URL

All API requests should be made to the following base URLs:

```
Sandbox:    https://sandbox.trustly.one/api/v1
Production: https://api.trustly.one/api/v1
```

## Authentication

The Trustly API uses [HTTP Basic Authentication](https://developer.mozilla.org/en-US/docs/Web/HTTP/Authentication#basic_authentication_scheme) over HTTPS. Authenticate requests using your provisioned `accessId` (username) and `accessKey` (password).

```shell
curl --user accessId:accessKey https://sandbox.trustly.one/api/v1/transactions
```

For additional security, you can encrypt individual requests and field-level data. See [Secure Requests and Signature Validation](/integrate/api-fundamentals/secure-requests-and-signature-validation) for details.

> **Check**
>
> All API requests must be made over HTTPS. Calls made over plain HTTP will
> fail. API requests without authentication will also fail.

## Core resources

Browse the key resource groups available in the Trustly API:

#### [Transactions](/api-reference/api/transactions/post-establish)

Create, authorize, capture, cancel, and refund transactions. The core
resource for all payment flows.

#### [Payments](/api-reference/api/payments/get-payments)

Retrieve payment details and list payments associated with your merchant
account.

#### [Accounts](/api-reference/api/accounts/get-accounts-verify)

Tokenize and verify bank accounts for secure, reusable payment methods.

#### [Customers](/api-reference/api/customers/get-customers)

Manage customer records and retrieve customer data across transactions.

#### [Account data](/api-reference/api/account-data/get-transaction-account-summary)

Retrieve verified bank account information, user details, and balance data.

#### [Event notifications](/api-reference/api/event-notifications/authorize)

Receive asynchronous webhook notifications for transaction state changes and
other events.

## Paging and filtering

Requests that return multiple items return 25 items per page by default. Use `count` and `startIndex` parameters to paginate through results.

| Parameter                           | Description                                                        |
| ----------------------------------- | ------------------------------------------------------------------ |
| `count`                             | Number of items to return. Default is 25, maximum is 100.          |
| `startIndex`                        | Zero-based index of the first item to return.                      |
| `orderBy`                           | Order results by `createdAt` or `updatedAt`.                       |
| `sortOrder`                         | Sort direction: `asc` (ascending) or `desc` (descending, default). |
| `createdAt.start` / `createdAt.end` | Filter by creation time range (Unix timestamp).                    |
| `updatedAt.start` / `updatedAt.end` | Filter by update time range (Unix timestamp).                      |

## Errors

The Trustly API uses conventional HTTP response codes to indicate success or failure:

| Code  | Description                                                      |
| ----- | ---------------------------------------------------------------- |
| `200` | OK — request succeeded.                                          |
| `400` | Bad Request — invalid parameters or missing required fields.     |
| `401` | Unauthorized — invalid or missing authentication credentials.    |
| `403` | Forbidden — insufficient permissions for the requested resource. |
| `404` | Not Found — the requested resource doesn't exist.                |
| `429` | Too Many Requests — rate limit exceeded.                         |
| `500` | Server Error — something went wrong on Trustly's end.            |