{ "openapi": "3.1.0", "info": { "title": "Skerry", "version": "1.0.0", "description": "Every call but `/` sends `Authorization: Bearer sk_test_…` or `sk_live_…`. The environment is in the key, not in a header, so the same code runs against sandbox and live by swapping one value.\n\nSend `Idempotency-Key` on every POST. A repeat returns the first response rather than acting twice; a repeat with a different body is refused. This is how a retry after a timeout stays safe.\n\nFailures are `{ error: { code, message, detail, request_id } }`. Branch on `code`, never on `message` — messages are written for people and will change.\n\nEvery response carries `x-request-id`. Keep it on anything you log: it is what lets us find one call out of millions.\n\nList endpoints return newest first and take `?limit=` and `?cursor=`. A response carrying `next_cursor` has more.\n\nPayments, refunds, settlements, conversions and ledger entries carry amounts as integer minor units (cents) beside a lowercase currency code. Payouts, rates and wallet balances predate this and use decimal strings.\n\nA `sk_test_` key reaches only sandbox data and test money; a `sk_live_` key only live. Nothing is shared between them, ids from one are not found in the other, and sandbox-only helpers refuse a live key.\n\nReads are limited to 600 and writes to 120 per minute per key. Past that, 429 `rate_limited` with `Retry-After`. Every response carries `RateLimit-Limit` and `RateLimit-Remaining`.\n\nSend `Skerry-Agent: ` when an agent calls through a shared key, so spend policies bound to that agent apply and the audit trail names it." }, "servers": [ { "url": "https://api.skerry.xyz" } ], "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_test_… | sk_live_…" } } }, "tags": [ { "name": "Getting started", "description": "The two calls worth making first. `/` needs no key and lists what exists; `/whoami` proves the key you were given works and says which environment it is in." }, { "name": "Customers", "description": "A customer is a business you bring to the platform. It is verified in its own right, and everything else — wallets, accounts, payees — hangs off one." }, { "name": "Custody", "description": "Where a customer's money sits. A wallet holds stablecoin; an account is fiat at a regulated institution; a card spends from one." }, { "name": "Paying out", "description": "A payee is somewhere money can go; a payout sends it there. Quote first when the amount matters — a quote fixes the rate for a short window." }, { "name": "Standing conversion", "description": "A standing order converts on a schedule rather than on a call, so a business can hold one currency and settle in another without writing a cron job." }, { "name": "Events and webhooks", "description": "Most state changes arrive here rather than in a response, because verification and settlement finish long after the call that started them. Replay is deliberate: a missed delivery is recoverable without asking us." }, { "name": "Accepting payments", "description": "Take card and wallet payments for a customer. The payer pays on a hosted page, so card details never reach Skerry or you. Amounts are integer minor units next to a currency code. Build orders from `payment.succeeded`, never from the payer's browser returning to your site." }, { "name": "Payers, saved methods and subscriptions", "description": "A payer is someone who pays your customer. Save a method once, with their agreement, and charge it later or on a schedule. The agreement is the mandate. Card numbers are never returned." }, { "name": "Limits, agents and approvals", "description": "Constrain what a key, or an agent acting through it, can move. A policy names the business accountable and the person who approved it, caps amounts, restricts destinations and currencies, and can require a person to approve large operations. A key that has ever had a policy stays restricted." }, { "name": "Conversion and ledger", "description": "Convert a customer's own balance between currencies with a priced, expiring quote, and export the double-entry books for an accountant." }, { "name": "Sandbox", "description": "Helpers that exist only with a test key, so an integration can be built and exercised without a browser or a bank." }, { "name": "Rewards and reporting", "description": "What the platform pays on balances, and what this project has consumed against its plan." } ], "paths": { "/": { "get": { "tags": [ "Getting started" ], "summary": "The index. Public, so a new developer can look before they have a key.", "operationId": "get_", "security": [], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "none" } }, "/openapi.json": { "get": { "tags": [ "Getting started" ], "summary": "This same reference as an OpenAPI 3.1 document, for Postman, a generator or an agent. Public.", "operationId": "get_openapi_json", "security": [], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "none" } }, "/whoami": { "get": { "tags": [ "Getting started" ], "summary": "The partner, project, mode and scopes behind the key you sent.", "operationId": "get_whoami", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "*" } }, "/capabilities": { "get": { "tags": [ "Getting started" ], "summary": "What this project may do right now, and what is merely coming.", "operationId": "get_capabilities", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "*" } }, "/terms": { "post": { "tags": [ "Getting started" ], "summary": "Accept the terms a customer must agree to before they can be verified.", "operationId": "post_terms", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ customer_id }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "customers:write" } }, "/customers": { "post": { "tags": [ "Customers" ], "summary": "Onboard a business.", "operationId": "post_customers", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ legal_name, address, external_id? }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "customers:write" }, "get": { "tags": [ "Customers" ], "summary": "The businesses this project has onboarded.", "operationId": "get_customers", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "customers:read" } }, "/customers/{id}": { "get": { "tags": [ "Customers" ], "summary": "One business, with its verification state.", "operationId": "get_customers_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "customers:read" }, "patch": { "tags": [ "Customers" ], "summary": "Correct details on a business.", "operationId": "patch_customers_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ legal_name?, address?, external_id? }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "customers:write" } }, "/customers/{id}/verification": { "post": { "tags": [ "Customers" ], "summary": "Start or re-run verification.", "operationId": "post_customers_id_verification", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "customers:write" }, "get": { "tags": [ "Customers" ], "summary": "Where verification has got to.", "operationId": "get_customers_id_verification", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "customers:read" } }, "/customers/{id}/onboarding-link": { "post": { "tags": [ "Customers" ], "summary": "A link the business owner opens to finish verification (and card-acceptance setup) on hosted pages. You send no people, birth dates or documents.", "operationId": "post_customers_id_onboarding_link", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ return_url, refresh_url?, steps? }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "customers:write" } }, "/onboard/{token}": { "get": { "tags": [ "Customers" ], "summary": "The page behind an onboarding link. Public: the token is the credential. Redirects to the next hosted step, then back to your return_url.", "operationId": "get_onboard_token", "security": [], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "none" } }, "/eligibility": { "get": { "tags": [ "Customers" ], "summary": "Whether a business like this can be served, from where, for what, with machine-readable reasons. `?country=&business_type=¤cy=&industry=`", "operationId": "get_eligibility", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "eligibility:read" } }, "/customers/{id}/wallets": { "post": { "tags": [ "Custody" ], "summary": "Create a stablecoin wallet.", "operationId": "post_customers_id_wallets", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ chain, currency }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "wallets:write" }, "get": { "tags": [ "Custody" ], "summary": "The customer's wallets and balances.", "operationId": "get_customers_id_wallets", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "wallets:read" } }, "/customers/{id}/accounts": { "post": { "tags": [ "Custody" ], "summary": "Open a fiat account.", "operationId": "post_customers_id_accounts", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ currency, country }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "accounts:write" }, "get": { "tags": [ "Custody" ], "summary": "The customer's fiat accounts.", "operationId": "get_customers_id_accounts", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "accounts:read" } }, "/customers/{id}/bank-link": { "post": { "tags": [ "Custody" ], "summary": "Link an external bank account.", "operationId": "post_customers_id_bank_link", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ account_number, routing, country }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "accounts:write" } }, "/customers/{id}/cards": { "post": { "tags": [ "Custody" ], "summary": "Issue a card against an account.", "operationId": "post_customers_id_cards", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ account_id }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "cards:write" }, "get": { "tags": [ "Custody" ], "summary": "The customer's cards.", "operationId": "get_customers_id_cards", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "cards:read" } }, "/customers/{id}/memos": { "post": { "tags": [ "Custody" ], "summary": "A deposit memo, for chains where one shared address serves everybody.", "operationId": "post_customers_id_memos", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ chain, currency }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "accounts:write" }, "get": { "tags": [ "Custody" ], "summary": "The customer's deposit memos. A payer who omits the memo cannot be attributed.", "operationId": "get_customers_id_memos", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "accounts:read" } }, "/customers/{id}/payees": { "post": { "tags": [ "Paying out" ], "summary": "Add a destination for money.", "operationId": "post_customers_id_payees", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ name, rail, details }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payees:write" }, "get": { "tags": [ "Paying out" ], "summary": "The customer's payees.", "operationId": "get_customers_id_payees", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payees:read" } }, "/payouts/quote": { "post": { "tags": [ "Paying out" ], "summary": "What a payout would cost, at a rate held briefly.", "operationId": "post_payouts_quote", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ from, to, amount, payee_id }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payouts:write" } }, "/payouts": { "post": { "tags": [ "Paying out" ], "summary": "Send money to a payee.", "operationId": "post_payouts", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ payee_id, amount, currency, quote_id? }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payouts:write" }, "get": { "tags": [ "Paying out" ], "summary": "Payouts this project has made.", "operationId": "get_payouts", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payouts:read" } }, "/payouts/{id}": { "get": { "tags": [ "Paying out" ], "summary": "One payout and where it has got to.", "operationId": "get_payouts_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payouts:read" }, "delete": { "tags": [ "Paying out" ], "summary": "Cancel a payout that has not left yet.", "operationId": "delete_payouts_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payouts:write" } }, "/rates": { "get": { "tags": [ "Paying out" ], "summary": "The rate between two currencies. `?from=&to=`", "operationId": "get_rates", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "*" } }, "/customers/{id}/standing-orders": { "post": { "tags": [ "Standing conversion" ], "summary": "Convert on a schedule.", "operationId": "post_customers_id_standing_orders", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ from, to, amount, cadence }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "standing_orders:write" }, "get": { "tags": [ "Standing conversion" ], "summary": "The customer's standing orders.", "operationId": "get_customers_id_standing_orders", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "standing_orders:read" } }, "/events": { "get": { "tags": [ "Events and webhooks" ], "summary": "What has happened, newest first.", "operationId": "get_events", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "events:read" } }, "/events/{id}/replay": { "post": { "tags": [ "Events and webhooks" ], "summary": "Deliver an event again, to every endpoint that wanted it.", "operationId": "post_events_id_replay", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "events:write" } }, "/webhooks": { "post": { "tags": [ "Events and webhooks" ], "summary": "Register an endpoint.", "operationId": "post_webhooks", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ url, event_types }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "webhooks:write" }, "get": { "tags": [ "Events and webhooks" ], "summary": "The endpoints this project has registered.", "operationId": "get_webhooks", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "webhooks:read" } }, "/webhooks/{id}": { "patch": { "tags": [ "Events and webhooks" ], "summary": "Change an endpoint's URL, events or status.", "operationId": "patch_webhooks_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ url?, event_types?, status? }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "webhooks:write" }, "delete": { "tags": [ "Events and webhooks" ], "summary": "Remove an endpoint.", "operationId": "delete_webhooks_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "webhooks:write" } }, "/checkout-sessions": { "post": { "tags": [ "Accepting payments" ], "summary": "Start a hosted checkout for a payer.", "operationId": "post_checkout_sessions", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ customer_id, amount | line_items, currency, success_url, cancel_url?, methods?, capture?, save_method?, payer_id? | payer?, expires_at?, reference?, metadata?, ui? }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:write" }, "get": { "tags": [ "Accepting payments" ], "summary": "Checkout sessions, newest first. `?customer_id=&status=`", "operationId": "get_checkout_sessions", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:read" } }, "/checkout-sessions/{id}": { "get": { "tags": [ "Accepting payments" ], "summary": "One session. While open, this also asks the processor so a missed webhook cannot mislead.", "operationId": "get_checkout_sessions_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:read" } }, "/checkout-sessions/{id}/expire": { "post": { "tags": [ "Accepting payments" ], "summary": "Close an open session so it can no longer be paid.", "operationId": "post_checkout_sessions_id_expire", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:write" } }, "/payment-links": { "post": { "tags": [ "Accepting payments" ], "summary": "A reusable or single-use link to a hosted checkout for a fixed amount.", "operationId": "post_payment_links", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ customer_id, amount, currency, description?, reusable?, max_uses?, expires_at?, reference?, success_url? }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:write" }, "get": { "tags": [ "Accepting payments" ], "summary": "Payment links, newest first.", "operationId": "get_payment_links", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:read" } }, "/payment-links/{id}": { "get": { "tags": [ "Accepting payments" ], "summary": "One payment link, with how many times it has been used.", "operationId": "get_payment_links_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:read" }, "patch": { "tags": [ "Accepting payments" ], "summary": "Pause, resume or disable a link.", "operationId": "patch_payment_links_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ status }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:write" } }, "/payments": { "get": { "tags": [ "Accepting payments" ], "summary": "Payments, newest first. `?customer_id=&status=&reference=`", "operationId": "get_payments", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:read" }, "post": { "tags": [ "Accepting payments" ], "summary": "Charge a saved method with the payer absent, under the mandate they gave. Needs an Idempotency-Key.", "operationId": "post_payments", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ customer_id, payer_id, payment_method_id, amount, currency, off_session: true, capture?, reference?, description?, metadata? }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:write" } }, "/payments/{id}": { "get": { "tags": [ "Accepting payments" ], "summary": "One payment: status, fee, amounts received and refunded.", "operationId": "get_payments_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:read" } }, "/payments/{id}/capture": { "post": { "tags": [ "Accepting payments" ], "summary": "Collect funds that were held. May capture less than the hold.", "operationId": "post_payments_id_capture", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ amount? }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:write" } }, "/payments/{id}/cancel": { "post": { "tags": [ "Accepting payments" ], "summary": "Release a hold, or abandon a payment that has not succeeded.", "operationId": "post_payments_id_cancel", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:write" } }, "/payments/{id}/refunds": { "post": { "tags": [ "Accepting payments" ], "summary": "Refund all or part of a payment. Needs an Idempotency-Key.", "operationId": "post_payments_id_refunds", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ amount?, reason? }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "refunds:write" }, "get": { "tags": [ "Accepting payments" ], "summary": "Refunds made against a payment.", "operationId": "get_payments_id_refunds", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:read" } }, "/disputes": { "get": { "tags": [ "Accepting payments" ], "summary": "Disputes against payments, newest first. `?customer_id=&status=`", "operationId": "get_disputes", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:read" } }, "/disputes/{id}": { "get": { "tags": [ "Accepting payments" ], "summary": "One dispute, with the date evidence is due.", "operationId": "get_disputes_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:read" } }, "/disputes/{id}/evidence": { "post": { "tags": [ "Accepting payments" ], "summary": "Send written evidence, and submit it when complete.", "operationId": "post_disputes_id_evidence", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ evidence: { ... }, submit? }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:write" } }, "/settlements": { "get": { "tags": [ "Accepting payments" ], "summary": "Card proceeds on their way to the business's bank, newest first. `?customer_id=`", "operationId": "get_settlements", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "settlements:read" }, "post": { "tags": [ "Accepting payments" ], "summary": "Send proceeds to the business's bank now. Needs an Idempotency-Key.", "operationId": "post_settlements", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ customer_id, amount, currency }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "settlements:write" } }, "/settlements/{id}": { "get": { "tags": [ "Accepting payments" ], "summary": "One settlement.", "operationId": "get_settlements_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "settlements:read" } }, "/customers/{id}/balances": { "get": { "tags": [ "Accepting payments" ], "summary": "What the customer holds per currency: card proceeds (available, pending) and stablecoin.", "operationId": "get_customers_id_balances", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "customers:read" } }, "/payers": { "post": { "tags": [ "Payers, saved methods and subscriptions" ], "summary": "Record someone who pays a customer.", "operationId": "post_payers", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ customer_id, email?, name?, external_id? }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:write" }, "get": { "tags": [ "Payers, saved methods and subscriptions" ], "summary": "Payers, newest first. `?customer_id=`", "operationId": "get_payers", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:read" } }, "/payers/{id}": { "get": { "tags": [ "Payers, saved methods and subscriptions" ], "summary": "One payer.", "operationId": "get_payers_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:read" } }, "/payers/{id}/payment-methods": { "get": { "tags": [ "Payers, saved methods and subscriptions" ], "summary": "Methods the payer saved: brand, last four, expiry, and the mandate.", "operationId": "get_payers_id_payment_methods", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:read" } }, "/payers/{id}/payment-methods/{method_id}": { "delete": { "tags": [ "Payers, saved methods and subscriptions" ], "summary": "Forget a saved method and revoke its mandate.", "operationId": "delete_payers_id_payment_methods_method_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "method_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:write" } }, "/customers/{id}/payment-method-setups": { "post": { "tags": [ "Payers, saved methods and subscriptions" ], "summary": "A hosted page where a payer saves a method for later, without paying now.", "operationId": "post_customers_id_payment_method_setups", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ payer_id | payer, success_url, cancel_url }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:write" } }, "/subscriptions": { "post": { "tags": [ "Payers, saved methods and subscriptions" ], "summary": "Charge a payer on a schedule from a saved method. Needs an Idempotency-Key.", "operationId": "post_subscriptions", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ customer_id, payer_id, payment_method_id, currency, interval, interval_count?, items: [{ name, amount, quantity? }], trial_days?, reference? }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:write" }, "get": { "tags": [ "Payers, saved methods and subscriptions" ], "summary": "Subscriptions, newest first. `?customer_id=&status=`", "operationId": "get_subscriptions", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:read" } }, "/subscriptions/{id}": { "get": { "tags": [ "Payers, saved methods and subscriptions" ], "summary": "One subscription.", "operationId": "get_subscriptions_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:read" } }, "/subscriptions/{id}/cancel": { "post": { "tags": [ "Payers, saved methods and subscriptions" ], "summary": "End a subscription now or at the end of the paid period.", "operationId": "post_subscriptions_id_cancel", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ at_period_end? }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:write" } }, "/spend-policies": { "post": { "tags": [ "Limits, agents and approvals" ], "summary": "Limit a key or an agent.", "operationId": "post_spend_policies", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ customer_id, approved_by, key_id? | agent_id?, max_amount?, daily_max?, monthly_max?, approval_above?, currencies?, operations?, payee_allow_list?, expires_at? }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "policies:write" }, "get": { "tags": [ "Limits, agents and approvals" ], "summary": "Policies, newest first. `?customer_id=&key_id=&status=`", "operationId": "get_spend_policies", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "policies:read" } }, "/spend-policies/{id}": { "get": { "tags": [ "Limits, agents and approvals" ], "summary": "One policy.", "operationId": "get_spend_policies_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "policies:read" }, "patch": { "tags": [ "Limits, agents and approvals" ], "summary": "Change a policy's amounts or expiry. Who it binds cannot change.", "operationId": "patch_spend_policies_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ max_amount?, daily_max?, monthly_max?, approval_above?, expires_at? }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "policies:write" } }, "/spend-policies/{id}/revoke": { "post": { "tags": [ "Limits, agents and approvals" ], "summary": "Revoke a policy, immediately.", "operationId": "post_spend_policies_id_revoke", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ reason? }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "policies:write" } }, "/approvals": { "get": { "tags": [ "Limits, agents and approvals" ], "summary": "Operations held for a person to approve. `?status=pending`", "operationId": "get_approvals", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "approvals:read" } }, "/approvals/{id}": { "get": { "tags": [ "Limits, agents and approvals" ], "summary": "One held operation, as it was asked.", "operationId": "get_approvals_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "approvals:read" } }, "/approvals/{id}/approve": { "post": { "tags": [ "Limits, agents and approvals" ], "summary": "Approve a held operation and run it once. The approving key must not be the one that asked.", "operationId": "post_approvals_id_approve", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ note? }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "approvals:write" } }, "/approvals/{id}/deny": { "post": { "tags": [ "Limits, agents and approvals" ], "summary": "Refuse a held operation.", "operationId": "post_approvals_id_deny", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ note? }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "approvals:write" } }, "/customers/{id}/limits": { "get": { "tags": [ "Limits, agents and approvals" ], "summary": "What the calling key may still move, per window.", "operationId": "get_customers_id_limits", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "customers:read" } }, "/conversions/quote": { "post": { "tags": [ "Conversion and ledger" ], "summary": "A priced offer to convert, valid for a short time and usable once.", "operationId": "post_conversions_quote", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ customer_id, from: { currency, wallet_id }, to: { currency, wallet_id | payee_id }, amount }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "conversions:write" } }, "/conversions": { "post": { "tags": [ "Conversion and ledger" ], "summary": "Execute a quote. Needs an Idempotency-Key.", "operationId": "post_conversions", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ quote_id }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "conversions:write" }, "get": { "tags": [ "Conversion and ledger" ], "summary": "Conversions, newest first. `?customer_id=`", "operationId": "get_conversions", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "conversions:read" } }, "/conversions/{id}": { "get": { "tags": [ "Conversion and ledger" ], "summary": "One conversion and whether it has settled.", "operationId": "get_conversions_id", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "conversions:read" } }, "/customers/{id}/ledger": { "get": { "tags": [ "Conversion and ledger" ], "summary": "Double-entry entries for a period, as JSON or CSV. `?from=&to=&kind=&format=csv`", "operationId": "get_customers_id_ledger", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "ledger:read" } }, "/sandbox/checkout-sessions/{id}/complete": { "post": { "tags": [ "Sandbox" ], "summary": "Act as the payer: succeed, decline, run short of funds, or open a dispute.", "operationId": "post_sandbox_checkout_sessions_id_complete", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ outcome }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "payments:write" } }, "/coins": { "get": { "tags": [ "Rewards and reporting" ], "summary": "The stablecoins this project can hold.", "operationId": "get_coins", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "*" }, "post": { "tags": [ "Rewards and reporting" ], "summary": "Enable a coin for this project.", "operationId": "post_coins", "security": [ { "bearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" }, "example": "{ currency }" } } }, "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "*" } }, "/coins/{currency}/rewards": { "get": { "tags": [ "Rewards and reporting" ], "summary": "What a balance in this coin earns.", "operationId": "get_coins_currency_rewards", "security": [ { "bearerAuth": [] } ], "parameters": [ { "name": "currency", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "*" } }, "/usage": { "get": { "tags": [ "Rewards and reporting" ], "summary": "Usage against the plan's limits — the same count a call is refused against.", "operationId": "get_usage", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "*" } }, "/compliance-requests": { "get": { "tags": [ "Rewards and reporting" ], "summary": "Anything compliance has asked a customer for.", "operationId": "get_compliance_requests", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "Success." }, "202": { "description": "requires_approval — Not an error: the operation is held for a person. The body names the approval." }, "400": { "description": "idempotency_key_required — This call moves money; send an Idempotency-Key so a retry cannot act twice." }, "401": { "description": "key_revoked — The key was revoked in the console. Issue another." }, "402": { "description": "payment_failed — The payer's bank or card refused. `detail.reason` says why in plain terms." }, "403": { "description": "self_approval — The key that asked for an operation cannot approve it." }, "404": { "description": "not_found — No such object in this project — including one that belongs to somebody else." }, "409": { "description": "capability_coming_soon — Built, not yet switched on for this project." }, "429": { "description": "rate_limited — Too many requests on this key. `Retry-After` says when to try again." }, "500": { "description": "internal_error — Ours. Quote the `request_id` and we can find the call." }, "502": { "description": "platform_error — A provider failed. Safe to retry with the same Idempotency-Key." } }, "x-scope": "customers:read" } } } }