> ## Documentation Index
> Fetch the complete documentation index at: https://docs.quidkey.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quidkey API v1

> Onboard merchants, create payment transactions, refund them and reconcile payouts, as a partner or as a merchant

The Quidkey API lets a partner onboard its merchants and create payment transactions for them, and lets a merchant create payment transactions, refund them and follow its payouts. Every request goes to one base URL:

```txt theme={null}
https://api.quidkey.com/v1
```

There's no separate sandbox host. A test payment transaction goes through the same API as a live one, with `is_test: true`, and moves no real money. See [Test an integration](https://docs.quidkey.com/api-v1/journeys/test-payments.md).

> [!NOTE]
>
> **Before you start:** a merchant finds its `client_id` and `client_secret` in the [Quidkey Console](https://console.quidkey.com). A partner gets them from Quidkey. [Getting started](https://docs.quidkey.com/api-v1/getting-started.md) exchanges them for a token and makes a first call.

## Who Calls the API

A credential belongs to one account: a partner or a merchant.

| Account | What its credential does |
| - | - |
| **Partner** | Creates and onboards its merchants, records the agreements their people accept, creates payment transactions and refunds for them, and receives their events at the partner's webhook endpoint. |
| **Merchant** | Creates payment transactions, refunds them, reads its payouts and runs its own webhook endpoints. It does its own onboarding too, apart from starting identity checks and requesting capabilities, which its partner does. |

## How the API Is Shaped

Every endpoint follows the same [standards](https://docs.quidkey.com/api-v1/standards/responses.md):

* **One document shape.** A successful response holds `result`, `entities` and `not_included`.
* **Links.** A relationship is a link object, and `include` hydrates it into `entities`.
* **Money as an object.** `{ "value": 4500, "currency": "GBP" }`, in the currency's minor units.
* **Errors.** Every error has a stable `code` and says whether it's `retryable`.
* **Idempotency.** Creates take an `Idempotency-Key`, so a lost response is recovered without paying twice.

> [!NOTE]
>
> IDs in these guides are shortened for readability, such as `m_1` and `tx_1`. Real IDs are opaque strings: store them as they are, and don't parse them.

## Journeys

Each journey is a complete path through the API, step by step. Steps marked **Console** or **Quidkey** are done by a person or by Quidkey, not by an API call.

> [card] [Set up a partner account](https://docs.quidkey.com/api-v1/journeys/partner-setup.md)
>
> Get a token and find your merchants

> [card] [Onboard a merchant](https://docs.quidkey.com/api-v1/journeys/onboard-a-merchant.md)
>
> From a new merchant to its first live payment transaction

> [card] [Take a payment with hosted checkout](https://docs.quidkey.com/api-v1/journeys/hosted-checkout.md)
>
> Create a payment transaction and send the customer to pay

> [card] [Refund a payment transaction](https://docs.quidkey.com/api-v1/journeys/refunds.md)
>
> Prepare, execute and follow a refund

## API Reference

The reference lists every endpoint with its permission, the representations it returns, what it can include, how it paginates, its error codes and whether it needs an `Idempotency-Key`. It's generated from the API's [OpenAPI document](https://docs.quidkey.com/api-reference/v1/openapi.json), which you can download and use with your own tooling.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.