{
  "openapi": "3.1.0",
  "info": {
    "title": "Railbed API",
    "version": "v1",
    "summary": "Card checkout for merchants, settled to a wallet the merchant controls.",
    "description": "The Railbed merchant API. JSON over HTTPS.\n\n- **Authentication.** Send `Authorization: Bearer <secret key>` from your server, or a connected AI agent's access token. The credential decides the account, the mode (`rb_test_…` keys see only Test data, `rb_live_…` keys only Live data) and the scopes. Secret keys are created in the dashboard under Developers and never belong in browser or mobile code; the API sends no CORS headers.\n- **Scopes.** Every operation needs one scope, named in its `security` and in `x-railbed-scope`. A credential without it gets `403 insufficient_scope`.\n- **Money** is a decimal string (`\"49.00\"`), never a number. **Timestamps** are Unix seconds; webhook payloads use milliseconds inside the event.\n- **Errors** are `{\"error\": {\"code\", \"message\", \"field\"?}}`. Branch on `code` and the status, never on `message`. `x-railbed-error-codes` lists each response's known codes; new codes can be added within `v1`.\n- **Pagination.** Lists return `{data, has_more, next_cursor}`, newest first. Pass `next_cursor` as `starting_after`.\n- **Versioning.** Changes within `v1` only add things: ignore fields, event types and statuses you don't know.\n- Responses are never cached (`Cache-Control: no-store`).\n\nThe reference with guides: https://railbed.com/docs/api/. Every endpoint for AI agents: https://railbed.com/docs/llms.txt.",
    "termsOfService": "https://railbed.com/terms/",
    "contact": {"name": "Railbed support", "email": "support@railbed.com", "url": "https://railbed.com/docs/"}
  },
  "externalDocs": {"description": "API reference", "url": "https://railbed.com/docs/api/"},
  "servers": [
    {"url": "https://pay.railbed.io/v1", "description": "Test and Live: the secret key decides the mode."}
  ],
  "security": [{"secretKey": []}, {"agentToken": []}],
  "tags": [
    {
      "name": "Checkout sessions",
      "description": "One attempt at paying, with a hosted page.",
      "externalDocs": {"url": "https://railbed.com/docs/api/checkout-sessions/"}
    },
    {
      "name": "Payments",
      "description": "Each session's payment: its status and settlement.",
      "externalDocs": {"url": "https://railbed.com/docs/api/payments/"}
    },
    {
      "name": "Payment methods",
      "description": "The card providers buyers can pay with.",
      "externalDocs": {"url": "https://railbed.com/docs/api/payment-methods/"}
    },
    {
      "name": "Payout wallets",
      "description": "The other wallets a payment link or invoice can pay.",
      "externalDocs": {"url": "https://railbed.com/docs/api/payout-wallets/"}
    },
    {
      "name": "Payment links",
      "description": "One amount from one payer.",
      "externalDocs": {"url": "https://railbed.com/docs/api/payment-links/"}
    },
    {
      "name": "Invoices",
      "description": "Invoices with lines, tax, a due date and part payments.",
      "externalDocs": {"url": "https://railbed.com/docs/api/invoices/"}
    },
    {
      "name": "Checkouts",
      "description": "Reusable pages a buy button opens.",
      "externalDocs": {"url": "https://railbed.com/docs/api/checkouts/"}
    },
    {
      "name": "Orders",
      "description": "What was bought and where it ships.",
      "externalDocs": {"url": "https://railbed.com/docs/api/orders/"}
    },
    {
      "name": "Customers",
      "description": "Buyers, one per email in each mode.",
      "externalDocs": {"url": "https://railbed.com/docs/api/customers/"}
    },
    {
      "name": "Webhook endpoints",
      "description": "Addresses that receive signed events.",
      "externalDocs": {"url": "https://railbed.com/docs/api/webhook-endpoints/"}
    },
    {
      "name": "Webhook events",
      "description": "What Railbed sends to your endpoints, signed with `Railbed-Signature`.",
      "externalDocs": {"url": "https://railbed.com/docs/webhooks/events/"}
    }
  ],
  "paths": {
    "/checkout_sessions": {
      "post": {
        "operationId": "createCheckoutSession",
        "summary": "Create a checkout session",
        "description": "Creates one attempt at paying, with a hosted page to send the buyer to. Send an `Idempotency-Key` so a retried request never makes a second payment. Live mode needs a payout wallet that can take payments.",
        "tags": ["Checkout sessions"],
        "security": [{"secretKey": ["checkouts:write"]}, {"agentToken": ["checkouts:write"]}],
        "x-railbed-scope": "checkouts:write",
        "parameters": [{"$ref": "#/components/parameters/IdempotencyKey"}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/CreateCheckoutSession"},
              "examples": {
                "basic": {
                  "summary": "A session for one amount",
                  "value": {
                    "amount": "49.00",
                    "currency": "USD",
                    "description": "Pro Membership",
                    "reference": "order_1042",
                    "customer_email": "buyer@example.com",
                    "metadata": {"user_id": "player_1042"},
                    "success_url": "https://yourstore.com/thanks?order={REFERENCE}&payment={PAYMENT_ID}",
                    "cancel_url": "https://yourstore.com/cart"
                  }
                },
                "store_order": {
                  "summary": "A store order with items, totals and a shipping address",
                  "value": {
                    "amount": "135.31",
                    "currency": "USD",
                    "description": "Order #1042",
                    "reference": "order_1042",
                    "customer_email": "maya@example.com",
                    "customer": {"name": "Maya Okafor", "phone": "+1 503 555 0142", "id": "88"},
                    "order": {
                      "id": "1042",
                      "number": "1042",
                      "url": "https://yourstore.com/admin/orders/1042",
                      "store": {"id": "yourstore", "name": "yourstore.com", "url": "https://yourstore.com"},
                      "items": [
                        {
                          "name": "Magnesium glycinate",
                          "variant": "120 capsules",
                          "sku": "HN-MG-120",
                          "quantity": 2,
                          "unit_amount": "32.00",
                          "amount": "64.00"
                        },
                        {"name": "Daily greens", "sku": "HN-DG-30", "quantity": 1, "amount": "54.00"},
                        {"name": "Shaker bottle", "quantity": 1, "amount": "12.00"}
                      ],
                      "discount": "13.00",
                      "discount_code": "WELCOME10",
                      "shipping": "8.95",
                      "shipping_method": "Standard",
                      "tax": "9.36",
                      "shipping_address": {
                        "name": "Maya Okafor",
                        "line1": "418 Linden Avenue",
                        "line2": "Apt 3B",
                        "city": "Portland",
                        "region": "OR",
                        "postal_code": "97214",
                        "country": "US"
                      }
                    },
                    "success_url": "https://yourstore.com/orders/1042/thanks"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A retry with the same `Idempotency-Key` and body: the original session, with its current status.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/CheckoutSession"},
                "examples": {
                  "replay": {
                    "summary": "The same session again",
                    "value": {
                      "id": "pay_7AAiYH0Ykt11ED4hmfiN",
                      "object": "checkout_session",
                      "url": "https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN",
                      "status": "open",
                      "livemode": false,
                      "amount": "49.00",
                      "currency": "USD",
                      "description": "Pro Membership",
                      "reference": "order_1042",
                      "customer_email": "buyer@example.com",
                      "created": 1790380525,
                      "expires_at": 1790466925,
                      "started_at": null,
                      "metadata": {"user_id": "player_1042"},
                      "order_id": "ord_M4tQx8ZkP1vRn6WcLs2B",
                      "collect": null,
                      "canceled_at": null,
                      "checkout_id": null,
                      "plan_label": null
                    },
                    "x-railbed-fixture": "session-created"
                  }
                }
              }
            }
          },
          "201": {
            "description": "The new session. `warnings` appears only when there is something to say about the card providers' minimums.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/CheckoutSession"},
                "examples": {
                  "created": {
                    "summary": "A new session",
                    "value": {
                      "id": "pay_7AAiYH0Ykt11ED4hmfiN",
                      "object": "checkout_session",
                      "url": "https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN",
                      "status": "open",
                      "livemode": false,
                      "amount": "49.00",
                      "currency": "USD",
                      "description": "Pro Membership",
                      "reference": "order_1042",
                      "customer_email": "buyer@example.com",
                      "created": 1790380525,
                      "expires_at": 1790466925,
                      "started_at": null,
                      "metadata": {"user_id": "player_1042"},
                      "order_id": "ord_M4tQx8ZkP1vRn6WcLs2B",
                      "collect": null,
                      "canceled_at": null,
                      "checkout_id": null,
                      "plan_label": null
                    },
                    "x-railbed-fixture": "session-created"
                  },
                  "store": {
                    "summary": "A Live session for a store order",
                    "value": {
                      "id": "pay_Rt5Wm2KxQ8zLb3NvYc7P",
                      "object": "checkout_session",
                      "url": "https://pay.railbed.io/p/pay_Rt5Wm2KxQ8zLb3NvYc7P",
                      "status": "open",
                      "livemode": true,
                      "amount": "135.31",
                      "currency": "USD",
                      "description": "Order #1042",
                      "reference": "order_1042",
                      "customer_email": "maya@example.com",
                      "created": 1790380525,
                      "expires_at": 1790466925,
                      "started_at": null,
                      "metadata": null,
                      "order_id": "ord_Vd3kR8mQ1xTn6LpZs0Wa",
                      "collect": null,
                      "canceled_at": null,
                      "checkout_id": null,
                      "plan_label": null
                    },
                    "x-railbed-fixture": "session-store"
                  },
                  "from_checkout": {
                    "summary": "A session from a saved pricing table",
                    "value": {
                      "id": "pay_Hq2Nc6Vx9LmT4bRz8KpW",
                      "object": "checkout_session",
                      "url": "https://pay.railbed.io/p/pay_Hq2Nc6Vx9LmT4bRz8KpW",
                      "status": "open",
                      "livemode": false,
                      "amount": "490.00",
                      "currency": "USD",
                      "description": "Membership",
                      "reference": "user_1042",
                      "customer_email": "player@example.com",
                      "created": 1790380525,
                      "expires_at": 1790466925,
                      "started_at": null,
                      "metadata": {"user_id": "player_1042"},
                      "order_id": "ord_Wc5Lr9Tz2QmX7vKn3BsH",
                      "collect": null,
                      "canceled_at": null,
                      "checkout_id": "chk_Np4wQ8sT2mXv7KcZr5Ld",
                      "plan_label": "Pro · Yearly"
                    },
                    "x-railbed-fixture": "session-from-checkout"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_json`, `invalid_amount`, `invalid_currency`, `missing_description`, `too_long`, `invalid_reference`, `invalid_email`, `invalid_url`, `invalid_metadata`, `invalid_idempotency_key`, `invalid_customer`, `invalid_order`, `invalid_order_totals`, `invalid_collect`, `field_not_allowed`, `invalid_checkout`, `invalid_plan`.",
            "x-railbed-error-codes": [
              "invalid_json",
              "invalid_amount",
              "invalid_currency",
              "missing_description",
              "too_long",
              "invalid_reference",
              "invalid_email",
              "invalid_url",
              "invalid_metadata",
              "invalid_idempotency_key",
              "invalid_customer",
              "invalid_order",
              "invalid_order_totals",
              "invalid_collect",
              "field_not_allowed",
              "invalid_checkout",
              "invalid_plan"
            ],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`, `merchant_read_only`, `integration_disabled`.",
            "x-railbed-error-codes": ["insufficient_scope", "merchant_read_only", "integration_disabled"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "409": {
            "description": "The object's state doesn't allow this. Read it and act on its current status. Codes: `idempotency_conflict`, `idempotency_in_progress`, `no_payout_wallet`, `account_review`, `order_paid`, `order_erased`, `checkout_off`, `checkout_deleted`, `commerce_paused`, `no_providers`.",
            "x-railbed-error-codes": [
              "idempotency_conflict",
              "idempotency_in_progress",
              "no_payout_wallet",
              "account_review",
              "order_paid",
              "order_erased",
              "checkout_off",
              "checkout_deleted",
              "commerce_paused",
              "no_providers"
            ],
            "headers": {
              "Retry-After": {
                "$ref": "#/components/headers/Retry-After",
                "description": "With `idempotency_in_progress`: send the same request again with the same key after this many seconds."
              }
            },
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "413": {"$ref": "#/components/responses/PayloadTooLarge"},
          "415": {"$ref": "#/components/responses/UnsupportedMediaType"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/checkout-sessions/#create-a-checkout-session"
        }
      }
    },
    "/checkout_sessions/{id}": {
      "get": {
        "operationId": "retrieveCheckoutSession",
        "summary": "Retrieve a checkout session",
        "description": "Returns a session by its id. For its settlement, retrieve the payment with the same id.",
        "tags": ["Checkout sessions"],
        "security": [{"secretKey": ["payments:read"]}, {"agentToken": ["payments:read"]}],
        "x-railbed-scope": "payments:read",
        "parameters": [{"$ref": "#/components/parameters/SessionId"}],
        "responses": {
          "200": {
            "description": "The session.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/CheckoutSession"},
                "examples": {
                  "session": {
                    "summary": "An open session",
                    "value": {
                      "id": "pay_7AAiYH0Ykt11ED4hmfiN",
                      "object": "checkout_session",
                      "url": "https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN",
                      "status": "open",
                      "livemode": false,
                      "amount": "49.00",
                      "currency": "USD",
                      "description": "Pro Membership",
                      "reference": "order_1042",
                      "customer_email": "buyer@example.com",
                      "created": 1790380525,
                      "expires_at": 1790466925,
                      "started_at": null,
                      "metadata": {"user_id": "player_1042"},
                      "order_id": "ord_M4tQx8ZkP1vRn6WcLs2B",
                      "collect": null,
                      "canceled_at": null,
                      "checkout_id": null,
                      "plan_label": null
                    },
                    "x-railbed-fixture": "session-created"
                  }
                }
              }
            }
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`.",
            "x-railbed-error-codes": ["insufficient_scope"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/checkout-sessions/#retrieve-a-checkout-session"
        }
      }
    },
    "/checkout_sessions/{id}/start": {
      "post": {
        "operationId": "startCheckoutSession",
        "summary": "Start a checkout session",
        "description": "For your own checkout: starts the session as the buyer would on the hosted page, and returns the card providers that can take it, each with a `handoff_url` to open in the buyer's browser. Starting again is safe.",
        "tags": ["Checkout sessions"],
        "security": [{"secretKey": ["checkouts:write"]}, {"agentToken": ["checkouts:write"]}],
        "x-railbed-scope": "checkouts:write",
        "parameters": [{"$ref": "#/components/parameters/SessionId"}],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/StartCheckoutSession"},
              "examples": {"country": {"summary": "With the buyer's country", "value": {"country": "US"}}}
            }
          }
        },
        "responses": {
          "200": {
            "description": "The started session and its providers, best match first.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/StartedCheckoutSession"},
                "examples": {
                  "started": {
                    "summary": "Two providers",
                    "value": {
                      "id": "pay_7AAiYH0Ykt11ED4hmfiN",
                      "object": "checkout_session",
                      "url": "https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN",
                      "status": "open",
                      "livemode": false,
                      "amount": "49.00",
                      "currency": "USD",
                      "description": "Pro Membership",
                      "reference": "order_1042",
                      "customer_email": "buyer@example.com",
                      "created": 1790380525,
                      "expires_at": 1790466925,
                      "started_at": 1790380611,
                      "metadata": {"user_id": "player_1042"},
                      "order_id": "ord_M4tQx8ZkP1vRn6WcLs2B",
                      "collect": null,
                      "canceled_at": null,
                      "checkout_id": null,
                      "plan_label": null,
                      "country": "US",
                      "providers": [
                        {
                          "id": "stripe",
                          "name": "Stripe",
                          "note": "Card, Apple Pay or Google Pay",
                          "recommended": true,
                          "handoff_url": "https://pay.railbed.io/go/pay_7AAiYH0Ykt11ED4hmfiN?provider=stripe"
                        },
                        {
                          "id": "coindisco",
                          "name": "Coindisco",
                          "note": "Card, through Coindisco",
                          "recommended": false,
                          "handoff_url": "https://pay.railbed.io/go/pay_7AAiYH0Ykt11ED4hmfiN?provider=coindisco"
                        }
                      ]
                    },
                    "x-railbed-fixture": "session-started"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_json`, `invalid_email`, `invalid_country`.",
            "x-railbed-error-codes": ["invalid_json", "invalid_email", "invalid_country"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`, `merchant_read_only`, `integration_disabled`.",
            "x-railbed-error-codes": ["insufficient_scope", "merchant_read_only", "integration_disabled"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "409": {
            "description": "The object's state doesn't allow this. Read it and act on its current status. `no_providers` says why in `reason`, with the `providers` it is about. Codes: `no_providers`, `already_paid`, `held`, `failed`, `unavailable`, `commerce_paused`, `start_changed`, `invoice_changed`.",
            "x-railbed-error-codes": [
              "no_providers",
              "already_paid",
              "held",
              "failed",
              "unavailable",
              "commerce_paused",
              "start_changed",
              "invoice_changed"
            ],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "410": {
            "description": "The session can't be paid any more. Create a new one. `invoice_void`: it paid toward an invoice that was voided. Codes: `expired`, `canceled`, `invoice_void`.",
            "x-railbed-error-codes": ["expired", "canceled", "invoice_void"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "413": {"$ref": "#/components/responses/PayloadTooLarge"},
          "415": {"$ref": "#/components/responses/UnsupportedMediaType"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "502": {
            "description": "The card network didn't answer while starting. Retry in a minute. Codes: `network_unavailable`.",
            "x-railbed-error-codes": ["network_unavailable"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "503": {
            "description": "Live only: new payments are paused for a few minutes while a problem is fixed. Nothing was started. Retry shortly; sessions already started still complete. Codes: `payments_paused`.",
            "x-railbed-error-codes": ["payments_paused"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/checkout-sessions/#start-a-checkout-session"
        }
      }
    },
    "/checkout_sessions/{id}/cancel": {
      "post": {
        "operationId": "cancelCheckoutSession",
        "summary": "Cancel a checkout session",
        "description": "Closes a session nobody has started paying, so its page and its `handoff_url` links can't be used any more. No body is needed, and canceling again returns the same session. Money already on its way can still settle a canceled session: keep honoring a late `paid`.",
        "tags": ["Checkout sessions"],
        "security": [{"secretKey": ["checkouts:write"]}, {"agentToken": ["checkouts:write"]}],
        "x-railbed-scope": "checkouts:write",
        "parameters": [{"$ref": "#/components/parameters/SessionId"}],
        "responses": {
          "200": {
            "description": "The session, with `status` `expired` and `canceled_at` set.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/CheckoutSession"},
                "examples": {
                  "canceled": {
                    "summary": "A canceled session",
                    "value": {
                      "id": "pay_7AAiYH0Ykt11ED4hmfiN",
                      "object": "checkout_session",
                      "url": "https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN",
                      "status": "expired",
                      "livemode": false,
                      "amount": "49.00",
                      "currency": "USD",
                      "description": "Pro Membership",
                      "reference": "order_1042",
                      "customer_email": "buyer@example.com",
                      "created": 1790380525,
                      "expires_at": 1790466925,
                      "started_at": null,
                      "metadata": {"user_id": "player_1042"},
                      "order_id": "ord_M4tQx8ZkP1vRn6WcLs2B",
                      "collect": null,
                      "canceled_at": 1790380711,
                      "checkout_id": null,
                      "plan_label": null
                    },
                    "x-railbed-fixture": "session-canceled"
                  }
                }
              }
            }
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`, `merchant_read_only`.",
            "x-railbed-error-codes": ["insufficient_scope", "merchant_read_only"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "409": {
            "description": "The object's state doesn't allow this. Read it and act on its current status. Codes: `not_cancelable`.",
            "x-railbed-error-codes": ["not_cancelable"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/checkout-sessions/#cancel-a-checkout-session"
        }
      }
    },
    "/payments": {
      "get": {
        "operationId": "listPayments",
        "summary": "List payments",
        "description": "Returns payments newest first. Filters combine.",
        "tags": ["Payments"],
        "security": [{"secretKey": ["payments:read"]}, {"agentToken": ["payments:read"]}],
        "x-railbed-scope": "payments:read",
        "parameters": [
          {"$ref": "#/components/parameters/Limit"},
          {"$ref": "#/components/parameters/PaymentCursor"},
          {"$ref": "#/components/parameters/StatusFilter"},
          {"$ref": "#/components/parameters/ReferenceFilter"},
          {"$ref": "#/components/parameters/InvoiceIdFilter"},
          {"$ref": "#/components/parameters/CreatedGte"},
          {"$ref": "#/components/parameters/CreatedLte"}
        ],
        "responses": {
          "200": {
            "description": "A page of payments.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/PaymentList"},
                "examples": {
                  "page": {
                    "summary": "A page",
                    "value": {
                      "data": [
                        {
                          "id": "pay_7AAiYH0Ykt11ED4hmfiN",
                          "object": "payment",
                          "url": "https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN",
                          "status": "paid",
                          "livemode": false,
                          "amount": "49.00",
                          "currency": "USD",
                          "description": "Pro Membership",
                          "reference": "order_1042",
                          "customer_email": "buyer@example.com",
                          "created": 1790380525,
                          "expires_at": 1790466925,
                          "started_at": 1790380611,
                          "metadata": {"user_id": "player_1042"},
                          "order_id": "ord_M4tQx8ZkP1vRn6WcLs2B",
                          "collect": null,
                          "canceled_at": null,
                          "checkout_id": null,
                          "plan_label": null,
                          "paid_at": 1790381342,
                          "provider": "stripe",
                          "hold_reason": null,
                          "hold_acceptable": false,
                          "method": "card",
                          "settlement": {
                            "network": null,
                            "coin": "polygon_usdc",
                            "value_coin": "47.53",
                            "merchant_received": "44.915850",
                            "merchant_received_usd": "44.915850",
                            "txid_in": "0x1111111111111111111111111111111111111111111111111111111111111111",
                            "txid_out": "0x2222222222222222222222222222222222222222222222222222222222222222",
                            "payout_wallet": "0x3333333333333333333333333333333333333333"
                          },
                          "invoice_id": null,
                          "tip": "0.00"
                        },
                        {
                          "id": "pay_Kx81mQv2PzR0dT7eWcYa",
                          "object": "payment",
                          "url": "https://pay.railbed.io/p/pay_Kx81mQv2PzR0dT7eWcYa",
                          "status": "held",
                          "livemode": false,
                          "amount": "49.00",
                          "currency": "USD",
                          "description": "Pro Membership",
                          "reference": "order_1042",
                          "customer_email": "buyer@example.com",
                          "created": 1790380465,
                          "expires_at": 1790466865,
                          "started_at": 1790380611,
                          "metadata": {"user_id": "player_1042"},
                          "order_id": "ord_Rx2Np5VqT9sW4mLb7ZaC",
                          "collect": null,
                          "canceled_at": null,
                          "checkout_id": null,
                          "plan_label": null,
                          "paid_at": null,
                          "provider": "stripe",
                          "hold_reason": "The provider sent 24.50 USDC, below 85% of the order’s 49.00 USD value.",
                          "hold_acceptable": true,
                          "method": "card",
                          "settlement": {
                            "network": null,
                            "coin": "polygon_usdc",
                            "value_coin": "24.50",
                            "merchant_received": "23.152500",
                            "merchant_received_usd": "23.152500",
                            "txid_in": "0x1111111111111111111111111111111111111111111111111111111111111111",
                            "txid_out": "0x2222222222222222222222222222222222222222222222222222222222222222",
                            "payout_wallet": "0x3333333333333333333333333333333333333333"
                          },
                          "invoice_id": null,
                          "tip": "0.00"
                        }
                      ],
                      "has_more": true,
                      "next_cursor": "pay_Kx81mQv2PzR0dT7eWcYa"
                    },
                    "x-railbed-fixture": "payment-list"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_limit`, `invalid_cursor`, `invalid_status`, `invalid_reference`, `invalid_invoice_id`, `invalid_created_gte`, `invalid_created_lte`, `invalid_dates`.",
            "x-railbed-error-codes": [
              "invalid_limit",
              "invalid_cursor",
              "invalid_status",
              "invalid_reference",
              "invalid_invoice_id",
              "invalid_created_gte",
              "invalid_created_lte",
              "invalid_dates"
            ],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`.",
            "x-railbed-error-codes": ["insufficient_scope"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/payments/#list-payments"
        }
      }
    },
    "/payments/{id}": {
      "get": {
        "operationId": "retrievePayment",
        "summary": "Retrieve a payment",
        "description": "Returns a payment by its id, the same as its session's. Fulfil only when `status` is `paid`.",
        "tags": ["Payments"],
        "security": [{"secretKey": ["payments:read"]}, {"agentToken": ["payments:read"]}],
        "x-railbed-scope": "payments:read",
        "parameters": [{"$ref": "#/components/parameters/PaymentId"}],
        "responses": {
          "200": {
            "description": "The payment.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Payment"},
                "examples": {
                  "card": {
                    "summary": "Paid by card",
                    "value": {
                      "id": "pay_7AAiYH0Ykt11ED4hmfiN",
                      "object": "payment",
                      "url": "https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN",
                      "status": "paid",
                      "livemode": false,
                      "amount": "49.00",
                      "currency": "USD",
                      "description": "Pro Membership",
                      "reference": "order_1042",
                      "customer_email": "buyer@example.com",
                      "created": 1790380525,
                      "expires_at": 1790466925,
                      "started_at": 1790380611,
                      "metadata": {"user_id": "player_1042"},
                      "order_id": "ord_M4tQx8ZkP1vRn6WcLs2B",
                      "collect": null,
                      "canceled_at": null,
                      "checkout_id": null,
                      "plan_label": null,
                      "paid_at": 1790381342,
                      "provider": "stripe",
                      "hold_reason": null,
                      "hold_acceptable": false,
                      "method": "card",
                      "settlement": {
                        "network": null,
                        "coin": "polygon_usdc",
                        "value_coin": "47.53",
                        "merchant_received": "44.915850",
                        "merchant_received_usd": "44.915850",
                        "txid_in": "0x1111111111111111111111111111111111111111111111111111111111111111",
                        "txid_out": "0x2222222222222222222222222222222222222222222222222222222222222222",
                        "payout_wallet": "0x3333333333333333333333333333333333333333"
                      },
                      "invoice_id": null,
                      "tip": "0.00"
                    },
                    "x-railbed-fixture": "payment-card"
                  },
                  "held": {
                    "summary": "Held: less arrived than the order's value",
                    "value": {
                      "id": "pay_Kx81mQv2PzR0dT7eWcYa",
                      "object": "payment",
                      "url": "https://pay.railbed.io/p/pay_Kx81mQv2PzR0dT7eWcYa",
                      "status": "held",
                      "livemode": false,
                      "amount": "49.00",
                      "currency": "USD",
                      "description": "Pro Membership",
                      "reference": "order_1042",
                      "customer_email": "buyer@example.com",
                      "created": 1790380465,
                      "expires_at": 1790466865,
                      "started_at": 1790380611,
                      "metadata": {"user_id": "player_1042"},
                      "order_id": "ord_Rx2Np5VqT9sW4mLb7ZaC",
                      "collect": null,
                      "canceled_at": null,
                      "checkout_id": null,
                      "plan_label": null,
                      "paid_at": null,
                      "provider": "stripe",
                      "hold_reason": "The provider sent 24.50 USDC, below 85% of the order’s 49.00 USD value.",
                      "hold_acceptable": true,
                      "method": "card",
                      "settlement": {
                        "network": null,
                        "coin": "polygon_usdc",
                        "value_coin": "24.50",
                        "merchant_received": "23.152500",
                        "merchant_received_usd": "23.152500",
                        "txid_in": "0x1111111111111111111111111111111111111111111111111111111111111111",
                        "txid_out": "0x2222222222222222222222222222222222222222222222222222222222222222",
                        "payout_wallet": "0x3333333333333333333333333333333333333333"
                      },
                      "invoice_id": null,
                      "tip": "0.00"
                    },
                    "x-railbed-fixture": "payment-held"
                  },
                  "crypto": {
                    "summary": "Paid in crypto",
                    "value": {
                      "id": "pay_Sd70mP9ArQ6cW2zXn8eV",
                      "object": "payment",
                      "url": "https://pay.railbed.io/p/pay_Sd70mP9ArQ6cW2zXn8eV",
                      "status": "paid",
                      "livemode": false,
                      "amount": "100.00",
                      "currency": "USD",
                      "description": "Annual Membership",
                      "reference": "order_1043",
                      "customer_email": "buyer@example.com",
                      "created": 1790380525,
                      "expires_at": 1790466925,
                      "started_at": 1790380611,
                      "metadata": {"user_id": "player_1042"},
                      "order_id": "ord_C9vMx2QpR5tN8wKa3sLb",
                      "collect": null,
                      "canceled_at": null,
                      "checkout_id": null,
                      "plan_label": null,
                      "paid_at": 1790381342,
                      "provider": null,
                      "hold_reason": null,
                      "hold_acceptable": false,
                      "method": "crypto",
                      "settlement": {
                        "network": "base",
                        "coin": "base_usdc",
                        "value_coin": "100.00",
                        "merchant_received": "98.000000",
                        "merchant_received_usd": "98.000000",
                        "txid_in": "0x1111111111111111111111111111111111111111111111111111111111111111",
                        "txid_out": "0x2222222222222222222222222222222222222222222222222222222222222222",
                        "payout_wallet": "0x3333333333333333333333333333333333333333"
                      },
                      "invoice_id": null,
                      "tip": "0.00"
                    },
                    "x-railbed-fixture": "payment-crypto"
                  }
                }
              }
            }
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`.",
            "x-railbed-error-codes": ["insufficient_scope"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/payments/#retrieve-a-payment"
        }
      }
    },
    "/payments/{id}/simulate": {
      "post": {
        "operationId": "simulatePayment",
        "summary": "Simulate a payment",
        "description": "Test mode only: plays out a provider's answer on a started Test payment. `paid` and `underpaid` run the same settlement checks as real money. No money moves.",
        "tags": ["Payments"],
        "security": [{"secretKey": ["checkouts:write"]}, {"agentToken": ["checkouts:write"]}],
        "x-railbed-scope": "checkouts:write",
        "parameters": [{"$ref": "#/components/parameters/PaymentId"}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/SimulatePayment"},
              "examples": {"paid": {"summary": "Settle it", "value": {"outcome": "paid"}}}
            }
          }
        },
        "responses": {
          "200": {
            "description": "The payment after the outcome.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Payment"},
                "examples": {
                  "paid": {
                    "summary": "Paid",
                    "value": {
                      "id": "pay_7AAiYH0Ykt11ED4hmfiN",
                      "object": "payment",
                      "url": "https://pay.railbed.io/p/pay_7AAiYH0Ykt11ED4hmfiN",
                      "status": "paid",
                      "livemode": false,
                      "amount": "49.00",
                      "currency": "USD",
                      "description": "Pro Membership",
                      "reference": "order_1042",
                      "customer_email": "buyer@example.com",
                      "created": 1790380525,
                      "expires_at": 1790466925,
                      "started_at": 1790380611,
                      "metadata": {"user_id": "player_1042"},
                      "order_id": "ord_M4tQx8ZkP1vRn6WcLs2B",
                      "collect": null,
                      "canceled_at": null,
                      "checkout_id": null,
                      "plan_label": null,
                      "paid_at": 1790381342,
                      "provider": "stripe",
                      "hold_reason": null,
                      "hold_acceptable": false,
                      "method": "card",
                      "settlement": {
                        "network": null,
                        "coin": "polygon_usdc",
                        "value_coin": "47.53",
                        "merchant_received": "44.915850",
                        "merchant_received_usd": "44.915850",
                        "txid_in": "0x1111111111111111111111111111111111111111111111111111111111111111",
                        "txid_out": "0x2222222222222222222222222222222222222222222222222222222222222222",
                        "payout_wallet": "0x3333333333333333333333333333333333333333"
                      },
                      "invoice_id": null,
                      "tip": "0.00"
                    },
                    "x-railbed-fixture": "payment-card"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_json`, `invalid_outcome`.",
            "x-railbed-error-codes": ["invalid_json", "invalid_outcome"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`, `merchant_read_only`, `live_payment`.",
            "x-railbed-error-codes": ["insufficient_scope", "merchant_read_only", "live_payment"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "409": {
            "description": "The object's state doesn't allow this. Read it and act on its current status. Codes: `not_started`.",
            "x-railbed-error-codes": ["not_started"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "413": {"$ref": "#/components/responses/PayloadTooLarge"},
          "415": {"$ref": "#/components/responses/UnsupportedMediaType"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/payments/#simulate-a-payment"
        }
      }
    },
    "/payment_methods": {
      "get": {
        "operationId": "listPaymentMethods",
        "summary": "List payment methods",
        "description": "Returns the card providers, which you turned off, and, with `amount`, what Smart Routing would offer a buyer for it today, why each other provider is ruled out, and why nothing is offered when nothing is.",
        "tags": ["Payment methods"],
        "security": [{"secretKey": ["payments:read"]}, {"agentToken": ["payments:read"]}],
        "x-railbed-scope": "payments:read",
        "parameters": [
          {
            "name": "amount",
            "in": "query",
            "required": false,
            "description": "An amount, to see what Smart Routing would offer for it.",
            "schema": {"$ref": "#/components/schemas/AmountInput"}
          },
          {
            "name": "currency",
            "in": "query",
            "required": false,
            "description": "With `amount`. Default `USD`.",
            "schema": {"$ref": "#/components/schemas/CurrencyInput"}
          },
          {
            "name": "country",
            "in": "query",
            "required": false,
            "description": "With `amount`: the buyer's two-letter country code.",
            "schema": {"type": "string", "pattern": "^[A-Za-z]{2}$"}
          }
        ],
        "responses": {
          "200": {
            "description": "The card providers.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/PaymentMethodList"},
                "examples": {
                  "list": {
                    "summary": "Every provider",
                    "value": {
                      "object": "list",
                      "data": [
                        {
                          "id": "stripe",
                          "name": "Stripe",
                          "note": "Card, Apple Pay or Google Pay",
                          "status": "available",
                          "minimum": {"amount": "2.00", "currency": "USD"},
                          "regions": ["US"],
                          "merchant_off": false
                        },
                        {
                          "id": "paypal",
                          "name": "PayPal",
                          "note": "PayPal balance or card",
                          "status": "available",
                          "minimum": {"amount": "5.00", "currency": "USD"},
                          "regions": ["US"],
                          "merchant_off": true
                        },
                        {
                          "id": "cashapp",
                          "name": "Cash App",
                          "note": "Cash App balance or card",
                          "status": "available",
                          "minimum": {"amount": "2.00", "currency": "USD"},
                          "regions": ["US"],
                          "merchant_off": false
                        }
                      ]
                    },
                    "x-railbed-fixture": "payment-method-list"
                  },
                  "offer": {
                    "summary": "With an amount",
                    "value": {
                      "object": "list",
                      "data": [
                        {
                          "id": "stripe",
                          "name": "Stripe",
                          "note": "Card, Apple Pay or Google Pay",
                          "status": "available",
                          "minimum": {"amount": "2.00", "currency": "USD"},
                          "regions": ["US"],
                          "merchant_off": false
                        },
                        {
                          "id": "paypal",
                          "name": "PayPal",
                          "note": "PayPal balance or card",
                          "status": "available",
                          "minimum": {"amount": "5.00", "currency": "USD"},
                          "regions": ["US"],
                          "merchant_off": true
                        },
                        {
                          "id": "cashapp",
                          "name": "Cash App",
                          "note": "Cash App balance or card",
                          "status": "available",
                          "minimum": {"amount": "2.00", "currency": "USD"},
                          "regions": ["US"],
                          "merchant_off": false
                        }
                      ],
                      "offered": [
                        {
                          "id": "stripe",
                          "name": "Stripe",
                          "note": "Card, Apple Pay or Google Pay",
                          "recommended": true
                        },
                        {
                          "id": "coindisco",
                          "name": "Coindisco",
                          "note": "Card, through Coindisco",
                          "recommended": false
                        },
                        {
                          "id": "cashapp",
                          "name": "Cash App",
                          "note": "Cash App balance or card",
                          "recommended": false
                        }
                      ],
                      "not_offered": [
                        {"id": "paypal", "reason": "merchant_off"},
                        {"id": "revolut", "reason": "country"},
                        {"id": "sardine", "reason": "below_minimum"}
                      ]
                    },
                    "x-railbed-fixture": "payment-method-offer"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_amount`, `invalid_currency`, `invalid_country`.",
            "x-railbed-error-codes": ["invalid_amount", "invalid_currency", "invalid_country"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`.",
            "x-railbed-error-codes": ["insufficient_scope"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/payment-methods/#list-payment-methods"
        }
      }
    },
    "/payout_wallets": {
      "get": {
        "operationId": "listPayoutWallets",
        "summary": "List payout wallets",
        "description": "Returns the account's other saved wallets, newest first, so a payment link or invoice can name one as `payout_wallet_id`. Read only: an owner saves and removes them in the dashboard, and no key or agent can. The list is the same in Test and Live mode and is never paged.",
        "tags": ["Payout wallets"],
        "security": [{"secretKey": ["payments:read"]}, {"agentToken": ["payments:read"]}],
        "x-railbed-scope": "payments:read",
        "responses": {
          "200": {
            "description": "Every saved wallet.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/PayoutWalletList"},
                "examples": {
                  "wallets": {
                    "summary": "One saved wallet",
                    "value": {
                      "data": [
                        {
                          "id": "pw_Wh7kQ2nVx9RtZ4mLp6Cb",
                          "object": "payout_wallet",
                          "network": "evm",
                          "address": "0x7a1c4e9b2d5f8a3c6e0b1d4f7a9c2e5b8d0f3a6c",
                          "label": "Wholesale",
                          "usable": true,
                          "created": 1790380525
                        }
                      ],
                      "has_more": false,
                      "next_cursor": null
                    },
                    "x-railbed-fixture": "payout-wallet-list"
                  }
                }
              }
            }
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`.",
            "x-railbed-error-codes": ["insufficient_scope"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/payout-wallets/#list-payout-wallets"
        }
      }
    },
    "/payment_links": {
      "post": {
        "operationId": "createPaymentLink",
        "summary": "Create a payment link",
        "description": "Asks one payer for one amount. The link is one payment, so its id is the payment's.",
        "tags": ["Payment links"],
        "security": [{"secretKey": ["checkouts:write"]}, {"agentToken": ["checkouts:write"]}],
        "x-railbed-scope": "checkouts:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/CreatePaymentLink"},
              "examples": {
                "invoice": {
                  "summary": "An invoice for two weeks",
                  "value": {
                    "amount": "250.00",
                    "currency": "USD",
                    "description": "Consulting, September",
                    "customer_name": "Ada Lovelace",
                    "customer_email": "ada@example.com",
                    "reference": "INV-0042",
                    "memo": "Thanks for your business.",
                    "expires_in_days": 14
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The new link. `warnings` appears only when there is something to say about the card providers' minimums.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/PaymentLink"},
                "examples": {
                  "link": {
                    "summary": "A new link",
                    "value": {
                      "id": "pay_Lk4mQ8vR2xTn7WcZs1Pb",
                      "object": "payment_link",
                      "url": "https://pay.railbed.io/p/pay_Lk4mQ8vR2xTn7WcZs1Pb",
                      "tracking_url": "https://pay.railbed.io/t/Tq3nV8xK2mRz7LpW4cYb5sDh",
                      "status": "open",
                      "livemode": false,
                      "amount": "250.00",
                      "currency": "USD",
                      "description": "Consulting, September",
                      "reference": "INV-0042",
                      "customer_name": "Ada Lovelace",
                      "customer_email": "ada@example.com",
                      "memo": "Thanks for your business.",
                      "success_url": null,
                      "collect": null,
                      "routing": {"choice": "buyer", "provider": null, "fallback": true, "providers": null},
                      "order_id": "ord_Hn6pW2zQ8rKt3VmXc9La",
                      "payout_wallet_id": null,
                      "created": 1790380525,
                      "expires_at": 1791590125,
                      "started_at": null,
                      "paid_at": null,
                      "canceled_at": null
                    },
                    "x-railbed-fixture": "payment-link"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_json`, `invalid_amount`, `invalid_currency`, `invalid_description`, `too_long`, `invalid_customer_name`, `invalid_customer_phone`, `invalid_reference`, `invalid_memo`, `invalid_email`, `invalid_address`, `invalid_expiry`, `invalid_payout_wallet`, `invalid_url`, `invalid_collect`, `invalid_routing`.",
            "x-railbed-error-codes": [
              "invalid_json",
              "invalid_amount",
              "invalid_currency",
              "invalid_description",
              "too_long",
              "invalid_customer_name",
              "invalid_customer_phone",
              "invalid_reference",
              "invalid_memo",
              "invalid_email",
              "invalid_address",
              "invalid_expiry",
              "invalid_payout_wallet",
              "invalid_url",
              "invalid_collect",
              "invalid_routing"
            ],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`, `merchant_read_only`, `integration_disabled`.",
            "x-railbed-error-codes": ["insufficient_scope", "merchant_read_only", "integration_disabled"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "409": {
            "description": "The object's state doesn't allow this. Read it and act on its current status. Codes: `no_payout_wallet`, `account_review`, `payout_wallet_unusable`, `commerce_paused`.",
            "x-railbed-error-codes": [
              "no_payout_wallet",
              "account_review",
              "payout_wallet_unusable",
              "commerce_paused"
            ],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "413": {"$ref": "#/components/responses/PayloadTooLarge"},
          "415": {"$ref": "#/components/responses/UnsupportedMediaType"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/payment-links/#create-a-payment-link"
        }
      },
      "get": {
        "operationId": "listPaymentLinks",
        "summary": "List payment links",
        "description": "Returns payment links newest first, with the same filters as payments.",
        "tags": ["Payment links"],
        "security": [{"secretKey": ["payments:read"]}, {"agentToken": ["payments:read"]}],
        "x-railbed-scope": "payments:read",
        "parameters": [
          {"$ref": "#/components/parameters/Limit"},
          {"$ref": "#/components/parameters/PaymentLinkCursor"},
          {"$ref": "#/components/parameters/StatusFilter"},
          {"$ref": "#/components/parameters/ReferenceFilter"},
          {"$ref": "#/components/parameters/CreatedGte"},
          {"$ref": "#/components/parameters/CreatedLte"}
        ],
        "responses": {
          "200": {
            "description": "A page of payment links.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/PaymentLinkList"},
                "examples": {
                  "page": {
                    "summary": "A page",
                    "value": {
                      "data": [
                        {
                          "id": "pay_Lk4mQ8vR2xTn7WcZs1Pb",
                          "object": "payment_link",
                          "url": "https://pay.railbed.io/p/pay_Lk4mQ8vR2xTn7WcZs1Pb",
                          "tracking_url": "https://pay.railbed.io/t/Tq3nV8xK2mRz7LpW4cYb5sDh",
                          "status": "open",
                          "livemode": false,
                          "amount": "250.00",
                          "currency": "USD",
                          "description": "Consulting, September",
                          "reference": "INV-0042",
                          "customer_name": "Ada Lovelace",
                          "customer_email": "ada@example.com",
                          "memo": "Thanks for your business.",
                          "success_url": null,
                          "collect": null,
                          "routing": {
                            "choice": "buyer",
                            "provider": null,
                            "fallback": true,
                            "providers": null
                          },
                          "order_id": "ord_Hn6pW2zQ8rKt3VmXc9La",
                          "payout_wallet_id": null,
                          "created": 1790380525,
                          "expires_at": 1791590125,
                          "started_at": null,
                          "paid_at": null,
                          "canceled_at": null
                        }
                      ],
                      "has_more": false,
                      "next_cursor": null
                    },
                    "x-railbed-fixture": "payment-link-list"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_limit`, `invalid_cursor`, `invalid_status`, `invalid_reference`, `invalid_created_gte`, `invalid_created_lte`, `invalid_dates`.",
            "x-railbed-error-codes": [
              "invalid_limit",
              "invalid_cursor",
              "invalid_status",
              "invalid_reference",
              "invalid_created_gte",
              "invalid_created_lte",
              "invalid_dates"
            ],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`.",
            "x-railbed-error-codes": ["insufficient_scope"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/payment-links/#list-payment-links"
        }
      }
    },
    "/payment_links/{id}": {
      "get": {
        "operationId": "retrievePaymentLink",
        "summary": "Retrieve a payment link",
        "description": "Returns a payment link by its id.",
        "tags": ["Payment links"],
        "security": [{"secretKey": ["payments:read"]}, {"agentToken": ["payments:read"]}],
        "x-railbed-scope": "payments:read",
        "parameters": [{"$ref": "#/components/parameters/PaymentLinkId"}],
        "responses": {
          "200": {
            "description": "The payment link.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/PaymentLink"},
                "examples": {
                  "link": {
                    "summary": "An open link",
                    "value": {
                      "id": "pay_Lk4mQ8vR2xTn7WcZs1Pb",
                      "object": "payment_link",
                      "url": "https://pay.railbed.io/p/pay_Lk4mQ8vR2xTn7WcZs1Pb",
                      "tracking_url": "https://pay.railbed.io/t/Tq3nV8xK2mRz7LpW4cYb5sDh",
                      "status": "open",
                      "livemode": false,
                      "amount": "250.00",
                      "currency": "USD",
                      "description": "Consulting, September",
                      "reference": "INV-0042",
                      "customer_name": "Ada Lovelace",
                      "customer_email": "ada@example.com",
                      "memo": "Thanks for your business.",
                      "success_url": null,
                      "collect": null,
                      "routing": {"choice": "buyer", "provider": null, "fallback": true, "providers": null},
                      "order_id": "ord_Hn6pW2zQ8rKt3VmXc9La",
                      "payout_wallet_id": null,
                      "created": 1790380525,
                      "expires_at": 1791590125,
                      "started_at": null,
                      "paid_at": null,
                      "canceled_at": null
                    },
                    "x-railbed-fixture": "payment-link"
                  }
                }
              }
            }
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`.",
            "x-railbed-error-codes": ["insufficient_scope"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/payment-links/#retrieve-a-payment-link"
        }
      }
    },
    "/payment_links/{id}/cancel": {
      "post": {
        "operationId": "cancelPaymentLink",
        "summary": "Cancel a payment link",
        "description": "Closes a link nobody has started paying. No body is needed, and canceling again returns the same link.",
        "tags": ["Payment links"],
        "security": [{"secretKey": ["checkouts:write"]}, {"agentToken": ["checkouts:write"]}],
        "x-railbed-scope": "checkouts:write",
        "parameters": [{"$ref": "#/components/parameters/PaymentLinkId"}],
        "responses": {
          "200": {
            "description": "The link, with `status` `expired` and `canceled_at` set.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/PaymentLink"},
                "examples": {
                  "canceled": {
                    "summary": "A canceled link",
                    "value": {
                      "id": "pay_Lk4mQ8vR2xTn7WcZs1Pb",
                      "object": "payment_link",
                      "url": "https://pay.railbed.io/p/pay_Lk4mQ8vR2xTn7WcZs1Pb",
                      "tracking_url": "https://pay.railbed.io/t/Tq3nV8xK2mRz7LpW4cYb5sDh",
                      "status": "expired",
                      "livemode": false,
                      "amount": "250.00",
                      "currency": "USD",
                      "description": "Consulting, September",
                      "reference": "INV-0042",
                      "customer_name": "Ada Lovelace",
                      "customer_email": "ada@example.com",
                      "memo": "Thanks for your business.",
                      "success_url": null,
                      "collect": null,
                      "routing": {"choice": "buyer", "provider": null, "fallback": true, "providers": null},
                      "order_id": "ord_Hn6pW2zQ8rKt3VmXc9La",
                      "payout_wallet_id": null,
                      "created": 1790380525,
                      "expires_at": 1791590125,
                      "started_at": null,
                      "paid_at": null,
                      "canceled_at": 1790384125
                    },
                    "x-railbed-fixture": "payment-link-canceled"
                  }
                }
              }
            }
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`, `merchant_read_only`.",
            "x-railbed-error-codes": ["insufficient_scope", "merchant_read_only"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "409": {
            "description": "The object's state doesn't allow this. Read it and act on its current status. Codes: `not_cancelable`.",
            "x-railbed-error-codes": ["not_cancelable"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/payment-links/#cancel-a-payment-link"
        }
      }
    },
    "/invoices": {
      "post": {
        "operationId": "createInvoice",
        "summary": "Create an invoice",
        "description": "Makes an invoice in the credential's mode: a draft by default, issued with `issue: true` (its `url` can then be shared and paid, with or without a customer: one who isn't named gives their email as they pay), or issued and emailed to the customer with `send: true`, which needs the customer's name and email. Send `Idempotency-Key` so a retried request answers the first invoice instead of making a second.",
        "tags": ["Invoices"],
        "security": [{"secretKey": ["checkouts:write"]}, {"agentToken": ["checkouts:write"]}],
        "x-railbed-scope": "checkouts:write",
        "parameters": [{"$ref": "#/components/parameters/InvoiceIdempotencyKey"}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/CreateInvoice"},
              "examples": {
                "send": {
                  "summary": "An invoice with two lines, sales tax and a deposit, emailed at once",
                  "value": {
                    "currency": "USD",
                    "memo": "Thanks for your business.",
                    "terms": "Due within 30 days. Bank details on request.",
                    "reference": "PO-1042",
                    "allow_partial": true,
                    "min_payment": "1000.00",
                    "reminders": [-3, 0, 3],
                    "customer": {
                      "name": "Ada Lovelace",
                      "email": "ada@example.com",
                      "company": "Analytical Engines Ltd"
                    },
                    "lines": [
                      {"description": "Brand strategy workshop", "unit_amount": "3200.00"},
                      {"description": "Design hours", "quantity": "12.5", "unit_amount": "150.00"}
                    ],
                    "tax": {"percent": "8.25", "label": "Sales tax"},
                    "due_date": "2026-10-26",
                    "send": true
                  }
                },
                "draft": {
                  "summary": "A draft to finish later",
                  "value": {
                    "currency": "USD",
                    "customer": {"name": "Ada Lovelace"},
                    "lines": [{"description": "Consulting, September", "unit_amount": "2500.00"}]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "A retry with the same `Idempotency-Key` and body: the first invoice, as it is now.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Invoice"},
                "examples": {
                  "replay": {
                    "summary": "The invoice the key made",
                    "value": {
                      "id": "in_Vn3qT8kR5xWm2LcZp7Hb",
                      "object": "invoice",
                      "kind": "invoice",
                      "number": "INV-0042",
                      "status": "sent",
                      "livemode": false,
                      "url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3",
                      "pdf_url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3/pdf",
                      "currency": "USD",
                      "lines": [
                        {
                          "description": "Brand strategy workshop",
                          "quantity": "1",
                          "unit_amount": "3200.00",
                          "amount": "3200.00"
                        },
                        {
                          "description": "Design hours",
                          "quantity": "12.5",
                          "unit_amount": "150.00",
                          "amount": "1875.00"
                        }
                      ],
                      "subtotal": "5075.00",
                      "discount": "0.00",
                      "discount_percent": null,
                      "tax": "418.69",
                      "tax_percent": "8.25",
                      "tax_label": "Sales tax",
                      "total": "5493.69",
                      "amount_paid": "0.00",
                      "amount_due": "5493.69",
                      "tips": "0.00",
                      "customer": {
                        "id": "cus_Rk8mW3pZ6tQv1NxLc4Ys",
                        "name": "Ada Lovelace",
                        "email": "ada@example.com",
                        "company": "Analytical Engines Ltd",
                        "phone": null,
                        "billing_address": null
                      },
                      "memo": "Thanks for your business.",
                      "terms": "Due within 30 days. Bank details on request.",
                      "reference": "PO-1042",
                      "due_date": "2026-10-26",
                      "allow_partial": true,
                      "min_payment": "1000.00",
                      "allow_tip": false,
                      "reminders": [-3, 0, 3],
                      "email_receipts": true,
                      "routing": {"choice": "buyer", "provider": null, "fallback": true, "providers": null},
                      "collect": null,
                      "success_url": null,
                      "payout_wallet_id": null,
                      "payment_link_id": null,
                      "owner": null,
                      "created_via": "api",
                      "send_count": 0,
                      "view_count": 0,
                      "version": 0,
                      "created": 1790380525,
                      "updated": 1790380525,
                      "issued_at": 1790380525,
                      "last_sent_at": null,
                      "viewed_at": null,
                      "paid_at": null,
                      "voided_at": null,
                      "void_reason": null,
                      "expires_at": null,
                      "next_reminder_at": 1792746000
                    },
                    "x-railbed-fixture": "invoice"
                  }
                }
              }
            }
          },
          "201": {
            "description": "The new invoice. With `send`, `email` is the email just queued, or `email_error` says why it couldn't be (the invoice is made and issued either way). `warnings` appears only when there is something to say about the card providers' minimums.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Invoice"},
                "examples": {
                  "sent": {
                    "summary": "Issued and emailed",
                    "value": {
                      "id": "in_Vn3qT8kR5xWm2LcZp7Hb",
                      "object": "invoice",
                      "kind": "invoice",
                      "number": "INV-0042",
                      "status": "sent",
                      "livemode": false,
                      "url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3",
                      "pdf_url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3/pdf",
                      "currency": "USD",
                      "lines": [
                        {
                          "description": "Brand strategy workshop",
                          "quantity": "1",
                          "unit_amount": "3200.00",
                          "amount": "3200.00"
                        },
                        {
                          "description": "Design hours",
                          "quantity": "12.5",
                          "unit_amount": "150.00",
                          "amount": "1875.00"
                        }
                      ],
                      "subtotal": "5075.00",
                      "discount": "0.00",
                      "discount_percent": null,
                      "tax": "418.69",
                      "tax_percent": "8.25",
                      "tax_label": "Sales tax",
                      "total": "5493.69",
                      "amount_paid": "0.00",
                      "amount_due": "5493.69",
                      "tips": "0.00",
                      "customer": {
                        "id": "cus_Rk8mW3pZ6tQv1NxLc4Ys",
                        "name": "Ada Lovelace",
                        "email": "ada@example.com",
                        "company": "Analytical Engines Ltd",
                        "phone": null,
                        "billing_address": null
                      },
                      "memo": "Thanks for your business.",
                      "terms": "Due within 30 days. Bank details on request.",
                      "reference": "PO-1042",
                      "due_date": "2026-10-26",
                      "allow_partial": true,
                      "min_payment": "1000.00",
                      "allow_tip": false,
                      "reminders": [-3, 0, 3],
                      "email_receipts": true,
                      "routing": {"choice": "buyer", "provider": null, "fallback": true, "providers": null},
                      "collect": null,
                      "success_url": null,
                      "payout_wallet_id": null,
                      "payment_link_id": null,
                      "owner": null,
                      "created_via": "api",
                      "send_count": 1,
                      "view_count": 0,
                      "version": 0,
                      "created": 1790380525,
                      "updated": 1790380525,
                      "issued_at": 1790380525,
                      "last_sent_at": 1790380645,
                      "viewed_at": null,
                      "paid_at": null,
                      "voided_at": null,
                      "void_reason": null,
                      "expires_at": null,
                      "next_reminder_at": 1792746000,
                      "email": {
                        "id": "iem_Hc6tN1vQ9rXk4WmZb2Lp",
                        "object": "invoice_email",
                        "kind": "invoice",
                        "to": "you@example.com",
                        "test_copy": true,
                        "status": "sent",
                        "delivery": null,
                        "error": null,
                        "created": 1790380645,
                        "sent_at": 1790380645
                      }
                    },
                    "x-railbed-fixture": "invoice-sent"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_json`, `unknown_field`, `invalid_customer`, `invalid_email`, `invalid_address`, `invalid_currency`, `invalid_lines`, `missing_description`, `invalid_quantity`, `invalid_amount`, `invalid_discount`, `invalid_tax`, `invalid_memo`, `invalid_terms`, `invalid_reference`, `too_long`, `invalid_due_date`, `invalid_value`, `invalid_min_payment`, `invalid_reminders`, `invalid_routing`, `invalid_collect`, `invalid_url`, `invalid_payout_wallet`, `invalid_owner`, `invalid_issue`, `invalid_send`, `invalid_message`, `customer_required`, `invalid_idempotency_key`.",
            "x-railbed-error-codes": [
              "invalid_json",
              "unknown_field",
              "invalid_customer",
              "invalid_email",
              "invalid_address",
              "invalid_currency",
              "invalid_lines",
              "missing_description",
              "invalid_quantity",
              "invalid_amount",
              "invalid_discount",
              "invalid_tax",
              "invalid_memo",
              "invalid_terms",
              "invalid_reference",
              "too_long",
              "invalid_due_date",
              "invalid_value",
              "invalid_min_payment",
              "invalid_reminders",
              "invalid_routing",
              "invalid_collect",
              "invalid_url",
              "invalid_payout_wallet",
              "invalid_owner",
              "invalid_issue",
              "invalid_send",
              "invalid_message",
              "customer_required",
              "invalid_idempotency_key"
            ],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`, `merchant_read_only`, `integration_disabled`.",
            "x-railbed-error-codes": ["insufficient_scope", "merchant_read_only", "integration_disabled"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "409": {
            "description": "The object's state doesn't allow this. Read it and act on its current status. Codes: `idempotency_conflict`, `idempotency_in_progress`, `no_payout_wallet`, `account_review`, `payout_wallet_unusable`, `commerce_paused`.",
            "x-railbed-error-codes": [
              "idempotency_conflict",
              "idempotency_in_progress",
              "no_payout_wallet",
              "account_review",
              "payout_wallet_unusable",
              "commerce_paused"
            ],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "413": {"$ref": "#/components/responses/PayloadTooLarge"},
          "415": {"$ref": "#/components/responses/UnsupportedMediaType"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/invoices/#create-an-invoice"
        }
      },
      "get": {
        "operationId": "listInvoices",
        "summary": "List invoices",
        "description": "Returns invoices newest first, payment links among them (`kind: \"link\"`), in the credential's mode.",
        "tags": ["Invoices"],
        "security": [{"secretKey": ["payments:read"]}, {"agentToken": ["payments:read"]}],
        "x-railbed-scope": "payments:read",
        "parameters": [
          {"$ref": "#/components/parameters/Limit"},
          {"$ref": "#/components/parameters/InvoiceCursor"},
          {"$ref": "#/components/parameters/InvoiceStatusFilter"},
          {"$ref": "#/components/parameters/InvoiceKindFilter"},
          {"$ref": "#/components/parameters/InvoiceCustomerFilter"},
          {"$ref": "#/components/parameters/InvoiceOwnerFilter"},
          {"$ref": "#/components/parameters/ReferenceFilter"},
          {"$ref": "#/components/parameters/CreatedGte"},
          {"$ref": "#/components/parameters/CreatedLte"},
          {"$ref": "#/components/parameters/DueDateGte"},
          {"$ref": "#/components/parameters/DueDateLte"}
        ],
        "responses": {
          "200": {
            "description": "A page of invoices.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/InvoiceList"},
                "examples": {
                  "page": {
                    "summary": "A page",
                    "value": {
                      "data": [
                        {
                          "id": "in_Vn3qT8kR5xWm2LcZp7Hb",
                          "object": "invoice",
                          "kind": "invoice",
                          "number": "INV-0042",
                          "status": "sent",
                          "livemode": false,
                          "url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3",
                          "pdf_url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3/pdf",
                          "currency": "USD",
                          "lines": [
                            {
                              "description": "Brand strategy workshop",
                              "quantity": "1",
                              "unit_amount": "3200.00",
                              "amount": "3200.00"
                            },
                            {
                              "description": "Design hours",
                              "quantity": "12.5",
                              "unit_amount": "150.00",
                              "amount": "1875.00"
                            }
                          ],
                          "subtotal": "5075.00",
                          "discount": "0.00",
                          "discount_percent": null,
                          "tax": "418.69",
                          "tax_percent": "8.25",
                          "tax_label": "Sales tax",
                          "total": "5493.69",
                          "amount_paid": "0.00",
                          "amount_due": "5493.69",
                          "tips": "0.00",
                          "customer": {
                            "id": "cus_Rk8mW3pZ6tQv1NxLc4Ys",
                            "name": "Ada Lovelace",
                            "email": "ada@example.com",
                            "company": "Analytical Engines Ltd",
                            "phone": null,
                            "billing_address": null
                          },
                          "memo": "Thanks for your business.",
                          "terms": "Due within 30 days. Bank details on request.",
                          "reference": "PO-1042",
                          "due_date": "2026-10-26",
                          "allow_partial": true,
                          "min_payment": "1000.00",
                          "allow_tip": false,
                          "reminders": [-3, 0, 3],
                          "email_receipts": true,
                          "routing": {
                            "choice": "buyer",
                            "provider": null,
                            "fallback": true,
                            "providers": null
                          },
                          "collect": null,
                          "success_url": null,
                          "payout_wallet_id": null,
                          "payment_link_id": null,
                          "owner": null,
                          "created_via": "api",
                          "send_count": 0,
                          "view_count": 0,
                          "version": 0,
                          "created": 1790380525,
                          "updated": 1790380525,
                          "issued_at": 1790380525,
                          "last_sent_at": null,
                          "viewed_at": null,
                          "paid_at": null,
                          "voided_at": null,
                          "void_reason": null,
                          "expires_at": null,
                          "next_reminder_at": 1792746000
                        }
                      ],
                      "has_more": false,
                      "next_cursor": null
                    },
                    "x-railbed-fixture": "invoice-list"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_limit`, `invalid_cursor`, `invalid_status`, `invalid_kind`, `invalid_customer`, `invalid_owner`, `invalid_reference`, `invalid_created_gte`, `invalid_created_lte`, `invalid_due_date_gte`, `invalid_due_date_lte`, `invalid_dates`.",
            "x-railbed-error-codes": [
              "invalid_limit",
              "invalid_cursor",
              "invalid_status",
              "invalid_kind",
              "invalid_customer",
              "invalid_owner",
              "invalid_reference",
              "invalid_created_gte",
              "invalid_created_lte",
              "invalid_due_date_gte",
              "invalid_due_date_lte",
              "invalid_dates"
            ],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`.",
            "x-railbed-error-codes": ["insufficient_scope"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/invoices/#list-invoices"
        }
      }
    },
    "/invoices/{id}": {
      "get": {
        "operationId": "retrieveInvoice",
        "summary": "Retrieve an invoice",
        "description": "Returns one of your invoices, or a payment link's invoice, as it is now: its status, what's paid and what's due.",
        "tags": ["Invoices"],
        "security": [{"secretKey": ["payments:read"]}, {"agentToken": ["payments:read"]}],
        "x-railbed-scope": "payments:read",
        "parameters": [{"$ref": "#/components/parameters/InvoiceId"}],
        "responses": {
          "200": {
            "description": "The invoice.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Invoice"},
                "examples": {
                  "invoice": {
                    "summary": "Sent, nothing paid yet",
                    "value": {
                      "id": "in_Vn3qT8kR5xWm2LcZp7Hb",
                      "object": "invoice",
                      "kind": "invoice",
                      "number": "INV-0042",
                      "status": "sent",
                      "livemode": false,
                      "url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3",
                      "pdf_url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3/pdf",
                      "currency": "USD",
                      "lines": [
                        {
                          "description": "Brand strategy workshop",
                          "quantity": "1",
                          "unit_amount": "3200.00",
                          "amount": "3200.00"
                        },
                        {
                          "description": "Design hours",
                          "quantity": "12.5",
                          "unit_amount": "150.00",
                          "amount": "1875.00"
                        }
                      ],
                      "subtotal": "5075.00",
                      "discount": "0.00",
                      "discount_percent": null,
                      "tax": "418.69",
                      "tax_percent": "8.25",
                      "tax_label": "Sales tax",
                      "total": "5493.69",
                      "amount_paid": "0.00",
                      "amount_due": "5493.69",
                      "tips": "0.00",
                      "customer": {
                        "id": "cus_Rk8mW3pZ6tQv1NxLc4Ys",
                        "name": "Ada Lovelace",
                        "email": "ada@example.com",
                        "company": "Analytical Engines Ltd",
                        "phone": null,
                        "billing_address": null
                      },
                      "memo": "Thanks for your business.",
                      "terms": "Due within 30 days. Bank details on request.",
                      "reference": "PO-1042",
                      "due_date": "2026-10-26",
                      "allow_partial": true,
                      "min_payment": "1000.00",
                      "allow_tip": false,
                      "reminders": [-3, 0, 3],
                      "email_receipts": true,
                      "routing": {"choice": "buyer", "provider": null, "fallback": true, "providers": null},
                      "collect": null,
                      "success_url": null,
                      "payout_wallet_id": null,
                      "payment_link_id": null,
                      "owner": null,
                      "created_via": "api",
                      "send_count": 0,
                      "view_count": 0,
                      "version": 0,
                      "created": 1790380525,
                      "updated": 1790380525,
                      "issued_at": 1790380525,
                      "last_sent_at": null,
                      "viewed_at": null,
                      "paid_at": null,
                      "voided_at": null,
                      "void_reason": null,
                      "expires_at": null,
                      "next_reminder_at": 1792746000
                    },
                    "x-railbed-fixture": "invoice"
                  }
                }
              }
            }
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`.",
            "x-railbed-error-codes": ["insufficient_scope"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/invoices/#retrieve-an-invoice"
        }
      },
      "patch": {
        "operationId": "updateInvoice",
        "summary": "Update an invoice",
        "description": "Changes the fields you send and leaves the rest. A draft takes any change; once a payment toward an issued invoice has started, only the due date, reminders, memo, terms, receipts and owner can change. Send the `version` you read as `expected_version`, so an edit made since answers `409 invoice_changed` instead of being overwritten.",
        "tags": ["Invoices"],
        "security": [{"secretKey": ["checkouts:write"]}, {"agentToken": ["checkouts:write"]}],
        "x-railbed-scope": "checkouts:write",
        "parameters": [{"$ref": "#/components/parameters/InvoiceId"}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/UpdateInvoice"},
              "examples": {
                "due": {
                  "summary": "A later due date, checked against the version read",
                  "value": {"due_date": "2026-10-26", "expected_version": 0}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The invoice as changed. `warnings` appears only when there is something to say about the card providers' minimums.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Invoice"},
                "examples": {
                  "invoice": {
                    "summary": "The invoice",
                    "value": {
                      "id": "in_Vn3qT8kR5xWm2LcZp7Hb",
                      "object": "invoice",
                      "kind": "invoice",
                      "number": "INV-0042",
                      "status": "sent",
                      "livemode": false,
                      "url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3",
                      "pdf_url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3/pdf",
                      "currency": "USD",
                      "lines": [
                        {
                          "description": "Brand strategy workshop",
                          "quantity": "1",
                          "unit_amount": "3200.00",
                          "amount": "3200.00"
                        },
                        {
                          "description": "Design hours",
                          "quantity": "12.5",
                          "unit_amount": "150.00",
                          "amount": "1875.00"
                        }
                      ],
                      "subtotal": "5075.00",
                      "discount": "0.00",
                      "discount_percent": null,
                      "tax": "418.69",
                      "tax_percent": "8.25",
                      "tax_label": "Sales tax",
                      "total": "5493.69",
                      "amount_paid": "0.00",
                      "amount_due": "5493.69",
                      "tips": "0.00",
                      "customer": {
                        "id": "cus_Rk8mW3pZ6tQv1NxLc4Ys",
                        "name": "Ada Lovelace",
                        "email": "ada@example.com",
                        "company": "Analytical Engines Ltd",
                        "phone": null,
                        "billing_address": null
                      },
                      "memo": "Thanks for your business.",
                      "terms": "Due within 30 days. Bank details on request.",
                      "reference": "PO-1042",
                      "due_date": "2026-10-26",
                      "allow_partial": true,
                      "min_payment": "1000.00",
                      "allow_tip": false,
                      "reminders": [-3, 0, 3],
                      "email_receipts": true,
                      "routing": {"choice": "buyer", "provider": null, "fallback": true, "providers": null},
                      "collect": null,
                      "success_url": null,
                      "payout_wallet_id": null,
                      "payment_link_id": null,
                      "owner": null,
                      "created_via": "api",
                      "send_count": 0,
                      "view_count": 0,
                      "version": 0,
                      "created": 1790380525,
                      "updated": 1790380525,
                      "issued_at": 1790380525,
                      "last_sent_at": null,
                      "viewed_at": null,
                      "paid_at": null,
                      "voided_at": null,
                      "void_reason": null,
                      "expires_at": null,
                      "next_reminder_at": 1792746000
                    },
                    "x-railbed-fixture": "invoice"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_json`, `unknown_field`, `invalid_customer`, `invalid_email`, `invalid_address`, `invalid_currency`, `invalid_lines`, `missing_description`, `invalid_quantity`, `invalid_amount`, `invalid_discount`, `invalid_tax`, `invalid_memo`, `invalid_terms`, `invalid_reference`, `too_long`, `invalid_due_date`, `invalid_value`, `invalid_min_payment`, `invalid_reminders`, `invalid_routing`, `invalid_collect`, `invalid_url`, `invalid_payout_wallet`, `invalid_owner`, `invalid_expected_version`, `not_editable`.",
            "x-railbed-error-codes": [
              "invalid_json",
              "unknown_field",
              "invalid_customer",
              "invalid_email",
              "invalid_address",
              "invalid_currency",
              "invalid_lines",
              "missing_description",
              "invalid_quantity",
              "invalid_amount",
              "invalid_discount",
              "invalid_tax",
              "invalid_memo",
              "invalid_terms",
              "invalid_reference",
              "too_long",
              "invalid_due_date",
              "invalid_value",
              "invalid_min_payment",
              "invalid_reminders",
              "invalid_routing",
              "invalid_collect",
              "invalid_url",
              "invalid_payout_wallet",
              "invalid_owner",
              "invalid_expected_version",
              "not_editable"
            ],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`, `merchant_read_only`, `integration_disabled`.",
            "x-railbed-error-codes": ["insufficient_scope", "merchant_read_only", "integration_disabled"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "409": {
            "description": "The object's state doesn't allow this. Read it and act on its current status. Codes: `payment_link`, `invoice_changed`, `invoice_not_editable`, `commerce_paused`.",
            "x-railbed-error-codes": [
              "payment_link",
              "invoice_changed",
              "invoice_not_editable",
              "commerce_paused"
            ],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "413": {"$ref": "#/components/responses/PayloadTooLarge"},
          "415": {"$ref": "#/components/responses/UnsupportedMediaType"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/invoices/#update-an-invoice"
        }
      },
      "delete": {
        "operationId": "deleteInvoice",
        "summary": "Delete a draft invoice",
        "description": "Deletes a draft. An issued invoice is never deleted: void it, so its number and history stay.",
        "tags": ["Invoices"],
        "security": [{"secretKey": ["checkouts:write"]}, {"agentToken": ["checkouts:write"]}],
        "x-railbed-scope": "checkouts:write",
        "parameters": [{"$ref": "#/components/parameters/InvoiceId"}],
        "responses": {
          "200": {
            "description": "The deleted draft.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/DeletedInvoice"},
                "examples": {
                  "deleted": {
                    "summary": "Deleted",
                    "value": {"id": "in_Vn3qT8kR5xWm2LcZp7Hb", "object": "invoice", "deleted": true},
                    "x-railbed-fixture": "invoice-deleted"
                  }
                }
              }
            }
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`, `merchant_read_only`.",
            "x-railbed-error-codes": ["insufficient_scope", "merchant_read_only"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "409": {
            "description": "The object's state doesn't allow this. Read it and act on its current status. Codes: `payment_link`, `not_draft`.",
            "x-railbed-error-codes": ["payment_link", "not_draft"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/invoices/#delete-a-draft-invoice"
        }
      }
    },
    "/invoices/{id}/issue": {
      "post": {
        "operationId": "issueInvoice",
        "summary": "Issue an invoice",
        "description": "Issues a draft without emailing it: from now on its `url` can be shared and paid. No body is needed.",
        "tags": ["Invoices"],
        "security": [{"secretKey": ["checkouts:write"]}, {"agentToken": ["checkouts:write"]}],
        "x-railbed-scope": "checkouts:write",
        "parameters": [{"$ref": "#/components/parameters/InvoiceId"}],
        "responses": {
          "200": {
            "description": "The invoice, with `status` `sent` and `issued_at` set.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Invoice"},
                "examples": {
                  "issued": {
                    "summary": "Issued",
                    "value": {
                      "id": "in_Vn3qT8kR5xWm2LcZp7Hb",
                      "object": "invoice",
                      "kind": "invoice",
                      "number": "INV-0042",
                      "status": "sent",
                      "livemode": false,
                      "url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3",
                      "pdf_url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3/pdf",
                      "currency": "USD",
                      "lines": [
                        {
                          "description": "Brand strategy workshop",
                          "quantity": "1",
                          "unit_amount": "3200.00",
                          "amount": "3200.00"
                        },
                        {
                          "description": "Design hours",
                          "quantity": "12.5",
                          "unit_amount": "150.00",
                          "amount": "1875.00"
                        }
                      ],
                      "subtotal": "5075.00",
                      "discount": "0.00",
                      "discount_percent": null,
                      "tax": "418.69",
                      "tax_percent": "8.25",
                      "tax_label": "Sales tax",
                      "total": "5493.69",
                      "amount_paid": "0.00",
                      "amount_due": "5493.69",
                      "tips": "0.00",
                      "customer": {
                        "id": "cus_Rk8mW3pZ6tQv1NxLc4Ys",
                        "name": "Ada Lovelace",
                        "email": "ada@example.com",
                        "company": "Analytical Engines Ltd",
                        "phone": null,
                        "billing_address": null
                      },
                      "memo": "Thanks for your business.",
                      "terms": "Due within 30 days. Bank details on request.",
                      "reference": "PO-1042",
                      "due_date": "2026-10-26",
                      "allow_partial": true,
                      "min_payment": "1000.00",
                      "allow_tip": false,
                      "reminders": [-3, 0, 3],
                      "email_receipts": true,
                      "routing": {"choice": "buyer", "provider": null, "fallback": true, "providers": null},
                      "collect": null,
                      "success_url": null,
                      "payout_wallet_id": null,
                      "payment_link_id": null,
                      "owner": null,
                      "created_via": "api",
                      "send_count": 0,
                      "view_count": 0,
                      "version": 0,
                      "created": 1790380525,
                      "updated": 1790380525,
                      "issued_at": 1790380525,
                      "last_sent_at": null,
                      "viewed_at": null,
                      "paid_at": null,
                      "voided_at": null,
                      "void_reason": null,
                      "expires_at": null,
                      "next_reminder_at": 1792746000
                    },
                    "x-railbed-fixture": "invoice"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_amount`, `invalid_routing`, `invalid_payout_wallet`.",
            "x-railbed-error-codes": ["invalid_amount", "invalid_routing", "invalid_payout_wallet"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`, `merchant_read_only`, `integration_disabled`.",
            "x-railbed-error-codes": ["insufficient_scope", "merchant_read_only", "integration_disabled"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "409": {
            "description": "The object's state doesn't allow this. Read it and act on its current status. Codes: `payment_link`, `already_issued`, `no_payout_wallet`, `account_review`, `payout_wallet_unusable`, `commerce_paused`.",
            "x-railbed-error-codes": [
              "payment_link",
              "already_issued",
              "no_payout_wallet",
              "account_review",
              "payout_wallet_unusable",
              "commerce_paused"
            ],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/invoices/#issue-an-invoice"
        }
      }
    },
    "/invoices/{id}/send": {
      "post": {
        "operationId": "sendInvoice",
        "summary": "Send an invoice",
        "description": "Emails the invoice to its customer in your business's name, with its PDF and a Pay button, issuing a draft first. Sent again, it reads as a reminder. A Test invoice's copy goes to the person behind the key or agent instead of the customer.",
        "tags": ["Invoices"],
        "security": [{"secretKey": ["checkouts:write"]}, {"agentToken": ["checkouts:write"]}],
        "x-railbed-scope": "checkouts:write",
        "parameters": [{"$ref": "#/components/parameters/InvoiceId"}],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/SendInvoice"},
              "examples": {
                "note": {
                  "summary": "With a few words above the invoice",
                  "value": {"message": "Thanks again for last week. Here is the invoice for the workshop."}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The invoice, with `email`: the email just queued.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Invoice"},
                "examples": {
                  "sent": {
                    "summary": "Sent",
                    "value": {
                      "id": "in_Vn3qT8kR5xWm2LcZp7Hb",
                      "object": "invoice",
                      "kind": "invoice",
                      "number": "INV-0042",
                      "status": "sent",
                      "livemode": false,
                      "url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3",
                      "pdf_url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3/pdf",
                      "currency": "USD",
                      "lines": [
                        {
                          "description": "Brand strategy workshop",
                          "quantity": "1",
                          "unit_amount": "3200.00",
                          "amount": "3200.00"
                        },
                        {
                          "description": "Design hours",
                          "quantity": "12.5",
                          "unit_amount": "150.00",
                          "amount": "1875.00"
                        }
                      ],
                      "subtotal": "5075.00",
                      "discount": "0.00",
                      "discount_percent": null,
                      "tax": "418.69",
                      "tax_percent": "8.25",
                      "tax_label": "Sales tax",
                      "total": "5493.69",
                      "amount_paid": "0.00",
                      "amount_due": "5493.69",
                      "tips": "0.00",
                      "customer": {
                        "id": "cus_Rk8mW3pZ6tQv1NxLc4Ys",
                        "name": "Ada Lovelace",
                        "email": "ada@example.com",
                        "company": "Analytical Engines Ltd",
                        "phone": null,
                        "billing_address": null
                      },
                      "memo": "Thanks for your business.",
                      "terms": "Due within 30 days. Bank details on request.",
                      "reference": "PO-1042",
                      "due_date": "2026-10-26",
                      "allow_partial": true,
                      "min_payment": "1000.00",
                      "allow_tip": false,
                      "reminders": [-3, 0, 3],
                      "email_receipts": true,
                      "routing": {"choice": "buyer", "provider": null, "fallback": true, "providers": null},
                      "collect": null,
                      "success_url": null,
                      "payout_wallet_id": null,
                      "payment_link_id": null,
                      "owner": null,
                      "created_via": "api",
                      "send_count": 1,
                      "view_count": 0,
                      "version": 0,
                      "created": 1790380525,
                      "updated": 1790380525,
                      "issued_at": 1790380525,
                      "last_sent_at": 1790380645,
                      "viewed_at": null,
                      "paid_at": null,
                      "voided_at": null,
                      "void_reason": null,
                      "expires_at": null,
                      "next_reminder_at": 1792746000,
                      "email": {
                        "id": "iem_Hc6tN1vQ9rXk4WmZb2Lp",
                        "object": "invoice_email",
                        "kind": "invoice",
                        "to": "you@example.com",
                        "test_copy": true,
                        "status": "sent",
                        "delivery": null,
                        "error": null,
                        "created": 1790380645,
                        "sent_at": 1790380645
                      }
                    },
                    "x-railbed-fixture": "invoice-sent"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_json`, `unknown_field`, `invalid_message`, `customer_required`, `invalid_amount`, `invalid_routing`.",
            "x-railbed-error-codes": [
              "invalid_json",
              "unknown_field",
              "invalid_message",
              "customer_required",
              "invalid_amount",
              "invalid_routing"
            ],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`, `merchant_read_only`, `integration_disabled`.",
            "x-railbed-error-codes": ["insufficient_scope", "merchant_read_only", "integration_disabled"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "409": {
            "description": "The object's state doesn't allow this. Read it and act on its current status. Codes: `payment_link`, `invoice_not_payable`, `email_blocked`, `email_suppressed`, `no_payout_wallet`, `account_review`, `payout_wallet_unusable`, `commerce_paused`.",
            "x-railbed-error-codes": [
              "payment_link",
              "invoice_not_payable",
              "email_blocked",
              "email_suppressed",
              "no_payout_wallet",
              "account_review",
              "payout_wallet_unusable",
              "commerce_paused"
            ],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "413": {"$ref": "#/components/responses/PayloadTooLarge"},
          "415": {"$ref": "#/components/responses/UnsupportedMediaType"},
          "429": {
            "description": "Over the rate limit, or over an invoice's email limits: one email a minute and 10 a day for each invoice, 200 invoice emails a day for each business. On `email_too_soon` wait a minute; on `email_limit` share the invoice's `url` instead. Codes: `rate_limited`, `email_too_soon`, `email_limit`.",
            "x-railbed-error-codes": ["rate_limited", "email_too_soon", "email_limit"],
            "headers": {"Retry-After": {"$ref": "#/components/headers/Retry-After"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "503": {
            "description": "Email can't be sent right now. Share the invoice's `url` with the customer yourself. Codes: `email_unavailable`.",
            "x-railbed-error-codes": ["email_unavailable"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/invoices/#send-an-invoice"
        }
      }
    },
    "/invoices/{id}/void": {
      "post": {
        "operationId": "voidInvoice",
        "summary": "Void an invoice",
        "description": "Voids an issued invoice: it can't be paid from now on, and payments toward it that nobody started are closed. One already on its way to a card provider stays open, and money that arrives still settles. Voiding again returns the same invoice.",
        "tags": ["Invoices"],
        "security": [{"secretKey": ["checkouts:write"]}, {"agentToken": ["checkouts:write"]}],
        "x-railbed-scope": "checkouts:write",
        "parameters": [{"$ref": "#/components/parameters/InvoiceId"}],
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/VoidInvoice"},
              "examples": {
                "reason": {
                  "summary": "With a reason for your records",
                  "value": {"reason": "Replaced by INV-0043"}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The invoice, with `status` `void` and `voided_at` set.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Invoice"},
                "examples": {
                  "voided": {
                    "summary": "Voided",
                    "value": {
                      "id": "in_Vn3qT8kR5xWm2LcZp7Hb",
                      "object": "invoice",
                      "kind": "invoice",
                      "number": "INV-0042",
                      "status": "void",
                      "livemode": false,
                      "url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3",
                      "pdf_url": "https://pay.railbed.io/i/4c9e1f7a2b6d48e3a5f0c8b1d7e2a9f3/pdf",
                      "currency": "USD",
                      "lines": [
                        {
                          "description": "Brand strategy workshop",
                          "quantity": "1",
                          "unit_amount": "3200.00",
                          "amount": "3200.00"
                        },
                        {
                          "description": "Design hours",
                          "quantity": "12.5",
                          "unit_amount": "150.00",
                          "amount": "1875.00"
                        }
                      ],
                      "subtotal": "5075.00",
                      "discount": "0.00",
                      "discount_percent": null,
                      "tax": "418.69",
                      "tax_percent": "8.25",
                      "tax_label": "Sales tax",
                      "total": "5493.69",
                      "amount_paid": "0.00",
                      "amount_due": "5493.69",
                      "tips": "0.00",
                      "customer": {
                        "id": "cus_Rk8mW3pZ6tQv1NxLc4Ys",
                        "name": "Ada Lovelace",
                        "email": "ada@example.com",
                        "company": "Analytical Engines Ltd",
                        "phone": null,
                        "billing_address": null
                      },
                      "memo": "Thanks for your business.",
                      "terms": "Due within 30 days. Bank details on request.",
                      "reference": "PO-1042",
                      "due_date": "2026-10-26",
                      "allow_partial": true,
                      "min_payment": "1000.00",
                      "allow_tip": false,
                      "reminders": [-3, 0, 3],
                      "email_receipts": true,
                      "routing": {"choice": "buyer", "provider": null, "fallback": true, "providers": null},
                      "collect": null,
                      "success_url": null,
                      "payout_wallet_id": null,
                      "payment_link_id": null,
                      "owner": null,
                      "created_via": "api",
                      "send_count": 0,
                      "view_count": 0,
                      "version": 1,
                      "created": 1790380525,
                      "updated": 1790384125,
                      "issued_at": 1790380525,
                      "last_sent_at": null,
                      "viewed_at": null,
                      "paid_at": null,
                      "voided_at": 1790384125,
                      "void_reason": "Replaced by INV-0043",
                      "expires_at": null,
                      "next_reminder_at": null
                    },
                    "x-railbed-fixture": "invoice-voided"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_json`, `unknown_field`, `invalid_reason`, `too_long`.",
            "x-railbed-error-codes": ["invalid_json", "unknown_field", "invalid_reason", "too_long"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`, `merchant_read_only`.",
            "x-railbed-error-codes": ["insufficient_scope", "merchant_read_only"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "409": {
            "description": "The object's state doesn't allow this. Read it and act on its current status. Codes: `payment_link`, `already_paid`, `invoice_draft`.",
            "x-railbed-error-codes": ["payment_link", "already_paid", "invoice_draft"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "413": {"$ref": "#/components/responses/PayloadTooLarge"},
          "415": {"$ref": "#/components/responses/UnsupportedMediaType"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/invoices/#void-an-invoice"
        }
      }
    },
    "/invoices/{id}/pdf": {
      "get": {
        "operationId": "downloadInvoicePdf",
        "summary": "Download an invoice PDF",
        "description": "The invoice as a PDF, as its customer gets it: a draft is marked Draft, and payments received are listed. Payment links' too.",
        "tags": ["Invoices"],
        "security": [{"secretKey": ["payments:read"]}, {"agentToken": ["payments:read"]}],
        "x-railbed-scope": "payments:read",
        "parameters": [{"$ref": "#/components/parameters/InvoiceId"}],
        "responses": {
          "200": {
            "description": "The PDF, with `Content-Disposition: attachment` and the invoice's number as the file name.",
            "content": {
              "application/pdf": {"schema": {"type": "string", "contentMediaType": "application/pdf"}}
            }
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`.",
            "x-railbed-error-codes": ["insufficient_scope"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/invoices/#download-an-invoice-pdf"
        }
      }
    },
    "/checkouts": {
      "post": {
        "operationId": "createCheckout",
        "summary": "Create a checkout",
        "description": "Creates a reusable checkout page. Every buyer who pays it gets their own payment.",
        "tags": ["Checkouts"],
        "security": [{"secretKey": ["checkouts:write"]}, {"agentToken": ["checkouts:write"]}],
        "x-railbed-scope": "checkouts:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/CreateCheckout"},
              "examples": {
                "page": {
                  "summary": "A checkout page",
                  "value": {
                    "name": "Ceramic mug",
                    "description": "Hand-thrown, 350 ml.",
                    "amount": "18.00",
                    "currency": "USD",
                    "success_url": "https://mugs.example/thanks"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The new checkout. `warnings` appears only when there is something to say about the card providers' minimums.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Checkout"},
                "examples": {
                  "page": {
                    "summary": "A checkout page",
                    "value": {
                      "id": "chk_Mg7tR2vX9kQp4WnZc8Lb",
                      "object": "checkout",
                      "kind": "page",
                      "slug": "mug4k7tq2z",
                      "url": "https://pay.railbed.io/c/mug4k7tq2z",
                      "livemode": false,
                      "active": true,
                      "name": "Ceramic mug",
                      "description": "Hand-thrown, 350 ml.",
                      "amount": "18.00",
                      "currency": "USD",
                      "success_url": "https://mugs.example/thanks",
                      "theme": "light",
                      "button_label": null,
                      "crypto": true,
                      "routing": {"choice": "smart", "provider": null, "fallback": true},
                      "collect": null,
                      "options": null,
                      "plans": [],
                      "created": 1790380525,
                      "updated": 1790380525
                    },
                    "x-railbed-fixture": "checkout"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_json`, `invalid_kind`, `missing_name`, `too_long`, `invalid_description`, `invalid_button_label`, `invalid_theme`, `invalid_value`, `invalid_amount`, `invalid_currency`, `invalid_url`, `invalid_routing`, `invalid_collect`.",
            "x-railbed-error-codes": [
              "invalid_json",
              "invalid_kind",
              "missing_name",
              "too_long",
              "invalid_description",
              "invalid_button_label",
              "invalid_theme",
              "invalid_value",
              "invalid_amount",
              "invalid_currency",
              "invalid_url",
              "invalid_routing",
              "invalid_collect"
            ],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`, `merchant_read_only`, `integration_disabled`.",
            "x-railbed-error-codes": ["insufficient_scope", "merchant_read_only", "integration_disabled"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "409": {
            "description": "The object's state doesn't allow this. Read it and act on its current status. Codes: `no_payout_wallet`, `account_review`, `commerce_paused`.",
            "x-railbed-error-codes": ["no_payout_wallet", "account_review", "commerce_paused"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "413": {"$ref": "#/components/responses/PayloadTooLarge"},
          "415": {"$ref": "#/components/responses/UnsupportedMediaType"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/checkouts/#create-a-checkout"
        }
      },
      "get": {
        "operationId": "listCheckouts",
        "summary": "List checkouts",
        "description": "Returns active checkouts of every kind, newest first.",
        "tags": ["Checkouts"],
        "security": [{"secretKey": ["payments:read"]}, {"agentToken": ["payments:read"]}],
        "x-railbed-scope": "payments:read",
        "parameters": [
          {"$ref": "#/components/parameters/Limit"},
          {"$ref": "#/components/parameters/CheckoutCursor"},
          {
            "name": "kind",
            "in": "query",
            "required": false,
            "description": "Only this kind.",
            "schema": {"type": "string", "enum": ["page", "pricing_table", "widget"]}
          }
        ],
        "responses": {
          "200": {
            "description": "A page of checkouts.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/CheckoutList"},
                "examples": {
                  "page": {
                    "summary": "A page",
                    "value": {
                      "data": [
                        {
                          "id": "chk_Mg7tR2vX9kQp4WnZc8Lb",
                          "object": "checkout",
                          "kind": "page",
                          "slug": "mug4k7tq2z",
                          "url": "https://pay.railbed.io/c/mug4k7tq2z",
                          "livemode": false,
                          "active": true,
                          "name": "Ceramic mug",
                          "description": "Hand-thrown, 350 ml.",
                          "amount": "18.00",
                          "currency": "USD",
                          "success_url": "https://mugs.example/thanks",
                          "theme": "light",
                          "button_label": null,
                          "crypto": true,
                          "routing": {"choice": "smart", "provider": null, "fallback": true},
                          "collect": null,
                          "options": null,
                          "plans": [],
                          "created": 1790380525,
                          "updated": 1790380525
                        }
                      ],
                      "has_more": false,
                      "next_cursor": null
                    },
                    "x-railbed-fixture": "checkout-list"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_limit`, `invalid_cursor`, `invalid_kind`.",
            "x-railbed-error-codes": ["invalid_limit", "invalid_cursor", "invalid_kind"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`.",
            "x-railbed-error-codes": ["insufficient_scope"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/checkouts/#list-checkouts"
        }
      }
    },
    "/checkouts/{id}": {
      "get": {
        "operationId": "retrieveCheckout",
        "summary": "Retrieve a checkout",
        "description": "Returns a checkout by its id, including a deleted one (`active: false`).",
        "tags": ["Checkouts"],
        "security": [{"secretKey": ["payments:read"]}, {"agentToken": ["payments:read"]}],
        "x-railbed-scope": "payments:read",
        "parameters": [{"$ref": "#/components/parameters/CheckoutId"}],
        "responses": {
          "200": {
            "description": "The checkout.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/Checkout"},
                "examples": {
                  "page": {
                    "summary": "A checkout page",
                    "value": {
                      "id": "chk_Mg7tR2vX9kQp4WnZc8Lb",
                      "object": "checkout",
                      "kind": "page",
                      "slug": "mug4k7tq2z",
                      "url": "https://pay.railbed.io/c/mug4k7tq2z",
                      "livemode": false,
                      "active": true,
                      "name": "Ceramic mug",
                      "description": "Hand-thrown, 350 ml.",
                      "amount": "18.00",
                      "currency": "USD",
                      "success_url": "https://mugs.example/thanks",
                      "theme": "light",
                      "button_label": null,
                      "crypto": true,
                      "routing": {"choice": "smart", "provider": null, "fallback": true},
                      "collect": null,
                      "options": null,
                      "plans": [],
                      "created": 1790380525,
                      "updated": 1790380525
                    },
                    "x-railbed-fixture": "checkout"
                  }
                }
              }
            }
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`.",
            "x-railbed-error-codes": ["insufficient_scope"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/checkouts/#retrieve-a-checkout"
        }
      }
    },
    "/orders": {
      "get": {
        "operationId": "listOrders",
        "summary": "List orders",
        "description": "Returns orders newest first, or finds one by your store's order id with `store_id` and `store_order_id`. `status=paid` with `fulfillment=unfulfilled` is the orders still to send.",
        "tags": ["Orders"],
        "security": [{"secretKey": ["orders:read"]}, {"agentToken": ["orders:read"]}],
        "x-railbed-scope": "orders:read",
        "parameters": [
          {"$ref": "#/components/parameters/Limit"},
          {"$ref": "#/components/parameters/OrderCursor"},
          {
            "name": "customer_id",
            "in": "query",
            "required": false,
            "description": "Only this customer's orders.",
            "schema": {"type": "string"}
          },
          {
            "name": "store_id",
            "in": "query",
            "required": false,
            "description": "Only orders from this store (the `order.store.id` you sent).",
            "schema": {"type": "string"}
          },
          {
            "name": "store_order_id",
            "in": "query",
            "required": false,
            "description": "With `store_id`: the order with this `order.id`.",
            "schema": {"type": "string"}
          },
          {"$ref": "#/components/parameters/OrderStatusFilter"},
          {"$ref": "#/components/parameters/OrderFulfillmentFilter"},
          {"$ref": "#/components/parameters/CreatedGte"},
          {"$ref": "#/components/parameters/CreatedLte"}
        ],
        "responses": {
          "200": {
            "description": "A page of orders.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/OrderList"}}}
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_limit`, `invalid_cursor`, `invalid_status`, `invalid_fulfillment`, `invalid_created_gte`, `invalid_created_lte`, `invalid_dates`.",
            "x-railbed-error-codes": [
              "invalid_limit",
              "invalid_cursor",
              "invalid_status",
              "invalid_fulfillment",
              "invalid_created_gte",
              "invalid_created_lte",
              "invalid_dates"
            ],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`.",
            "x-railbed-error-codes": ["insufficient_scope"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/orders/#list-orders"
        }
      }
    },
    "/orders/{id}": {
      "get": {
        "operationId": "retrieveOrder",
        "summary": "Retrieve an order",
        "description": "Returns an order with every item and every payment attempt.",
        "tags": ["Orders"],
        "security": [{"secretKey": ["orders:read"]}, {"agentToken": ["orders:read"]}],
        "x-railbed-scope": "orders:read",
        "parameters": [{"$ref": "#/components/parameters/OrderId"}],
        "responses": {
          "200": {
            "description": "The order.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Order"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`.",
            "x-railbed-error-codes": ["insufficient_scope"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/orders/#retrieve-an-order"
        }
      },
      "patch": {
        "operationId": "updateOrder",
        "summary": "Update an order",
        "description": "Sets an order's fulfilment. The change is on the order's timeline.",
        "tags": ["Orders"],
        "security": [{"secretKey": ["orders:write"]}, {"agentToken": ["orders:write"]}],
        "x-railbed-scope": "orders:write",
        "parameters": [{"$ref": "#/components/parameters/OrderId"}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/UpdateOrder"},
              "examples": {
                "fulfilled": {"summary": "Mark it fulfilled", "value": {"fulfillment": "fulfilled"}}
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The order.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Order"}}}
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_json`, `invalid_fulfillment`.",
            "x-railbed-error-codes": ["invalid_json", "invalid_fulfillment"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`, `merchant_read_only`.",
            "x-railbed-error-codes": ["insufficient_scope", "merchant_read_only"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "413": {"$ref": "#/components/responses/PayloadTooLarge"},
          "415": {"$ref": "#/components/responses/UnsupportedMediaType"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/orders/#update-an-order"
        }
      }
    },
    "/orders/{id}/events": {
      "post": {
        "operationId": "createOrderEvent",
        "summary": "Report a cancellation or refund",
        "description": "Records that your store canceled its order or refunded it, on the order's timeline. It never changes the order's status, its payments or any money: refunds are sent from your wallet.",
        "tags": ["Orders"],
        "security": [{"secretKey": ["orders:write"]}, {"agentToken": ["orders:write"]}],
        "x-railbed-scope": "orders:write",
        "parameters": [{"$ref": "#/components/parameters/OrderId"}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/CreateOrderEvent"},
              "examples": {
                "refund": {
                  "summary": "A partial refund",
                  "value": {"type": "refunded", "id": "refund-5521", "amount": "12.00"}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "This `id` was already recorded with the same details: the same event.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/OrderEvent"}}}
          },
          "201": {
            "description": "The event, recorded.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/OrderEvent"}}}
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_json`, `invalid_event_type`, `invalid_event_id`, `invalid_amount`.",
            "x-railbed-error-codes": [
              "invalid_json",
              "invalid_event_type",
              "invalid_event_id",
              "invalid_amount"
            ],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`, `merchant_read_only`.",
            "x-railbed-error-codes": ["insufficient_scope", "merchant_read_only"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "409": {
            "description": "The object's state doesn't allow this. Read it and act on its current status. Codes: `event_conflict`.",
            "x-railbed-error-codes": ["event_conflict"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "413": {"$ref": "#/components/responses/PayloadTooLarge"},
          "415": {"$ref": "#/components/responses/UnsupportedMediaType"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/orders/#report-a-cancellation-or-refund"
        }
      }
    },
    "/customers": {
      "get": {
        "operationId": "listCustomers",
        "summary": "List customers",
        "description": "Returns customers newest first, or finds one by email.",
        "tags": ["Customers"],
        "security": [{"secretKey": ["customers:read"]}, {"agentToken": ["customers:read"]}],
        "x-railbed-scope": "customers:read",
        "parameters": [
          {"$ref": "#/components/parameters/Limit"},
          {"$ref": "#/components/parameters/CustomerCursor"},
          {
            "name": "email",
            "in": "query",
            "required": false,
            "description": "Only the customer with this email (any letter case).",
            "schema": {"type": "string"}
          }
        ],
        "responses": {
          "200": {
            "description": "A page of customers.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/CustomerList"}}}
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_limit`, `invalid_cursor`.",
            "x-railbed-error-codes": ["invalid_limit", "invalid_cursor"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`.",
            "x-railbed-error-codes": ["insufficient_scope"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/customers/#list-customers"
        }
      }
    },
    "/customers/{id}": {
      "get": {
        "operationId": "retrieveCustomer",
        "summary": "Retrieve a customer",
        "description": "Returns a customer with their order counts and what they've spent.",
        "tags": ["Customers"],
        "security": [{"secretKey": ["customers:read"]}, {"agentToken": ["customers:read"]}],
        "x-railbed-scope": "customers:read",
        "parameters": [{"$ref": "#/components/parameters/CustomerId"}],
        "responses": {
          "200": {
            "description": "The customer.",
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Customer"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`.",
            "x-railbed-error-codes": ["insufficient_scope"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/customers/#retrieve-a-customer"
        }
      }
    },
    "/webhook_endpoints": {
      "post": {
        "operationId": "createWebhookEndpoint",
        "summary": "Create a webhook endpoint",
        "description": "Adds an endpoint and returns its signing secret, the only time the API shows it. Secret keys with Full access for the API only: connected agents, WooCommerce keys and Read only keys can't manage webhook endpoints.",
        "tags": ["Webhook endpoints"],
        "security": [{"secretKey": ["webhooks:write"]}],
        "x-railbed-scope": "webhooks:write",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/CreateWebhookEndpoint"},
              "examples": {
                "n8n": {
                  "summary": "An automation tool's endpoint",
                  "value": {
                    "url": "https://automation.example.com/webhook/railbed-orders",
                    "description": "n8n: Fulfil paid orders",
                    "events": ["payment.paid", "payment.held"]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The new endpoint, with its secret.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/CreatedWebhookEndpoint"},
                "examples": {
                  "created": {
                    "summary": "A new endpoint",
                    "value": {
                      "id": "we_N8nQ4vRx7KtZ2mLp9WcB",
                      "object": "webhook_endpoint",
                      "url": "https://automation.example.com/webhook/railbed-orders",
                      "description": "n8n: Fulfil paid orders",
                      "events": ["payment.paid", "payment.held"],
                      "livemode": false,
                      "mode": "test",
                      "previous_secret_expires_at": null,
                      "created": 1790380525,
                      "secret": "whsec_Tq7mVx2RkL9pZc4WbN8yHd3Jf6Gs1Ae0Ku5Xo-Pi_Mr"
                    },
                    "x-railbed-fixture": "webhook-endpoint-created"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_json`, `invalid_url`, `invalid_events`, `invalid_description`, `too_long`.",
            "x-railbed-error-codes": [
              "invalid_json",
              "invalid_url",
              "invalid_events",
              "invalid_description",
              "too_long"
            ],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`, `merchant_read_only`.",
            "x-railbed-error-codes": ["insufficient_scope", "merchant_read_only"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "409": {
            "description": "The object's state doesn't allow this. Read it and act on its current status. Codes: `duplicate_url`, `too_many`.",
            "x-railbed-error-codes": ["duplicate_url", "too_many"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "413": {"$ref": "#/components/responses/PayloadTooLarge"},
          "415": {"$ref": "#/components/responses/UnsupportedMediaType"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/webhook-endpoints/#create-a-webhook-endpoint"
        }
      },
      "get": {
        "operationId": "listWebhookEndpoints",
        "summary": "List webhook endpoints",
        "description": "Returns this mode's endpoints newest first. Secret keys with Full access for the API only: connected agents, WooCommerce keys and Read only keys can't manage webhook endpoints.",
        "tags": ["Webhook endpoints"],
        "security": [{"secretKey": ["webhooks:read"]}],
        "x-railbed-scope": "webhooks:read",
        "parameters": [
          {"$ref": "#/components/parameters/Limit"},
          {"$ref": "#/components/parameters/WebhookEndpointCursor"}
        ],
        "responses": {
          "200": {
            "description": "A page of endpoints.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/WebhookEndpointList"},
                "examples": {
                  "page": {
                    "summary": "A page",
                    "value": {
                      "data": [
                        {
                          "id": "we_N8nQ4vRx7KtZ2mLp9WcB",
                          "object": "webhook_endpoint",
                          "url": "https://automation.example.com/webhook/railbed-orders",
                          "description": "n8n: Fulfil paid orders",
                          "events": ["payment.paid", "payment.held"],
                          "livemode": false,
                          "mode": "test",
                          "previous_secret_expires_at": null,
                          "created": 1790380525
                        }
                      ],
                      "has_more": false,
                      "next_cursor": null
                    },
                    "x-railbed-fixture": "webhook-endpoint-list"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_limit`, `invalid_cursor`.",
            "x-railbed-error-codes": ["invalid_limit", "invalid_cursor"],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`.",
            "x-railbed-error-codes": ["insufficient_scope"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/webhook-endpoints/#list-webhook-endpoints"
        }
      }
    },
    "/webhook_endpoints/{id}": {
      "get": {
        "operationId": "retrieveWebhookEndpoint",
        "summary": "Retrieve a webhook endpoint",
        "description": "Returns an endpoint, without its secret. A removed endpoint is `404`. Secret keys with Full access for the API only: connected agents, WooCommerce keys and Read only keys can't manage webhook endpoints.",
        "tags": ["Webhook endpoints"],
        "security": [{"secretKey": ["webhooks:read"]}],
        "x-railbed-scope": "webhooks:read",
        "parameters": [{"$ref": "#/components/parameters/WebhookEndpointId"}],
        "responses": {
          "200": {
            "description": "The endpoint.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/WebhookEndpoint"},
                "examples": {
                  "endpoint": {
                    "summary": "An endpoint",
                    "value": {
                      "id": "we_N8nQ4vRx7KtZ2mLp9WcB",
                      "object": "webhook_endpoint",
                      "url": "https://automation.example.com/webhook/railbed-orders",
                      "description": "n8n: Fulfil paid orders",
                      "events": ["payment.paid", "payment.held"],
                      "livemode": false,
                      "mode": "test",
                      "previous_secret_expires_at": null,
                      "created": 1790380525
                    },
                    "x-railbed-fixture": "webhook-endpoint"
                  }
                }
              }
            }
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`.",
            "x-railbed-error-codes": ["insufficient_scope"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/webhook-endpoints/#retrieve-a-webhook-endpoint"
        }
      },
      "patch": {
        "operationId": "updateWebhookEndpoint",
        "summary": "Update a webhook endpoint",
        "description": "Changes the events an endpoint receives, or its description, and leaves the rest. Its address and signing secret never change: for a new address, delete the endpoint and create another. Secret keys with Full access for the API only: connected agents, WooCommerce keys and Read only keys can't manage webhook endpoints.",
        "tags": ["Webhook endpoints"],
        "security": [{"secretKey": ["webhooks:write"]}],
        "x-railbed-scope": "webhooks:write",
        "parameters": [{"$ref": "#/components/parameters/WebhookEndpointId"}],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {"$ref": "#/components/schemas/UpdateWebhookEndpoint"},
              "examples": {
                "events": {
                  "summary": "Also receive paid invoices",
                  "value": {"events": ["payment.paid", "payment.held", "invoice.paid"]}
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The endpoint as it now stands, without its secret.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/WebhookEndpoint"},
                "examples": {
                  "updated": {
                    "summary": "The endpoint, changed",
                    "value": {
                      "id": "we_N8nQ4vRx7KtZ2mLp9WcB",
                      "object": "webhook_endpoint",
                      "url": "https://automation.example.com/webhook/railbed-orders",
                      "description": "n8n: Fulfil paid orders",
                      "events": ["payment.paid", "payment.held", "invoice.paid"],
                      "livemode": false,
                      "mode": "test",
                      "previous_secret_expires_at": null,
                      "created": 1790380525
                    },
                    "x-railbed-fixture": "webhook-endpoint-updated"
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is invalid. Fix it: retrying unchanged fails the same way. `field` names the field at fault. Codes: `invalid_json`, `invalid_events`, `invalid_description`, `too_long`, `not_editable`.",
            "x-railbed-error-codes": [
              "invalid_json",
              "invalid_events",
              "invalid_description",
              "too_long",
              "not_editable"
            ],
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`, `merchant_read_only`.",
            "x-railbed-error-codes": ["insufficient_scope", "merchant_read_only"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "413": {"$ref": "#/components/responses/PayloadTooLarge"},
          "415": {"$ref": "#/components/responses/UnsupportedMediaType"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/webhook-endpoints/#update-a-webhook-endpoint"
        }
      },
      "delete": {
        "operationId": "deleteWebhookEndpoint",
        "summary": "Delete a webhook endpoint",
        "description": "Removes an endpoint and cancels its pending retries. It works in every account state, as revoking a key does. Secret keys with Full access for the API only: connected agents, WooCommerce keys and Read only keys can't manage webhook endpoints.",
        "tags": ["Webhook endpoints"],
        "security": [{"secretKey": ["webhooks:write"]}],
        "x-railbed-scope": "webhooks:write",
        "x-railbed-revoke": true,
        "parameters": [{"$ref": "#/components/parameters/WebhookEndpointId"}],
        "responses": {
          "200": {
            "description": "The removed endpoint.",
            "content": {
              "application/json": {
                "schema": {"$ref": "#/components/schemas/DeletedWebhookEndpoint"},
                "examples": {
                  "deleted": {
                    "summary": "Removed",
                    "value": {"id": "we_N8nQ4vRx7KtZ2mLp9WcB", "object": "webhook_endpoint", "deleted": true},
                    "x-railbed-fixture": "webhook-endpoint-deleted"
                  }
                }
              }
            }
          },
          "401": {"$ref": "#/components/responses/Unauthorized"},
          "403": {
            "description": "Not allowed for this account, key or agent. Don't retry. On `insufficient_scope`, use a key or agent with Full access. Codes: `insufficient_scope`.",
            "x-railbed-error-codes": ["insufficient_scope"],
            "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
            "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
          },
          "404": {"$ref": "#/components/responses/NotFound"},
          "405": {"$ref": "#/components/responses/MethodNotAllowed"},
          "429": {"$ref": "#/components/responses/RateLimited"},
          "5XX": {"$ref": "#/components/responses/ServerError"}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/api/webhook-endpoints/#delete-a-webhook-endpoint"
        }
      }
    }
  },
  "webhooks": {
    "payment.started": {
      "post": {
        "operationId": "webhookPaymentStarted",
        "summary": "payment.started",
        "description": "The buyer entered their email and was given a way to pay: the payment has its deposit address, and the fee and the order's USD value are locked. The payment is still `open`. Never fulfil from it. Answer `2xx` within 10 seconds; failed deliveries are retried 1m, 5m, 30m, 2h, 6h and 12h after each failure. Events can arrive more than once and out of order: deduplicate on the event `id`.",
        "tags": ["Webhook events"],
        "security": [],
        "parameters": [{"$ref": "#/components/parameters/RailbedSignature"}],
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}
        },
        "responses": {
          "2XX": {"description": "Received. Anything else, or no answer within 10 seconds, is retried."}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/webhooks/events/#payment-started"
        }
      }
    },
    "payment.paid": {
      "post": {
        "operationId": "webhookPaymentPaid",
        "summary": "payment.paid",
        "description": "The money arrived and passed every settlement check, or the merchant accepted a held payment as paid. This is the event to fulfil from, once. Answer `2xx` within 10 seconds; failed deliveries are retried 1m, 5m, 30m, 2h, 6h and 12h after each failure. Events can arrive more than once and out of order: deduplicate on the event `id`.",
        "tags": ["Webhook events"],
        "security": [],
        "parameters": [{"$ref": "#/components/parameters/RailbedSignature"}],
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}
        },
        "responses": {
          "2XX": {"description": "Received. Anything else, or no answer within 10 seconds, is retried."}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/webhooks/events/#payment-paid"
        }
      }
    },
    "payment.held": {
      "post": {
        "operationId": "webhookPaymentHeld",
        "summary": "payment.held",
        "description": "Money arrived but failed a check, most often because less arrived than 85% of the order's value. Don't fulfil: the payment waits for the merchant in the dashboard. `holdReason` says what failed. Answer `2xx` within 10 seconds; failed deliveries are retried 1m, 5m, 30m, 2h, 6h and 12h after each failure. Events can arrive more than once and out of order: deduplicate on the event `id`.",
        "tags": ["Webhook events"],
        "security": [],
        "parameters": [{"$ref": "#/components/parameters/RailbedSignature"}],
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}
        },
        "responses": {
          "2XX": {"description": "Received. Anything else, or no answer within 10 seconds, is retried."}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/webhooks/events/#payment-held"
        }
      }
    },
    "payment.updated": {
      "post": {
        "operationId": "webhookPaymentUpdated",
        "summary": "payment.updated",
        "description": "A paid payment's settlement details arrived after it was confirmed. The status stays `paid`; there's nothing to fulfil again. Answer `2xx` within 10 seconds; failed deliveries are retried 1m, 5m, 30m, 2h, 6h and 12h after each failure. Events can arrive more than once and out of order: deduplicate on the event `id`.",
        "tags": ["Webhook events"],
        "security": [],
        "parameters": [{"$ref": "#/components/parameters/RailbedSignature"}],
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}
        },
        "responses": {
          "2XX": {"description": "Received. Anything else, or no answer within 10 seconds, is retried."}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/webhooks/events/#payment-updated"
        }
      }
    },
    "payment.failed": {
      "post": {
        "operationId": "webhookPaymentFailed",
        "summary": "payment.failed",
        "description": "The payment reached a terminal failure. Today this is sent in Test mode only, for a simulation with `outcome: \"failed\"`. Answer `2xx` within 10 seconds; failed deliveries are retried 1m, 5m, 30m, 2h, 6h and 12h after each failure. Events can arrive more than once and out of order: deduplicate on the event `id`.",
        "tags": ["Webhook events"],
        "security": [],
        "parameters": [{"$ref": "#/components/parameters/RailbedSignature"}],
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}
        },
        "responses": {
          "2XX": {"description": "Received. Anything else, or no answer within 10 seconds, is retried."}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/webhooks/events/#payment-failed"
        }
      }
    },
    "payment.expired": {
      "post": {
        "operationId": "webhookPaymentExpired",
        "summary": "payment.expired",
        "description": "Nobody paid before the payment's `expiresAt`. Money that arrives late still settles it, and a `payment.paid` or `payment.held` follows. Answer `2xx` within 10 seconds; failed deliveries are retried 1m, 5m, 30m, 2h, 6h and 12h after each failure. Events can arrive more than once and out of order: deduplicate on the event `id`.",
        "tags": ["Webhook events"],
        "security": [],
        "parameters": [{"$ref": "#/components/parameters/RailbedSignature"}],
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}
        },
        "responses": {
          "2XX": {"description": "Received. Anything else, or no answer within 10 seconds, is retried."}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/webhooks/events/#payment-expired"
        }
      }
    },
    "payment.canceled": {
      "post": {
        "operationId": "webhookPaymentCanceled",
        "summary": "payment.canceled",
        "description": "The session or payment link was canceled before anyone had gone to a provider. Money already on its way still settles it. Answer `2xx` within 10 seconds; failed deliveries are retried 1m, 5m, 30m, 2h, 6h and 12h after each failure. Events can arrive more than once and out of order: deduplicate on the event `id`.",
        "tags": ["Webhook events"],
        "security": [],
        "parameters": [{"$ref": "#/components/parameters/RailbedSignature"}],
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}
        },
        "responses": {
          "2XX": {"description": "Received. Anything else, or no answer within 10 seconds, is retried."}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/webhooks/events/#payment-canceled"
        }
      }
    },
    "invoice.issued": {
      "post": {
        "operationId": "webhookInvoiceIssued",
        "summary": "invoice.issued",
        "description": "The invoice was issued: from now on its `url` can be shared and paid. Sent once, whether it was issued alone or by its first send. Sent only to endpoints that chose it, for invoices built as invoices (`kind: \"invoice\"`). Answer `2xx` within 10 seconds; failed deliveries are retried 1m, 5m, 30m, 2h, 6h and 12h after each failure. Events can arrive more than once and out of order: deduplicate on the event `id`.",
        "tags": ["Webhook events"],
        "security": [],
        "parameters": [{"$ref": "#/components/parameters/RailbedSignature"}],
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}
        },
        "responses": {
          "2XX": {"description": "Received. Anything else, or no answer within 10 seconds, is retried."}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/webhooks/events/#invoice-issued"
        }
      }
    },
    "invoice.sent": {
      "post": {
        "operationId": "webhookInvoiceSent",
        "summary": "invoice.sent",
        "description": "Railbed emailed the invoice to its customer: the first send, a send again or a scheduled reminder. A Test invoice's copy to the team counts too. `sendCount` says how many. Sent only to endpoints that chose it, for invoices built as invoices (`kind: \"invoice\"`). Answer `2xx` within 10 seconds; failed deliveries are retried 1m, 5m, 30m, 2h, 6h and 12h after each failure. Events can arrive more than once and out of order: deduplicate on the event `id`.",
        "tags": ["Webhook events"],
        "security": [],
        "parameters": [{"$ref": "#/components/parameters/RailbedSignature"}],
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}
        },
        "responses": {
          "2XX": {"description": "Received. Anything else, or no answer within 10 seconds, is retried."}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/webhooks/events/#invoice-sent"
        }
      }
    },
    "invoice.viewed": {
      "post": {
        "operationId": "webhookInvoiceViewed",
        "summary": "invoice.viewed",
        "description": "Its customer opened the invoice's page for the first time. Later visits send nothing. Sent only to endpoints that chose it, for invoices built as invoices (`kind: \"invoice\"`). Answer `2xx` within 10 seconds; failed deliveries are retried 1m, 5m, 30m, 2h, 6h and 12h after each failure. Events can arrive more than once and out of order: deduplicate on the event `id`.",
        "tags": ["Webhook events"],
        "security": [],
        "parameters": [{"$ref": "#/components/parameters/RailbedSignature"}],
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}
        },
        "responses": {
          "2XX": {"description": "Received. Anything else, or no answer within 10 seconds, is retried."}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/webhooks/events/#invoice-viewed"
        }
      }
    },
    "invoice.partially_paid": {
      "post": {
        "operationId": "webhookInvoicePartiallyPaid",
        "summary": "invoice.partially_paid",
        "description": "A payment toward the invoice settled and a balance is left. `data.payment` is that payment; `amountDue` is what's left. Sent only to endpoints that chose it, for invoices built as invoices (`kind: \"invoice\"`). Answer `2xx` within 10 seconds; failed deliveries are retried 1m, 5m, 30m, 2h, 6h and 12h after each failure. Events can arrive more than once and out of order: deduplicate on the event `id`.",
        "tags": ["Webhook events"],
        "security": [],
        "parameters": [{"$ref": "#/components/parameters/RailbedSignature"}],
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}
        },
        "responses": {
          "2XX": {"description": "Received. Anything else, or no answer within 10 seconds, is retried."}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/webhooks/events/#invoice-partially-paid"
        }
      }
    },
    "invoice.paid": {
      "post": {
        "operationId": "webhookInvoicePaid",
        "summary": "invoice.paid",
        "description": "The invoice is paid in full. `data.payment` is the payment that finished it. Fulfil from this, once, and deduplicate on the invoice `id` as well as the event `id`. Sent only to endpoints that chose it, for invoices built as invoices (`kind: \"invoice\"`). Answer `2xx` within 10 seconds; failed deliveries are retried 1m, 5m, 30m, 2h, 6h and 12h after each failure. Events can arrive more than once and out of order: deduplicate on the event `id`.",
        "tags": ["Webhook events"],
        "security": [],
        "parameters": [{"$ref": "#/components/parameters/RailbedSignature"}],
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}
        },
        "responses": {
          "2XX": {"description": "Received. Anything else, or no answer within 10 seconds, is retried."}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/webhooks/events/#invoice-paid"
        }
      }
    },
    "invoice.voided": {
      "post": {
        "operationId": "webhookInvoiceVoided",
        "summary": "invoice.voided",
        "description": "The invoice was voided and can no longer be paid. Money already on its way still settles, and its payment's events follow. Sent only to endpoints that chose it, for invoices built as invoices (`kind: \"invoice\"`). Answer `2xx` within 10 seconds; failed deliveries are retried 1m, 5m, 30m, 2h, 6h and 12h after each failure. Events can arrive more than once and out of order: deduplicate on the event `id`.",
        "tags": ["Webhook events"],
        "security": [],
        "parameters": [{"$ref": "#/components/parameters/RailbedSignature"}],
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}
        },
        "responses": {
          "2XX": {"description": "Received. Anything else, or no answer within 10 seconds, is retried."}
        },
        "externalDocs": {
          "description": "Reference",
          "url": "https://railbed.com/docs/webhooks/events/#invoice-voided"
        }
      }
    },
    "ping": {
      "post": {
        "operationId": "webhookPing",
        "summary": "ping",
        "description": "Sent only when you send a test ping from the dashboard. `data.payment`, `data.order` and `data.customer` are `null`. Answer `2xx` within 10 seconds; failed deliveries are retried 1m, 5m, 30m, 2h, 6h and 12h after each failure. Events can arrive more than once and out of order: deduplicate on the event `id`.",
        "tags": ["Webhook events"],
        "security": [],
        "parameters": [{"$ref": "#/components/parameters/RailbedSignature"}],
        "requestBody": {
          "required": true,
          "content": {"application/json": {"schema": {"$ref": "#/components/schemas/WebhookEvent"}}}
        },
        "responses": {
          "2XX": {"description": "Received. Anything else, or no answer within 10 seconds, is retried."}
        },
        "externalDocs": {"description": "Reference", "url": "https://railbed.com/docs/webhooks/events/#ping"}
      }
    }
  },
  "components": {
    "securitySchemes": {
      "secretKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "rb_live_… or rb_test_…",
        "description": "A secret key from Developers: `rb_live_` or `rb_test_` and 43 URL-safe characters. Full access keys have every scope; Read only keys have `payments:read`, `orders:read` and `customers:read`."
      },
      "agentToken": {
        "type": "http",
        "scheme": "bearer",
        "description": "A connected AI agent's access token, from agent sign-in (https://railbed.com/auth.md). It lasts about five minutes and never carries the webhook scopes. Every `401` names the protected resource metadata in `WWW-Authenticate`."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "description": "The body of every error response.",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "Stable and machine-readable. Branch on this and the HTTP status, never on `message`. New codes can be added within `v1`."
              },
              "message": {
                "type": "string",
                "description": "A sentence for people. It can be reworded at any time: show it or log it, never parse it."
              },
              "field": {
                "type": "string",
                "description": "The request field at fault, when there is one, such as `amount`, `metadata` or `order.items[0].amount`."
              },
              "reason": {
                "$ref": "#/components/schemas/NoProvidersReason",
                "description": "With `no_providers` on a session start: why no card provider is offered. Branch on this, never on `message`."
              },
              "providers": {
                "type": "array",
                "description": "With `reason`: the ids of the card providers it is about, such as the ones you turned off that could have taken this buyer. Empty when it names none.",
                "items": {"type": "string"}
              },
              "minimum": {
                "$ref": "#/components/schemas/MinimumAmount",
                "description": "With `reason` `below_minimum`, when known: the smallest card payment your buyers can make, in the session's currency."
              }
            },
            "required": ["code", "message"]
          }
        },
        "required": ["error"]
      },
      "NoProvidersReason": {
        "type": "string",
        "description": "Why no card provider is offered. `providers_off`: card providers you turned off in Integrations → Card providers could have taken this buyer. `below_minimum`: the amount is under every card provider's minimum. `country`: none serves the buyer's country. `unavailable`: the providers that could take it are down, paused or failing checks for now, or a rate couldn't be read; try again later. `closing`: the payment closes too soon for the one provider left. New reasons can be added within `v1`: treat one you don't know as `unavailable`.",
        "enum": ["providers_off", "below_minimum", "country", "unavailable", "closing"]
      },
      "NoProviders": {
        "type": "object",
        "description": "Why no card provider is offered, as a session start's `no_providers` error says it.",
        "properties": {
          "reason": {"$ref": "#/components/schemas/NoProvidersReason"},
          "providers": {
            "type": "array",
            "description": "The ids of the card providers the reason is about. Empty when it names none.",
            "items": {"type": "string"}
          },
          "minimum": {
            "$ref": "#/components/schemas/MinimumAmount",
            "description": "With `below_minimum`, when known: the smallest card payment your buyers can make, in the amount's currency."
          }
        },
        "required": ["reason", "providers"]
      },
      "NotOffered": {
        "type": "object",
        "description": "A card provider routing ruled out for an amount, and why.",
        "properties": {
          "id": {"type": "string", "description": "The provider's id, such as `paypal`."},
          "reason": {
            "type": "string",
            "description": "`below_minimum`: the amount is under its minimum. `currency`: it doesn't take the currency. `country`: it doesn't serve the buyer's country. `merchant_off`: you turned it off. `unavailable`: down, paused or failing checks for now, or in Live a provider your payout wallet can't take. New reasons can be added within `v1`: treat one you don't know as `unavailable`.",
            "enum": ["below_minimum", "currency", "country", "merchant_off", "unavailable"]
          }
        },
        "required": ["id", "reason"]
      },
      "Money": {
        "type": "string",
        "description": "A decimal string with two decimal places, such as `\"49.00\"`. Never a number, so nothing is rounded in transit.",
        "pattern": "^\\d+\\.\\d{2}$"
      },
      "AmountInput": {
        "type": "string",
        "description": "A decimal string from `\"1.00\"` to `\"100000.00\"` with at most two decimal places, such as `\"49.00\"` (`\"49\"` means the same). A JSON number is refused. An amount under the smallest card payment (about 2.00 USD) is refused unless the account takes crypto payments.",
        "pattern": "^\\d{1,7}(\\.\\d{1,2})?$"
      },
      "OrderAmountInput": {
        "type": "string",
        "description": "A decimal string with at most two decimal places, never a number. Zero is allowed.",
        "pattern": "^\\d{1,7}(\\.\\d{1,2})?$"
      },
      "Currency": {
        "type": "string",
        "enum": ["USD", "EUR", "GBP", "CAD", "AUD", "INR", "SEK"],
        "description": "The currency of the price."
      },
      "CurrencyInput": {
        "type": "string",
        "description": "`USD`, `EUR`, `GBP`, `CAD`, `AUD`, `INR` or `SEK`, in any letter case.",
        "pattern": "^[A-Za-z]{3}$"
      },
      "PaymentStatus": {
        "type": "string",
        "enum": ["open", "pending", "paid", "held", "failed", "expired"],
        "description": "`open` and `pending`: wait. `paid`: fulfil, once. `held`: money arrived but failed a check, so never fulfil automatically. `failed`: a terminal failure. `expired`: can still become `paid` or `held` if money arrives late. Treat any status you don't recognise as not paid."
      },
      "Metadata": {
        "type": ["object", "null"],
        "description": "Your metadata, as sent and normalized; `null` when there is none.",
        "additionalProperties": {"type": "string"}
      },
      "MetadataInput": {
        "type": "object",
        "description": "Up to 20 keys of 1–40 characters (not starting with `__`), each with a string value of up to 500 characters.",
        "maxProperties": 20,
        "additionalProperties": {"type": "string", "maxLength": 500}
      },
      "FieldRequirement": {
        "type": "string",
        "enum": ["off", "optional", "required"],
        "description": "Whether the hosted page asks for this detail."
      },
      "CustomFieldInput": {
        "type": "object",
        "description": "A question of your own, answered in one line of text.",
        "properties": {
          "key": {
            "type": "string",
            "description": "1–40 of `a`–`z`, `0`–`9` and `_`, starting with a letter and unique in the list. Left out, it's made from the label.",
            "pattern": "^[a-z][a-z0-9_]{0,39}$"
          },
          "label": {"type": "string", "description": "What the buyer reads.", "maxLength": 50},
          "required": {"type": "boolean", "description": "Default `false`."}
        },
        "required": ["label"]
      },
      "CollectInput": {
        "type": "object",
        "description": "What the hosted page asks the buyer for besides their email. Each detail defaults to `off`. A bad `collect` is `400 invalid_collect`.",
        "properties": {
          "name": {"$ref": "#/components/schemas/FieldRequirement", "description": "The buyer's name."},
          "phone": {
            "$ref": "#/components/schemas/FieldRequirement",
            "description": "The buyer's phone number."
          },
          "date_of_birth": {
            "$ref": "#/components/schemas/FieldRequirement",
            "description": "Self-declared: what the buyer types, not an ID check."
          },
          "minimum_age": {
            "type": ["integer", "null"],
            "description": "13 to 99, only with `date_of_birth` required: a younger buyer can't buy.",
            "minimum": 13,
            "maximum": 99
          },
          "shipping_address": {
            "$ref": "#/components/schemas/FieldRequirement",
            "description": "Where to ship."
          },
          "billing_address": {
            "$ref": "#/components/schemas/FieldRequirement",
            "description": "The billing address."
          },
          "marketing_opt_in": {
            "type": "boolean",
            "description": "Show an unticked \"Email me news and offers\" box."
          },
          "custom_fields": {
            "type": "array",
            "description": "Up to 5 questions of your own.",
            "items": {"$ref": "#/components/schemas/CustomFieldInput"},
            "maxItems": 5
          }
        }
      },
      "CustomField": {
        "type": "object",
        "description": "A question the page asks.",
        "properties": {
          "key": {"type": "string", "description": "The question's key."},
          "label": {"type": "string", "description": "What the buyer reads."},
          "required": {"type": "boolean", "description": "Whether the buyer must answer."}
        },
        "required": ["key", "label", "required"]
      },
      "Collect": {
        "type": "object",
        "description": "What the hosted page asks besides the email.",
        "properties": {
          "name": {"$ref": "#/components/schemas/FieldRequirement"},
          "phone": {"$ref": "#/components/schemas/FieldRequirement"},
          "date_of_birth": {"$ref": "#/components/schemas/FieldRequirement"},
          "minimum_age": {
            "type": ["integer", "null"],
            "description": "The minimum age, when `date_of_birth` is required and one is set."
          },
          "shipping_address": {"$ref": "#/components/schemas/FieldRequirement"},
          "billing_address": {"$ref": "#/components/schemas/FieldRequirement"},
          "marketing_opt_in": {"type": "boolean", "description": "Whether the page shows the email-list box."},
          "custom_fields": {
            "type": "array",
            "description": "Your questions, in the order asked.",
            "items": {"$ref": "#/components/schemas/CustomField"}
          }
        },
        "required": [
          "name",
          "phone",
          "date_of_birth",
          "minimum_age",
          "shipping_address",
          "billing_address",
          "marketing_opt_in",
          "custom_fields"
        ]
      },
      "MinimumAmount": {
        "type": "object",
        "description": "A smallest payment.",
        "properties": {
          "amount": {"type": "string", "description": "A decimal string, such as `\"2.00\"`."},
          "currency": {
            "type": "string",
            "description": "A three-letter currency code.",
            "pattern": "^[A-Z]{3}$"
          }
        },
        "required": ["amount", "currency"]
      },
      "AmountWarning": {
        "type": "object",
        "description": "A note about an amount at creation, never a promise about one buyer.",
        "properties": {
          "code": {
            "type": "string",
            "enum": ["below_card_minimum", "limited_coverage", "minimums_unchecked"],
            "description": "What the card providers' minimums say about the amount."
          },
          "message": {"type": "string", "description": "A sentence for people."},
          "minimum": {
            "anyOf": [{"$ref": "#/components/schemas/MinimumAmount"}, {"type": "null"}],
            "description": "The smallest card payment in the amount's currency, when known."
          }
        },
        "required": ["code", "message", "minimum"]
      },
      "AddressInput": {
        "type": "object",
        "description": "A postal address. Every field is optional; an address with nothing in it counts as none.",
        "properties": {
          "name": {"type": ["string", "null"], "description": "Up to 120 characters.", "maxLength": 120},
          "line1": {"type": ["string", "null"], "description": "Up to 200 characters.", "maxLength": 200},
          "line2": {"type": ["string", "null"], "description": "Up to 200 characters.", "maxLength": 200},
          "city": {"type": ["string", "null"], "description": "Up to 120 characters.", "maxLength": 120},
          "region": {
            "type": ["string", "null"],
            "description": "A state, province or county, up to 120 characters.",
            "maxLength": 120
          },
          "postal_code": {"type": ["string", "null"], "description": "Up to 32 characters.", "maxLength": 32},
          "country": {
            "type": ["string", "null"],
            "description": "A two-letter code such as `US`, in any letter case.",
            "pattern": "^[A-Za-z]{2}$"
          }
        }
      },
      "PostalAddressInput": {
        "type": "object",
        "description": "A payment link's address, named after `customer_name`. `region` is a code for US, CA and AU (such as `NY`), free text elsewhere.",
        "properties": {
          "line1": {"type": ["string", "null"], "description": "Up to 200 characters.", "maxLength": 200},
          "line2": {"type": ["string", "null"], "description": "Up to 200 characters.", "maxLength": 200},
          "city": {"type": ["string", "null"], "description": "Up to 120 characters.", "maxLength": 120},
          "region": {
            "type": ["string", "null"],
            "description": "A state, province or county, up to 120 characters.",
            "maxLength": 120
          },
          "postal_code": {"type": ["string", "null"], "description": "Up to 32 characters.", "maxLength": 32},
          "country": {
            "type": ["string", "null"],
            "description": "A two-letter code such as `US`, in any letter case.",
            "pattern": "^[A-Za-z]{2}$"
          }
        }
      },
      "Address": {
        "type": "object",
        "description": "A postal address.",
        "properties": {
          "name": {"type": ["string", "null"]},
          "line1": {"type": ["string", "null"]},
          "line2": {"type": ["string", "null"]},
          "city": {"type": ["string", "null"]},
          "region": {"type": ["string", "null"]},
          "postal_code": {"type": ["string", "null"]},
          "country": {"type": ["string", "null"], "description": "A two-letter code such as `US`."}
        },
        "required": ["name", "line1", "line2", "city", "region", "postal_code", "country"]
      },
      "CustomerInput": {
        "type": "object",
        "description": "Who is buying. A `customer` that isn't an object, or a `customer.email` that differs from `customer_email`, is `400 invalid_customer`.",
        "properties": {
          "email": {
            "type": ["string", "null"],
            "description": "The buyer's email. When `customer_email` is sent too, they must be the same address.",
            "format": "email"
          },
          "name": {"type": ["string", "null"], "description": "Up to 120 characters.", "maxLength": 120},
          "phone": {
            "type": ["string", "null"],
            "description": "Up to 40 characters, in any format.",
            "maxLength": 40
          },
          "date_of_birth": {
            "type": ["string", "null"],
            "description": "A past date as `YYYY-MM-DD`.",
            "format": "date"
          },
          "accepts_marketing": {
            "type": ["boolean", "null"],
            "description": "`true` joins your email list. `false` or absent changes nothing."
          },
          "id": {
            "type": ["string", "null"],
            "description": "The buyer's customer id in your store, up to 64 characters.",
            "maxLength": 64
          }
        }
      },
      "OrderItemInput": {
        "type": "object",
        "description": "One line of an order.",
        "properties": {
          "name": {"type": "string", "description": "Up to 200 characters.", "maxLength": 200},
          "quantity": {
            "type": "integer",
            "description": "A whole number from 1 to 100,000.",
            "minimum": 1,
            "maximum": 100000
          },
          "amount": {
            "$ref": "#/components/schemas/OrderAmountInput",
            "description": "The line's total for all its units, such as `\"64.00\"`."
          },
          "unit_amount": {
            "anyOf": [{"$ref": "#/components/schemas/OrderAmountInput"}, {"type": "null"}],
            "description": "One unit's price, for display. It isn't checked against `amount`."
          },
          "sku": {"type": ["string", "null"], "description": "Up to 64 characters.", "maxLength": 64},
          "variant": {
            "type": ["string", "null"],
            "description": "Which version, up to 120 characters.",
            "maxLength": 120
          }
        },
        "required": ["name", "quantity", "amount"]
      },
      "StoreInput": {
        "type": "object",
        "description": "Which of your stores the order is from.",
        "properties": {
          "id": {
            "type": "string",
            "description": "A stable id for the store, up to 64 characters.",
            "maxLength": 64
          },
          "platform": {
            "type": "string",
            "enum": ["woocommerce", "shopify", "other"],
            "description": "Default `other`."
          },
          "name": {"type": ["string", "null"], "description": "Up to 120 characters.", "maxLength": 120},
          "url": {
            "type": ["string", "null"],
            "description": "The store's address, up to 1,000 characters. Kept only when it's `http://` or `https://`.",
            "maxLength": 1000
          }
        },
        "required": ["id"]
      },
      "OrderInput": {
        "type": "object",
        "description": "What the buyer is buying. With `items`, the items less `discount` plus `shipping` and `tax` must equal `amount` to the cent (`400 invalid_order_totals` otherwise). Any field that breaks its rules is `400 invalid_order`, with `field` naming it.",
        "properties": {
          "id": {
            "type": ["string", "null"],
            "description": "Your order id, up to 64 characters. A later session with the same `id` joins this order.",
            "maxLength": 64
          },
          "number": {
            "type": ["string", "null"],
            "description": "The order number your buyers see, up to 32 characters. Used only with `id`.",
            "maxLength": 32
          },
          "url": {
            "type": ["string", "null"],
            "description": "The order's page in your admin, up to 1,000 characters. Used only with `id`.",
            "maxLength": 1000
          },
          "store": {"anyOf": [{"$ref": "#/components/schemas/StoreInput"}, {"type": "null"}]},
          "items": {
            "type": ["array", "null"],
            "description": "What's being bought, 1–100 items. Leave it out for a single line.",
            "items": {"$ref": "#/components/schemas/OrderItemInput"},
            "minItems": 1,
            "maxItems": 100
          },
          "discount": {
            "anyOf": [{"$ref": "#/components/schemas/OrderAmountInput"}, {"type": "null"}],
            "description": "Taken off the items' total. Default `\"0.00\"`."
          },
          "discount_code": {
            "type": ["string", "null"],
            "description": "Up to 64 characters.",
            "maxLength": 64
          },
          "shipping": {
            "anyOf": [{"$ref": "#/components/schemas/OrderAmountInput"}, {"type": "null"}],
            "description": "Shipping charged. Default `\"0.00\"`."
          },
          "shipping_method": {
            "type": ["string", "null"],
            "description": "Up to 120 characters.",
            "maxLength": 120
          },
          "tax": {
            "anyOf": [{"$ref": "#/components/schemas/OrderAmountInput"}, {"type": "null"}],
            "description": "Tax charged. Default `\"0.00\"`."
          },
          "shipping_address": {"anyOf": [{"$ref": "#/components/schemas/AddressInput"}, {"type": "null"}]},
          "billing_address": {"anyOf": [{"$ref": "#/components/schemas/AddressInput"}, {"type": "null"}]},
          "fulfillment": {
            "type": ["string", "null"],
            "description": "Default `unfulfilled` when there's a shipping address, otherwise `none`.",
            "enum": ["none", "unfulfilled", "fulfilled", null]
          }
        }
      },
      "CreateCheckoutSession": {
        "type": "object",
        "description": "Send `amount`, `currency` and `description`, or `checkout` for a session that buys a saved checkout. Unknown fields are ignored.",
        "properties": {
          "checkout": {
            "type": "string",
            "description": "A saved checkout's id (`chk_…`) or slug: its price, currency, description and plan come from the checkout. Then `amount`, `currency`, `description`, `collect` and `order` are refused (`400 field_not_allowed`).",
            "pattern": "^[A-Za-z0-9_-]{1,64}$"
          },
          "plan": {
            "type": "string",
            "description": "Pricing tables: the id of the plan the buyer chose. Required there."
          },
          "option": {
            "type": "integer",
            "enum": [0, 1],
            "description": "Pricing tables with a switch: which side of it. Required there."
          },
          "amount": {"$ref": "#/components/schemas/AmountInput"},
          "currency": {"$ref": "#/components/schemas/CurrencyInput"},
          "description": {
            "type": "string",
            "description": "What the buyer is paying for, shown on the page. Up to 120 characters.",
            "maxLength": 120
          },
          "customer_email": {
            "type": ["string", "null"],
            "description": "The buyer's email, filled in on the page.",
            "format": "email"
          },
          "reference": {
            "type": ["string", "null"],
            "description": "Your order id or other reference, up to 120 characters. Echoed in webhooks.",
            "maxLength": 120
          },
          "success_url": {
            "type": ["string", "null"],
            "description": "Where the buyer lands once paid; `{PAYMENT_ID}` and `{REFERENCE}` are filled in. Up to 1,000 characters; a public `https://` address in Live mode. Never fulfil from this return.",
            "maxLength": 1000
          },
          "cancel_url": {
            "type": ["string", "null"],
            "description": "Where the buyer goes if they leave the checkout. The same rules as `success_url`.",
            "maxLength": 1000
          },
          "metadata": {"$ref": "#/components/schemas/MetadataInput"},
          "customer": {"anyOf": [{"$ref": "#/components/schemas/CustomerInput"}, {"type": "null"}]},
          "order": {"anyOf": [{"$ref": "#/components/schemas/OrderInput"}, {"type": "null"}]},
          "collect": {"anyOf": [{"$ref": "#/components/schemas/CollectInput"}, {"type": "null"}]}
        },
        "anyOf": [{"required": ["amount", "currency", "description"]}, {"required": ["checkout"]}]
      },
      "CheckoutSession": {
        "type": "object",
        "description": "One attempt at paying. Its id is also its payment's id.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The session's id, `pay_…`. It is also the payment's id.",
            "pattern": "^pay_"
          },
          "object": {"type": "string", "const": "checkout_session"},
          "url": {
            "type": "string",
            "description": "The hosted checkout page: send the buyer here.",
            "format": "uri"
          },
          "status": {"$ref": "#/components/schemas/PaymentStatus"},
          "livemode": {"type": "boolean", "description": "`true` for Live, `false` for Test."},
          "amount": {"$ref": "#/components/schemas/Money"},
          "currency": {"$ref": "#/components/schemas/Currency"},
          "description": {"type": "string", "description": "What the buyer is paying for."},
          "reference": {"type": ["string", "null"], "description": "Your reference."},
          "customer_email": {"type": ["string", "null"], "description": "The buyer's email, when known."},
          "created": {"type": "integer", "description": "When it was created. Unix seconds.", "minimum": 0},
          "expires_at": {
            "type": "integer",
            "description": "When an unpaid session expires. Unix seconds.",
            "minimum": 0
          },
          "started_at": {
            "type": ["integer", "null"],
            "description": "When it was first started. Unix seconds; `null` until then.",
            "minimum": 0
          },
          "metadata": {"$ref": "#/components/schemas/Metadata"},
          "order_id": {"type": ["string", "null"], "description": "The order it belongs to, `ord_…`."},
          "collect": {
            "anyOf": [{"$ref": "#/components/schemas/Collect"}, {"type": "null"}],
            "description": "What the hosted page asks besides the email; `null` when nothing more."
          },
          "canceled_at": {
            "type": ["integer", "null"],
            "description": "When it was canceled (its status is then `expired`). Unix seconds; `null` until then.",
            "minimum": 0
          },
          "checkout_id": {"type": ["string", "null"], "description": "The saved checkout it buys, `chk_…`."},
          "plan_label": {
            "type": ["string", "null"],
            "description": "Pricing tables: the plan bought, such as `Pro · Yearly`."
          },
          "warnings": {
            "type": "array",
            "description": "Only on create, and only when there is something to say about the card providers' minimums.",
            "items": {"$ref": "#/components/schemas/AmountWarning"}
          }
        },
        "required": [
          "id",
          "object",
          "url",
          "status",
          "livemode",
          "amount",
          "currency",
          "description",
          "reference",
          "customer_email",
          "created",
          "expires_at",
          "started_at",
          "metadata",
          "order_id",
          "collect",
          "canceled_at",
          "checkout_id",
          "plan_label"
        ]
      },
      "StartCheckoutSession": {
        "type": "object",
        "description": "Send `{}` when the saved email is enough.",
        "properties": {
          "customer_email": {
            "type": "string",
            "description": "The buyer's email. Optional when the session already has one; a new one replaces it.",
            "format": "email"
          },
          "country": {
            "type": "string",
            "description": "The buyer's two-letter country code, any letter case. Use the buyer's country, never your server's.",
            "pattern": "^[A-Za-z]{2}$"
          }
        }
      },
      "ProviderHandoff": {
        "type": "object",
        "description": "A card provider that can take the payment.",
        "properties": {
          "id": {"type": "string", "description": "The provider's id, such as `stripe`."},
          "name": {"type": "string", "description": "Its display name."},
          "note": {"type": "string", "description": "A short line on how the buyer pays there."},
          "recommended": {"type": "boolean", "description": "`true` for at most one: the best match."},
          "handoff_url": {
            "type": "string",
            "description": "Open this in the buyer's browser, from their click, in a new tab. Never fetch it from your server.",
            "format": "uri"
          }
        },
        "required": ["id", "name", "note", "recommended", "handoff_url"]
      },
      "StartedCheckoutSession": {
        "type": "object",
        "description": "The session, with the providers the buyer can pay with.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The session's id, `pay_…`. It is also the payment's id.",
            "pattern": "^pay_"
          },
          "object": {"type": "string", "const": "checkout_session"},
          "url": {
            "type": "string",
            "description": "The hosted checkout page: send the buyer here.",
            "format": "uri"
          },
          "status": {"$ref": "#/components/schemas/PaymentStatus"},
          "livemode": {"type": "boolean", "description": "`true` for Live, `false` for Test."},
          "amount": {"$ref": "#/components/schemas/Money"},
          "currency": {"$ref": "#/components/schemas/Currency"},
          "description": {"type": "string", "description": "What the buyer is paying for."},
          "reference": {"type": ["string", "null"], "description": "Your reference."},
          "customer_email": {"type": ["string", "null"], "description": "The buyer's email, when known."},
          "created": {"type": "integer", "description": "When it was created. Unix seconds.", "minimum": 0},
          "expires_at": {
            "type": "integer",
            "description": "When an unpaid session expires. Unix seconds.",
            "minimum": 0
          },
          "started_at": {
            "type": ["integer", "null"],
            "description": "When it was first started. Unix seconds; `null` until then.",
            "minimum": 0
          },
          "metadata": {"$ref": "#/components/schemas/Metadata"},
          "order_id": {"type": ["string", "null"], "description": "The order it belongs to, `ord_…`."},
          "collect": {
            "anyOf": [{"$ref": "#/components/schemas/Collect"}, {"type": "null"}],
            "description": "What the hosted page asks besides the email; `null` when nothing more."
          },
          "canceled_at": {
            "type": ["integer", "null"],
            "description": "When it was canceled (its status is then `expired`). Unix seconds; `null` until then.",
            "minimum": 0
          },
          "checkout_id": {"type": ["string", "null"], "description": "The saved checkout it buys, `chk_…`."},
          "plan_label": {
            "type": ["string", "null"],
            "description": "Pricing tables: the plan bought, such as `Pro · Yearly`."
          },
          "country": {"type": ["string", "null"], "description": "The country you sent, uppercased."},
          "providers": {
            "type": "array",
            "description": "The card providers that can take this payment, best match first.",
            "items": {"$ref": "#/components/schemas/ProviderHandoff"}
          }
        },
        "required": [
          "id",
          "object",
          "url",
          "status",
          "livemode",
          "amount",
          "currency",
          "description",
          "reference",
          "customer_email",
          "created",
          "expires_at",
          "started_at",
          "metadata",
          "order_id",
          "collect",
          "canceled_at",
          "checkout_id",
          "plan_label",
          "country",
          "providers"
        ]
      },
      "Settlement": {
        "type": "object",
        "description": "What arrived and where it went.",
        "properties": {
          "network": {
            "type": ["string", "null"],
            "description": "Crypto payments: the network the money arrived on, such as `base`. `null` for card, whose `coin` names it."
          },
          "coin": {"type": ["string", "null"], "description": "What arrived, such as `polygon_usdc`."},
          "value_coin": {
            "type": ["string", "null"],
            "description": "How much arrived at the deposit address, in `coin`."
          },
          "merchant_received": {
            "type": ["string", "null"],
            "description": "How much was forwarded to your wallet, in `coin`, with six decimal places. `null` until reported; never estimated."
          },
          "merchant_received_usd": {
            "type": ["string", "null"],
            "description": "The same share in US dollars, with six decimal places. `null` until reported."
          },
          "txid_in": {"type": ["string", "null"], "description": "The transaction that delivered the money."},
          "txid_out": {
            "type": ["string", "null"],
            "description": "The transaction that forwarded it to your wallet."
          },
          "payout_wallet": {
            "type": ["string", "null"],
            "description": "Your wallet the payment is forwarded to, fixed when it starts."
          }
        },
        "required": [
          "network",
          "coin",
          "value_coin",
          "merchant_received",
          "merchant_received_usd",
          "txid_in",
          "txid_out",
          "payout_wallet"
        ]
      },
      "Payment": {
        "type": "object",
        "description": "A session's payment: its status and what arrived. Fulfil only when `status` is `paid`.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The session's id, `pay_…`. It is also the payment's id.",
            "pattern": "^pay_"
          },
          "object": {"type": "string", "const": "payment"},
          "url": {
            "type": "string",
            "description": "The hosted checkout page: send the buyer here.",
            "format": "uri"
          },
          "status": {"$ref": "#/components/schemas/PaymentStatus"},
          "livemode": {"type": "boolean", "description": "`true` for Live, `false` for Test."},
          "amount": {"$ref": "#/components/schemas/Money"},
          "currency": {"$ref": "#/components/schemas/Currency"},
          "description": {"type": "string", "description": "What the buyer is paying for."},
          "reference": {"type": ["string", "null"], "description": "Your reference."},
          "customer_email": {"type": ["string", "null"], "description": "The buyer's email, when known."},
          "created": {"type": "integer", "description": "When it was created. Unix seconds.", "minimum": 0},
          "expires_at": {
            "type": "integer",
            "description": "When an unpaid session expires. Unix seconds.",
            "minimum": 0
          },
          "started_at": {
            "type": ["integer", "null"],
            "description": "When it was first started. Unix seconds; `null` until then.",
            "minimum": 0
          },
          "metadata": {"$ref": "#/components/schemas/Metadata"},
          "order_id": {"type": ["string", "null"], "description": "The order it belongs to, `ord_…`."},
          "collect": {
            "anyOf": [{"$ref": "#/components/schemas/Collect"}, {"type": "null"}],
            "description": "What the hosted page asks besides the email; `null` when nothing more."
          },
          "canceled_at": {
            "type": ["integer", "null"],
            "description": "When it was canceled (its status is then `expired`). Unix seconds; `null` until then.",
            "minimum": 0
          },
          "checkout_id": {"type": ["string", "null"], "description": "The saved checkout it buys, `chk_…`."},
          "plan_label": {
            "type": ["string", "null"],
            "description": "Pricing tables: the plan bought, such as `Pro · Yearly`."
          },
          "paid_at": {
            "type": ["integer", "null"],
            "description": "When it became `paid`. Unix seconds; `null` until then.",
            "minimum": 0
          },
          "provider": {
            "type": ["string", "null"],
            "description": "The card provider the buyer chose, such as `stripe`; `null` for crypto."
          },
          "hold_reason": {"type": ["string", "null"], "description": "Why it's `held`, in plain words."},
          "hold_acceptable": {
            "type": "boolean",
            "description": "For a held payment: whether you can accept it as paid in the dashboard."
          },
          "method": {
            "type": "string",
            "enum": ["card", "crypto"],
            "description": "How the money arrived: `crypto` when the buyer sent stablecoins from their own wallet."
          },
          "settlement": {"$ref": "#/components/schemas/Settlement"},
          "invoice_id": {
            "type": ["string", "null"],
            "description": "The invoice it pays toward, `in_…` (every payment link is one), or `null`."
          },
          "tip": {
            "$ref": "#/components/schemas/Money",
            "description": "The part of `amount` the buyer added as a tip on an invoice, `\"0.00\"` without one. Tips never count toward the invoice."
          }
        },
        "required": [
          "id",
          "object",
          "url",
          "status",
          "livemode",
          "amount",
          "currency",
          "description",
          "reference",
          "customer_email",
          "created",
          "expires_at",
          "started_at",
          "metadata",
          "order_id",
          "collect",
          "canceled_at",
          "checkout_id",
          "plan_label",
          "paid_at",
          "provider",
          "hold_reason",
          "hold_acceptable",
          "method",
          "settlement",
          "invoice_id",
          "tip"
        ]
      },
      "PaymentList": {
        "type": "object",
        "description": "A page of payments.",
        "properties": {
          "data": {
            "type": "array",
            "description": "A page of payments, newest first.",
            "items": {"$ref": "#/components/schemas/Payment"}
          },
          "has_more": {"type": "boolean", "description": "`true` when there are more after this page."},
          "next_cursor": {
            "type": ["string", "null"],
            "description": "Pass this as `starting_after` for the next page; `null` on the last page."
          }
        },
        "required": ["data", "has_more", "next_cursor"]
      },
      "SimulatePayment": {
        "type": "object",
        "description": "Test mode only.",
        "properties": {
          "outcome": {
            "type": "string",
            "enum": ["paid", "underpaid", "declined", "failed"],
            "description": "`paid` and `underpaid` run the settlement checks; `declined` records a provider decline and keeps the payment open; `failed` ends it."
          }
        },
        "required": ["outcome"]
      },
      "ProviderOffer": {
        "type": "object",
        "description": "A provider Smart Routing would offer.",
        "properties": {
          "id": {"type": "string", "description": "The provider's id."},
          "name": {"type": "string", "description": "Its display name."},
          "note": {"type": "string", "description": "A short line on how the buyer pays there."},
          "recommended": {"type": "boolean", "description": "`true` for at most one."}
        },
        "required": ["id", "name", "note", "recommended"]
      },
      "PaymentMethod": {
        "type": "object",
        "description": "A card provider.",
        "properties": {
          "id": {"type": "string", "description": "The provider's id, such as `stripe`."},
          "name": {"type": "string", "description": "Its display name."},
          "note": {"type": "string", "description": "How the buyer pays there."},
          "status": {
            "type": "string",
            "enum": ["available", "unavailable"],
            "description": "`unavailable`: down for now, paused or failing checks, or in Live a provider that pays off Polygon while your payout wallet isn't an ordinary wallet; buyers aren't offered it."
          },
          "minimum": {
            "anyOf": [{"$ref": "#/components/schemas/MinimumAmount"}, {"type": "null"}],
            "description": "Its smallest payment, in its own currency; `null` when the list doesn't say."
          },
          "regions": {
            "type": ["array", "null"],
            "description": "The countries it serves, or `null` for no restriction.",
            "items": {"type": "string"}
          },
          "merchant_off": {
            "type": "boolean",
            "description": "You turned it off in Integrations → Card providers: buyers are never offered it."
          }
        },
        "required": ["id", "name", "note", "status", "minimum", "regions", "merchant_off"]
      },
      "PaymentMethodList": {
        "type": "object",
        "description": "The card providers.",
        "properties": {
          "object": {"type": "string", "const": "list"},
          "data": {
            "type": "array",
            "description": "Every card provider, in the order you saved for the key's mode in Integrations → Card providers (any it doesn't name after it), or in a fixed order until you save one.",
            "items": {"$ref": "#/components/schemas/PaymentMethod"}
          },
          "offered": {
            "type": "array",
            "description": "With `amount`: what Smart Routing would offer a buyer for it today, best first, at most 8. Never a promise.",
            "items": {"$ref": "#/components/schemas/ProviderOffer"},
            "maxItems": 8
          },
          "not_offered": {
            "type": "array",
            "description": "With `amount`: every card provider routing ruled out for it, in `data`'s order, with why. A provider in neither `offered` nor here only ranked below the eight offered.",
            "items": {"$ref": "#/components/schemas/NotOffered"}
          },
          "no_providers": {
            "$ref": "#/components/schemas/NoProviders",
            "description": "With `amount`, only when `offered` is empty: why, as starting a session for that amount and buyer would be refused."
          }
        },
        "required": ["object", "data"]
      },
      "PayoutWallet": {
        "type": "object",
        "description": "One of the account's other saved wallets.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The wallet's id, `pw_…`: what `payout_wallet_id` takes.",
            "pattern": "^pw_"
          },
          "object": {"type": "string", "const": "payout_wallet"},
          "network": {
            "type": "string",
            "description": "`evm` for a wallet on Polygon and the other EVM networks, which a payment link or invoice can pay. Any other value is the one network a wallet for crypto payments in that network's coins is on.",
            "enum": [
              "evm",
              "bitcoin",
              "litecoin",
              "dogecoin",
              "bitcoin_cash",
              "zcash",
              "monero",
              "tron",
              "solana",
              "ton"
            ]
          },
          "address": {"type": "string", "description": "The wallet's address, in its network's own form."},
          "label": {
            "type": ["string", "null"],
            "description": "The owner's name for an `evm` wallet, up to 40 characters. `null` on other networks."
          },
          "usable": {
            "type": "boolean",
            "description": "`true` when a Live payment link or invoice can pay this wallet today: an `evm` wallet that passes the wallet checks. `false` for a wallet on another network, and for one the checks refuse (`409 payout_wallet_unusable` in Live)."
          },
          "created": {"type": "integer", "description": "When it was saved, in Unix seconds.", "minimum": 0}
        },
        "required": ["id", "object", "network", "address", "label", "usable", "created"]
      },
      "PayoutWalletList": {
        "type": "object",
        "description": "Every saved wallet, in one page.",
        "properties": {
          "data": {
            "type": "array",
            "description": "The saved wallets, newest first. At most ten `evm` wallets and one for each other network.",
            "items": {"$ref": "#/components/schemas/PayoutWallet"}
          },
          "has_more": {
            "type": "boolean",
            "const": false,
            "description": "Always `false`: the list is never paged."
          },
          "next_cursor": {"type": "null", "description": "Always `null`."}
        },
        "required": ["data", "has_more", "next_cursor"]
      },
      "RoutingInput": {
        "type": "object",
        "description": "How buyers reach a card provider. A bad rule is `400 invalid_routing`.",
        "properties": {
          "choice": {
            "type": "string",
            "enum": ["smart", "buyer", "fixed"],
            "description": "`smart`: Smart Routing picks. `buyer`: the buyer chooses. `fixed`: one provider."
          },
          "provider": {
            "type": ["string", "null"],
            "description": "`fixed` only: a card provider id, such as `stripe`."
          },
          "fallback": {
            "type": "boolean",
            "description": "`fixed` only: use Smart Routing when that provider can't take the buyer. Default `true`."
          }
        },
        "required": ["choice"]
      },
      "LinkRoutingInput": {
        "type": "object",
        "description": "Which card providers a payment link offers, and how the payer reaches one. Default: the payer chooses from every provider.",
        "properties": {
          "choice": {
            "type": "string",
            "enum": ["smart", "buyer", "fixed"],
            "description": "`smart`: Smart Routing picks. `buyer`: the buyer chooses. `fixed`: one provider."
          },
          "provider": {"type": ["string", "null"], "description": "`fixed` only: a card provider id."},
          "fallback": {
            "type": "boolean",
            "description": "`fixed` only: use Smart Routing when that provider can't take the payer. Default `true`."
          },
          "providers": {
            "type": ["array", "null"],
            "description": "Smart Routing and buyer's choice: the only provider ids this link offers; `null` for all.",
            "items": {"type": "string"},
            "minItems": 1
          }
        },
        "required": ["choice"]
      },
      "Routing": {
        "type": "object",
        "description": "How buyers reach a card provider.",
        "properties": {
          "choice": {
            "type": "string",
            "enum": ["smart", "buyer", "fixed"],
            "description": "`smart`: Smart Routing picks. `buyer`: the buyer chooses. `fixed`: one provider."
          },
          "provider": {"type": ["string", "null"], "description": "With `fixed`: the provider."},
          "fallback": {
            "type": "boolean",
            "description": "With `fixed`: whether Smart Routing takes over when it can't take the buyer."
          }
        },
        "required": ["choice", "provider", "fallback"]
      },
      "LinkRouting": {
        "type": "object",
        "description": "Which card providers a payment link offers.",
        "properties": {
          "choice": {
            "type": "string",
            "enum": ["smart", "buyer", "fixed"],
            "description": "`smart`: Smart Routing picks. `buyer`: the buyer chooses. `fixed`: one provider."
          },
          "provider": {"type": ["string", "null"], "description": "With `fixed`: the provider."},
          "fallback": {"type": "boolean", "description": "With `fixed`: whether Smart Routing takes over."},
          "providers": {
            "type": ["array", "null"],
            "description": "The only providers it offers; `null` for all.",
            "items": {"type": "string"}
          }
        },
        "required": ["choice", "provider", "fallback", "providers"]
      },
      "CreatePaymentLink": {
        "type": "object",
        "description": "A payment request for one payer.",
        "properties": {
          "amount": {"$ref": "#/components/schemas/AmountInput"},
          "currency": {"$ref": "#/components/schemas/CurrencyInput"},
          "description": {
            "type": "string",
            "description": "What it's for, shown to the payer. Up to 120 characters. Optional: without one, the link reads \"Payment to\" and the business name.",
            "maxLength": 120
          },
          "customer_name": {
            "type": ["string", "null"],
            "description": "Who it's for, up to 80 characters.",
            "maxLength": 80
          },
          "customer_email": {
            "type": ["string", "null"],
            "description": "Prefilled on the payer's page.",
            "format": "email"
          },
          "customer_phone": {
            "type": ["string", "null"],
            "description": "Up to 40 characters.",
            "maxLength": 40
          },
          "shipping_address": {
            "anyOf": [{"$ref": "#/components/schemas/PostalAddressInput"}, {"type": "null"}]
          },
          "billing_address": {
            "anyOf": [{"$ref": "#/components/schemas/PostalAddressInput"}, {"type": "null"}]
          },
          "reference": {
            "type": ["string", "null"],
            "description": "Up to 64 characters, such as an invoice number.",
            "maxLength": 64
          },
          "memo": {
            "type": ["string", "null"],
            "description": "A note to the payer, up to 500 characters.",
            "maxLength": 500
          },
          "expires_in_days": {
            "type": "integer",
            "description": "A whole number from 1 to 365, as a JSON number. Default 7.",
            "minimum": 1,
            "maximum": 365,
            "default": 7
          },
          "success_url": {
            "type": ["string", "null"],
            "description": "Where the payer lands once paid. A public `https://` address in Live mode.",
            "maxLength": 1000
          },
          "collect": {"anyOf": [{"$ref": "#/components/schemas/CollectInput"}, {"type": "null"}]},
          "payout_wallet_id": {
            "type": ["string", "null"],
            "description": "One of your saved payout wallets (`pw_…`) to pay instead of the main one; `null` or absent for the main wallet. Wallets are saved in the dashboard only.",
            "pattern": "^pw_"
          },
          "routing": {"$ref": "#/components/schemas/LinkRoutingInput"}
        },
        "required": ["amount", "currency"]
      },
      "PaymentLink": {
        "type": "object",
        "description": "A one-off payment request. Read its settlement with `GET /v1/payments/:id`.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The link's id, `pay_…`. It is also its payment's id.",
            "pattern": "^pay_"
          },
          "object": {"type": "string", "const": "payment_link"},
          "url": {"type": "string", "description": "The payer's page: send this to them.", "format": "uri"},
          "tracking_url": {
            "type": ["string", "null"],
            "description": "A status-only page, safe to share with anyone.",
            "format": "uri"
          },
          "status": {"$ref": "#/components/schemas/PaymentStatus"},
          "livemode": {"type": "boolean", "description": "`true` for Live, `false` for Test."},
          "amount": {"$ref": "#/components/schemas/Money"},
          "currency": {"$ref": "#/components/schemas/Currency"},
          "description": {"type": "string", "description": "What it's for."},
          "reference": {"type": ["string", "null"], "description": "Your reference."},
          "customer_name": {"type": ["string", "null"], "description": "Who it's for."},
          "customer_email": {"type": ["string", "null"], "description": "The payer's email, when known."},
          "memo": {"type": ["string", "null"], "description": "The note to the payer."},
          "success_url": {"type": ["string", "null"], "description": "Where the payer lands once paid."},
          "collect": {"anyOf": [{"$ref": "#/components/schemas/Collect"}, {"type": "null"}]},
          "routing": {"$ref": "#/components/schemas/LinkRouting"},
          "order_id": {"type": ["string", "null"], "description": "The order it belongs to, `ord_…`."},
          "payout_wallet_id": {
            "type": ["string", "null"],
            "description": "The saved payout wallet it pays (`pw_…`), or `null` for the main one."
          },
          "created": {"type": "integer", "description": "When it was created. Unix seconds.", "minimum": 0},
          "expires_at": {
            "type": "integer",
            "description": "When it expires unpaid. Unix seconds.",
            "minimum": 0
          },
          "started_at": {
            "type": ["integer", "null"],
            "description": "When the payer started paying. Unix seconds; `null` until then.",
            "minimum": 0
          },
          "paid_at": {
            "type": ["integer", "null"],
            "description": "When it became `paid`. Unix seconds; `null` until then.",
            "minimum": 0
          },
          "canceled_at": {
            "type": ["integer", "null"],
            "description": "When you canceled it (its status is then `expired`). Unix seconds; `null` until then.",
            "minimum": 0
          },
          "warnings": {
            "type": "array",
            "description": "Only on create, and only when there is something to say about the card providers' minimums.",
            "items": {"$ref": "#/components/schemas/AmountWarning"}
          }
        },
        "required": [
          "id",
          "object",
          "url",
          "tracking_url",
          "status",
          "livemode",
          "amount",
          "currency",
          "description",
          "reference",
          "customer_name",
          "customer_email",
          "memo",
          "success_url",
          "collect",
          "routing",
          "order_id",
          "payout_wallet_id",
          "created",
          "expires_at",
          "started_at",
          "paid_at",
          "canceled_at"
        ]
      },
      "PaymentLinkList": {
        "type": "object",
        "description": "A page of payment links.",
        "properties": {
          "data": {
            "type": "array",
            "description": "A page of payment links, newest first.",
            "items": {"$ref": "#/components/schemas/PaymentLink"}
          },
          "has_more": {"type": "boolean", "description": "`true` when there are more after this page."},
          "next_cursor": {
            "type": ["string", "null"],
            "description": "Pass this as `starting_after` for the next page; `null` on the last page."
          }
        },
        "required": ["data", "has_more", "next_cursor"]
      },
      "InvoiceStatus": {
        "type": "string",
        "enum": ["draft", "sent", "viewed", "partially_paid", "overdue", "paid", "void", "expired"],
        "description": "What a person sees: `draft` (not issued), `sent` (issued, not opened yet), `viewed` (its customer opened it), `partially_paid`, `overdue` (past its due date with a balance left), `paid`, `void`, or `expired` (a payment link that can no longer be paid)."
      },
      "InvoiceLineInput": {
        "type": "object",
        "description": "One line: what it's for, how many and the price of one.",
        "properties": {
          "description": {
            "type": "string",
            "description": "What it's for, up to 200 characters.",
            "maxLength": 200
          },
          "quantity": {
            "type": ["string", "number"],
            "description": "How many, from 0.01 to 99,999 with up to two decimals (`\"12.5\"` hours). Default 1."
          },
          "unit_amount": {
            "type": "string",
            "pattern": "^\\d{1,7}(\\.\\d{1,2})?$",
            "description": "The price of one, as a decimal string such as `\"150.00\"`. A JSON number is refused."
          }
        },
        "required": ["description", "unit_amount"]
      },
      "InvoiceCustomerInput": {
        "type": "object",
        "description": "Who an invoice is for. Pass `id` for a saved customer: their details fill in what you leave out.",
        "properties": {
          "id": {
            "type": ["string", "null"],
            "description": "A saved customer in this mode, `cus_…`.",
            "pattern": "^cus_"
          },
          "name": {"type": ["string", "null"], "description": "Up to 80 characters.", "maxLength": 80},
          "email": {
            "type": ["string", "null"],
            "description": "Where Railbed emails the invoice, lowercased."
          },
          "company": {"type": ["string", "null"], "description": "Up to 120 characters.", "maxLength": 120},
          "phone": {"type": ["string", "null"], "description": "Up to 40 characters.", "maxLength": 40},
          "billing_address": {
            "anyOf": [{"$ref": "#/components/schemas/PostalAddressInput"}, {"type": "null"}],
            "description": "Shown on the invoice and its PDF."
          }
        }
      },
      "InvoiceDiscountInput": {
        "type": "object",
        "description": "A fixed amount or a percentage of the subtotal, one of the two: sending both is `400 invalid_discount`.",
        "properties": {
          "amount": {
            "type": ["string", "null"],
            "description": "A decimal string, such as `\"25.00\"`.",
            "pattern": "^\\d{1,7}(\\.\\d{1,2})?$"
          },
          "percent": {
            "type": ["string", "number", "null"],
            "description": "From 0.01 to 100, such as `\"10\"`."
          }
        }
      },
      "InvoiceTaxInput": {
        "type": "object",
        "description": "Tax as a percentage, with its name.",
        "properties": {
          "percent": {
            "type": ["string", "number"],
            "description": "From 0 to 100 with up to two decimals, such as `\"8.25\"`."
          },
          "label": {
            "type": ["string", "null"],
            "description": "Its name on the invoice, such as `\"Sales tax\"` or `\"VAT\"`, up to 40 characters.",
            "maxLength": 40
          }
        },
        "required": ["percent"]
      },
      "CreateInvoice": {
        "type": "object",
        "description": "An invoice. Fields this schema doesn't name are refused with `400 unknown_field`, with the nearest field's name in the message.",
        "properties": {
          "customer": {
            "anyOf": [{"$ref": "#/components/schemas/InvoiceCustomerInput"}, {"type": "null"}],
            "description": "Who it's for. Issuing or sending needs a name and an email."
          },
          "currency": {"$ref": "#/components/schemas/CurrencyInput"},
          "lines": {
            "type": "array",
            "description": "What you're charging for, 1–50 lines. The total must be from 1.00 to 100,000.00.",
            "items": {"$ref": "#/components/schemas/InvoiceLineInput"},
            "minItems": 1,
            "maxItems": 50
          },
          "discount": {
            "anyOf": [{"$ref": "#/components/schemas/InvoiceDiscountInput"}, {"type": "null"}],
            "description": "Taken off the subtotal before tax; `null` for none."
          },
          "tax": {
            "anyOf": [{"$ref": "#/components/schemas/InvoiceTaxInput"}, {"type": "null"}],
            "description": "Tax on the subtotal less the discount; `null` for none."
          },
          "memo": {
            "type": ["string", "null"],
            "description": "A note to the customer, up to 1,000 characters.",
            "maxLength": 1000
          },
          "terms": {
            "type": ["string", "null"],
            "description": "Payment terms, up to 2,000 characters.",
            "maxLength": 2000
          },
          "reference": {
            "type": ["string", "null"],
            "description": "Your own id, such as a purchase order number, up to 64 characters.",
            "maxLength": 64
          },
          "due_date": {
            "type": ["string", "null"],
            "description": "When it's due, `YYYY-MM-DD`, from today to two years ahead. It's overdue after the end of that day everywhere. `null` for none.",
            "format": "date"
          },
          "allow_partial": {
            "type": "boolean",
            "description": "Let the customer pay in parts. Default `false`."
          },
          "min_payment": {
            "type": ["string", "null"],
            "description": "With `allow_partial`: the least first payment, a deposit, as a decimal string under the total.",
            "pattern": "^\\d{1,7}(\\.\\d{1,2})?$"
          },
          "allow_tip": {
            "type": "boolean",
            "description": "Let the customer add a tip. Tips never count toward the total. Default `false`."
          },
          "reminders": {
            "type": ["array", "null"],
            "description": "Days around the due date to email the customer a reminder (negative: before it), from -7, -3, -1, 0, 1, 3, 7, 14 and 30. Reminders need a due date. Default none.",
            "items": {"type": "integer", "enum": [-7, -3, -1, 0, 1, 3, 7, 14, 30]},
            "maxItems": 9
          },
          "email_receipts": {
            "type": ["boolean", "null"],
            "description": "Email the customer a receipt for each payment. Default `true`; `null` reads as the default."
          },
          "owner_id": {
            "type": ["string", "null"],
            "description": "Who on the team it belongs to: an owner, manager or salesperson's user id (`usr_…`, from an invoice's `owner`). Send `owner_id` or `owner_email`, not both.",
            "pattern": "^usr_[A-Za-z0-9]{1,64}$"
          },
          "owner_email": {
            "type": ["string", "null"],
            "description": "Who on the team it belongs to, by the email they sign in with."
          },
          "routing": {"$ref": "#/components/schemas/LinkRoutingInput"},
          "collect": {
            "anyOf": [{"$ref": "#/components/schemas/CollectInput"}, {"type": "null"}],
            "description": "What the customer's page asks for besides their email; `null` for nothing more."
          },
          "success_url": {
            "type": ["string", "null"],
            "description": "Where the customer lands once paid in full. Live mode needs a public `https://` page on your own site.",
            "maxLength": 2048,
            "format": "uri"
          },
          "payout_wallet_id": {
            "type": ["string", "null"],
            "description": "Pay one of the account's other saved wallets, `pw_…`, instead of its payout wallet (card only). Chosen before the invoice is issued.",
            "pattern": "^pw_"
          },
          "issue": {
            "type": "boolean",
            "description": "Issue it at once, so its `url` can be shared and paid. Default `false`: a draft."
          },
          "send": {
            "type": "boolean",
            "description": "Issue it and email it to the customer. A Test invoice's copy goes to the person behind the key or agent."
          },
          "message": {
            "type": ["string", "null"],
            "description": "With `send`: a few words shown above the invoice in the email, up to 1,000 characters.",
            "maxLength": 1000
          }
        },
        "required": ["currency", "lines"]
      },
      "UpdateInvoice": {
        "type": "object",
        "description": "The fields to change; the rest stay. Fields this schema doesn't name are refused with `400 unknown_field`.",
        "properties": {
          "customer": {
            "anyOf": [{"$ref": "#/components/schemas/InvoiceCustomerInput"}, {"type": "null"}],
            "description": "Who it's for. Issuing or sending needs a name and an email."
          },
          "currency": {"$ref": "#/components/schemas/CurrencyInput"},
          "lines": {
            "type": "array",
            "description": "What you're charging for, 1–50 lines. The total must be from 1.00 to 100,000.00.",
            "items": {"$ref": "#/components/schemas/InvoiceLineInput"},
            "minItems": 1,
            "maxItems": 50
          },
          "discount": {
            "anyOf": [{"$ref": "#/components/schemas/InvoiceDiscountInput"}, {"type": "null"}],
            "description": "Taken off the subtotal before tax; `null` for none."
          },
          "tax": {
            "anyOf": [{"$ref": "#/components/schemas/InvoiceTaxInput"}, {"type": "null"}],
            "description": "Tax on the subtotal less the discount; `null` for none."
          },
          "memo": {
            "type": ["string", "null"],
            "description": "A note to the customer, up to 1,000 characters.",
            "maxLength": 1000
          },
          "terms": {
            "type": ["string", "null"],
            "description": "Payment terms, up to 2,000 characters.",
            "maxLength": 2000
          },
          "reference": {
            "type": ["string", "null"],
            "description": "Your own id, such as a purchase order number, up to 64 characters.",
            "maxLength": 64
          },
          "due_date": {
            "type": ["string", "null"],
            "description": "When it's due, `YYYY-MM-DD`, from today to two years ahead. It's overdue after the end of that day everywhere. `null` for none.",
            "format": "date"
          },
          "allow_partial": {
            "type": "boolean",
            "description": "Let the customer pay in parts. Default `false`."
          },
          "min_payment": {
            "type": ["string", "null"],
            "description": "With `allow_partial`: the least first payment, a deposit, as a decimal string under the total.",
            "pattern": "^\\d{1,7}(\\.\\d{1,2})?$"
          },
          "allow_tip": {
            "type": "boolean",
            "description": "Let the customer add a tip. Tips never count toward the total. Default `false`."
          },
          "reminders": {
            "type": ["array", "null"],
            "description": "Days around the due date to email the customer a reminder (negative: before it), from -7, -3, -1, 0, 1, 3, 7, 14 and 30. Reminders need a due date. Default none.",
            "items": {"type": "integer", "enum": [-7, -3, -1, 0, 1, 3, 7, 14, 30]},
            "maxItems": 9
          },
          "email_receipts": {
            "type": ["boolean", "null"],
            "description": "Email the customer a receipt for each payment. Default `true`; `null` reads as the default."
          },
          "owner_id": {
            "type": ["string", "null"],
            "description": "Who on the team it belongs to: an owner, manager or salesperson's user id (`usr_…`, from an invoice's `owner`). Send `owner_id` or `owner_email`, not both.",
            "pattern": "^usr_[A-Za-z0-9]{1,64}$"
          },
          "owner_email": {
            "type": ["string", "null"],
            "description": "Who on the team it belongs to, by the email they sign in with."
          },
          "routing": {"$ref": "#/components/schemas/LinkRoutingInput"},
          "collect": {
            "anyOf": [{"$ref": "#/components/schemas/CollectInput"}, {"type": "null"}],
            "description": "What the customer's page asks for besides their email; `null` for nothing more."
          },
          "success_url": {
            "type": ["string", "null"],
            "description": "Where the customer lands once paid in full. Live mode needs a public `https://` page on your own site.",
            "maxLength": 2048,
            "format": "uri"
          },
          "payout_wallet_id": {
            "type": ["string", "null"],
            "description": "Pay one of the account's other saved wallets, `pw_…`, instead of its payout wallet (card only). Chosen before the invoice is issued.",
            "pattern": "^pw_"
          },
          "expected_version": {
            "type": ["integer", "null"],
            "description": "The `version` you read. An edit made since answers `409 invoice_changed`. Left out, or `null`, the edit isn't checked against a version.",
            "minimum": 0
          }
        }
      },
      "SendInvoice": {
        "type": "object",
        "description": "Optional.",
        "properties": {
          "message": {
            "type": ["string", "null"],
            "description": "A few words shown above the invoice in the email, up to 1,000 characters.",
            "maxLength": 1000
          }
        }
      },
      "VoidInvoice": {
        "type": "object",
        "description": "Optional.",
        "properties": {
          "reason": {
            "type": ["string", "null"],
            "description": "Why, for your records and the invoice's history, up to 200 characters. Never shown to the customer.",
            "maxLength": 200
          }
        }
      },
      "InvoiceLine": {
        "type": "object",
        "description": "One line of an invoice.",
        "properties": {
          "description": {"type": "string"},
          "quantity": {"type": "string", "description": "Such as `\"1\"` or `\"12.5\"`."},
          "unit_amount": {"$ref": "#/components/schemas/Money"},
          "amount": {
            "$ref": "#/components/schemas/Money",
            "description": "`quantity` × `unit_amount`, rounded to the cent."
          }
        },
        "required": ["description", "quantity", "unit_amount", "amount"]
      },
      "InvoiceCustomer": {
        "type": "object",
        "description": "Who the invoice is for, as it was issued.",
        "properties": {
          "id": {"type": ["string", "null"], "description": "The saved customer, `cus_…`, once there is one."},
          "name": {"type": ["string", "null"]},
          "email": {"type": ["string", "null"]},
          "company": {"type": ["string", "null"]},
          "phone": {"type": ["string", "null"]},
          "billing_address": {"anyOf": [{"$ref": "#/components/schemas/Address"}, {"type": "null"}]}
        },
        "required": ["id", "name", "email", "company", "phone", "billing_address"]
      },
      "InvoiceOwner": {
        "type": "object",
        "description": "The person on the team an invoice belongs to.",
        "properties": {
          "id": {"type": "string", "description": "Their user id, `usr_…`.", "pattern": "^usr_"},
          "name": {"type": ["string", "null"]},
          "email": {"type": "string"}
        },
        "required": ["id", "name", "email"]
      },
      "InvoiceEmail": {
        "type": "object",
        "description": "One email about an invoice.",
        "properties": {
          "id": {"type": "string", "pattern": "^iem_"},
          "object": {"type": "string", "const": "invoice_email"},
          "kind": {
            "type": "string",
            "enum": ["invoice", "reminder", "receipt"],
            "description": "The invoice itself, a reminder (any send after the first) or a payment's receipt."
          },
          "to": {"type": "string"},
          "test_copy": {
            "type": "boolean",
            "description": "A Test invoice's copy, sent to a person on the team instead of the customer."
          },
          "status": {
            "type": "string",
            "enum": ["pending", "sent", "failed"],
            "description": "`pending`: queued or being retried. `sent`: the mail service took it. `failed`: it won't be sent, and `error` says why."
          },
          "delivery": {
            "type": ["string", "null"],
            "description": "What the inbox said once it answered: `delivered`, `delayed`, `bounced`, `complained`, `suppressed` or `failed`."
          },
          "error": {"type": ["string", "null"]},
          "created": {"type": "integer", "minimum": 0},
          "sent_at": {"type": ["integer", "null"], "minimum": 0}
        },
        "required": [
          "id",
          "object",
          "kind",
          "to",
          "test_copy",
          "status",
          "delivery",
          "error",
          "created",
          "sent_at"
        ]
      },
      "Invoice": {
        "type": "object",
        "description": "An invoice. Money is a decimal string in the invoice's currency; times are Unix seconds.",
        "properties": {
          "id": {"type": "string", "description": "`in_…`.", "pattern": "^in_"},
          "object": {"type": "string", "const": "invoice"},
          "kind": {
            "type": "string",
            "enum": ["invoice", "link"],
            "description": "`invoice`: built as an invoice. `link`: a payment link, listed here too and changed with the payment links endpoints."
          },
          "number": {"type": "string", "description": "Such as `INV-0042`, counted per account and mode."},
          "status": {"$ref": "#/components/schemas/InvoiceStatus"},
          "livemode": {"type": "boolean"},
          "url": {
            "type": ["string", "null"],
            "description": "The customer's page, where they pay: send them this. `null` for a draft.",
            "format": "uri"
          },
          "pdf_url": {
            "type": ["string", "null"],
            "description": "The PDF the customer can download. `null` for a draft.",
            "format": "uri"
          },
          "currency": {"$ref": "#/components/schemas/Currency"},
          "lines": {"type": "array", "items": {"$ref": "#/components/schemas/InvoiceLine"}},
          "subtotal": {"$ref": "#/components/schemas/Money"},
          "discount": {"$ref": "#/components/schemas/Money"},
          "discount_percent": {
            "type": ["string", "null"],
            "description": "Set when the discount is a percentage, such as `\"10\"`."
          },
          "tax": {"$ref": "#/components/schemas/Money"},
          "tax_percent": {"type": ["string", "null"]},
          "tax_label": {"type": ["string", "null"]},
          "total": {"$ref": "#/components/schemas/Money"},
          "amount_paid": {
            "$ref": "#/components/schemas/Money",
            "description": "Paid toward the total. Tips never count."
          },
          "amount_due": {"$ref": "#/components/schemas/Money"},
          "tips": {"$ref": "#/components/schemas/Money"},
          "customer": {"$ref": "#/components/schemas/InvoiceCustomer"},
          "memo": {"type": ["string", "null"]},
          "terms": {"type": ["string", "null"]},
          "reference": {"type": ["string", "null"]},
          "due_date": {"type": ["string", "null"], "format": "date"},
          "allow_partial": {"type": "boolean"},
          "min_payment": {"anyOf": [{"$ref": "#/components/schemas/Money"}, {"type": "null"}]},
          "allow_tip": {"type": "boolean"},
          "reminders": {"type": ["array", "null"], "items": {"type": "integer"}},
          "email_receipts": {"type": "boolean"},
          "routing": {"$ref": "#/components/schemas/LinkRouting"},
          "collect": {"anyOf": [{"$ref": "#/components/schemas/Collect"}, {"type": "null"}]},
          "success_url": {"type": ["string", "null"]},
          "payout_wallet_id": {"type": ["string", "null"]},
          "payment_link_id": {
            "type": ["string", "null"],
            "description": "A link invoice's payment link, `pay_…`. `null` for an invoice."
          },
          "owner": {"anyOf": [{"$ref": "#/components/schemas/InvoiceOwner"}, {"type": "null"}]},
          "created_via": {
            "type": "string",
            "description": "Where it was made: `dashboard`, `api` or `mcp`. A payment link's invoice reads `link`, wherever the link was made."
          },
          "send_count": {"type": "integer", "minimum": 0},
          "view_count": {"type": "integer", "minimum": 0},
          "version": {
            "type": "integer",
            "description": "Goes up with every change. Send it back as `expected_version`.",
            "minimum": 0
          },
          "created": {"type": "integer", "minimum": 0},
          "updated": {"type": "integer", "minimum": 0},
          "issued_at": {"type": ["integer", "null"], "minimum": 0},
          "last_sent_at": {"type": ["integer", "null"], "minimum": 0},
          "viewed_at": {
            "type": ["integer", "null"],
            "minimum": 0,
            "description": "When its customer first opened it."
          },
          "paid_at": {"type": ["integer", "null"], "minimum": 0},
          "voided_at": {"type": ["integer", "null"], "minimum": 0},
          "void_reason": {"type": ["string", "null"]},
          "expires_at": {
            "type": ["integer", "null"],
            "minimum": 0,
            "description": "Payment links only: when it stops being payable."
          },
          "next_reminder_at": {"type": ["integer", "null"], "minimum": 0},
          "warnings": {
            "type": "array",
            "description": "Create and update only, and only when there is something to say about the card providers' minimums.",
            "items": {"$ref": "#/components/schemas/AmountWarning"}
          },
          "email": {
            "$ref": "#/components/schemas/InvoiceEmail",
            "description": "Create with `send`, and send: the email just queued."
          },
          "email_error": {
            "type": "object",
            "description": "Create with `send` only: the invoice was made and issued, but the email couldn't be queued. Fix the cause, then send it.",
            "properties": {"code": {"type": "string"}, "message": {"type": "string"}},
            "required": ["code", "message"]
          }
        },
        "required": [
          "id",
          "object",
          "kind",
          "number",
          "status",
          "livemode",
          "url",
          "pdf_url",
          "currency",
          "lines",
          "subtotal",
          "discount",
          "discount_percent",
          "tax",
          "tax_percent",
          "tax_label",
          "total",
          "amount_paid",
          "amount_due",
          "tips",
          "customer",
          "memo",
          "terms",
          "reference",
          "due_date",
          "allow_partial",
          "min_payment",
          "allow_tip",
          "reminders",
          "email_receipts",
          "routing",
          "collect",
          "success_url",
          "payout_wallet_id",
          "payment_link_id",
          "owner",
          "created_via",
          "send_count",
          "view_count",
          "version",
          "created",
          "updated",
          "issued_at",
          "last_sent_at",
          "viewed_at",
          "paid_at",
          "voided_at",
          "void_reason",
          "expires_at",
          "next_reminder_at"
        ]
      },
      "InvoiceList": {
        "type": "object",
        "description": "A page of invoices, newest first.",
        "properties": {
          "data": {"type": "array", "items": {"$ref": "#/components/schemas/Invoice"}},
          "has_more": {"type": "boolean"},
          "next_cursor": {
            "type": ["string", "null"],
            "description": "Pass as `starting_after` for the next page."
          }
        },
        "required": ["data", "has_more", "next_cursor"]
      },
      "DeletedInvoice": {
        "type": "object",
        "description": "A deleted draft.",
        "properties": {
          "id": {"type": "string"},
          "object": {"type": "string", "const": "invoice"},
          "deleted": {"type": "boolean", "const": true}
        },
        "required": ["id", "object", "deleted"]
      },
      "CreateCheckout": {
        "type": "object",
        "description": "A reusable checkout page.",
        "properties": {
          "kind": {
            "type": "string",
            "enum": ["page"],
            "description": "The only kind the API creates. Pricing tables and widgets are made in the dashboard."
          },
          "name": {"type": "string", "description": "Shown to buyers, up to 80 characters.", "maxLength": 80},
          "description": {
            "type": ["string", "null"],
            "description": "Up to 280 characters.",
            "maxLength": 280
          },
          "amount": {"$ref": "#/components/schemas/AmountInput"},
          "currency": {"$ref": "#/components/schemas/CurrencyInput"},
          "success_url": {
            "type": ["string", "null"],
            "description": "Where buyers land once paid. A public `https://` address in Live mode.",
            "maxLength": 1000
          },
          "theme": {"type": "string", "enum": ["light", "dark"], "description": "Default `light`."},
          "button_label": {
            "type": ["string", "null"],
            "description": "Up to 32 characters. Default \"Continue to pay {price}\".",
            "maxLength": 32
          },
          "crypto": {
            "type": "boolean",
            "description": "Let buyers pay in crypto when crypto payments are on for the account. Default `true`."
          },
          "routing": {"$ref": "#/components/schemas/RoutingInput"},
          "collect": {"anyOf": [{"$ref": "#/components/schemas/CollectInput"}, {"type": "null"}]}
        },
        "required": ["name", "amount", "currency"]
      },
      "PlanPrice": {
        "type": "object",
        "description": "A plan's price for one side of the switch.",
        "properties": {
          "amount": {"$ref": "#/components/schemas/Money"},
          "unit": {"type": ["string", "null"], "description": "Such as `month`."}
        },
        "required": ["amount", "unit"]
      },
      "Plan": {
        "type": "object",
        "description": "A pricing table's plan.",
        "properties": {
          "id": {"type": "string", "description": "The plan's id, stable across edits."},
          "name": {"type": "string", "description": "Its name."},
          "description": {"type": ["string", "null"]},
          "prices": {
            "type": "array",
            "description": "One price per switch option.",
            "items": {"$ref": "#/components/schemas/PlanPrice"}
          },
          "features": {"type": "array", "description": "What's included.", "items": {"type": "string"}},
          "recommended": {"type": "boolean", "description": "Whether the table highlights it."}
        },
        "required": ["id", "name", "description", "prices", "features", "recommended"]
      },
      "Checkout": {
        "type": "object",
        "description": "A reusable checkout. Every buyer who pays it gets their own payment.",
        "properties": {
          "id": {"type": "string", "description": "The checkout's id, `chk_…`.", "pattern": "^chk_"},
          "object": {"type": "string", "const": "checkout"},
          "kind": {
            "type": "string",
            "enum": ["page", "pricing_table", "widget"],
            "description": "What kind of checkout it is."
          },
          "slug": {
            "type": "string",
            "description": "What `<railbed-button checkout=\"…\">` and `<railbed-checkout checkout=\"…\">` take."
          },
          "url": {"type": "string", "description": "The hosted page.", "format": "uri"},
          "livemode": {"type": "boolean", "description": "`true` for Live, `false` for Test."},
          "active": {"type": "boolean", "description": "`false` once deleted."},
          "name": {"type": "string", "description": "Shown to buyers."},
          "description": {"type": ["string", "null"]},
          "amount": {
            "$ref": "#/components/schemas/Money",
            "description": "Pages and widgets: the price. Pricing tables: the lowest plan price."
          },
          "currency": {"$ref": "#/components/schemas/Currency"},
          "success_url": {"type": ["string", "null"], "description": "Where buyers land once paid."},
          "theme": {"type": "string", "enum": ["light", "dark"]},
          "button_label": {
            "type": ["string", "null"],
            "description": "The pay button's words, or `null` for the default."
          },
          "crypto": {"type": "boolean", "description": "Whether buyers may pay in crypto."},
          "routing": {"$ref": "#/components/schemas/Routing"},
          "collect": {"anyOf": [{"$ref": "#/components/schemas/Collect"}, {"type": "null"}]},
          "options": {
            "type": ["array", "null"],
            "description": "Pricing tables: the two sides of the switch, such as `[\"Monthly\", \"Yearly\"]`; `null` otherwise.",
            "items": {"type": "string"},
            "minItems": 2,
            "maxItems": 2
          },
          "plans": {
            "type": "array",
            "description": "Pricing tables: their plans. Empty for pages and widgets.",
            "items": {"$ref": "#/components/schemas/Plan"}
          },
          "created": {"type": "integer", "description": "When it was created. Unix seconds.", "minimum": 0},
          "updated": {"type": "integer", "description": "When it last changed. Unix seconds.", "minimum": 0},
          "warnings": {
            "type": "array",
            "description": "Only on create, and only when there is something to say about the card providers' minimums.",
            "items": {"$ref": "#/components/schemas/AmountWarning"}
          }
        },
        "required": [
          "id",
          "object",
          "kind",
          "slug",
          "url",
          "livemode",
          "active",
          "name",
          "description",
          "amount",
          "currency",
          "success_url",
          "theme",
          "button_label",
          "crypto",
          "routing",
          "collect",
          "options",
          "plans",
          "created",
          "updated"
        ]
      },
      "CheckoutList": {
        "type": "object",
        "description": "A page of checkouts.",
        "properties": {
          "data": {
            "type": "array",
            "description": "A page of checkouts, newest first.",
            "items": {"$ref": "#/components/schemas/Checkout"}
          },
          "has_more": {"type": "boolean", "description": "`true` when there are more after this page."},
          "next_cursor": {
            "type": ["string", "null"],
            "description": "Pass this as `starting_after` for the next page; `null` on the last page."
          }
        },
        "required": ["data", "has_more", "next_cursor"]
      },
      "OrderItem": {
        "type": "object",
        "description": "One line of an order.",
        "properties": {
          "name": {"type": "string"},
          "variant": {"type": ["string", "null"]},
          "sku": {"type": ["string", "null"]},
          "quantity": {"type": "integer", "minimum": 1},
          "unit_amount": {
            "anyOf": [{"$ref": "#/components/schemas/Money"}, {"type": "null"}],
            "description": "One unit's price, when sent."
          },
          "amount": {"$ref": "#/components/schemas/Money", "description": "The line's total."}
        },
        "required": ["name", "variant", "sku", "quantity", "unit_amount", "amount"]
      },
      "OrderStore": {
        "type": "object",
        "description": "Where a store order came from.",
        "properties": {
          "platform": {"type": "string", "enum": ["woocommerce", "shopify", "other"]},
          "id": {"type": "string", "description": "The store's id, as you sent it."},
          "name": {"type": ["string", "null"]},
          "url": {"type": ["string", "null"]},
          "order_id": {"type": "string", "description": "The order's id in the store."},
          "order_number": {"type": ["string", "null"], "description": "The number buyers see."},
          "order_url": {"type": ["string", "null"], "description": "The order's page in your admin."},
          "customer_id": {"type": ["string", "null"], "description": "The buyer's customer id in the store."}
        },
        "required": ["platform", "id", "name", "url", "order_id", "order_number", "order_url", "customer_id"]
      },
      "CustomFieldAnswer": {
        "type": "object",
        "description": "A buyer's answer to one of your questions.",
        "properties": {"key": {"type": "string"}, "label": {"type": "string"}, "value": {"type": "string"}},
        "required": ["key", "label", "value"]
      },
      "Order": {
        "type": "object",
        "description": "What was bought, where it ships and how it's going. Every session belongs to one.",
        "properties": {
          "id": {"type": "string", "description": "The order's id, `ord_…`.", "pattern": "^ord_"},
          "object": {"type": "string", "const": "order"},
          "livemode": {"type": "boolean", "description": "`true` for Live, `false` for Test."},
          "number": {
            "type": "integer",
            "description": "The Railbed order number, counting from 1001 in each mode."
          },
          "status": {
            "type": "string",
            "enum": ["open", "pending", "paid", "held", "failed", "expired", "canceled"],
            "description": "Derived from its payments: `paid` only when paid payments cover `total`."
          },
          "needs_review": {"type": "boolean", "description": "`true` when it's `held` and waiting on you."},
          "fulfillment": {"type": "string", "enum": ["none", "unfulfilled", "fulfilled"]},
          "fulfilled_at": {
            "type": ["integer", "null"],
            "description": "When it was marked `fulfilled`. Unix seconds; `null` until then.",
            "minimum": 0
          },
          "customer_id": {"type": ["string", "null"], "description": "Its customer, `cus_…`."},
          "currency": {"$ref": "#/components/schemas/Currency"},
          "subtotal": {"$ref": "#/components/schemas/Money", "description": "The items' amounts added up."},
          "discount": {"$ref": "#/components/schemas/Money"},
          "discount_code": {"type": ["string", "null"]},
          "shipping": {"$ref": "#/components/schemas/Money"},
          "shipping_method": {"type": ["string", "null"]},
          "tax": {"$ref": "#/components/schemas/Money"},
          "total": {
            "$ref": "#/components/schemas/Money",
            "description": "`subtotal` − `discount` + `shipping` + `tax`."
          },
          "amount_paid": {
            "$ref": "#/components/schemas/Money",
            "description": "What its paid payments in `currency` add up to."
          },
          "items": {
            "type": "array",
            "description": "Every line.",
            "items": {"$ref": "#/components/schemas/OrderItem"}
          },
          "shipping_address": {"anyOf": [{"$ref": "#/components/schemas/Address"}, {"type": "null"}]},
          "billing_address": {"anyOf": [{"$ref": "#/components/schemas/Address"}, {"type": "null"}]},
          "custom_fields": {
            "type": "array",
            "description": "The buyer's answers, in the order asked.",
            "items": {"$ref": "#/components/schemas/CustomFieldAnswer"}
          },
          "store": {
            "anyOf": [{"$ref": "#/components/schemas/OrderStore"}, {"type": "null"}],
            "description": "For orders sent with `order.id`."
          },
          "payment_ids": {
            "type": "array",
            "description": "Every attempt at paying, newest first.",
            "items": {"type": "string", "pattern": "^pay_"}
          },
          "created": {"type": "integer", "description": "When it was created. Unix seconds.", "minimum": 0},
          "paid_at": {
            "type": ["integer", "null"],
            "description": "When it became `paid`. Unix seconds; `null` until then.",
            "minimum": 0
          }
        },
        "required": [
          "id",
          "object",
          "livemode",
          "number",
          "status",
          "needs_review",
          "fulfillment",
          "fulfilled_at",
          "customer_id",
          "currency",
          "subtotal",
          "discount",
          "discount_code",
          "shipping",
          "shipping_method",
          "tax",
          "total",
          "amount_paid",
          "items",
          "shipping_address",
          "billing_address",
          "custom_fields",
          "store",
          "payment_ids",
          "created",
          "paid_at"
        ]
      },
      "OrderList": {
        "type": "object",
        "description": "A page of orders.",
        "properties": {
          "data": {
            "type": "array",
            "description": "A page of orders, newest first.",
            "items": {"$ref": "#/components/schemas/Order"}
          },
          "has_more": {"type": "boolean", "description": "`true` when there are more after this page."},
          "next_cursor": {
            "type": ["string", "null"],
            "description": "Pass this as `starting_after` for the next page; `null` on the last page."
          }
        },
        "required": ["data", "has_more", "next_cursor"]
      },
      "UpdateOrder": {
        "type": "object",
        "description": "How a store reports fulfilment.",
        "properties": {
          "fulfillment": {
            "type": "string",
            "enum": ["none", "unfulfilled", "fulfilled"],
            "description": "The order's fulfilment."
          }
        },
        "required": ["fulfillment"]
      },
      "CreateOrderEvent": {
        "type": "object",
        "description": "Timeline only: it never changes the order's status, its payments or any money.",
        "properties": {
          "type": {"type": "string", "enum": ["canceled", "refunded"], "description": "What your store did."},
          "id": {
            "type": "string",
            "description": "Your store's own id for this event: 1 to 64 printable characters without spaces. The same id is recorded once.",
            "pattern": "^[\\x21-\\x7e]{1,64}$"
          },
          "amount": {
            "type": ["string", "null"],
            "description": "`refunded` only, optional: the refunded amount in the order's currency, from `\"0.01\"` up to its `total`.",
            "pattern": "^\\d{1,7}(\\.\\d{1,2})?$"
          }
        },
        "required": ["type", "id"]
      },
      "OrderEvent": {
        "type": "object",
        "description": "A cancellation or refund on an order's timeline.",
        "properties": {
          "id": {"type": "string", "description": "The event's id, `oev_…`.", "pattern": "^oev_"},
          "object": {"type": "string", "const": "order_event"},
          "order_id": {"type": "string"},
          "type": {"type": "string", "enum": ["canceled", "refunded"]},
          "store_event_id": {"type": "string", "description": "Your store's id for it."},
          "amount": {"type": ["string", "null"], "description": "The refunded amount, when sent."},
          "currency": {"type": ["string", "null"], "description": "The amount's currency, when sent."},
          "created": {"type": "integer", "description": "When it was recorded. Unix seconds.", "minimum": 0}
        },
        "required": ["id", "object", "order_id", "type", "store_event_id", "amount", "currency", "created"]
      },
      "StoreAccount": {
        "type": "object",
        "description": "A buyer's account in one of your stores.",
        "properties": {
          "platform": {"type": "string", "enum": ["woocommerce", "shopify", "other"]},
          "store_id": {"type": "string"},
          "store_name": {"type": ["string", "null"]},
          "customer_id": {"type": "string", "description": "Their customer id in that store."}
        },
        "required": ["platform", "store_id", "store_name", "customer_id"]
      },
      "Customer": {
        "type": "object",
        "description": "One buyer, by email, in one mode.",
        "properties": {
          "id": {"type": "string", "description": "The customer's id, `cus_…`.", "pattern": "^cus_"},
          "object": {"type": "string", "const": "customer"},
          "livemode": {"type": "boolean", "description": "`true` for Live, `false` for Test."},
          "email": {
            "type": ["string", "null"],
            "description": "Their email, lowercased. `null` once you've deleted their details."
          },
          "name": {"type": ["string", "null"]},
          "phone": {"type": ["string", "null"]},
          "date_of_birth": {
            "type": ["string", "null"],
            "description": "`YYYY-MM-DD`, self-declared.",
            "format": "date"
          },
          "accepts_marketing": {"type": "boolean", "description": "`true` once they joined your email list."},
          "accepts_marketing_updated_at": {
            "type": ["integer", "null"],
            "description": "When that last changed. Unix seconds; `null` until then.",
            "minimum": 0
          },
          "shipping_address": {"anyOf": [{"$ref": "#/components/schemas/Address"}, {"type": "null"}]},
          "billing_address": {"anyOf": [{"$ref": "#/components/schemas/Address"}, {"type": "null"}]},
          "store_accounts": {
            "type": "array",
            "description": "Their customer ids in your stores.",
            "items": {"$ref": "#/components/schemas/StoreAccount"}
          },
          "orders_count": {"type": "integer", "description": "How many orders they have.", "minimum": 0},
          "paid_orders_count": {"type": "integer", "description": "How many of them are paid.", "minimum": 0},
          "spent": {
            "type": "object",
            "description": "What their paid payments add up to, per currency.",
            "additionalProperties": {"$ref": "#/components/schemas/Money"}
          },
          "created": {
            "type": "integer",
            "description": "When they first appeared. Unix seconds.",
            "minimum": 0
          },
          "last_order_at": {
            "type": ["integer", "null"],
            "description": "When their latest order was made. Unix seconds; `null` until then.",
            "minimum": 0
          },
          "erased": {"type": "boolean", "description": "`true` once you've deleted their details."}
        },
        "required": [
          "id",
          "object",
          "livemode",
          "email",
          "name",
          "phone",
          "date_of_birth",
          "accepts_marketing",
          "accepts_marketing_updated_at",
          "shipping_address",
          "billing_address",
          "store_accounts",
          "orders_count",
          "paid_orders_count",
          "spent",
          "created",
          "last_order_at",
          "erased"
        ]
      },
      "CustomerList": {
        "type": "object",
        "description": "A page of customers.",
        "properties": {
          "data": {
            "type": "array",
            "description": "A page of customers, newest first.",
            "items": {"$ref": "#/components/schemas/Customer"}
          },
          "has_more": {"type": "boolean", "description": "`true` when there are more after this page."},
          "next_cursor": {
            "type": ["string", "null"],
            "description": "Pass this as `starting_after` for the next page; `null` on the last page."
          }
        },
        "required": ["data", "has_more", "next_cursor"]
      },
      "WebhookEventType": {
        "type": "string",
        "enum": [
          "payment.started",
          "payment.paid",
          "payment.held",
          "payment.updated",
          "payment.failed",
          "payment.expired",
          "payment.canceled",
          "invoice.issued",
          "invoice.sent",
          "invoice.viewed",
          "invoice.partially_paid",
          "invoice.paid",
          "invoice.voided"
        ],
        "description": "A webhook event type."
      },
      "CreateWebhookEndpoint": {
        "type": "object",
        "description": "Up to 10 endpoints per mode.",
        "properties": {
          "url": {
            "type": "string",
            "description": "A full `https://` address, up to 2,048 characters; on the public internet in Live mode. Test mode also allows `http://localhost`.",
            "maxLength": 2048,
            "format": "uri"
          },
          "events": {
            "type": "array",
            "description": "The events to receive. Default: every `payment.*` event. Invoice events go only to an endpoint that names them.",
            "items": {"$ref": "#/components/schemas/WebhookEventType"},
            "minItems": 1
          },
          "description": {
            "type": ["string", "null"],
            "description": "Your label, up to 80 characters.",
            "maxLength": 80
          }
        },
        "required": ["url"]
      },
      "UpdateWebhookEndpoint": {
        "type": "object",
        "description": "Only the fields you send change.",
        "properties": {
          "events": {
            "type": ["array", "null"],
            "description": "The events to receive from now on, replacing the list it has. Events already queued for it still arrive.",
            "items": {"$ref": "#/components/schemas/WebhookEventType"},
            "minItems": 1
          },
          "description": {
            "type": ["string", "null"],
            "description": "Your label, up to 80 characters. `null` clears it.",
            "maxLength": 80
          }
        }
      },
      "WebhookEndpoint": {
        "type": "object",
        "description": "An address that receives signed events.",
        "properties": {
          "id": {"type": "string", "description": "The endpoint's id, `we_…`.", "pattern": "^we_"},
          "object": {"type": "string", "const": "webhook_endpoint"},
          "url": {"type": "string", "description": "Where deliveries go.", "format": "uri"},
          "description": {"type": ["string", "null"], "description": "Your label."},
          "events": {
            "type": "array",
            "description": "The events it receives.",
            "items": {"$ref": "#/components/schemas/WebhookEventType"}
          },
          "livemode": {"type": "boolean", "description": "`true` for Live, `false` for Test."},
          "mode": {"type": "string", "enum": ["test", "live"]},
          "previous_secret_expires_at": {
            "type": ["integer", "null"],
            "description": "While a rolled secret's 24-hour overlap lasts, deliveries carry two `v1` signatures until this time. Unix seconds; `null` until then.",
            "minimum": 0
          },
          "created": {"type": "integer", "description": "When it was added. Unix seconds.", "minimum": 0}
        },
        "required": [
          "id",
          "object",
          "url",
          "description",
          "events",
          "livemode",
          "mode",
          "previous_secret_expires_at",
          "created"
        ]
      },
      "CreatedWebhookEndpoint": {
        "type": "object",
        "description": "A new endpoint, with its signing secret.",
        "properties": {
          "id": {"type": "string", "description": "The endpoint's id, `we_…`.", "pattern": "^we_"},
          "object": {"type": "string", "const": "webhook_endpoint"},
          "url": {"type": "string", "description": "Where deliveries go.", "format": "uri"},
          "description": {"type": ["string", "null"], "description": "Your label."},
          "events": {
            "type": "array",
            "description": "The events it receives.",
            "items": {"$ref": "#/components/schemas/WebhookEventType"}
          },
          "livemode": {"type": "boolean", "description": "`true` for Live, `false` for Test."},
          "mode": {"type": "string", "enum": ["test", "live"]},
          "previous_secret_expires_at": {
            "type": ["integer", "null"],
            "description": "While a rolled secret's 24-hour overlap lasts, deliveries carry two `v1` signatures until this time. Unix seconds; `null` until then.",
            "minimum": 0
          },
          "created": {"type": "integer", "description": "When it was added. Unix seconds.", "minimum": 0},
          "secret": {
            "type": "string",
            "description": "The signing secret, `whsec_…`, shown in this response only. Store it as a secret.",
            "pattern": "^whsec_"
          }
        },
        "required": [
          "id",
          "object",
          "url",
          "description",
          "events",
          "livemode",
          "mode",
          "previous_secret_expires_at",
          "created",
          "secret"
        ]
      },
      "WebhookEndpointList": {
        "type": "object",
        "description": "A page of webhook endpoints.",
        "properties": {
          "data": {
            "type": "array",
            "description": "A page of webhook endpoints, newest first.",
            "items": {"$ref": "#/components/schemas/WebhookEndpoint"}
          },
          "has_more": {"type": "boolean", "description": "`true` when there are more after this page."},
          "next_cursor": {
            "type": ["string", "null"],
            "description": "Pass this as `starting_after` for the next page; `null` on the last page."
          }
        },
        "required": ["data", "has_more", "next_cursor"]
      },
      "DeletedWebhookEndpoint": {
        "type": "object",
        "description": "A removed endpoint.",
        "properties": {
          "id": {"type": "string"},
          "object": {"type": "string", "const": "webhook_endpoint"},
          "deleted": {"type": "boolean", "const": true}
        },
        "required": ["id", "object", "deleted"]
      },
      "WebhookAddress": {
        "type": "object",
        "description": "A postal address in a webhook payload.",
        "properties": {
          "name": {"type": ["string", "null"]},
          "line1": {"type": ["string", "null"]},
          "line2": {"type": ["string", "null"]},
          "city": {"type": ["string", "null"]},
          "region": {"type": ["string", "null"]},
          "postalCode": {"type": ["string", "null"]},
          "country": {"type": ["string", "null"]}
        },
        "required": ["name", "line1", "line2", "city", "region", "postalCode", "country"]
      },
      "WebhookPayment": {
        "type": "object",
        "description": "The payment in a webhook event: camelCase, with millisecond timestamps.",
        "properties": {
          "id": {"type": "string", "description": "The payment's id, `pay_…`.", "pattern": "^pay_"},
          "mode": {"type": "string", "enum": ["live", "test"]},
          "source": {
            "type": "string",
            "enum": ["api", "checkout", "payment_link"],
            "description": "Where it came from."
          },
          "checkoutId": {"type": ["string", "null"], "description": "The checkout it came from, `chk_…`."},
          "planLabel": {
            "type": ["string", "null"],
            "description": "Pricing tables: the plan and price chosen."
          },
          "description": {"type": "string"},
          "reference": {"type": ["string", "null"], "description": "Your reference."},
          "customerEmail": {
            "type": ["string", "null"],
            "description": "The email the buyer entered. Don't use it to identify an account."
          },
          "amount": {"$ref": "#/components/schemas/Money"},
          "currency": {"$ref": "#/components/schemas/Currency"},
          "status": {"$ref": "#/components/schemas/PaymentStatus"},
          "provider": {
            "type": ["string", "null"],
            "description": "The card provider the buyer chose; `null` for crypto."
          },
          "providerName": {
            "type": ["string", "null"],
            "description": "Its display name, or the coin and network for crypto."
          },
          "depositAddress": {
            "type": ["string", "null"],
            "description": "The one-time address this payment is paid into."
          },
          "payoutWallet": {
            "type": ["string", "null"],
            "description": "Your wallet the payment is forwarded to."
          },
          "feeBps": {
            "type": "integer",
            "description": "The Railbed fee locked into this payment, in basis points of what arrives.",
            "minimum": 0
          },
          "valueCoin": {"type": ["string", "null"], "description": "How much arrived, in `coin`."},
          "merchantReceived": {
            "type": ["string", "null"],
            "description": "How much was forwarded to your wallet, in `coin`. `null` until reported."
          },
          "receivedUsd": {
            "type": ["string", "null"],
            "description": "The same share in US dollars. `null` until reported."
          },
          "coin": {"type": ["string", "null"], "description": "What arrived, such as `polygon_usdc`."},
          "holdReason": {"type": ["string", "null"], "description": "Why it's held."},
          "holdAcceptable": {
            "type": "boolean",
            "description": "For a held payment: whether you can accept it as paid."
          },
          "txidIn": {"type": ["string", "null"], "description": "The transaction that delivered the money."},
          "txidOut": {"type": ["string", "null"], "description": "The transaction that forwarded it to you."},
          "metadata": {"$ref": "#/components/schemas/Metadata"},
          "customerName": {"type": ["string", "null"], "description": "Payment links: who it's for."},
          "memo": {"type": ["string", "null"], "description": "Payment links: the note to the payer."},
          "trackingUrl": {
            "type": ["string", "null"],
            "description": "Payment links: the read-only tracking page."
          },
          "canceledAt": {
            "type": ["integer", "null"],
            "description": "When it was canceled. Unix milliseconds.",
            "minimum": 0
          },
          "successUrl": {
            "type": ["string", "null"],
            "description": "The success URL as you set it, placeholders left in."
          },
          "createdAt": {
            "type": "integer",
            "description": "When it was created. Unix milliseconds.",
            "minimum": 0
          },
          "paidAt": {
            "type": ["integer", "null"],
            "description": "When it became `paid`. Unix milliseconds.",
            "minimum": 0
          },
          "expiresAt": {
            "type": "integer",
            "description": "When an unpaid payment expires. Unix milliseconds.",
            "minimum": 0
          },
          "url": {"type": "string", "description": "The hosted checkout page.", "format": "uri"},
          "orderId": {"type": ["string", "null"], "description": "Its order, `ord_…`."},
          "method": {"type": "string", "enum": ["card", "crypto"]},
          "network": {
            "type": ["string", "null"],
            "description": "Crypto payments: the network the money arrived on. `null` for card.",
            "enum": ["polygon", "base", "arbitrum", "optimism", "bep20", "erc20", null]
          },
          "invoiceId": {
            "type": ["string", "null"],
            "description": "The invoice it pays toward, `in_…`, or `null`."
          },
          "tip": {
            "$ref": "#/components/schemas/Money",
            "description": "The part of `amount` the buyer added as a tip on an invoice, `\"0.00\"` without one."
          }
        },
        "required": [
          "id",
          "mode",
          "source",
          "checkoutId",
          "planLabel",
          "description",
          "reference",
          "customerEmail",
          "amount",
          "currency",
          "status",
          "provider",
          "providerName",
          "depositAddress",
          "payoutWallet",
          "feeBps",
          "valueCoin",
          "merchantReceived",
          "receivedUsd",
          "coin",
          "holdReason",
          "holdAcceptable",
          "txidIn",
          "txidOut",
          "metadata",
          "customerName",
          "memo",
          "trackingUrl",
          "canceledAt",
          "successUrl",
          "createdAt",
          "paidAt",
          "expiresAt",
          "url",
          "orderId",
          "method",
          "network",
          "invoiceId",
          "tip"
        ]
      },
      "WebhookOrderStore": {
        "type": "object",
        "description": "Where a store order came from.",
        "properties": {
          "platform": {"type": "string", "enum": ["woocommerce", "shopify", "other"]},
          "id": {"type": "string"},
          "name": {"type": ["string", "null"]},
          "url": {"type": ["string", "null"]},
          "orderId": {"type": "string"},
          "orderNumber": {"type": ["string", "null"]},
          "orderUrl": {"type": ["string", "null"]},
          "customerId": {"type": ["string", "null"]}
        },
        "required": ["platform", "id", "name", "url", "orderId", "orderNumber", "orderUrl", "customerId"]
      },
      "WebhookCustomerRef": {
        "type": "object",
        "description": "The order's customer at a glance.",
        "properties": {
          "id": {"type": "string"},
          "email": {"type": ["string", "null"]},
          "name": {"type": ["string", "null"]},
          "erased": {"type": "boolean"}
        },
        "required": ["id", "email", "name", "erased"]
      },
      "WebhookOrderItem": {
        "type": "object",
        "description": "One line of the order.",
        "properties": {
          "name": {"type": "string"},
          "variant": {"type": ["string", "null"]},
          "sku": {"type": ["string", "null"]},
          "quantity": {"type": "integer", "minimum": 1},
          "unitAmount": {"anyOf": [{"$ref": "#/components/schemas/Money"}, {"type": "null"}]},
          "amount": {"$ref": "#/components/schemas/Money"}
        },
        "required": ["name", "variant", "sku", "quantity", "unitAmount", "amount"]
      },
      "WebhookOrder": {
        "type": "object",
        "description": "The payment's order in a webhook event.",
        "properties": {
          "id": {"type": "string", "description": "The order's id, `ord_…`.", "pattern": "^ord_"},
          "mode": {"type": "string", "enum": ["live", "test"]},
          "number": {"type": "integer", "description": "The Railbed order number."},
          "displayNumber": {"type": "string", "description": "The number to show people, such as `#1042`."},
          "source": {"type": "string", "enum": ["api", "checkout", "payment_link"]},
          "checkoutId": {"type": ["string", "null"]},
          "store": {"anyOf": [{"$ref": "#/components/schemas/WebhookOrderStore"}, {"type": "null"}]},
          "status": {
            "type": "string",
            "enum": ["open", "pending", "paid", "held", "failed", "expired", "canceled"],
            "description": "The order's status, including this event."
          },
          "needsReview": {"type": "boolean"},
          "reviewReason": {
            "type": ["string", "null"],
            "description": "Why the order needs you when its payments don't say."
          },
          "fulfillment": {"type": "string", "enum": ["none", "unfulfilled", "fulfilled"]},
          "fulfilledAt": {
            "type": ["integer", "null"],
            "description": "When it was marked `fulfilled`. Unix milliseconds.",
            "minimum": 0
          },
          "customer": {"anyOf": [{"$ref": "#/components/schemas/WebhookCustomerRef"}, {"type": "null"}]},
          "summary": {"type": "string", "description": "The first item and how many more lines."},
          "lineCount": {"type": "integer", "minimum": 0},
          "unitCount": {"type": "integer", "minimum": 0},
          "currency": {"$ref": "#/components/schemas/Currency"},
          "subtotal": {"$ref": "#/components/schemas/Money"},
          "discount": {"$ref": "#/components/schemas/Money"},
          "discountCode": {"type": ["string", "null"]},
          "shipping": {"$ref": "#/components/schemas/Money"},
          "shippingMethod": {"type": ["string", "null"]},
          "tax": {"$ref": "#/components/schemas/Money"},
          "total": {"$ref": "#/components/schemas/Money"},
          "amountPaid": {"$ref": "#/components/schemas/Money"},
          "received": {
            "type": ["string", "null"],
            "description": "USDC that reached your wallet from its paid payments. `null` until reported."
          },
          "shipTo": {"anyOf": [{"$ref": "#/components/schemas/WebhookAddress"}, {"type": "null"}]},
          "billTo": {"anyOf": [{"$ref": "#/components/schemas/WebhookAddress"}, {"type": "null"}]},
          "customFields": {
            "type": "array",
            "description": "The buyer's answers, in the order asked.",
            "items": {"$ref": "#/components/schemas/CustomFieldAnswer"}
          },
          "reference": {"type": ["string", "null"]},
          "paymentId": {"type": ["string", "null"], "description": "The payment that decides its status."},
          "attemptCount": {"type": "integer", "minimum": 0},
          "createdAt": {
            "type": "integer",
            "description": "When it was created. Unix milliseconds.",
            "minimum": 0
          },
          "updatedAt": {
            "type": "integer",
            "description": "When it last changed. Unix milliseconds.",
            "minimum": 0
          },
          "paidAt": {
            "type": ["integer", "null"],
            "description": "When it became `paid`. Unix milliseconds.",
            "minimum": 0
          },
          "items": {
            "type": "array",
            "description": "The first 50 lines; `lineCount` says how many there are.",
            "items": {"$ref": "#/components/schemas/WebhookOrderItem"}
          }
        },
        "required": [
          "id",
          "mode",
          "number",
          "displayNumber",
          "source",
          "checkoutId",
          "store",
          "status",
          "needsReview",
          "fulfillment",
          "fulfilledAt",
          "customer",
          "summary",
          "lineCount",
          "unitCount",
          "currency",
          "subtotal",
          "discount",
          "discountCode",
          "shipping",
          "shippingMethod",
          "tax",
          "total",
          "amountPaid",
          "received",
          "shipTo",
          "billTo",
          "customFields",
          "reference",
          "paymentId",
          "attemptCount",
          "createdAt",
          "updatedAt",
          "paidAt",
          "items"
        ]
      },
      "WebhookStoreAccount": {
        "type": "object",
        "properties": {
          "platform": {"type": "string", "enum": ["woocommerce", "shopify", "other"]},
          "storeId": {"type": "string"},
          "storeName": {"type": ["string", "null"]},
          "customerId": {"type": "string"}
        },
        "required": ["platform", "storeId", "storeName", "customerId"]
      },
      "WebhookCustomer": {
        "type": "object",
        "description": "The order's customer in a webhook event: contact details only.",
        "properties": {
          "id": {"type": "string", "description": "The customer's id, `cus_…`.", "pattern": "^cus_"},
          "mode": {"type": "string", "enum": ["live", "test"]},
          "email": {"type": ["string", "null"]},
          "name": {"type": ["string", "null"]},
          "phone": {"type": ["string", "null"]},
          "birthDate": {"type": ["string", "null"], "description": "`YYYY-MM-DD`, self-declared."},
          "acceptsMarketing": {"type": "boolean"},
          "acceptsMarketingUpdatedAt": {
            "type": ["integer", "null"],
            "description": "When that last changed. Unix milliseconds.",
            "minimum": 0
          },
          "location": {"type": ["string", "null"], "description": "Such as `Portland, OR, US`."},
          "shipTo": {"anyOf": [{"$ref": "#/components/schemas/WebhookAddress"}, {"type": "null"}]},
          "billTo": {"anyOf": [{"$ref": "#/components/schemas/WebhookAddress"}, {"type": "null"}]},
          "storeAccounts": {"type": "array", "items": {"$ref": "#/components/schemas/WebhookStoreAccount"}},
          "firstSeenAt": {
            "type": "integer",
            "description": "When they first appeared. Unix milliseconds.",
            "minimum": 0
          },
          "erased": {"type": "boolean"}
        },
        "required": [
          "id",
          "mode",
          "email",
          "name",
          "phone",
          "birthDate",
          "acceptsMarketing",
          "acceptsMarketingUpdatedAt",
          "location",
          "shipTo",
          "billTo",
          "storeAccounts",
          "firstSeenAt",
          "erased"
        ]
      },
      "WebhookInvoice": {
        "type": "object",
        "description": "The invoice in an `invoice.*` event, as the change left it. Lines, terms and settings come from GET /v1/invoices/{id}. Times are Unix milliseconds, as in the other webhook objects.",
        "properties": {
          "id": {"type": "string", "pattern": "^in_"},
          "mode": {"type": "string", "enum": ["live", "test"]},
          "kind": {
            "type": "string",
            "enum": ["invoice", "link"],
            "description": "Always `invoice`: a payment link's story is its payment's events."
          },
          "number": {"type": "string"},
          "status": {"$ref": "#/components/schemas/InvoiceStatus"},
          "currency": {"type": "string"},
          "total": {"$ref": "#/components/schemas/Money"},
          "amountPaid": {
            "$ref": "#/components/schemas/Money",
            "description": "Paid toward the total. Tips never count."
          },
          "amountDue": {"$ref": "#/components/schemas/Money"},
          "tips": {"$ref": "#/components/schemas/Money"},
          "customer": {
            "type": "object",
            "properties": {
              "id": {"type": ["string", "null"]},
              "name": {"type": ["string", "null"]},
              "email": {"type": ["string", "null"]},
              "company": {"type": ["string", "null"]}
            },
            "required": ["id", "name", "email", "company"]
          },
          "reference": {"type": ["string", "null"]},
          "dueDate": {"type": ["string", "null"], "format": "date"},
          "issuedAt": {"type": ["integer", "null"], "minimum": 0},
          "lastSentAt": {"type": ["integer", "null"], "minimum": 0},
          "sendCount": {"type": "integer", "minimum": 0},
          "viewedAt": {"type": ["integer", "null"], "minimum": 0},
          "paidAt": {"type": ["integer", "null"], "minimum": 0},
          "voidedAt": {"type": ["integer", "null"], "minimum": 0},
          "url": {"type": ["string", "null"], "format": "uri"},
          "pdfUrl": {"type": ["string", "null"], "format": "uri"},
          "createdAt": {"type": "integer", "minimum": 0}
        },
        "required": [
          "id",
          "mode",
          "kind",
          "number",
          "status",
          "currency",
          "total",
          "amountPaid",
          "amountDue",
          "tips",
          "customer",
          "reference",
          "dueDate",
          "issuedAt",
          "lastSentAt",
          "sendCount",
          "viewedAt",
          "paidAt",
          "voidedAt",
          "url",
          "pdfUrl",
          "createdAt"
        ]
      },
      "WebhookEvent": {
        "type": "object",
        "description": "The body of every webhook delivery.",
        "properties": {
          "id": {
            "type": "string",
            "description": "The event's id, `evt_…`. The same on every attempt and resend: deduplicate on it.",
            "pattern": "^evt_"
          },
          "type": {
            "type": "string",
            "enum": [
              "payment.started",
              "payment.paid",
              "payment.held",
              "payment.updated",
              "payment.failed",
              "payment.expired",
              "payment.canceled",
              "invoice.issued",
              "invoice.sent",
              "invoice.viewed",
              "invoice.partially_paid",
              "invoice.paid",
              "invoice.voided",
              "ping"
            ],
            "description": "The event type. Acknowledge types you don't handle and ignore them."
          },
          "created": {
            "type": "integer",
            "description": "When the event happened. Unix seconds.",
            "minimum": 0
          },
          "livemode": {"type": "boolean", "description": "`true` for Live events."},
          "data": {
            "type": "object",
            "properties": {
              "payment": {
                "anyOf": [{"$ref": "#/components/schemas/WebhookPayment"}, {"type": "null"}],
                "description": "The payment as it was when the event happened. For `invoice.partially_paid` and `invoice.paid`, the payment that landed; `null` for the other invoice events and `ping`."
              },
              "order": {
                "anyOf": [{"$ref": "#/components/schemas/WebhookOrder"}, {"type": "null"}],
                "description": "The payment's order, as this event leaves it. `null` for invoice events and `ping`."
              },
              "customer": {
                "anyOf": [{"$ref": "#/components/schemas/WebhookCustomer"}, {"type": "null"}],
                "description": "The order's customer. `null` for invoice events, `ping`, and until the buyer has given an email."
              },
              "invoice": {
                "anyOf": [{"$ref": "#/components/schemas/WebhookInvoice"}, {"type": "null"}],
                "description": "The invoice, for `invoice.*` events. `null` for payment events and `ping`: a payment's `invoiceId` names its invoice."
              }
            },
            "required": ["payment", "order", "customer", "invoice"]
          }
        },
        "required": ["id", "type", "created", "livemode", "data"]
      }
    },
    "parameters": {
      "Limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "How many to return, 1–100. Anything else is `400 invalid_limit`.",
        "schema": {"type": "integer", "minimum": 1, "maximum": 100, "default": 20}
      },
      "PaymentCursor": {
        "name": "starting_after",
        "in": "query",
        "required": false,
        "description": "The `next_cursor` of the previous page: a payment id from this list, in this mode. Anything else is `400 invalid_cursor`.",
        "schema": {"type": "string", "pattern": "^pay_[A-Za-z0-9_-]{1,64}$"}
      },
      "PaymentLinkCursor": {
        "name": "starting_after",
        "in": "query",
        "required": false,
        "description": "The `next_cursor` of the previous page: a payment link id from this list, in this mode. Anything else is `400 invalid_cursor`.",
        "schema": {"type": "string", "pattern": "^pay_[A-Za-z0-9_-]{1,64}$"}
      },
      "CheckoutCursor": {
        "name": "starting_after",
        "in": "query",
        "required": false,
        "description": "The `next_cursor` of the previous page: a checkout id from this list, in this mode. Anything else is `400 invalid_cursor`.",
        "schema": {"type": "string", "pattern": "^chk_[A-Za-z0-9_-]{1,64}$"}
      },
      "OrderCursor": {
        "name": "starting_after",
        "in": "query",
        "required": false,
        "description": "The `next_cursor` of the previous page: an order id from this list, in this mode. Anything else is `400 invalid_cursor`.",
        "schema": {"type": "string", "pattern": "^ord_[A-Za-z0-9_-]{1,64}$"}
      },
      "CustomerCursor": {
        "name": "starting_after",
        "in": "query",
        "required": false,
        "description": "The `next_cursor` of the previous page: a customer id from this list, in this mode. Anything else is `400 invalid_cursor`.",
        "schema": {"type": "string", "pattern": "^cus_[A-Za-z0-9_-]{1,64}$"}
      },
      "WebhookEndpointCursor": {
        "name": "starting_after",
        "in": "query",
        "required": false,
        "description": "The `next_cursor` of the previous page: a webhook endpoint id from this list, in this mode. Anything else is `400 invalid_cursor`.",
        "schema": {"type": "string", "pattern": "^we_[A-Za-z0-9_-]{1,64}$"}
      },
      "StatusFilter": {
        "name": "status",
        "in": "query",
        "required": false,
        "description": "Only this status.",
        "schema": {"$ref": "#/components/schemas/PaymentStatus"}
      },
      "ReferenceFilter": {
        "name": "reference",
        "in": "query",
        "required": false,
        "description": "Only this `reference`, up to 120 characters.",
        "schema": {"type": "string", "maxLength": 120}
      },
      "CreatedGte": {
        "name": "created_gte",
        "in": "query",
        "required": false,
        "description": "Created at or after this time, in Unix seconds.",
        "schema": {"type": "integer", "minimum": 0}
      },
      "CreatedLte": {
        "name": "created_lte",
        "in": "query",
        "required": false,
        "description": "Created at or before this time, in Unix seconds. Not before `created_gte` (`400 invalid_dates`).",
        "schema": {"type": "integer", "minimum": 0}
      },
      "DueDateGte": {
        "name": "due_date_gte",
        "in": "query",
        "required": false,
        "description": "Due on or after this date. An invoice with no due date never matches.",
        "schema": {"type": "string", "format": "date"}
      },
      "DueDateLte": {
        "name": "due_date_lte",
        "in": "query",
        "required": false,
        "description": "Due on or before this date. Not before `due_date_gte` (`400 invalid_dates`).",
        "schema": {"type": "string", "format": "date"}
      },
      "OrderStatusFilter": {
        "name": "status",
        "in": "query",
        "required": false,
        "description": "Only orders with this `status`.",
        "schema": {
          "type": "string",
          "enum": ["open", "pending", "paid", "held", "failed", "expired", "canceled"]
        }
      },
      "OrderFulfillmentFilter": {
        "name": "fulfillment",
        "in": "query",
        "required": false,
        "description": "Only orders with this `fulfillment`.",
        "schema": {"type": "string", "enum": ["none", "unfulfilled", "fulfilled"]}
      },
      "SessionId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "The checkout session's id.",
        "schema": {"type": "string"},
        "example": "pay_7AAiYH0Ykt11ED4hmfiN"
      },
      "PaymentId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "The payment's id.",
        "schema": {"type": "string"},
        "example": "pay_7AAiYH0Ykt11ED4hmfiN"
      },
      "PaymentLinkId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "The payment link's id.",
        "schema": {"type": "string"},
        "example": "pay_Lk4mQ8vR2xTn7WcZs1Pb"
      },
      "InvoiceId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "The invoice's id.",
        "schema": {"type": "string"},
        "example": "in_Vn3qT8kR5xWm2LcZp7Hb"
      },
      "InvoiceCursor": {
        "name": "starting_after",
        "in": "query",
        "required": false,
        "description": "The `next_cursor` of the previous page: an invoice id from this list, in this mode. Anything else is `400 invalid_cursor`.",
        "schema": {"type": "string", "pattern": "^in_[A-Za-z0-9_-]{1,64}$"}
      },
      "InvoiceStatusFilter": {
        "name": "status",
        "in": "query",
        "required": false,
        "description": "Only invoices showing this status. `unpaid` is every issued invoice that can still be paid (sent, viewed, partially paid or overdue).",
        "schema": {
          "type": "string",
          "enum": [
            "draft",
            "unpaid",
            "sent",
            "viewed",
            "partially_paid",
            "overdue",
            "paid",
            "void",
            "expired"
          ]
        }
      },
      "InvoiceKindFilter": {
        "name": "kind",
        "in": "query",
        "required": false,
        "description": "`invoice` for invoices built as invoices, `link` for payment links.",
        "schema": {"type": "string", "enum": ["invoice", "link"]}
      },
      "InvoiceCustomerFilter": {
        "name": "customer",
        "in": "query",
        "required": false,
        "description": "Only this customer's invoices.",
        "schema": {"type": "string", "pattern": "^cus_[A-Za-z0-9_-]{1,64}$"},
        "example": "cus_Rk8mW3pZ6tQv1NxLc4Ys"
      },
      "InvoiceOwnerFilter": {
        "name": "owner",
        "in": "query",
        "required": false,
        "description": "Only invoices this person on the team owns (their `owner.id`), or `none` for invoices nobody owns.",
        "schema": {"type": "string", "pattern": "^(usr_[A-Za-z0-9_-]{1,64}|none)$"}
      },
      "InvoiceIdFilter": {
        "name": "invoice_id",
        "in": "query",
        "required": false,
        "description": "Only payments toward this invoice, `in_…`: each part payment of an invoice paid in parts is its own payment.",
        "schema": {"type": "string", "pattern": "^in_[A-Za-z0-9_-]{1,64}$"},
        "example": "in_Vn3qT8kR5xWm2LcZp7Hb"
      },
      "InvoiceIdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "A value unique to the invoice you mean to make, 1–120 printable ASCII characters, remembered for 24 hours per account and mode. A retry with the same key and body returns the first invoice (`200`); the same key with a different body is `409 idempotency_conflict`. A draft deleted since frees its key.",
        "schema": {"type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[\\x20-\\x7e]{1,120}$"},
        "example": "invoice-PO-1042"
      },
      "CheckoutId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "The checkout's id.",
        "schema": {"type": "string"},
        "example": "chk_Mg7tR2vX9kQp4WnZc8Lb"
      },
      "OrderId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "The order's id.",
        "schema": {"type": "string"},
        "example": "ord_Vd3kR8mQ1xTn6LpZs0Wa"
      },
      "CustomerId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "The customer's id.",
        "schema": {"type": "string"},
        "example": "cus_Hc7nQ2wVz9KpT4mRb1Ye"
      },
      "WebhookEndpointId": {
        "name": "id",
        "in": "path",
        "required": true,
        "description": "The webhook endpoint's id.",
        "schema": {"type": "string"},
        "example": "we_N8nQ4vRx7KtZ2mLp9WcB"
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "A value unique to the order attempt, 1–120 printable ASCII characters, remembered for 24 hours per account and mode. A retry with the same key and body returns the original session (`200`); the same key with a different body is `409 idempotency_conflict`.",
        "schema": {"type": "string", "minLength": 1, "maxLength": 120, "pattern": "^[\\x20-\\x7e]{1,120}$"},
        "example": "order_1042"
      },
      "RailbedSignature": {
        "name": "Railbed-Signature",
        "in": "header",
        "required": true,
        "description": "`t=<unix seconds>,v1=<hex HMAC-SHA256 of \"<t>.<raw body>\">`, keyed with the endpoint's whole `whsec_…` secret. For 24 hours after a secret roll it repeats `v1` for the previous and current keys: accept any matching signature. Verify against the raw body and reject timestamps more than 5 minutes off.",
        "schema": {"type": "string", "pattern": "^t=\\d+(,v1=[0-9a-f]{64})+$"}
      }
    },
    "headers": {
      "WWW-Authenticate": {
        "description": "Where an agent finds out how to get access (RFC 9728): `Bearer resource_metadata=\"https://pay.railbed.io/.well-known/oauth-protected-resource/v1\"`. When a credential was sent and refused it adds `error=\"invalid_token\"`; a `403 insufficient_scope` carries `error=\"insufficient_scope\", scope=\"…\"`.",
        "schema": {"type": "string"}
      },
      "Allow": {"description": "The methods this path supports.", "schema": {"type": "string"}},
      "Retry-After": {
        "description": "Seconds to wait before retrying.",
        "schema": {"type": "integer", "minimum": 0}
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "The key or agent access token is missing, malformed, expired or revoked. A secret key: check it and its mode, and don't retry. An agent: get a new token on `invalid_token`; ask its person to connect it again on `agent_disconnected`. Codes: `invalid_api_key`, `invalid_token`, `agent_disconnected`.",
        "x-railbed-error-codes": ["invalid_api_key", "invalid_token", "agent_disconnected"],
        "headers": {"WWW-Authenticate": {"$ref": "#/components/headers/WWW-Authenticate"}},
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
      },
      "NotFound": {
        "description": "No such object in your account in this credential's mode. For one of yours in the other mode, the message says so. Codes: `not_found`.",
        "x-railbed-error-codes": ["not_found"],
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
      },
      "MethodNotAllowed": {
        "description": "The path exists but doesn't support this method. Authentication and access checks run first. Codes: `method_not_allowed`.",
        "x-railbed-error-codes": ["method_not_allowed"],
        "headers": {"Allow": {"$ref": "#/components/headers/Allow"}},
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
      },
      "PayloadTooLarge": {
        "description": "The body is over 64 KiB. Codes: `request_too_large`.",
        "x-railbed-error-codes": ["request_too_large"],
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
      },
      "UnsupportedMediaType": {
        "description": "The body isn't sent as `Content-Type: application/json`. Codes: `unsupported_media_type`.",
        "x-railbed-error-codes": ["unsupported_media_type"],
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
      },
      "RateLimited": {
        "description": "Over the rate limit: about 120 requests a minute per business in each mode, 12 session starts a minute, and 120 a minute for each connected agent. Wait `Retry-After` seconds, then retry. Codes: `rate_limited`.",
        "x-railbed-error-codes": ["rate_limited"],
        "headers": {"Retry-After": {"$ref": "#/components/headers/Retry-After"}},
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
      },
      "ServerError": {
        "description": "Something failed on our side. Retry with backoff. Codes: `internal`, `misconfigured`, `auth_unavailable`.",
        "x-railbed-error-codes": ["internal", "misconfigured", "auth_unavailable"],
        "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Error"}}}
      }
    }
  }
}
