---
title: "Pay the existing letter with a shared payment token. An empty body reconciles a pending payment or requests an MPP challenge; use Payment-Authorization for its credential."
method: POST
path: "/v1/letters/{id}/checkout"
---

# Pay the existing letter with a shared payment token. An empty body reconciles a pending payment or requests an MPP challenge; use Payment-Authorization for its credential.

`POST /v1/letters/{id}/checkout`

## Request

- Base URL: `https://paperagent.dev`
- URL: `https://paperagent.dev/v1/letters/{id}/checkout`
- Auth: one of:
  - OAuth 2 (authorization code, authorization URL `https://paperagent.dev/oauth/authorize`, token URL `https://paperagent.dev/oauth/token`, scopes: `letters:write`)
  - API key in header `X-Api-Key`
  - HTTP bearer

## Path parameters

- `id` string, required

## Headers

- `Payment-Authorization` string

## Request body

- object
  - `shared_payment_token` string
  - `token_constraints` object
    - `amount_limit_cents` integer: The most the token may be charged, in US cents.
    - `expires_at` integer: Unix seconds after which the token can no longer be spent.
    - `seller` string: The seller the token is scoped to.

## Response `200`

The existing order is paid, including an idempotent replay.

- object
  - `order_id` string, required
  - `letter_id` string, nullable, required
  - `order_status` 'pending' | 'awaiting_payment' | 'paid' | 'failed' | 'refunded' | 'disputed' | 'abandoned', required: `paid` means the money moved and the letter is released to print.
  - `payment_intent_id` string, nullable, required: The payment record at the provider, for the user’s receipt questions.
  - `already_paid` boolean, required: True when this order was already paid, so this call charged nothing.
  - `message` string, required: What to tell the user. Read it before answering.

## Other responses

- `400`: Invalid input or payment credential.
- `402`: payment_required/payment_challenge_expired: approve the exact order. payment_action_required: complete the existing wallet spend request within 30 minutes and reconcile with an empty POST; no new challenge, receipt or checkout link (an authentication left unfinished is canceled and the checkout link returns). spt_payment_declined: confirmed refusal, use a new approved token or the checkout fallback.
- `409`: Payment is unresolved or the order is no longer payable. Unresolved payments have no new challenge, receipt or checkout fallback. Reconcile the existing payment; do not authorize another charge.
- `503`: The matching payment configuration is unavailable.
- `default`: A stable error code and actionable message. 401: authenticate; 403: permission or policy; 404: unavailable object; 409: conflict; 422: domain refusal; 429: quota; 5xx: retry or contact support.

---

[API](https://skmtc.dev/paperagent/apis/paperagent-rest-api.md) · [All operations](https://skmtc.dev/paperagent/apis/paperagent-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/paperagent/apis/paperagent-rest-api/revisions/388148938051?raw)