---
title: "Get a checkout"
method: GET
path: "/api/checkouts/{id}"
tags: ["checkouts"]
---

# Get a checkout

`GET /api/checkouts/{id}`

## Request

- Base URL: `https://api.depixapp.com`
- URL: `https://api.depixapp.com/api/checkouts/{id}`
- Auth: HTTP bearer

Full checkout detail (owner view). `pix_payload` is present only while pending. Poll until a terminal status (see the status enum) or subscribe to checkout.* webhooks. Requires scope `merchant_read` on the API-key path.

`processing` means the payer's money reached us — it does NOT mean the money has landed in the merchant's wallet, and a checkout can sit there for days while a hold runs. It is also not a settled outcome: a sale in `processing` can still resolve to `cancelled` (a refunded or reversed payment — see `rejection_reasons`). `delay_until` says when the money lands (null until the provider answers with a date) and `vault_hours` says whether it was held at all. Releasing the order at `processing` or waiting for `completed` is the merchant's own policy; this endpoint publishes the facts either choice needs.

## Path parameters

- `id` string, required

## Response `200`

Checkout detail.

- CheckoutGetResponse: Envelope of the authenticated checkout read.
  - `checkout` CheckoutDetail, required: Full checkout row (authenticated read).
    - `id` string, required: Checkout id (chk_*).
    - `status` union, required: Checkout lifecycle status — the enum below is the complete, closed set. `completed` is the terminal SUCCESS state. Terminal states (safe to stop polling): completed, expired, cancelled.
      - 'pending': Awaiting payment; the PIX QR is active until expires_at.
      - 'processing': PIX paid; settlement in progress.
      - 'approved': Payment approved by the provider; DePix on the way to the merchant.
      - 'completed': TERMINAL — success: DePix delivered to the merchant.
      - 'expired': TERMINAL — QR expired unpaid.
      - 'cancelled': TERMINAL — cancelled upstream by the provider (refund/error).
    - `amount` integer, required: Charge amount in cents (face value).
    - `description` string, nullable, required: Checkout description.
    - `image_url` string, nullable, required: Checkout image URL.
    - `payment_method` 'pix' | 'depix': Which rail settles the checkout. `pix` (default): the payer pays a PIX QR and the provider delivers DePix to the merchant. `depix`: the payer sends DePix wallet-to-wallet on Liquid to an address dedicated to this merchant, and settlement is observed on-chain — no PIX QR exists on this rail.
    - `depix` DepixPayment: Payment instructions for the depix rail — present only on checkouts created with payment_method=depix, and only while the checkout can still be paid. The payer must send EXACTLY `amount_cents` of the DePix asset to `address`: attribution is by exact amount, so any other value stays unattributed and cannot be credited automatically. An on-chain payment is irreversible.
      - `address` string, required: Confidential Liquid address (lq1…) dedicated to this merchant's direct DePix receipts. In sandbox it is a non-payable placeholder — never send funds to it.
      - `amount_cents` integer, required: EXACT amount to send, in cents. It is the face amount minus the merchant's discount and minus a per-checkout cents adjustment (at most 99 cents, always DOWNWARDS) that makes the value unique among the merchant's open checkouts — that uniqueness is how an incoming payment is matched to this checkout.
      - `amount` string, required: The same amount as the decimal string a wallet signs (e.g. "89.97"). Display and transmit this value verbatim; never round it.
      - `asset_id` string, required: Liquid asset id of DePix. Sending any other asset to this address loses the funds — they cannot be returned.
      - `uri` string, nullable, required: BIP21-style Liquid payment URI carrying address, amount, asset and this checkout's id (`liquidnetwork:<address>?amount=<amount>&assetid=<asset_id>&depixid=<checkout_id>`) — hand it to a wallet instead of asking the payer to type anything. Any BIP21 wallet ignores `depixid` (it is deliberately not `req-`-prefixed, which would make a wallet reject the whole URI); the DePix App uses it to re-read this checkout and confirm the address and status before offering to pay, so a URI written by someone else is refused rather than paid. The URI never carries a store name: a name in the URI is a name in the payer's clipboard, which anyone can write. Null in sandbox, which has no payable destination, and null on a checkout that is no longer payable (see the `depix` field on CheckoutDetail): the rest of the object is then a settlement record, not an instruction.
      - `discount_pct` integer, required: Merchant discount applied on this rail, 0–90 (0 when the merchant offers none).
      - `original_amount_cents` integer, required: Face amount in cents before discount and uniqueness adjustment — the same value as the checkout's `amount`.
      - `detected` boolean, required: True once a matching payment has been SEEN on the network but not yet confirmed. Informational only: the status stays `pending` and no webhook fires until the first confirmation.
    - `pix_payload` string: PIX copy-and-paste payload — present only while status is "pending" on the pix rail.
    - `rejection_reasons` string[], required: Provider reasons for a refunded/held payment on the underlying deposit — e.g. PAYER_MISMATCH, PAST_DAILY_LIMIT, BLOCKED_USER, HIGH_VELOCITY. Empty array when the payment was not refused. New reason codes may appear; display unknown codes as-is.
    - `callback_url` string, nullable, required: Webhook endpoint receiving this checkout's checkout.* events.
    - `redirect_url` string, nullable, required: Post-payment redirect URL.
    - `metadata` union, required: Merchant metadata. Parsed back to an object when valid JSON; the raw string is preserved otherwise.
      - object
      - string
    - `expires_at` string, required: QR expiry timestamp (RFC 3339 UTC).
    - `is_live` 0 | 1, required: 1 = live, 0 = sandbox (raw SQLite boolean).
    - `created_at` string, required: Creation timestamp (RFC 3339 UTC).
    - `processing_at` string, nullable, required: When the checkout entered processing (null if never).
    - `approved_at` string, nullable, required: When the checkout was approved (null if never).
    - `completed_at` string, nullable, required: When the checkout completed (null if never).
    - `cancelled_at` string, nullable, required: When the checkout was cancelled (null if never).
    - `blockchain_tx_id` string, nullable, required: Liquid transaction id of the DePix settlement (null until completed).
    - `delay_until` string, nullable: When this sale's money is released, if it is being held. Same RFC 3339 UTC instant as every other timestamp here (`"2026-08-13T12:03:00.000Z"`). Non-null only once the provider has answered with a date, so a sale that is held right now still reads null for a while; it also stays set after the money lands, so it is a hold RECORD, not a live flag. Pair it with `status`: a sale still waiting sits in `processing`. Never a reason — what triggered the hold is not published.
    - `vault_hours` integer, nullable: How many hours this sale was booked to wait when it was created. `0` means the hold policy looked at it and imposed no wait. **Null is not zero**: it means no hold decision was recorded against this sale at all — a sandbox checkout (no paired deposit exists), a row created before the mechanism shipped, or one created while the mechanism was switched off. Today the vast majority of rows read null. Use it as an answer to WHETHER, never to WHEN: the real wait starts when the payer pays, not when the sale was created, so `created_at + vault_hours` lands EARLY and must not be presented as a release date. `delay_until` is the only date.

## Other responses

- `401`: Missing/invalid credentials. `invalid_api_key` for a failed sk_* lookup (revoked/expired/unknown); `invalid_token` for a bad or missing JWT/Authorization header.
- `403`: The API key lacks the `merchant_read` scope required by this operation. May also be `account_blocked`, or an operation-specific 403 — see the error catalog.
- `404`: Checkout not found — includes rows owned by another account (ownership is never disclosed).
- `429`: Rate limited. Beyond the endpoint's own limit when set (`rate_limited`), API-key calls are also bounded by the shared per-merchant budget (`merchant_rate_limited`, default 30 req/min across all endpoints) and by the key's own rate limit when configured (`rate_limited`). Retry after `retry_after` seconds (also in the Retry-After header).

---

[API](https://skmtc.dev/depixapp/apis/depix-api.md) · [All operations](https://skmtc.dev/depixapp/apis/depix-api/llms.txt) · [OpenAPI document](https://skmtc.dev/depixapp/apis/depix-api/revisions/04094536dd0f?raw)