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

# Take a Payment with Hosted Checkout

> Create a payment transaction, send the customer to the hosted page, and confirm it

A merchant's credential and a partner's both create payment transactions. A partner finds the merchant's ID with `GET /partners/{id}/merchants`, and a merchant with `GET /api-keys/current`.

| # | Step | Who |
| - | - | - |
| 1 | Check which currencies the merchant can take | API, optional |
| 2 | Create the payment transaction | API |
| 3 | Send the customer to `checkout.url`, where they pay | **Customer** |
| 4 | Receive `transaction.payment.completed` or `transaction.payment.processing` | Quidkey sends it |
| 5 | Read the payment transaction | API |

## 1. Check the Currencies

```bash theme={null}
curl 'https://api.quidkey.com/v1/merchants/m_1/receivable-currencies' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

It lists the currencies routed to the merchant's active accounts, for live and for test payment transactions. A payment transaction in another currency is refused.

## 2. Create the Payment Transaction

```bash theme={null}
curl -X POST 'https://api.quidkey.com/v1/merchants/m_1/transactions' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Idempotency-Key: "8e03978e-40d5-43e8-bc93-6894a57f9324"' \
  -H 'Content-Type: application/json' \
  -d '{
    "type": "payment",
    "amount": { "value": 2550, "currency": "EUR" },
    "order": { "order_id": "ORD-123" },
    "customer_details": {
      "full_name": "Jane Doe",
      "email": "jane@example.com",
      "phone": "+353861234567",
      "country": "IE"
    },
    "statement_descriptor": "Example Store",
    "authorization": {
      "method": "checkout",
      "success_url": "https://shop.example.com/paid",
      "failure_url": "https://shop.example.com/failed"
    }
  }'
```

* `amount` is in minor units: `2550` is EUR 25.50.
* `customer_details.country` decides how the payment transaction is routed.
* `statement_descriptor`, up to 18 characters, goes to the customer's bank, which makes it alphanumeric. On a payment transaction through a virtual account, the customer's statement shows Quidkey's reconciliation reference instead.
* `authorization` says how the customer authorizes the payment transaction: with `checkout`, they authorize it themselves at their bank, and come back to `success_url` or `failure_url`.
* Use one `Idempotency-Key` for each attempt to pay, and store it with the attempt before you send the request. When the customer tries again after a payment transaction has failed or been cancelled, use a new key: the old one keeps answering the payment transaction that failed. See [Idempotency](https://docs.quidkey.com/api-v1/standards/idempotency.md#choosing-a-key) and [Recover a lost response](https://docs.quidkey.com/api-v1/journeys/lost-responses.md).

The answer is 201, with the payment transaction at `status: pending`:

```json Response theme={null}
{
  "result": {
    "_type": "transaction",
    "_uri": "/transactions/tx_1",
    "_view": "full",
    "id": "tx_1",
    "type": "payment",
    "is_test": false,
    "transaction_number": "QK-10041",
    "status": "pending",
    "reason": null,
    "failure": null,
    "required_actions": [],
    "amount": { "value": 2550, "currency": "EUR" },
    "payout_amount": null,
    "exchange_rate": null,
    "fees": null,
    "routing": "virtual_account",
    "refund_status": null,
    "can_refund": false,
    "order": { "order_id": "ORD-123" },
    "rewards": null,
    "reported_statement_descriptor": null,
    "platform": "api",
    "merchant": { "_link": "/merchants/m_1", "_type": "merchant", "id": "m_1" },
    "customer_details": { "_link": "/transactions/tx_1/customer-details", "_type": "customer_details", "id": "tx_1" },
    "parent_transaction": null,
    "refunds": { "_link": "/transactions/tx_1/refunds", "_type": "collection" },
    "reversals": [],
    "payout": null,
    "checkout": {
      "url": "https://checkout.example/YOUR_CHECKOUT_PATH",
      "expires_at": "2026-11-02T10:15:00.000Z"
    },
    "created_at": "2026-11-02T10:00:00.000Z",
    "updated_at": "2026-11-02T10:00:00.000Z"
  },
  "entities": {},
  "not_included": []
}
```

`checkout` is a one-time value: it appears only here and in the answer to `POST /transactions/{id}:issueCheckout`. A replay leaves it out, and so can the answer to a create you sent once, when Quidkey sent it on again after a dropped connection. If the answer has no `checkout`, call `POST /transactions/{id}:issueCheckout` for it.

| Refusal | Meaning |
| - | - |
| 409 `LIVE_PAYMENTS_NOT_ALLOWED` | The merchant can't take live payment transactions yet. A [test payment transaction](https://docs.quidkey.com/api-v1/journeys/test-payments.md) works before go-live. |
| 409 `MERCHANT_CANNOT_TAKE_PAYMENT` | The merchant can't take a payment transaction in this currency from a customer in this country yet. |
| 400 `CURRENCY_COUNTRY_MISMATCH` | This currency can't be taken from a customer in this country. |
| 400 `AMOUNT_TOO_LARGE` | `amount.value` is more than 9999999. |
| 422 `BANK_NOT_AVAILABLE` | `authorization.bank` isn't one `GET /merchants/{id}/banks` lists for this payment transaction. |
| 422 `BANK_SELECTION_NOT_SUPPORTED` | `authorization.bank` was sent, and this payment transaction is taken on its provider's own page, where the customer doesn't choose a bank. |

The reference lists every code.

### Open Checkout at the Customer's Bank

If the customer chooses their bank on your own page, send it as `authorization.bank` at create. List the banks they can choose from with `GET /merchants/{id}/banks`, for the same country, currency and `is_test` as the payment transaction. See [Banks](https://docs.quidkey.com/api-v1/reference/banks.md).

```json theme={null}
"authorization": {
  "method": "checkout",
  "success_url": "https://shop.example.com/paid",
  "failure_url": "https://shop.example.com/failed",
  "bank": { "id": "38c39d03-8df3-4980-b0a8-7e283c8c62dd" }
}
```

`checkout.url` then opens with that bank chosen, and the customer confirms it with one tap. They can still pick another bank on the same page.

## 3. Send the Customer to Pay

Redirect the customer to `checkout.url`. They choose their bank, approve the payment transaction there, and come back to your `authorization.success_url` or `failure_url`. **Customer.**

The redirect only says where the customer went. Confirm the payment transaction with the event or a read, never with the redirect alone.

## 4. Receive the Event

`transaction.payment.completed` arrives when the customer's bank accepts a direct payment transaction, and `transaction.payment.processing` when it accepts one through a virtual account. A payment transaction created with a partner's credential reports to the partner's endpoint, and one created with the merchant's to the merchant's. See [Webhooks](https://docs.quidkey.com/api-v1/webhooks.md#where-a-payment-transactions-events-go).

`result.subject` links to the payment transaction, whose `order.order_id` is the one you sent.

## 5. Read the Payment Transaction

```bash theme={null}
curl 'https://api.quidkey.com/v1/transactions/tx_1?include=customer_details' \
  -H 'Authorization: Bearer ACCESS_TOKEN'
```

The payment transaction reads `processing` while the money is on its way, and `completed` once the provider reports it finished. `fees` holds what Quidkey charged, and `payout` links to the payout that carries it, once it's batched. `?include=customer_details` adds the customer's details to `entities`.

If the customer leaves before paying, the payment transaction stays `pending`. `POST /transactions/{id}:issueCheckout` answers its live checkout again, or a new one once it has expired, so you can send the customer back.


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