{ "openapi": "3.1.0", "info": { "title": "BitPal Public API", "version": "1.0.0", "description": "Non-custodial crypto checkout and x402 pay-per-call. Generated from the API source (zod schemas + route manifest) — do not edit by hand. Amounts are strings: session amounts are 6-decimal integers (\"29000000\" = 29); deposit/token amounts use the token’s own decimals." }, "servers": [ { "url": "https://api.bitpal.io", "description": "Test and live share one host — the API key prefix selects the mode." } ], "tags": [ { "name": "Checkout sessions", "description": "Create a session per order, send the buyer to the hosted page (or build your own UI), and track it." }, { "name": "Products & prices", "description": "Catalog objects. Prices are immutable." }, { "name": "Payment links", "description": "Shareable hosted URLs for a price." }, { "name": "x402", "description": "Charge per API call with HTTP 402 and EIP-3009 authorizations." }, { "name": "Webhook endpoints", "description": "Manage where BitPal delivers signed events." }, { "name": "Webhook events", "description": "Signed JSON events BitPal POSTs to your endpoint. Delivered at least once." } ], "paths": { "/v1/checkout/sessions": { "post": { "operationId": "createCheckoutSession", "tags": [ "Checkout sessions" ], "summary": "Create a checkout session", "description": "Creates a session for one order and returns the hosted `checkout_url`. Line items take either `amount` (plain decimal string, e.g. \"29\") or `amount_atomic` (6-decimal integer string), or reference a `price_id`.\n\n**Minimum amount:** the session total (sum of `amount × quantity`) must be at least 1.00 in the session currency (USDC/USDT: $1, JPYC: ¥1); a lower total returns 400 `CHECKOUT_AMOUNT_TOO_LOW`. Some networks also have a higher per-network minimum (Tron: currently $300, testnet included; JPYC: ¥100) — a network whose minimum is above the total is not offered to the buyer, and requesting a deposit address on it returns 400 `CHECKOUT_BELOW_MIN_PAYMENT`.\n\n**Payout wallet:** you need a payout wallet registered in the session's mode (test/live). With `pay_chain`, a wallet for that network's type (EVM, Tron or Solana) is required. With `allowed_pay_chains` / `allowed_assets`, at least one listed network must have a wallet of its type, and the buyer is only offered networks you can receive on. Without any network restriction, any payout wallet is enough: with an EVM wallet the buyer is offered Base USDC as before; without one, the networks of the wallet types you registered (if the total is below the minimum of all of them, 400 `CHECKOUT_BELOW_MIN_PAYMENT`). No usable payout wallet returns 400 `SELLER_WALLET_NOT_CONFIGURED`.", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateCheckoutSessionRequest" }, "example": { "line_items": [ { "name": "Pro plan", "amount": "29", "currency": "USDC" } ], "pay_chain": "eip155:84532", "expires_in_minutes": 30, "success_url": "https://your.store/thanks?session={CHECKOUT_SESSION_ID}" } } } }, "responses": { "201": { "description": "Session created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CreatedCheckoutSession" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] }, "example": { "data": { "id": "cs_Q2FxKhomCEju_OqvKfrQsTOh", "checkout_url": "https://bitpal.io/pay/cs_Q2FxKhomCEju_OqvKfrQsTOh?token=", "session_token": "", "status": "created", "amount_total": "29000000", "currency": "USDC", "expires_at": "2026-11-06T07:58:28.776Z", "tax": { "tax_amount": "0", "total_with_tax": "29000000" } }, "meta": { "mode": "TEST", "requestId": "ec091faf-…" } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "422": { "$ref": "#/components/responses/Error422" }, "429": { "$ref": "#/components/responses/Error429" } } }, "get": { "operationId": "listCheckoutSessions", "tags": [ "Checkout sessions" ], "summary": "List checkout sessions", "description": "Newest first, in the API key’s mode (test/live).", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "name": "status", "in": "query", "required": false, "description": "Filter by status, or `succeeded` for all successful states.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Sessions.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSessionListItem" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Error401" } } } }, "/v1/checkout/sessions/{id}": { "get": { "operationId": "getCheckoutSession", "tags": [ "Checkout sessions" ], "summary": "Retrieve a checkout session", "description": "Server-side source of truth for an order, together with webhooks.", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Checkout session id (`cs_…`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The session.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CheckoutSession" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" } } } }, "/v1/checkout/sessions/{id}/status": { "get": { "operationId": "getCheckoutSessionStatus", "tags": [ "Checkout sessions" ], "summary": "Get session status", "description": "Lightweight status for polling from your server. Requires your API key (N13 — it is not a public endpoint). Buyer-facing pages should use `GET /v1/checkout/sessions/{id}/public`.", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Checkout session id (`cs_…`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Status.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CheckoutSessionStatus" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] }, "example": { "data": { "status": "awaiting_deposit", "paid_at": null } } } } }, "404": { "$ref": "#/components/responses/Error404" } } } }, "/v1/checkout/sessions/{id}/public": { "get": { "operationId": "getPublicCheckoutSession", "tags": [ "Checkout sessions" ], "summary": "Get the public session view", "description": "Buyer-facing view used by the checkout page: payment options, deposit address once issued, refunds. No authentication; CORS-open.", "security": [], "x-bitpal-auth": "none", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Checkout session id (`cs_…`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public view.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PublicCheckoutSession" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "404": { "$ref": "#/components/responses/Error404" } } } }, "/v1/checkout/sessions/{id}/deposit-address": { "post": { "operationId": "issueDepositAddress", "tags": [ "Checkout sessions" ], "summary": "Issue the deposit address", "description": "Fixes the buyer’s network, token and refund address, and returns the one-time deposit address with the exact amount. Calling again returns the same address and keeps the first refund address. Requires the session token (header `X-Session-Token` or body `session_token`).", "security": [], "x-bitpal-auth": "sessionToken", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Checkout session id (`cs_…`).", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Accepted but not yet enforced on this endpoint — retries are not de-duplicated by key.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } }, { "name": "X-Session-Token", "in": "header", "required": false, "description": "Session token from the create-session response. Alternative to the `session_token` body field.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueDepositAddressRequest" }, "example": { "session_token": "", "refundAddress": "0xa0Ee7A142d267C1f36714E4a8F75612F20a79720", "chain": "eip155:84532", "token": "USDC" } } } }, "responses": { "200": { "description": "Deposit address.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/DepositAddress" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] }, "example": { "data": { "sessionId": "cs_…", "chain": "eip155:84532", "depositAddress": "0x6b19e871c934aB52775B6712e110f3e4b0626347", "expectedToken": "0x943b94dacf1507f2658f1cfe103ac36ebc13ef65", "expectedAmount": "29000000", "feeAmount": "435000", "refundAddress": "0xa0Ee7A142d267C1f36714E4a8F75612F20a79720", "deadline": "1793951938", "expiresAt": "2026-11-06T07:58:28.776Z", "depositOwner": null } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" }, "410": { "$ref": "#/components/responses/Error410" } } } }, "/v1/checkout/sessions/{id}/refunds": { "get": { "operationId": "listSessionRefunds", "tags": [ "Checkout sessions" ], "summary": "List refunds for a session", "description": "Refunds recorded for this session: automatic on-chain refunds from the deposit address (overpayment, expired underpayment, wrong token, late deposit) and refunds you sent from your own wallet and recorded in the console (`kind: merchant`). There is no API to make a refund — BitPal is non-custodial; refund a completed payment from Console → Sessions → session → Refund.", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Checkout session id (`cs_…`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Refunds.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SessionRefund" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" } } } }, "/v1/checkout/fee-preview": { "get": { "operationId": "previewFee", "tags": [ "Checkout sessions" ], "summary": "Preview the fee for an amount", "description": "Pass exactly one of `amount` or `amount_atomic`. The response is always atomic.", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "name": "amount", "in": "query", "required": false, "description": "Decimal string, e.g. \"100\".", "schema": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,6})?$" } }, { "name": "amount_atomic", "in": "query", "required": false, "description": "6-decimal integer string, e.g. \"100000000\".", "schema": { "type": "string", "pattern": "^\\d+$" } } ], "responses": { "200": { "description": "Fee breakdown.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/FeePreview" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] }, "example": { "data": { "amount": "100000000", "fee_rate": "0.015", "fee_amount": "1500000", "net_amount": "98500000" } } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" } } } }, "/v1/checkout/products": { "post": { "operationId": "createProduct", "tags": [ "Products & prices" ], "summary": "Create a product", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProductRequest" }, "example": { "name": "Pro plan" } } } }, "responses": { "201": { "description": "Product created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" } } }, "get": { "operationId": "listProducts", "tags": [ "Products & prices" ], "summary": "List products", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Products.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" } } } }, "/v1/checkout/products/{id}": { "get": { "operationId": "getProduct", "tags": [ "Products & prices" ], "summary": "Retrieve a product", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Product id (`prod_…`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" } } }, "patch": { "operationId": "updateProduct", "tags": [ "Products & prices" ], "summary": "Update a product", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Product id (`prod_…`).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProductRequest" } } } }, "responses": { "200": { "description": "The updated product.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Product" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" } } } }, "/v1/checkout/products/{id}/prices": { "post": { "operationId": "createPrice", "tags": [ "Products & prices" ], "summary": "Create a price", "description": "Prices are immutable: to change an amount, create a new price. Pass exactly one of `amount` (decimal string) or `amount_atomic` (6-decimal integer string). The currency is derived from `token_symbol`.", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Product id (`prod_…`).", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePriceRequest" }, "example": { "amount": "29", "token_symbol": "USDC" } } } }, "responses": { "201": { "description": "Price created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Price" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" } } }, "get": { "operationId": "listPrices", "tags": [ "Products & prices" ], "summary": "List a product’s prices", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Product id (`prod_…`).", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Prices.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Price" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" } } } }, "/v1/checkout/prices/{id}": { "get": { "operationId": "getPrice", "tags": [ "Products & prices" ], "summary": "Retrieve a price", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Price id (`price_…`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The price.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Price" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" } } }, "patch": { "operationId": "updatePrice", "tags": [ "Products & prices" ], "summary": "Update a price’s nickname", "description": "Only `nickname` can change. Sending an amount/currency field returns `PRICE_IMMUTABLE_FIELD`.", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Price id (`price_…`).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePriceRequest" } } } }, "responses": { "200": { "description": "The updated price.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Price" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" } } } }, "/v1/checkout/payment-links": { "post": { "operationId": "createPaymentLink", "tags": [ "Payment links" ], "summary": "Create a payment link", "description": "A shareable hosted URL for one price. The link ↔ price binding is fixed after creation.", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatePaymentLinkRequest" }, "example": { "price_id": "price_…", "allowed_pay_chains": [ "eip155:8453" ] } } } }, "responses": { "201": { "description": "Link created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PaymentLink" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" } } }, "get": { "operationId": "listPaymentLinks", "tags": [ "Payment links" ], "summary": "List payment links", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "active", "inactive" ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Links.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLink" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" } } } }, "/v1/checkout/payment-links/{id}": { "get": { "operationId": "getPaymentLink", "tags": [ "Payment links" ], "summary": "Retrieve a payment link", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment link id (`plink_…`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The link, with product/price summary fields.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PaymentLink" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" } } }, "patch": { "operationId": "updatePaymentLink", "tags": [ "Payment links" ], "summary": "Update a payment link", "description": "Operational settings and active ↔ inactive. The price cannot change — create a new link instead. Deactivating (`status: \"inactive\"`) requires `reason_code` (`user_request`, `security_concern`, `rotation`, `no_longer_needed` or `other`, plus an optional `reason_note`); without it the request returns 400 `REASON_CODE_REQUIRED`. Reactivating accepts the same fields optionally. Every status change is recorded in your audit log with its reason.", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment link id (`plink_…`).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdatePaymentLinkRequest" } } } }, "responses": { "200": { "description": "The updated link.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/PaymentLink" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" } } } }, "/v1/x402/assets": { "get": { "operationId": "listX402Assets", "tags": [ "x402" ], "summary": "List x402 assets for this mode", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "responses": { "200": { "description": "Assets.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/X402Assets" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Error401" } } } }, "/v1/x402/requirements": { "post": { "operationId": "createX402Requirements", "tags": [ "x402" ], "summary": "Build the 402 payment requirements", "description": "Returns the body your resource server sends with `402 Payment Required`, including the fee split. Pass exactly one of `amount` or `amountAtomic`.", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402RequirementsRequest" }, "example": { "payTo": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "amount": "0.1", "resource": "https://api.example.com/report" } } } }, "responses": { "200": { "description": "402 body.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/X402Requirements" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" } } } }, "/v1/x402/verify": { "post": { "operationId": "verifyX402Payment", "tags": [ "x402" ], "summary": "Verify an X-PAYMENT header", "description": "Checks the EIP-3009 authorization against the requirements. Sends nothing on-chain.", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequest" } } } }, "responses": { "200": { "description": "Valid.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/X402VerifyResult" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" } } } }, "/v1/x402/settle": { "post": { "operationId": "settleX402Payment", "tags": [ "x402" ], "summary": "Settle an x402 payment", "description": "Broadcasts the transfer and waits for the receipt. Serve the resource only when `status` is `confirmed`. Settlement is idempotent per authorization — retry with the same body on 5xx.", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/X402PaymentRequest" } } } }, "responses": { "200": { "description": "Settlement result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/X402SettleResult" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "403": { "$ref": "#/components/responses/Error403" }, "409": { "$ref": "#/components/responses/Error409" }, "503": { "$ref": "#/components/responses/Error503" } } } }, "/v1/x402/payments/{id}": { "get": { "operationId": "getX402Payment", "tags": [ "x402" ], "summary": "Retrieve an x402 payment", "description": "Recovery path when a settle response was lost — check here before settling again.", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The payment.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/X402Payment" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" } } } }, "/v1/x402/payments": { "get": { "operationId": "listX402Payments", "tags": [ "x402" ], "summary": "List x402 payments", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "exclusiveMinimum": 0, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "status", "in": "query", "required": false, "description": "pending | confirmed | failed | needs_review", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payments.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/X402Payment" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" } } } }, "/v1/webhooks": { "post": { "operationId": "createWebhookEndpoint", "tags": [ "Webhook endpoints" ], "summary": "Create a webhook endpoint", "description": "**Console only.** Manage this from Console → Developers → Webhooks; calls with an API key return 403.\n\nThe response carries the `whsec_…` signing secret — it is shown only once.", "security": [ { "consoleSession": [] } ], "x-bitpal-auth": "console", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointRequest" }, "example": { "endpoint_url": "https://your.store/webhooks/bitpal", "subscribed_events": [ "checkout.session.paid" ] } } } }, "responses": { "201": { "description": "Endpoint created.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" } } }, "get": { "operationId": "listWebhookEndpoints", "tags": [ "Webhook endpoints" ], "summary": "List webhook endpoints", "description": "**Console only.** Manage this from Console → Developers → Webhooks; calls with an API key return 403.\n\nEndpoints of the API key’s environment and mode. Note: list items use camelCase keys.", "security": [ { "consoleSession": [] } ], "x-bitpal-auth": "console", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 50 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Endpoints, newest first. `meta` carries total/limit/offset.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpointListItem" } }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "401": { "$ref": "#/components/responses/Error401" } } } }, "/v1/webhooks/{id}": { "patch": { "operationId": "updateWebhookEndpoint", "tags": [ "Webhook endpoints" ], "summary": "Update a webhook endpoint", "description": "**Console only.** Manage this from Console → Developers → Webhooks; calls with an API key return 403.\n\nSetting `status` to `disabled` removes the endpoint and requires `reason_code` (otherwise 400 `REASON_CODE_REQUIRED`). It is recorded in the audit log.", "security": [ { "consoleSession": [] } ], "x-bitpal-auth": "console", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook endpoint id (uuid).", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateWebhookEndpointRequest" } } } }, "responses": { "200": { "description": "The updated endpoint.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpoint" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" } } } }, "/v1/webhooks/{id}/rotate-secret": { "post": { "operationId": "rotateWebhookSecret", "tags": [ "Webhook endpoints" ], "summary": "Rotate the signing secret", "description": "**Console only.** Manage this from Console → Developers → Webhooks; calls with an API key return 403.\n\nTakes effect immediately. The new secret is returned once — update your verifier. Requires `reason_code` (400 `REASON_CODE_REQUIRED` if missing); recorded in the audit log.", "security": [ { "consoleSession": [] } ], "x-bitpal-auth": "console", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Webhook endpoint id (uuid).", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RotateWebhookSecretRequest" }, "example": { "reason_code": "rotation" } } } }, "responses": { "200": { "description": "Endpoint with the new secret.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookEndpointWithSecret" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" } } } }, "/v1/developers/webhooks/test": { "post": { "operationId": "sendTestWebhook", "tags": [ "Webhook endpoints" ], "summary": "Send a test event", "description": "Posts one signed sample event to an endpoint (no retries). The envelope id is prefixed `test_`, `data.test` is true and the request carries `X-Webhook-Test: true`.", "security": [ { "apiKey": [] } ], "x-bitpal-auth": "apiKey", "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendTestWebhookRequest" }, "example": { "webhook_id": "00000000-0000-4000-8000-000000000000", "event_type": "checkout.session.paid" } } } }, "responses": { "200": { "description": "Delivery result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/WebhookTestResult" }, "meta": { "$ref": "#/components/schemas/ResponseMeta", "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." } }, "required": [ "data" ] } } } }, "400": { "$ref": "#/components/responses/Error400" }, "401": { "$ref": "#/components/responses/Error401" }, "404": { "$ref": "#/components/responses/Error404" }, "409": { "$ref": "#/components/responses/Error409" } } } } }, "webhooks": { "checkout.session.created": { "post": { "operationId": "webhook_checkout_session_created", "tags": [ "Webhook events" ], "summary": "checkout.session.created", "description": "A session is created.", "parameters": [ { "name": "X-Webhook-Signature-256", "in": "header", "required": true, "description": "`sha256=` — HMAC-SHA256 of `.` with your whsec_… secret.", "schema": { "type": "string" } }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "ISO-8601 UTC time of this attempt (new on every retry).", "schema": { "type": "string" } }, { "name": "X-Webhook-Event", "in": "header", "required": true, "description": "Event name (unsigned — read it from the body).", "schema": { "type": "string" } }, { "name": "X-Webhook-Id", "in": "header", "required": true, "description": "Event id (unsigned — dedup on the body `id`).", "schema": { "type": "string" } }, { "name": "X-Webhook-Delivery-Id", "in": "header", "required": true, "description": "Id of this delivery, for support requests.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id — deduplicate on this. Test events are prefixed with `test_`." }, "event": { "type": "string", "const": "checkout.session.created" }, "created_at": { "type": "string", "description": "When the event happened (unchanged on retries)." }, "data": { "$ref": "#/components/schemas/CheckoutSessionCreatedEventData" } }, "required": [ "id", "event", "created_at", "data" ] } } } }, "responses": { "2XX": { "description": "Acknowledge within 10 seconds. Any other outcome is retried with backoff." } } } }, "checkout.session.deposit_detected": { "post": { "operationId": "webhook_checkout_session_deposit_detected", "tags": [ "Webhook events" ], "summary": "checkout.session.deposit_detected", "description": "Funds seen on-chain, awaiting confirmations. Optional — skipped when the first time BitPal sees the deposit it is already confirmed; then `checkout.session.paid` (or `unresolved`) arrives with no `deposit_detected` before it. Do not wait for it.", "parameters": [ { "name": "X-Webhook-Signature-256", "in": "header", "required": true, "description": "`sha256=` — HMAC-SHA256 of `.` with your whsec_… secret.", "schema": { "type": "string" } }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "ISO-8601 UTC time of this attempt (new on every retry).", "schema": { "type": "string" } }, { "name": "X-Webhook-Event", "in": "header", "required": true, "description": "Event name (unsigned — read it from the body).", "schema": { "type": "string" } }, { "name": "X-Webhook-Id", "in": "header", "required": true, "description": "Event id (unsigned — dedup on the body `id`).", "schema": { "type": "string" } }, { "name": "X-Webhook-Delivery-Id", "in": "header", "required": true, "description": "Id of this delivery, for support requests.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id — deduplicate on this. Test events are prefixed with `test_`." }, "event": { "type": "string", "const": "checkout.session.deposit_detected" }, "created_at": { "type": "string", "description": "When the event happened (unchanged on retries)." }, "data": { "$ref": "#/components/schemas/CheckoutSessionDepositDetectedEventData" } }, "required": [ "id", "event", "created_at", "data" ] } } } }, "responses": { "2XX": { "description": "Acknowledge within 10 seconds. Any other outcome is retried with backoff." } } } }, "checkout.session.paid": { "post": { "operationId": "webhook_checkout_session_paid", "tags": [ "Webhook events" ], "summary": "checkout.session.paid", "description": "Confirmed — safe to fulfil. `late: true` if it arrived after the deadline.", "parameters": [ { "name": "X-Webhook-Signature-256", "in": "header", "required": true, "description": "`sha256=` — HMAC-SHA256 of `.` with your whsec_… secret.", "schema": { "type": "string" } }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "ISO-8601 UTC time of this attempt (new on every retry).", "schema": { "type": "string" } }, { "name": "X-Webhook-Event", "in": "header", "required": true, "description": "Event name (unsigned — read it from the body).", "schema": { "type": "string" } }, { "name": "X-Webhook-Id", "in": "header", "required": true, "description": "Event id (unsigned — dedup on the body `id`).", "schema": { "type": "string" } }, { "name": "X-Webhook-Delivery-Id", "in": "header", "required": true, "description": "Id of this delivery, for support requests.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id — deduplicate on this. Test events are prefixed with `test_`." }, "event": { "type": "string", "const": "checkout.session.paid" }, "created_at": { "type": "string", "description": "When the event happened (unchanged on retries)." }, "data": { "$ref": "#/components/schemas/CheckoutSessionPaidEventData" } }, "required": [ "id", "event", "created_at", "data" ] }, "example": { "id": "1ff63374-9417-4f87-850d-e869a3bd2dbe", "event": "checkout.session.paid", "created_at": "2026-11-06T07:20:49.549Z", "data": { "session_id": "cs_HFoj91aFFbHSRk1LN1-9K01q", "amount_total": "1000000", "currency": "USDC", "late": false, "tx_hash": "0xd9a75dfe753b20027a0a93841c4e70af1b6be061b59e530d1bc381e88c196fe3", "metadata": { "order_id": "ord_1042" } } } } } }, "responses": { "2XX": { "description": "Acknowledge within 10 seconds. Any other outcome is retried with backoff." } } } }, "checkout.session.settled": { "post": { "operationId": "webhook_checkout_session_settled", "tags": [ "Webhook events" ], "summary": "checkout.session.settled", "description": "Funds swept to your payout wallet.", "parameters": [ { "name": "X-Webhook-Signature-256", "in": "header", "required": true, "description": "`sha256=` — HMAC-SHA256 of `.` with your whsec_… secret.", "schema": { "type": "string" } }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "ISO-8601 UTC time of this attempt (new on every retry).", "schema": { "type": "string" } }, { "name": "X-Webhook-Event", "in": "header", "required": true, "description": "Event name (unsigned — read it from the body).", "schema": { "type": "string" } }, { "name": "X-Webhook-Id", "in": "header", "required": true, "description": "Event id (unsigned — dedup on the body `id`).", "schema": { "type": "string" } }, { "name": "X-Webhook-Delivery-Id", "in": "header", "required": true, "description": "Id of this delivery, for support requests.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id — deduplicate on this. Test events are prefixed with `test_`." }, "event": { "type": "string", "const": "checkout.session.settled" }, "created_at": { "type": "string", "description": "When the event happened (unchanged on retries)." }, "data": { "$ref": "#/components/schemas/CheckoutSessionSettledEventData" } }, "required": [ "id", "event", "created_at", "data" ] } } } }, "responses": { "2XX": { "description": "Acknowledge within 10 seconds. Any other outcome is retried with backoff." } } } }, "checkout.session.unresolved": { "post": { "operationId": "webhook_checkout_session_unresolved", "tags": [ "Webhook events" ], "summary": "checkout.session.unresolved", "description": "Underpaid, wrong token, or a confirmed deposit reverted by a reorg (`reason`).", "parameters": [ { "name": "X-Webhook-Signature-256", "in": "header", "required": true, "description": "`sha256=` — HMAC-SHA256 of `.` with your whsec_… secret.", "schema": { "type": "string" } }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "ISO-8601 UTC time of this attempt (new on every retry).", "schema": { "type": "string" } }, { "name": "X-Webhook-Event", "in": "header", "required": true, "description": "Event name (unsigned — read it from the body).", "schema": { "type": "string" } }, { "name": "X-Webhook-Id", "in": "header", "required": true, "description": "Event id (unsigned — dedup on the body `id`).", "schema": { "type": "string" } }, { "name": "X-Webhook-Delivery-Id", "in": "header", "required": true, "description": "Id of this delivery, for support requests.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id — deduplicate on this. Test events are prefixed with `test_`." }, "event": { "type": "string", "const": "checkout.session.unresolved" }, "created_at": { "type": "string", "description": "When the event happened (unchanged on retries)." }, "data": { "$ref": "#/components/schemas/CheckoutSessionUnresolvedEventData" } }, "required": [ "id", "event", "created_at", "data" ] }, "example": { "id": "18d80275-45be-43d7-a57b-4b5038bd2736", "event": "checkout.session.unresolved", "created_at": "2026-11-06T07:14:19.252Z", "data": { "session_id": "cs_1ATJ7V5QknzeFpTNPMU_449s", "amount_total": "5000000", "currency": "USDC", "late": false, "reason": "underpaid", "amount_expected": "5000000", "amount_received": "2500000", "received_token": "0x943b94Dacf1507F2658f1CfE103Ac36Ebc13Ef65", "tx_hash": "0x4461291b5d743d3950a474c015098b8cb53b4373346bd510f74481dd8dbb9d65", "metadata": { "order_id": "ord_1041" } } } } } }, "responses": { "2XX": { "description": "Acknowledge within 10 seconds. Any other outcome is retried with backoff." } } } }, "checkout.session.expired": { "post": { "operationId": "webhook_checkout_session_expired", "tags": [ "Webhook events" ], "summary": "checkout.session.expired", "description": "Deadline passed without full payment.", "parameters": [ { "name": "X-Webhook-Signature-256", "in": "header", "required": true, "description": "`sha256=` — HMAC-SHA256 of `.` with your whsec_… secret.", "schema": { "type": "string" } }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "ISO-8601 UTC time of this attempt (new on every retry).", "schema": { "type": "string" } }, { "name": "X-Webhook-Event", "in": "header", "required": true, "description": "Event name (unsigned — read it from the body).", "schema": { "type": "string" } }, { "name": "X-Webhook-Id", "in": "header", "required": true, "description": "Event id (unsigned — dedup on the body `id`).", "schema": { "type": "string" } }, { "name": "X-Webhook-Delivery-Id", "in": "header", "required": true, "description": "Id of this delivery, for support requests.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id — deduplicate on this. Test events are prefixed with `test_`." }, "event": { "type": "string", "const": "checkout.session.expired" }, "created_at": { "type": "string", "description": "When the event happened (unchanged on retries)." }, "data": { "$ref": "#/components/schemas/CheckoutSessionExpiredEventData" } }, "required": [ "id", "event", "created_at", "data" ] } } } }, "responses": { "2XX": { "description": "Acknowledge within 10 seconds. Any other outcome is retried with backoff." } } } }, "checkout.refund.recorded": { "post": { "operationId": "webhook_checkout_refund_recorded", "tags": [ "Webhook events" ], "summary": "checkout.refund.recorded", "description": "A refund was made on-chain (`kind`): automatic, or recorded by you in the console (`merchant`).", "parameters": [ { "name": "X-Webhook-Signature-256", "in": "header", "required": true, "description": "`sha256=` — HMAC-SHA256 of `.` with your whsec_… secret.", "schema": { "type": "string" } }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "ISO-8601 UTC time of this attempt (new on every retry).", "schema": { "type": "string" } }, { "name": "X-Webhook-Event", "in": "header", "required": true, "description": "Event name (unsigned — read it from the body).", "schema": { "type": "string" } }, { "name": "X-Webhook-Id", "in": "header", "required": true, "description": "Event id (unsigned — dedup on the body `id`).", "schema": { "type": "string" } }, { "name": "X-Webhook-Delivery-Id", "in": "header", "required": true, "description": "Id of this delivery, for support requests.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id — deduplicate on this. Test events are prefixed with `test_`." }, "event": { "type": "string", "const": "checkout.refund.recorded" }, "created_at": { "type": "string", "description": "When the event happened (unchanged on retries)." }, "data": { "$ref": "#/components/schemas/CheckoutRefundRecordedEventData" } }, "required": [ "id", "event", "created_at", "data" ] }, "example": { "id": "f2fdcce6-1880-44b2-8351-906c42b7c4cd", "event": "checkout.refund.recorded", "created_at": "2026-11-06T07:20:29.547Z", "data": { "session_id": "cs_YsrZGcZzVsVHJo8ZNVmsTL1D", "kind": "overpay_excess", "amount": "1000000", "token": "0x943b94Dacf1507F2658f1CfE103Ac36Ebc13Ef65", "tx_hash": "0xe943412e2be8b3e3fc6359b47a8eea0cc4de17768b069f52ebab1aacd873aec4", "refund_address": "0xa0Ee7A142d267C1f36714E4a8F75612F20a79720", "metadata": { "order_id": "ord_1040" } } } } } }, "responses": { "2XX": { "description": "Acknowledge within 10 seconds. Any other outcome is retried with backoff." } } } }, "x402.payment.resolved": { "post": { "operationId": "webhook_x402_payment_resolved", "tags": [ "Webhook events" ], "summary": "x402.payment.resolved", "description": "An x402 call that settled with `503` reached its outcome. Only fires for those — the normal path answers inline.", "parameters": [ { "name": "X-Webhook-Signature-256", "in": "header", "required": true, "description": "`sha256=` — HMAC-SHA256 of `.` with your whsec_… secret.", "schema": { "type": "string" } }, { "name": "X-Webhook-Timestamp", "in": "header", "required": true, "description": "ISO-8601 UTC time of this attempt (new on every retry).", "schema": { "type": "string" } }, { "name": "X-Webhook-Event", "in": "header", "required": true, "description": "Event name (unsigned — read it from the body).", "schema": { "type": "string" } }, { "name": "X-Webhook-Id", "in": "header", "required": true, "description": "Event id (unsigned — dedup on the body `id`).", "schema": { "type": "string" } }, { "name": "X-Webhook-Delivery-Id", "in": "header", "required": true, "description": "Id of this delivery, for support requests.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Event id — deduplicate on this. Test events are prefixed with `test_`." }, "event": { "type": "string", "const": "x402.payment.resolved" }, "created_at": { "type": "string", "description": "When the event happened (unchanged on retries)." }, "data": { "$ref": "#/components/schemas/X402PaymentResolvedEventData" } }, "required": [ "id", "event", "created_at", "data" ] } } } }, "responses": { "2XX": { "description": "Acknowledge within 10 seconds. Any other outcome is retried with backoff." } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "bearerFormat": "bp_test_… / bp_live_…", "description": "Secret API key from Console → Developers → API Keys. Server-side only. The prefix selects test or live mode." }, "consoleSession": { "type": "http", "scheme": "bearer", "description": "BitPal Console login session. Not available to API keys — these operations are done in the Console." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "description": "8–128 characters, unique per operation. A retry with the same key and body within 24 hours returns the original response with `X-Idempotency-Replayed: true`.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } }, "responses": { "Error400": { "description": "Invalid request — fix it before retrying. Validation failures carry `details`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Error401": { "description": "Missing, invalid, revoked or expired API key / session token, or a key for the other mode.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Error403": { "description": "Not allowed — for example the merchant account is frozen or suspended.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Error404": { "description": "Not found in this environment (test and live are separate).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Error409": { "description": "Conflicts with the current state, or the same Idempotency-Key is still in progress.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Error410": { "description": "Gone — expired, sold out or deactivated.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Error422": { "description": "Idempotency-Key reused with a different body.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Error429": { "description": "Rate limited. Honour `Retry-After`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "Error503": { "description": "Outcome not confirmed yet. Retry the same request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "schemas": { "CheckoutRefundRecordedEventData": { "type": "object", "properties": { "session_id": { "type": "string" }, "metadata": { "type": "object", "additionalProperties": true, "description": "The `metadata` you set when creating the session (`{}` if none). Reserved keys BitPal writes itself (`_bitpal`, `payer_email`, `allowed_pay_chains`, `allowed_assets`) are not included." }, "kind": { "type": "string", "enum": [ "overpay_excess", "underpay_expired", "wrong_token", "late_deposit", "merchant" ], "description": "Automatic on-chain refunds from the deposit address: `overpay_excess`, `underpay_expired`, `wrong_token`, `late_deposit`. `merchant` = you refunded a completed payment from your own wallet and recorded it in the console. More kinds may be added." }, "amount": { "type": "string", "description": "Atomic amount in the pay token’s own decimals." }, "token": { "type": "string" }, "tx_hash": { "type": "string" }, "refund_address": { "type": "string" }, "from_address": { "type": "string", "description": "kind `merchant` only: the wallet the refund was sent from." }, "reason_code": { "type": "string", "enum": [ "customer_request", "duplicate", "product_issue", "other" ], "description": "kind `merchant` only: the reason selected in the console." } }, "required": [ "session_id", "metadata", "kind", "amount", "token", "tx_hash", "refund_address" ], "additionalProperties": true }, "CheckoutSession": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "description": "created | awaiting_deposit | deposit_detected | paid_confirmed | swept | expired | unresolved_* | wrong_token …" }, "mode": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "amount_total": { "type": "string", "pattern": "^\\d+$", "description": "Atomic integer string. Session amounts are canonical 6-decimal (\"29000000\" = 29)." }, "amount_received": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "pay_chain": { "type": [ "string", "null" ] }, "pay_asset": { "type": [ "string", "null" ] }, "token_decimals": { "type": [ "integer", "null" ], "description": "Decimals of the payment token (USDC/USDT = 6, BSC-USD = 18). `amount_received` is in these units; `amount_total` is always 6-decimal." }, "payment_method": { "type": [ "string", "null" ] }, "payer_wallet": { "type": [ "string", "null" ], "description": "Sender of the deposit (or the wallet the buyer connected), in the network’s address format (Tron: base58 `T…`). May be an exchange hot wallet." }, "seller_wallet": { "type": "string" }, "tolerance_percent": { "type": [ "string", "null" ] }, "late_payments": { "type": "string", "enum": [ "accept", "refund" ], "description": "What happens to a full payment that arrives after the payment deadline: `accept` (default) = accepted as a late payment for up to 7 days; `refund` = refunded automatically about 7 days after the deadline." }, "deposit_address": { "type": [ "string", "null" ] }, "refund_address": { "type": [ "string", "null" ] }, "received_token": { "type": [ "string", "null" ], "description": "Token contract/mint address actually received at the deposit address (an address, not the symbol — see `received_token_symbol`). Tron addresses are base58 `T…`." }, "received_token_symbol": { "type": [ "string", "null" ], "description": "Symbol of `received_token` (e.g. `USDC`, `USDT`). Null when nothing was received yet or the token is not one BitPal knows (e.g. a wrong token)." }, "fee_amount": { "type": [ "string", "null" ], "description": "Platform fee in 6-decimal units (same scale as amount_total)." }, "fee_rate": { "type": [ "string", "null" ] }, "net_amount": { "type": [ "string", "null" ], "description": "Merchant net in 6-decimal units (same scale as amount_total)." }, "fee_amount_token": { "type": [ "string", "null" ], "description": "Platform fee in the payment token atomic units (token_decimals) — exactly what is transferred on-chain. Null before a deposit address is issued." }, "net_amount_token": { "type": [ "string", "null" ], "description": "Merchant net in the payment token atomic units (token_decimals) — exactly what is swept on-chain. Null before a deposit address is issued." }, "tx_hash": { "type": [ "string", "null" ], "description": "Deprecated: kept for compatibility and returns the same value as `deposit_tx_hash`. Use `deposit_tx_hash` (buyer payment) and `sweep_tx_hash` (settlement to your wallet).", "deprecated": true }, "deposit_tx_hash": { "type": [ "string", "null" ], "description": "Transaction that paid into the deposit address." }, "sweep_tx_hash": { "type": [ "string", "null" ], "description": "Transaction that settled the funds to your payout wallet (or refunded/rescued them)." }, "success_url": { "type": [ "string", "null" ] }, "cancel_url": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The `metadata` you set when creating the session. Reserved keys BitPal writes itself (`_bitpal`, `payer_email`, `allowed_pay_chains`, `allowed_assets`) are not included." }, "payment_source": { "type": [ "string", "null" ] }, "payment_link_id": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp" }, "settled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Atomic integer string. Session amounts are canonical 6-decimal (\"29000000\" = 29)." }, "currency": { "type": "string" }, "quantity": { "type": [ "integer", "null" ] }, "price_id": { "type": [ "string", "null" ] }, "product_id": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" } }, "required": [ "id", "name", "amount", "currency", "quantity", "price_id", "product_id", "created_at" ], "additionalProperties": false } } }, "required": [ "id", "status", "mode", "amount_total", "amount_received", "currency", "pay_chain", "pay_asset", "token_decimals", "payment_method", "payer_wallet", "seller_wallet", "tolerance_percent", "late_payments", "deposit_address", "refund_address", "received_token", "received_token_symbol", "fee_amount", "fee_rate", "net_amount", "fee_amount_token", "net_amount_token", "tx_hash", "deposit_tx_hash", "sweep_tx_hash", "success_url", "cancel_url", "metadata", "payment_source", "payment_link_id", "expires_at", "paid_at", "settled_at", "created_at", "line_items" ], "additionalProperties": false }, "CheckoutSessionCreatedEventData": { "type": "object", "properties": { "session_id": { "type": "string", "description": "cs_…" }, "metadata": { "type": "object", "additionalProperties": true, "description": "The `metadata` you set when creating the session (`{}` if none). Reserved keys BitPal writes itself (`_bitpal`, `payer_email`, `allowed_pay_chains`, `allowed_assets`) are not included." }, "amount_total": { "type": "string", "description": "6-decimal integer string (\"1000000\" = 1)." }, "currency": { "type": "string" }, "late": { "type": "boolean", "description": "true when the full amount arrived after the payment window." } }, "required": [ "session_id", "metadata", "amount_total", "currency" ], "additionalProperties": true }, "CheckoutSessionDepositDetectedEventData": { "type": "object", "properties": { "session_id": { "type": "string", "description": "cs_…" }, "metadata": { "type": "object", "additionalProperties": true, "description": "The `metadata` you set when creating the session (`{}` if none). Reserved keys BitPal writes itself (`_bitpal`, `payer_email`, `allowed_pay_chains`, `allowed_assets`) are not included." }, "amount_total": { "type": "string", "description": "6-decimal integer string (\"1000000\" = 1)." }, "currency": { "type": "string" }, "late": { "type": "boolean", "description": "true when the full amount arrived after the payment window." }, "tx_hash": { "type": "string" }, "amount_received": { "type": "string", "description": "Atomic amount in the pay token’s own decimals." }, "received_token": { "type": "string", "description": "Token contract / mint address actually received (not the symbol)." } }, "required": [ "session_id", "metadata", "amount_total", "currency", "tx_hash", "amount_received", "received_token" ], "additionalProperties": true }, "CheckoutSessionExpiredEventData": { "type": "object", "properties": { "session_id": { "type": "string", "description": "cs_…" }, "metadata": { "type": "object", "additionalProperties": true, "description": "The `metadata` you set when creating the session (`{}` if none). Reserved keys BitPal writes itself (`_bitpal`, `payer_email`, `allowed_pay_chains`, `allowed_assets`) are not included." }, "amount_total": { "type": "string", "description": "6-decimal integer string (\"1000000\" = 1)." }, "currency": { "type": "string" }, "late": { "type": "boolean", "description": "true when the full amount arrived after the payment window." }, "reason": { "type": "string", "const": "no_deposit", "description": "Set when nothing was paid." }, "expired_at": { "type": "string", "format": "date-time", "description": "When the session was marked expired. Sent for sessions that expired before a deposit address was issued." }, "source": { "type": "string", "enum": [ "lazy", "cron" ], "description": "What noticed the expiry: a read of the session (`lazy`) or the scheduled sweep (`cron`). Informational." }, "refund_tx_hash": { "type": "string", "description": "Set when a partial payment was refunded." } }, "required": [ "session_id", "metadata", "amount_total", "currency" ], "additionalProperties": true }, "CheckoutSessionListItem": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "description": "created | awaiting_deposit | deposit_detected | paid_confirmed | swept | expired | unresolved_* | wrong_token …" }, "mode": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "amount_total": { "type": "string", "pattern": "^\\d+$", "description": "Atomic integer string. Session amounts are canonical 6-decimal (\"29000000\" = 29)." }, "amount_received": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "pay_chain": { "type": [ "string", "null" ] }, "pay_asset": { "type": [ "string", "null" ] }, "token_decimals": { "type": [ "integer", "null" ], "description": "Decimals of the payment token (USDC/USDT = 6, BSC-USD = 18). `amount_received` is in these units; `amount_total` is always 6-decimal." }, "payment_method": { "type": [ "string", "null" ] }, "payer_wallet": { "type": [ "string", "null" ], "description": "Sender of the deposit (or the wallet the buyer connected), in the network’s address format (Tron: base58 `T…`). May be an exchange hot wallet." }, "seller_wallet": { "type": "string" }, "tolerance_percent": { "type": [ "string", "null" ] }, "late_payments": { "type": "string", "enum": [ "accept", "refund" ], "description": "What happens to a full payment that arrives after the payment deadline: `accept` (default) = accepted as a late payment for up to 7 days; `refund` = refunded automatically about 7 days after the deadline." }, "deposit_address": { "type": [ "string", "null" ] }, "refund_address": { "type": [ "string", "null" ] }, "received_token": { "type": [ "string", "null" ], "description": "Token contract/mint address actually received at the deposit address (an address, not the symbol — see `received_token_symbol`). Tron addresses are base58 `T…`." }, "received_token_symbol": { "type": [ "string", "null" ], "description": "Symbol of `received_token` (e.g. `USDC`, `USDT`). Null when nothing was received yet or the token is not one BitPal knows (e.g. a wrong token)." }, "fee_amount": { "type": [ "string", "null" ], "description": "Platform fee in 6-decimal units (same scale as amount_total)." }, "fee_rate": { "type": [ "string", "null" ] }, "net_amount": { "type": [ "string", "null" ], "description": "Merchant net in 6-decimal units (same scale as amount_total)." }, "fee_amount_token": { "type": [ "string", "null" ], "description": "Platform fee in the payment token atomic units (token_decimals) — exactly what is transferred on-chain. Null before a deposit address is issued." }, "net_amount_token": { "type": [ "string", "null" ], "description": "Merchant net in the payment token atomic units (token_decimals) — exactly what is swept on-chain. Null before a deposit address is issued." }, "tx_hash": { "type": [ "string", "null" ], "description": "Deprecated: kept for compatibility and returns the same value as `deposit_tx_hash`. Use `deposit_tx_hash` (buyer payment) and `sweep_tx_hash` (settlement to your wallet).", "deprecated": true }, "deposit_tx_hash": { "type": [ "string", "null" ], "description": "Transaction that paid into the deposit address." }, "sweep_tx_hash": { "type": [ "string", "null" ], "description": "Transaction that settled the funds to your payout wallet (or refunded/rescued them)." }, "success_url": { "type": [ "string", "null" ] }, "cancel_url": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true, "description": "The `metadata` you set when creating the session. Reserved keys BitPal writes itself (`_bitpal`, `payer_email`, `allowed_pay_chains`, `allowed_assets`) are not included." }, "payment_source": { "type": [ "string", "null" ] }, "payment_link_id": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp" }, "settled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" }, "raw_status": { "type": "string", "description": "Same as `status`; kept for compatibility." } }, "required": [ "id", "status", "mode", "amount_total", "amount_received", "currency", "pay_chain", "pay_asset", "token_decimals", "payment_method", "payer_wallet", "seller_wallet", "tolerance_percent", "late_payments", "deposit_address", "refund_address", "received_token", "received_token_symbol", "fee_amount", "fee_rate", "net_amount", "fee_amount_token", "net_amount_token", "tx_hash", "deposit_tx_hash", "sweep_tx_hash", "success_url", "cancel_url", "metadata", "payment_source", "payment_link_id", "expires_at", "paid_at", "settled_at", "created_at", "raw_status" ], "additionalProperties": false }, "CheckoutSessionPaidEventData": { "type": "object", "properties": { "session_id": { "type": "string", "description": "cs_…" }, "metadata": { "type": "object", "additionalProperties": true, "description": "The `metadata` you set when creating the session (`{}` if none). Reserved keys BitPal writes itself (`_bitpal`, `payer_email`, `allowed_pay_chains`, `allowed_assets`) are not included." }, "amount_total": { "type": "string", "description": "6-decimal integer string (\"1000000\" = 1)." }, "currency": { "type": "string" }, "late": { "type": "boolean", "description": "true when the full amount arrived after the payment window." }, "tx_hash": { "type": "string" } }, "required": [ "session_id", "metadata", "amount_total", "currency", "tx_hash" ], "additionalProperties": true }, "CheckoutSessionSettledEventData": { "type": "object", "properties": { "session_id": { "type": "string", "description": "cs_…" }, "metadata": { "type": "object", "additionalProperties": true, "description": "The `metadata` you set when creating the session (`{}` if none). Reserved keys BitPal writes itself (`_bitpal`, `payer_email`, `allowed_pay_chains`, `allowed_assets`) are not included." }, "amount_total": { "type": "string", "description": "6-decimal integer string (\"1000000\" = 1)." }, "currency": { "type": "string" }, "late": { "type": "boolean", "description": "true when the full amount arrived after the payment window." }, "sweep_tx_hash": { "type": "string" } }, "required": [ "session_id", "metadata", "amount_total", "currency", "sweep_tx_hash" ], "additionalProperties": true }, "CheckoutSessionStatus": { "type": "object", "properties": { "status": { "type": "string", "description": "created | awaiting_deposit | deposit_detected | paid_confirmed | swept | expired | unresolved_* | wrong_token …" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp" } }, "required": [ "status", "paid_at" ] }, "CheckoutSessionUnresolvedEventData": { "type": "object", "properties": { "session_id": { "type": "string", "description": "cs_…" }, "metadata": { "type": "object", "additionalProperties": true, "description": "The `metadata` you set when creating the session (`{}` if none). Reserved keys BitPal writes itself (`_bitpal`, `payer_email`, `allowed_pay_chains`, `allowed_assets`) are not included." }, "amount_total": { "type": "string", "description": "6-decimal integer string (\"1000000\" = 1)." }, "currency": { "type": "string" }, "late": { "type": "boolean", "description": "true when the full amount arrived after the payment window." }, "reason": { "type": "string", "enum": [ "underpaid", "wrong_token", "reorg" ] }, "amount_expected": { "type": "string", "description": "Atomic amount in the pay token’s own decimals." }, "amount_received": { "type": "string", "description": "Atomic amount in the pay token’s own decimals." }, "received_token": { "type": "string" }, "tx_hash": { "type": "string" } }, "required": [ "session_id", "metadata", "amount_total", "currency", "reason" ], "additionalProperties": true }, "CreateCheckoutSessionRequest": { "type": "object", "properties": { "line_items": { "description": "Raw items (`name`, `currency`, `amount` XOR `amount_atomic`) or price items (`price_id`). Do not mix the two kinds. The total (sum of `amount × quantity`) must be at least 1.00 in the session currency, otherwise 400 `CHECKOUT_AMOUNT_TOO_LOW`.", "type": "array", "items": { "anyOf": [ { "type": "object", "properties": { "price_id": { "type": "string", "pattern": "^price_[A-Za-z0-9_-]+$" }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "default": 1 } }, "required": [ "price_id" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "type": "string", "minLength": 1 }, "currency": { "type": "string", "minLength": 1 }, "quantity": { "type": "integer", "exclusiveMinimum": 0, "default": 1 }, "amount": { "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,6})?$" }, "amount_atomic": { "type": "string", "pattern": "^(0|[1-9]\\d*)$" } }, "required": [ "name", "currency" ], "additionalProperties": true, "oneOf": [ { "required": [ "amount" ] }, { "required": [ "amount_atomic" ] } ], "not": { "required": [ "price_id" ] } } ] }, "minItems": 1 }, "currency": { "description": "Session currency. Defaults to the line items’ currency.", "type": "string", "minLength": 1 }, "success_url": { "description": "Where the buyer returns after paying. `{CHECKOUT_SESSION_ID}` is replaced with the session id.", "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "cancel_url": { "description": "Where the buyer goes when cancelling.", "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "customer_email": { "description": "Buyer email. Pre-fills the receipt form on the payment completion screen; no receipt is sent automatically — the buyer requests it there.", "type": "string", "format": "email" }, "metadata": { "description": "Your key/value data, echoed back on the session and in webhooks (`data.metadata`). Reserved keys BitPal writes itself (`_bitpal`, `payer_email`, `allowed_pay_chains`, `allowed_assets`) are not returned — do not use them.", "type": "object", "additionalProperties": true }, "expires_in_minutes": { "description": "Payment window in minutes (1–60). Default 15.", "type": "integer", "minimum": 1, "maximum": 60, "default": 15 }, "tolerance_percent": { "description": "Deprecated. Underpayments are never accepted — a short payment becomes `unresolved_underpaid` and can be topped up to the same address. Only `\"0\"` is accepted; any other value returns 400.", "type": "string", "pattern": "^0+(\\.0+)?$" }, "pay_chain": { "description": "Fix the payment network: CAIP-2 (`eip155:84532`) or a short name (`base`), which resolves to the testnet in test mode and the mainnet in live mode. Mutually exclusive with `allowed_pay_chains`.", "type": "string" }, "allowed_pay_chains": { "description": "Networks the buyer may choose from (CAIP-2 or short names, resolved like `pay_chain`).", "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 8 }, "allowed_assets": { "description": "Allowed (chain, token) cells. Takes precedence over `allowed_pay_chains`.", "type": "array", "items": { "type": "object", "properties": { "caip2": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 } }, "required": [ "caip2", "token" ], "x-unknown-keys": "strip" }, "minItems": 1, "maxItems": 16 }, "late_payments": { "description": "What to do with a full payment that arrives after the payment deadline. `accept` (default): accepted as a late payment for up to 7 days (`checkout.session.paid` with `late: true`). `refund`: never accepted — it is refunded automatically to the buyer about 7 days after the deadline (refund kind `late_deposit`); the non-custodial deposit contract does not allow an earlier refund.", "type": "string", "enum": [ "accept", "refund" ] } }, "required": [ "line_items" ], "x-unknown-keys": "strip" }, "CreatePaymentLinkRequest": { "type": "object", "properties": { "price_id": { "description": "The price this link sells (`price_…`).", "type": "string", "pattern": "^price_[A-Za-z0-9_-]+$" }, "title": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "collect_email": { "description": "Ask the buyer for an email. Default true.", "type": "boolean", "default": true }, "email_required": { "description": "Require the email: the hosted link page asks for it and no checkout is created without it. Default true; needs `collect_email`.", "type": "boolean", "default": true }, "allowed_pay_chains": { "description": "Networks the buyer may choose from (CAIP-2 or short names).", "type": "array", "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 8 }, "allowed_assets": { "description": "Allowed (chain, token) cells. Takes precedence over `allowed_pay_chains`.", "type": "array", "items": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 } }, "required": [ "chain", "token" ], "x-unknown-keys": "strip" }, "minItems": 1, "maxItems": 16 }, "success_url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "cancel_url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "max_uses": { "description": "Stop accepting payments after this many paid uses.", "type": "integer", "minimum": 1 }, "expires_at": { "description": "ISO-8601 time after which the link stops working.", "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true } }, "required": [ "price_id" ], "additionalProperties": false }, "CreatePriceRequest": { "type": "object", "properties": { "amount": { "description": "Decimal string, e.g. \"29\". Mutually exclusive with `amount_atomic`.", "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,6})?$" }, "amount_atomic": { "description": "6-decimal integer string (\"29000000\" = 29).", "type": "string", "pattern": "^[1-9]\\d*$" }, "token_symbol": { "description": "The price’s asset. The currency is derived from it.", "type": "string", "enum": [ "USDC", "USDT", "JPYC" ], "default": "USDC" }, "billing_type": { "description": "Only `one_time` for now.", "type": "string", "const": "one_time", "default": "one_time" }, "nickname": { "description": "Display name.", "type": "string", "maxLength": 200 }, "lookup_key": { "description": "Your own stable key for this price.", "type": "string", "minLength": 1, "maxLength": 200 } }, "additionalProperties": false }, "CreateProductRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": "string", "maxLength": 2000 }, "image_url": { "type": "string", "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "metadata": { "type": "object", "additionalProperties": true } }, "required": [ "name" ], "additionalProperties": false }, "CreateWebhookEndpointRequest": { "type": "object", "properties": { "endpoint_url": { "description": "HTTPS URL that receives events. Private hosts are rejected.", "type": "string", "format": "uri" }, "subscribed_events": { "description": "Event names to deliver (see the `webhooks` section), or `*` for every event. Unknown names are rejected with 400.", "type": "array", "items": { "type": "string", "enum": [ "*", "checkout.session.created", "checkout.session.deposit_detected", "checkout.session.paid", "checkout.session.settled", "checkout.session.expired", "checkout.session.unresolved", "checkout.refund.recorded", "x402.payment.resolved" ] }, "minItems": 1 }, "retry_policy": { "description": "`max_retries` caps the total delivery attempts (1–20, default 10: 3 right away, then 1 min, 5 min, 30 min, 2 h, 6 h, 12 h, 24 h). The schedule itself is fixed; `backoff` is ignored.", "type": "object", "properties": { "max_retries": { "type": "integer", "minimum": 1, "maximum": 20 }, "backoff": { "type": "string", "enum": [ "exponential", "linear", "fixed" ] } }, "x-unknown-keys": "strip" }, "dead_letter_destination": { "description": "Optional URL for dead-lettered deliveries.", "type": [ "string", "null" ], "format": "uri" } }, "required": [ "endpoint_url", "subscribed_events" ], "x-unknown-keys": "strip" }, "CreatedCheckoutSession": { "type": "object", "properties": { "id": { "type": "string", "description": "cs_…" }, "checkout_url": { "type": "string", "description": "Hosted checkout page, including the session token. Redirect the buyer here." }, "session_token": { "type": "string", "description": "Proof of access for the buyer-facing endpoints (deposit-address)." }, "status": { "type": "string" }, "amount_total": { "type": "string", "pattern": "^\\d+$", "description": "Atomic integer string. Session amounts are canonical 6-decimal (\"29000000\" = 29)." }, "currency": { "type": "string" }, "expires_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" }, "tax": { "type": [ "object", "null" ], "properties": { "tax_amount": { "type": "string", "pattern": "^\\d+$", "description": "Atomic integer string. Session amounts are canonical 6-decimal (\"29000000\" = 29)." }, "total_with_tax": { "type": "string", "pattern": "^\\d+$", "description": "Atomic integer string. Session amounts are canonical 6-decimal (\"29000000\" = 29)." } }, "required": [ "tax_amount", "total_with_tax" ] } }, "required": [ "id", "checkout_url", "session_token", "status", "amount_total", "currency", "tax" ] }, "DepositAddress": { "type": "object", "properties": { "sessionId": { "type": "string" }, "chain": { "type": "string", "description": "CAIP-2 of the chosen network." }, "depositAddress": { "type": "string", "description": "One-time deposit address for this order (EVM 0x… / Tron T… / Solana base58)." }, "expectedToken": { "type": "string" }, "expectedAmount": { "type": "string", "description": "Exact amount to send, in the token’s own decimals." }, "feeAmount": { "type": "string" }, "refundAddress": { "type": "string" }, "deadline": { "type": "string", "description": "Unix seconds — on-chain deadline." }, "expiresAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp" }, "depositOwner": { "type": [ "string", "null" ], "description": "Solana only: the wallet (owner) address to send to — the order account that owns the deposit token account. Wallets derive the token account from this address, so use it as the recipient. Null on EVM/Tron." } }, "required": [ "sessionId", "chain", "depositAddress", "expectedToken", "expectedAmount", "feeAmount", "refundAddress", "deadline", "expiresAt", "depositOwner" ] }, "ErrorResponse": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable message." }, "code": { "type": "string", "description": "Machine-readable error code, e.g. VALIDATION_FAILED. Branch on this, not on `error`." }, "retryable": { "type": "boolean", "description": "Whether retrying the same request may succeed." }, "trace_id": { "type": "string", "description": "Quote this to support." }, "details": { "description": "Validation issues (array) for 400 responses." } }, "required": [ "error", "code", "retryable" ], "additionalProperties": true }, "FeePreview": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+$", "description": "Atomic integer string. Session amounts are canonical 6-decimal (\"29000000\" = 29)." }, "fee_rate": { "type": "string", "description": "Fraction, e.g. \"0.015\" = 1.5%." }, "fee_amount": { "type": "string", "pattern": "^\\d+$", "description": "Atomic integer string. Session amounts are canonical 6-decimal (\"29000000\" = 29)." }, "net_amount": { "type": "string", "pattern": "^\\d+$", "description": "Atomic integer string. Session amounts are canonical 6-decimal (\"29000000\" = 29)." } }, "required": [ "amount", "fee_rate", "fee_amount", "net_amount" ] }, "IssueDepositAddressRequest": { "type": "object", "properties": { "session_token": { "description": "From the create-session response. May be sent as the `X-Session-Token` header instead.", "type": "string" }, "refundAddress": { "description": "Buyer refund address in the chosen network’s format (EVM 0x…, Tron T…, Solana base58). Cannot change later.", "type": "string", "pattern": "^(0x[0-9a-fA-F]{40}|T[1-9A-HJ-NP-Za-km-z]{33}|[1-9A-HJ-NP-Za-km-z]{32,44})$" }, "chain": { "description": "CAIP-2 or short name of the chosen network. Required for multi-option sessions.", "type": "string", "minLength": 1 }, "token": { "description": "Token symbol of the chosen asset, e.g. USDC. Required for multi-option sessions.", "type": "string", "minLength": 1 } }, "required": [ "refundAddress" ], "x-unknown-keys": "strip" }, "PaymentLink": { "type": "object", "properties": { "id": { "type": "string", "description": "plink_…" }, "share_token": { "type": "string", "description": "Hosted URL: {checkout base}/plink/{share_token}" }, "price_id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "collect_email": { "type": "boolean" }, "email_required": { "type": "boolean" }, "allowed_pay_chains": { "type": [ "array", "null" ], "items": { "type": "string" } }, "allowed_assets": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "caip2": { "type": "string" }, "token": { "type": "string" } }, "required": [ "caip2", "token" ] } }, "success_url": { "type": [ "string", "null" ] }, "cancel_url": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "max_uses": { "type": [ "integer", "null" ] }, "paid_use_count": { "type": "integer" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp" }, "metadata": { "type": "object", "additionalProperties": true }, "mode": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" } }, "required": [ "id", "share_token", "price_id", "title", "description", "collect_email", "email_required", "allowed_pay_chains", "allowed_assets", "success_url", "cancel_url", "status", "max_uses", "paid_use_count", "expires_at", "metadata", "mode", "created_at", "updated_at" ], "additionalProperties": true }, "Price": { "type": "object", "properties": { "id": { "type": "string", "description": "price_…" }, "product_id": { "type": "string" }, "amount_atomic": { "type": "string", "pattern": "^\\d+$", "description": "Atomic integer string. Session amounts are canonical 6-decimal (\"29000000\" = 29)." }, "currency": { "type": "string" }, "token_symbol": { "type": "string" }, "billing_type": { "type": "string", "const": "one_time" }, "nickname": { "type": [ "string", "null" ] }, "lookup_key": { "type": [ "string", "null" ] }, "mode": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" } }, "required": [ "id", "product_id", "amount_atomic", "currency", "token_symbol", "billing_type", "nickname", "lookup_key", "mode", "created_at" ], "additionalProperties": true }, "Product": { "type": "object", "properties": { "id": { "type": "string", "description": "prod_…" }, "name": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "metadata": { "type": "object", "additionalProperties": true }, "mode": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" } }, "required": [ "id", "name", "description", "image_url", "status", "metadata", "mode", "created_at", "updated_at" ], "additionalProperties": true }, "PublicCheckoutSession": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "description": "created | awaiting_deposit | deposit_detected | paid_confirmed | swept | expired | unresolved_* | wrong_token …" }, "token_decimals": { "type": "integer" }, "pay_amount": { "type": "string", "description": "amount_total rescaled to the pay token decimals." }, "mode": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "chain_id": { "type": [ "integer", "null" ] }, "token_address": { "type": [ "string", "null" ] }, "payment_options": { "type": "array", "items": { "type": "object", "properties": { "caip2": { "type": "string", "description": "CAIP-2 chain id, e.g. eip155:8453" }, "chain_id": { "type": [ "integer", "null" ], "description": "EVM chain id; null for Tron/Solana." }, "token_symbol": { "type": "string" }, "token_address": { "type": "string" }, "decimals": { "type": "integer" }, "amount_atomic": { "type": "string", "description": "Exact amount to pay in this token, in its own decimals." }, "available": { "type": "boolean", "description": "false = shown but not selectable yet (see unavailable_reason). Deposit-address requests for it are rejected with CHECKOUT_CHAIN_COMING_SOON." }, "unavailable_reason": { "anyOf": [ { "type": "string", "enum": [ "coming_soon" ] }, { "type": "null" } ], "description": "Why the option is not selectable. coming_soon = this network opens for payments soon." } }, "required": [ "caip2", "chain_id", "token_symbol", "token_address", "decimals", "amount_atomic", "available", "unavailable_reason" ] } }, "currency": { "type": "string" }, "amount_total": { "type": "string", "pattern": "^\\d+$", "description": "Atomic integer string. Session amounts are canonical 6-decimal (\"29000000\" = 29)." }, "amount_received": { "type": [ "string", "null" ] }, "chain": { "type": [ "string", "null" ] }, "tx_hash": { "type": [ "string", "null" ], "description": "The buyer’s payment transaction into the deposit address." }, "release_tx_hash": { "type": [ "string", "null" ], "description": "The settlement transaction to the merchant’s payout wallet." }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp" }, "success_url": { "type": [ "string", "null" ] }, "cancel_url": { "type": [ "string", "null" ] }, "fee_amount": { "type": [ "string", "null" ] }, "fee_rate": { "type": [ "string", "null" ] }, "net_amount": { "type": [ "string", "null" ] }, "tax_amount": { "type": "null" }, "tax_rate": { "type": "null" }, "pay_chain": { "type": [ "string", "null" ] }, "pay_asset": { "type": [ "string", "null" ] }, "deposit_address": { "type": [ "string", "null" ] }, "deposit_owner": { "type": [ "string", "null" ], "description": "Solana only: the wallet (owner) address to send to — the order account that owns the deposit token account. Wallets derive the token account from this address, so use it as the recipient. Null on EVM/Tron." }, "payment_deadline_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp" }, "payment_method": { "type": [ "string", "null" ] }, "payer_wallet": { "type": [ "string", "null" ] }, "seller_wallet": { "type": "string" }, "tolerance_percent": { "type": "string" }, "paid_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp" }, "settled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp" }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Atomic integer string. Session amounts are canonical 6-decimal (\"29000000\" = 29)." }, "currency": { "type": "string" }, "quantity": { "type": [ "integer", "null" ] } }, "required": [ "name", "amount", "currency", "quantity" ] } }, "payment_source": { "type": "string" }, "refunds": { "type": "array", "items": { "type": "object", "properties": { "kind": { "type": "string", "description": "overpay_excess | underpay_expired | wrong_token | late_deposit | merchant" }, "amount": { "type": "string" }, "token_symbol": { "type": [ "string", "null" ] }, "decimals": { "type": "integer" }, "tx_hash": { "type": "string" }, "caip2": { "type": "string" } }, "required": [ "kind", "amount", "token_symbol", "decimals", "tx_hash", "caip2" ] } } }, "required": [ "id", "status", "token_decimals", "pay_amount", "mode", "chain_id", "token_address", "payment_options", "currency", "amount_total", "amount_received", "chain", "tx_hash", "release_tx_hash", "expires_at", "success_url", "cancel_url", "fee_amount", "fee_rate", "net_amount", "tax_amount", "tax_rate", "pay_chain", "pay_asset", "deposit_address", "deposit_owner", "payment_deadline_at", "payment_method", "payer_wallet", "seller_wallet", "tolerance_percent", "paid_at", "settled_at", "created_at", "line_items", "payment_source", "refunds" ] }, "ResponseMeta": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "requestId": { "type": [ "string", "null" ] }, "total": { "type": "integer" }, "limit": { "type": "integer" }, "offset": { "type": "integer" } }, "required": [ "mode", "requestId" ], "description": "Added to responses of authenticated endpoints. List endpoints may also carry total/limit/offset." }, "RotateWebhookSecretRequest": { "type": "object", "properties": { "reason_code": { "description": "One of user_request, security_concern, rotation, no_longer_needed, other.", "type": "string", "enum": [ "user_request", "security_concern", "rotation", "no_longer_needed", "other" ] }, "reason_note": { "description": "Optional free text (≤ 500 chars) stored with the audit record.", "type": "string", "maxLength": 500 } }, "required": [ "reason_code" ], "x-unknown-keys": "strip" }, "SendTestWebhookRequest": { "type": "object", "properties": { "webhook_id": { "description": "Endpoint id.", "type": "string", "format": "uuid" }, "event_type": { "description": "Event name to put in the envelope, e.g. checkout.session.paid.", "type": "string", "minLength": 1, "maxLength": 200 }, "payload": { "description": "Custom `data` object. Defaults to a sample message.", "type": "object", "additionalProperties": true } }, "required": [ "webhook_id", "event_type" ], "x-unknown-keys": "strip" }, "SessionRefund": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "description": "overpay_excess | underpay_expired | wrong_token | late_deposit (automatic, from the deposit address) | merchant (you refunded from your own wallet and recorded it in the console). More kinds may be added — treat unknown values as a generic refund." }, "token": { "type": "string" }, "token_symbol": { "type": [ "string", "null" ] }, "amount": { "type": "string", "description": "Atomic, in the token decimals." }, "amount_display": { "type": "string" }, "decimals": { "type": "integer" }, "refund_address": { "type": "string" }, "tx_hash": { "type": "string" }, "caip2": { "type": "string" }, "block_number": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" }, "from_address": { "type": [ "string", "null" ], "description": "kind `merchant` only: the wallet the refund was sent from." }, "reason_code": { "type": [ "string", "null" ], "description": "kind `merchant` only: customer_request | duplicate | product_issue | other." }, "note": { "type": [ "string", "null" ], "description": "kind `merchant` only: the note entered in the console." }, "explorer_url": { "type": [ "string", "null" ], "description": "Block explorer link for `tx_hash`." } }, "required": [ "id", "kind", "token", "token_symbol", "amount", "amount_display", "decimals", "refund_address", "tx_hash", "caip2", "block_number", "created_at", "from_address", "reason_code", "note", "explorer_url" ] }, "UpdatePaymentLinkRequest": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "collect_email": { "type": "boolean" }, "email_required": { "type": "boolean" }, "allowed_pay_chains": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 1 }, "minItems": 1, "maxItems": 8 }, "allowed_assets": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "chain": { "type": "string", "minLength": 1 }, "token": { "type": "string", "minLength": 1 } }, "required": [ "chain", "token" ], "x-unknown-keys": "strip" }, "minItems": 1, "maxItems": 16 }, "success_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "cancel_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "max_uses": { "type": [ "integer", "null" ], "minimum": 1 }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": true }, "reason_code": { "type": "string", "enum": [ "user_request", "security_concern", "rotation", "no_longer_needed", "other" ] }, "reason_note": { "type": "string", "maxLength": 500 } }, "additionalProperties": false }, "UpdatePriceRequest": { "type": "object", "properties": { "nickname": { "type": [ "string", "null" ], "maxLength": 200 } }, "additionalProperties": false }, "UpdateProductRequest": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 200 }, "description": { "type": [ "string", "null" ], "maxLength": 2000 }, "image_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048, "pattern": "^https?://" }, "metadata": { "type": "object", "additionalProperties": true }, "status": { "type": "string", "enum": [ "active", "inactive" ] } }, "additionalProperties": false }, "UpdateWebhookEndpointRequest": { "type": "object", "properties": { "endpoint_url": { "type": "string", "format": "uri" }, "subscribed_events": { "type": "array", "items": { "type": "string", "enum": [ "*", "checkout.session.created", "checkout.session.deposit_detected", "checkout.session.paid", "checkout.session.settled", "checkout.session.expired", "checkout.session.unresolved", "checkout.refund.recorded", "x402.payment.resolved" ] }, "minItems": 1 }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ] }, "retry_policy": { "type": "object", "properties": { "max_retries": { "type": "integer", "minimum": 1, "maximum": 20 }, "backoff": { "type": "string", "enum": [ "exponential", "linear", "fixed" ] } }, "x-unknown-keys": "strip" }, "dead_letter_destination": { "type": [ "string", "null" ], "format": "uri" }, "reason_code": { "description": "Required when `status` is `disabled`: one of user_request, security_concern, rotation, no_longer_needed, other.", "type": "string", "enum": [ "user_request", "security_concern", "rotation", "no_longer_needed", "other" ] }, "reason_note": { "description": "Optional free text (≤ 500 chars) stored with the audit record.", "type": "string", "maxLength": 500 } }, "x-unknown-keys": "strip" }, "WebhookEndpoint": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "mode": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "endpoint_url": { "type": "string" }, "subscribed_events": { "type": "array", "items": { "type": "string" } }, "retry_policy": { "type": "object", "properties": { "max_retries": { "type": "integer" }, "backoff": { "type": "string", "enum": [ "exponential", "linear", "fixed" ] } } }, "dead_letter_destination": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" } }, "required": [ "id", "mode", "endpoint_url", "subscribed_events", "retry_policy", "dead_letter_destination", "status", "created_at", "updated_at" ], "additionalProperties": true }, "WebhookEndpointListItem": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "mode": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "endpoint_url": { "type": "string" }, "subscribed_events": { "type": "array", "items": { "type": "string" } }, "retry_policy": { "type": "object", "properties": { "max_retries": { "type": "integer" }, "backoff": { "type": "string", "enum": [ "exponential", "linear", "fixed" ] } } }, "dead_letter_destination": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" } }, "required": [ "id", "mode", "endpoint_url", "subscribed_events", "retry_policy", "dead_letter_destination", "status", "created_at", "updated_at" ] }, "WebhookEndpointWithSecret": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "mode": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "endpoint_url": { "type": "string" }, "subscribed_events": { "type": "array", "items": { "type": "string" } }, "retry_policy": { "type": "object", "properties": { "max_retries": { "type": "integer" }, "backoff": { "type": "string", "enum": [ "exponential", "linear", "fixed" ] } } }, "dead_letter_destination": { "type": [ "string", "null" ] }, "status": { "type": "string", "enum": [ "active", "paused", "disabled" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" }, "updated_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" }, "secret": { "type": "string", "description": "whsec_… signing secret. Returned only on create and rotate-secret." } }, "required": [ "id", "mode", "endpoint_url", "subscribed_events", "retry_policy", "dead_letter_destination", "status", "created_at", "updated_at", "secret" ], "additionalProperties": true }, "WebhookTestResult": { "type": "object", "properties": { "delivery_id": { "type": "string", "format": "uuid" }, "webhook_id": { "type": "string", "format": "uuid" }, "endpoint_url": { "type": "string" }, "event_type": { "type": "string" }, "http_status": { "type": "integer", "description": "0 when the request did not complete." }, "response_body": { "type": "string", "description": "First 1 KB of your endpoint’s response." }, "error": { "type": [ "string", "null" ] }, "duration_ms": { "type": "integer" }, "test": { "type": "boolean", "const": true }, "sent_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" } }, "required": [ "delivery_id", "webhook_id", "endpoint_url", "event_type", "http_status", "response_body", "error", "duration_ms", "test", "sent_at" ] }, "X402Assets": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "TEST", "LIVE" ] }, "assets": { "type": "array", "items": { "type": "object", "properties": { "caip2": { "type": "string" }, "network": { "type": "string", "description": "x402 network name, e.g. base / base-sepolia" }, "chain_name": { "type": "string" }, "symbol": { "type": "string" }, "decimals": { "type": "integer" }, "address": { "type": "string" } }, "required": [ "caip2", "network", "chain_name", "symbol", "decimals", "address" ] } } }, "required": [ "mode", "assets" ] }, "X402Payment": { "type": "object", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "confirmed", "failed", "needs_review" ] }, "raw_status": { "type": "string" }, "resource": { "type": "string" }, "chain": { "type": "string" }, "asset": { "type": "string" }, "decimals": { "type": [ "integer", "null" ] }, "amount": { "type": "string", "pattern": "^\\d+$", "description": "Net amount to the merchant (atomic)." }, "gross_amount": { "type": "string", "pattern": "^\\d+$", "description": "Atomic integer string. Session amounts are canonical 6-decimal (\"29000000\" = 29)." }, "payer": { "type": "string" }, "pay_to": { "type": "string" }, "tx_hash": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp" }, "settled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp" } }, "required": [ "id", "status", "raw_status", "resource", "chain", "asset", "decimals", "amount", "gross_amount", "payer", "pay_to", "tx_hash", "created_at", "settled_at" ] }, "X402PaymentRequest": { "type": "object", "properties": { "x402Version": { "type": "integer", "const": 1 }, "paymentPayload": { "type": "object", "properties": { "scheme": { "type": "string", "const": "exact" }, "network": { "type": "string", "minLength": 1 }, "payload": { "type": "object", "properties": { "signature": { "type": "string", "pattern": "^0x[0-9a-fA-F]{130}$" }, "authorization": { "type": "object", "properties": { "from": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "to": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "value": { "type": "string", "pattern": "^\\d+$" }, "validAfter": { "type": "string", "pattern": "^\\d+$" }, "validBefore": { "type": "string", "pattern": "^\\d+$" }, "nonce": { "type": "string", "pattern": "^0x[a-fA-F0-9]{64}$" } }, "required": [ "from", "to", "value", "validAfter", "validBefore", "nonce" ], "x-unknown-keys": "strip" } }, "required": [ "signature", "authorization" ], "x-unknown-keys": "strip" } }, "required": [ "scheme", "network", "payload" ], "x-unknown-keys": "strip" }, "paymentRequirements": { "type": "object", "properties": { "asset": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "payTo": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "merchant": { "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "maxAmountRequired": { "type": "string", "pattern": "^\\d+$" }, "resource": { "type": "string", "minLength": 1, "maxLength": 2048 } }, "required": [ "asset", "payTo", "merchant", "maxAmountRequired", "resource" ], "x-unknown-keys": "strip" } }, "required": [ "x402Version", "paymentPayload", "paymentRequirements" ], "x-unknown-keys": "strip" }, "X402PaymentResolvedEventData": { "type": "object", "properties": { "payment_id": { "type": "string" }, "status": { "type": "string", "enum": [ "confirmed", "reverted", "expired" ] }, "resource": { "type": "string" }, "amount": { "type": "string", "description": "Atomic amount in the pay token’s own decimals." }, "asset": { "type": "string" }, "chain": { "type": "string" }, "tx_hash": { "type": [ "string", "null" ] }, "payer": { "type": "string" }, "resolved_by": { "type": "string", "const": "reconciler" } }, "required": [ "payment_id", "status", "resource", "amount", "asset", "chain", "tx_hash", "payer", "resolved_by" ], "additionalProperties": true }, "X402Requirements": { "type": "object", "properties": { "x402Version": { "type": "integer", "const": 1 }, "accepts": { "type": "array", "items": { "type": "object", "properties": { "scheme": { "type": "string", "const": "exact" }, "network": { "type": "string" }, "asset": { "type": "string" }, "payTo": { "type": "string", "description": "Settlement address the payer signs to (commits the fee split)." }, "maxAmountRequired": { "type": "string", "pattern": "^\\d+$", "description": "Atomic integer string. Session amounts are canonical 6-decimal (\"29000000\" = 29)." }, "resource": { "type": "string" }, "description": { "type": "string" }, "mimeType": { "type": "string" }, "maxTimeoutSeconds": { "type": "integer" }, "extra": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "chainId": { "type": "integer" } }, "required": [ "name", "version", "chainId" ] }, "feeBreakdown": { "type": "object", "properties": { "netAmount": { "type": "string", "pattern": "^\\d+$", "description": "Atomic integer string. Session amounts are canonical 6-decimal (\"29000000\" = 29)." }, "feeAmount": { "type": "string", "pattern": "^\\d+$", "description": "Atomic integer string. Session amounts are canonical 6-decimal (\"29000000\" = 29)." }, "feeBps": { "type": "integer" }, "feeRecipient": { "type": [ "string", "null" ] } }, "required": [ "netAmount", "feeAmount", "feeBps", "feeRecipient" ], "description": "BitPal extension; standard x402 clients can ignore it." } }, "required": [ "scheme", "network", "asset", "payTo", "maxAmountRequired", "resource", "description", "mimeType", "maxTimeoutSeconds", "extra", "feeBreakdown" ] } } }, "required": [ "x402Version", "accepts" ] }, "X402RequirementsRequest": { "type": "object", "properties": { "network": { "description": "x402 network name (`base`, `base-sepolia`). Defaults to the mode’s first asset.", "type": "string", "minLength": 1 }, "asset": { "description": "Token symbol. Default USDC.", "type": "string", "minLength": 1, "default": "USDC" }, "payTo": { "description": "Your payout wallet (0x) — must be the one registered in Console for this mode, otherwise `PAYTO_NOT_MERCHANT_WALLET`.", "type": "string", "pattern": "^0x[a-fA-F0-9]{40}$" }, "amount": { "description": "Gross amount per call as a decimal string, e.g. \"0.1\". The fee is taken from it.", "type": "string", "pattern": "^(0|[1-9]\\d*)(\\.\\d{1,6})?$" }, "amountAtomic": { "description": "Same as `amount`, as a 6-decimal integer string.", "type": "string", "pattern": "^\\d+$" }, "resource": { "description": "The URL being paid for.", "type": "string", "minLength": 1, "maxLength": 2048 }, "description": { "type": "string", "maxLength": 512 }, "mimeType": { "type": "string", "maxLength": 128 }, "maxTimeoutSeconds": { "description": "How long the payer has to sign (max 3600). Default 300.", "type": "integer", "exclusiveMinimum": 0, "maximum": 3600 } }, "required": [ "payTo", "resource" ], "x-unknown-keys": "strip" }, "X402SettleResult": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "payment_id": { "type": "string" }, "status": { "type": "string", "description": "confirmed → serve the resource. Anything else: do not serve; retry with the same X-PAYMENT header." }, "tx_hash": { "type": [ "string", "null" ] }, "fee_tx_hash": { "type": [ "string", "null" ] }, "network": { "type": "string" }, "idempotent": { "type": "boolean" } }, "required": [ "success", "payment_id", "status", "tx_hash", "fee_tx_hash", "network", "idempotent" ] }, "X402VerifyResult": { "type": "object", "properties": { "valid": { "type": "boolean", "const": true }, "payment_id": { "type": "string" }, "status": { "type": "string" }, "idempotent": { "type": "boolean" } }, "required": [ "valid", "payment_id", "status", "idempotent" ] } } } }