{ "openapi": "3.1.0", "info": { "title": "uCrypto merchant API", "version": "2026-10-22", "description": "Every route the payment API service answers today (API-001), in API version 2026-10-22, the launch version. Every answer names the version that served it in a UQT-Version header; a request may choose a known version with the same header, and otherwise is answered in its API key's version. Amounts are whole numbers of minor units, sent as strings of digits. Tested against the service by tests/integration/api/contract.test.ts; see docs/reference/api.md." }, "servers": [{ "url": "/", "description": "Sandbox; not yet running in any environment" }], "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Your API key; the list names the scope the route needs." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "pattern": "^\\S{1,128}$", "examples": ["order-1001-try-1"] } }, "IntentId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "examples": ["00000000-0000-4000-8000-000000000001"] } }, "ApiKeyId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "examples": ["2"] } }, "WebhookEndpointId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "examples": ["1"] } }, "EventId": { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "examples": ["00000000-0000-4000-8000-000000000002"] } } }, "schemas": { "Amount": { "type": "string", "pattern": "^-?(0|[1-9][0-9]*)$", "description": "Minor units as a string of digits." }, "Unit": { "type": "string", "enum": ["UQT.USD", "UQT.EUR"] }, "Time": { "type": "string", "format": "date-time" }, "Error": { "type": "object", "additionalProperties": false, "required": ["error"], "properties": { "error": { "type": "object", "additionalProperties": false, "required": ["code", "message", "doc_url", "request_id"], "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string", "description": "The request field at fault (a body field, query parameter or header), sent only when one field caused the error." }, "doc_url": { "type": "string", "description": "The code's own entry in the error reference, https://ucrypto.co/developers/errors.html#." }, "request_id": { "type": "string" } } } } }, "Health": { "type": "object", "additionalProperties": false, "required": ["status"], "properties": { "status": { "type": "string", "enum": ["ok"] } } }, "Balances": { "type": "object", "additionalProperties": false, "required": ["balances"], "properties": { "balances": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["unit", "available"], "properties": { "unit": { "$ref": "#/components/schemas/Unit" }, "available": { "$ref": "#/components/schemas/Amount" } } } } } }, "Transactions": { "type": "object", "additionalProperties": false, "required": ["data", "next_cursor"], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "type", "unit", "amount", "created_at", "notice_no", "order_ref", "fee" ], "properties": { "id": { "type": "string", "pattern": "^[0-9]+$" }, "type": { "type": "string" }, "unit": { "$ref": "#/components/schemas/Unit" }, "amount": { "$ref": "#/components/schemas/Amount" }, "created_at": { "$ref": "#/components/schemas/Time" }, "notice_no": { "type": ["string", "null"] }, "order_ref": { "type": ["string", "null"] }, "fee": { "$ref": "#/components/schemas/Amount" } } } }, "next_cursor": { "type": ["string", "null"], "pattern": "^[0-9]+$" } } }, "Statements": { "type": "object", "additionalProperties": false, "required": ["month", "data"], "properties": { "month": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}$" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "unit", "currency", "face_value", "opening_balance", "redemptions", "fees", "reversals", "payouts", "closing_balance" ], "properties": { "unit": { "$ref": "#/components/schemas/Unit" }, "currency": { "type": "string", "enum": ["USD", "EUR"] }, "face_value": { "type": "string", "pattern": "^0\\.01$", "description": "What one token is worth in the currency." }, "opening_balance": { "$ref": "#/components/schemas/Amount" }, "redemptions": { "$ref": "#/components/schemas/Amount" }, "fees": { "$ref": "#/components/schemas/Amount" }, "reversals": { "$ref": "#/components/schemas/Amount" }, "payouts": { "$ref": "#/components/schemas/Amount" }, "closing_balance": { "$ref": "#/components/schemas/Amount" } } } } } }, "CheckoutSales": { "type": "object", "additionalProperties": false, "required": ["month", "data"], "properties": { "month": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}$" }, "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "sold_at", "unit", "currency", "amount", "credited", "spent_with_you", "spent_elsewhere", "not_yet_spent", "refunded" ], "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "sold_at": { "$ref": "#/components/schemas/Time" }, "unit": { "type": "string", "pattern": "^UQT\\.[A-Z]{3}$" }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "amount": { "$ref": "#/components/schemas/Amount", "description": "Tokens the customer bought at your checkout." }, "credited": { "type": "boolean", "enum": [false], "description": "Always false: you are credited only for tokens spent with you, as redemptions." }, "spent_with_you": { "$ref": "#/components/schemas/Amount" }, "spent_elsewhere": { "$ref": "#/components/schemas/Amount", "description": "Spent with other merchants, added up; which merchants is never given." }, "not_yet_spent": { "$ref": "#/components/schemas/Amount" }, "refunded": { "$ref": "#/components/schemas/Amount", "description": "Refunded to the customer's card, charged back or reversed." } } } } } }, "NewRedemptionIntent": { "type": "object", "required": ["amount", "unit", "order_ref", "return_url"], "properties": { "amount": { "type": ["integer", "string"], "description": "Minor units above zero, below 2^53.", "examples": ["2000"] }, "unit": { "$ref": "#/components/schemas/Unit" }, "order_ref": { "type": "string", "minLength": 1, "maxLength": 200, "examples": ["order-1001"] }, "return_url": { "type": "string", "maxLength": 2048, "description": "An https address on your verified domain.", "examples": ["https://shop.example/thanks"] } } }, "RedemptionIntent": { "type": "object", "additionalProperties": false, "required": [ "id", "unit", "amount", "order_ref", "return_url", "status", "created_at", "expires_at", "confirmed_at", "cancelled_at" ], "properties": { "id": { "type": "string", "format": "uuid" }, "unit": { "$ref": "#/components/schemas/Unit" }, "amount": { "$ref": "#/components/schemas/Amount" }, "order_ref": { "type": "string" }, "return_url": { "type": "string" }, "status": { "type": "string", "enum": ["open", "confirmed", "cancelled", "expired"] }, "created_at": { "$ref": "#/components/schemas/Time" }, "expires_at": { "$ref": "#/components/schemas/Time" }, "confirmed_at": { "type": ["string", "null"], "format": "date-time" }, "cancelled_at": { "type": ["string", "null"], "format": "date-time" } } }, "NewReversal": { "type": "object", "required": ["amount"], "properties": { "amount": { "type": ["integer", "string"], "description": "Minor units above zero, below 2^53: all or part of what the customer paid.", "examples": ["500"] } } }, "Reversal": { "type": "object", "additionalProperties": false, "required": ["id", "redemption_intent", "notice_no", "unit", "amount", "status"], "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "redemption_intent": { "type": "string", "format": "uuid" }, "notice_no": { "type": "string" }, "unit": { "$ref": "#/components/schemas/Unit" }, "amount": { "$ref": "#/components/schemas/Amount" }, "status": { "type": "string", "enum": ["pending", "completed"] } } }, "NewPayout": { "type": "object", "required": ["unit", "amount", "bank_account"], "properties": { "unit": { "$ref": "#/components/schemas/Unit" }, "amount": { "type": ["integer", "string"], "description": "Minor units above zero, below 2^53, from your available balance.", "examples": ["2000"] }, "bank_account": { "type": "string", "minLength": 1, "maxLength": 200, "description": "The payment provider's reference for one of your verified bank accounts.", "examples": ["SANDBOX-ACCOUNT"] } } }, "Payout": { "type": "object", "additionalProperties": false, "required": ["id", "unit", "amount", "fee", "net_payout", "bank_account", "status"], "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "unit": { "$ref": "#/components/schemas/Unit" }, "amount": { "$ref": "#/components/schemas/Amount" }, "fee": { "$ref": "#/components/schemas/Amount" }, "net_payout": { "$ref": "#/components/schemas/Amount" }, "bank_account": { "type": "string" }, "status": { "type": "string", "enum": ["pending", "processing", "failed"] } } }, "Payouts": { "type": "object", "additionalProperties": false, "required": ["data", "next_cursor"], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "unit", "amount", "fee", "net_payout", "bank_account", "status", "created_at", "updated_at" ], "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "unit": { "$ref": "#/components/schemas/Unit" }, "amount": { "$ref": "#/components/schemas/Amount" }, "fee": { "$ref": "#/components/schemas/Amount" }, "net_payout": { "$ref": "#/components/schemas/Amount" }, "bank_account": { "type": ["string", "null"] }, "status": { "type": "string", "enum": ["processing", "pending", "paid", "failed", "returned"] }, "created_at": { "$ref": "#/components/schemas/Time" }, "updated_at": { "$ref": "#/components/schemas/Time" } } } }, "next_cursor": { "type": ["string", "null"], "pattern": "^[0-9]+$" } } }, "Disputes": { "type": "object", "additionalProperties": false, "required": ["data", "next_cursor"], "properties": { "data": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "id", "receipt_no", "amount", "currency", "status", "deadline", "received_at" ], "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 200, "description": "Names the dispute; the cursor for the next page." }, "receipt_no": { "type": "string" }, "amount": { "$ref": "#/components/schemas/Amount", "description": "The disputed amount, in the card currency's minor units." }, "currency": { "type": "string", "pattern": "^[A-Z]{3}$" }, "status": { "type": "string", "enum": ["open", "won", "lost"] }, "deadline": { "type": ["string", "null"], "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "description": "The day (UTC) uCrypto must answer the dispute by; null when the market sets none." }, "received_at": { "$ref": "#/components/schemas/Time" } } } }, "next_cursor": { "type": ["string", "null"], "minLength": 1, "maxLength": 200 } } }, "ApiKey": { "type": "object", "additionalProperties": false, "required": ["id", "mode", "scopes", "created_at", "revoked_at"], "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "mode": { "enum": ["sandbox", "live"], "description": "A sandbox key works only until the account goes live; a live key only after." }, "scopes": { "type": "array", "items": { "type": "string" } }, "created_at": { "$ref": "#/components/schemas/Time" }, "revoked_at": { "type": ["string", "null"], "format": "date-time" } } }, "ApiKeys": { "type": "object", "additionalProperties": false, "required": ["data"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKey" } } } }, "SimulatedEventRequest": { "type": "object", "additionalProperties": false, "required": ["type"], "properties": { "type": { "enum": [ "token.purchased", "token.redeemed", "redemption.reversed", "payout.paid", "payout.failed", "dispute.opened", "dispute.closed" ] } } }, "SimulatedEvent": { "type": "object", "additionalProperties": false, "required": ["id", "type", "simulated", "endpoints"], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "enum": [ "token.purchased", "token.redeemed", "redemption.reversed", "payout.paid", "payout.failed", "dispute.opened", "dispute.closed" ] }, "simulated": { "enum": [true] }, "endpoints": { "type": "integer", "minimum": 0 } } }, "NewApiKey": { "type": "object", "additionalProperties": false, "required": ["scopes"], "properties": { "scopes": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "pattern": "^[a-z_]{1,32}$", "examples": ["read"] } } } }, "CreatedApiKey": { "type": "object", "additionalProperties": false, "required": ["id", "mode", "scopes", "created_at", "revoked_at", "key"], "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "mode": { "enum": ["sandbox", "live"], "description": "The calling key's mode: a sandbox key makes sandbox keys, a live key live keys." }, "scopes": { "type": "array", "items": { "type": "string" } }, "created_at": { "$ref": "#/components/schemas/Time" }, "revoked_at": { "type": ["string", "null"], "format": "date-time" }, "key": { "type": ["string", "null"], "description": "The new API key, shown only in the first answer; null when the call is repeated with the same Idempotency-Key." } } }, "WebhookEventType": { "type": "string", "enum": [ "token.purchased", "token.redeemed", "redemption.reversed", "payout.paid", "payout.failed", "dispute.opened", "dispute.closed" ] }, "WebhookEndpoint": { "type": "object", "additionalProperties": false, "required": ["id", "url", "event_types", "created_at", "removed_at"], "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "url": { "type": "string" }, "event_types": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "created_at": { "$ref": "#/components/schemas/Time" }, "removed_at": { "type": ["string", "null"], "format": "date-time" } } }, "WebhookEndpoints": { "type": "object", "additionalProperties": false, "required": ["data"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "NewWebhookEndpoint": { "type": "object", "additionalProperties": false, "required": ["url", "event_types"], "properties": { "url": { "type": "string", "maxLength": 2048, "pattern": "^https://", "description": "Where to deliver events: an https:// address.", "examples": ["https://shop.example/uqt-webhooks"] }, "event_types": { "type": "array", "minItems": 1, "maxItems": 7, "items": { "$ref": "#/components/schemas/WebhookEventType" } } } }, "CreatedWebhookEndpoint": { "type": "object", "additionalProperties": false, "required": ["id", "url", "event_types", "created_at", "removed_at", "signing_secret"], "properties": { "id": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "url": { "type": "string" }, "event_types": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEventType" } }, "created_at": { "$ref": "#/components/schemas/Time" }, "removed_at": { "type": ["string", "null"], "format": "date-time" }, "signing_secret": { "type": ["string", "null"], "description": "The endpoint's signing secret (whsec_…), shown only in the first answer; null when the call is repeated with the same Idempotency-Key." } } }, "WebhookEvent": { "type": "object", "additionalProperties": false, "required": ["id", "type", "created_at", "data"], "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "$ref": "#/components/schemas/WebhookEventType" }, "created_at": { "$ref": "#/components/schemas/Time" }, "data": { "type": "object", "description": "The event's data, exactly as it is delivered to your endpoints." } } }, "WebhookEvents": { "type": "object", "additionalProperties": false, "required": ["data", "next_cursor"], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "next_cursor": { "type": ["string", "null"] } } }, "ReplayedEvent": { "type": "object", "additionalProperties": false, "required": ["id", "endpoints"], "properties": { "id": { "type": "string", "format": "uuid" }, "endpoints": { "type": "integer", "minimum": 0, "description": "How many of your active endpoints that chose this event's type it was queued for." } } } } }, "paths": { "/v1/health": { "get": { "operationId": "health", "summary": "Check the service and its database are answering", "responses": { "200": { "description": "Healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } }, "503": { "description": "service_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/balances": { "get": { "operationId": "listBalances", "summary": "Your token balances", "security": [{ "apiKey": ["read"] }], "responses": { "200": { "description": "Balances", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balances" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/transactions": { "get": { "operationId": "listTransactions", "summary": "Your transactions, newest first, a page at a time", "security": [{ "apiKey": ["read"] }], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of transactions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transactions" } } } }, "400": { "description": "invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/statements": { "get": { "operationId": "listStatements", "summary": "Your monthly statement, one per token unit, computed from the ledger", "security": [{ "apiKey": ["read"] }], "parameters": [ { "name": "month", "in": "query", "description": "The calendar month (UTC), YYYY-MM. Defaults to this month.", "schema": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}$" } } ], "responses": { "200": { "description": "The month's statements", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Statements" } } } }, "400": { "description": "invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/checkout-sales": { "get": { "operationId": "listCheckoutSales", "summary": "Tokens customers bought at your checkout, and what has become of them", "security": [{ "apiKey": ["read"] }], "parameters": [ { "name": "month", "in": "query", "description": "The calendar month (UTC) the sales were made in, YYYY-MM. Defaults to this month.", "schema": { "type": "string", "pattern": "^[0-9]{4}-[0-9]{2}$" } } ], "responses": { "200": { "description": "The month's checkout sales, newest first", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSales" } } } }, "400": { "description": "invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/redemption_intents": { "post": { "operationId": "createRedemptionIntent", "summary": "Ask a customer to pay you in tokens", "security": [{ "apiKey": ["redeem"] }], "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewRedemptionIntent" } } } }, "responses": { "201": { "description": "The new intent, open", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionIntent" } } } }, "400": { "description": "invalid_json, invalid_number, invalid_amount, invalid_parameter, missing_idempotency_key, invalid_idempotency_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_key_in_use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "idempotency_key_reused, return_url_not_verified, merchant_not_eligible, currency_not_accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/redemption_intents/{id}": { "get": { "operationId": "getRedemptionIntent", "summary": "One of your redemption intents", "security": [{ "apiKey": ["read"] }], "parameters": [{ "$ref": "#/components/parameters/IntentId" }], "responses": { "200": { "description": "The intent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionIntent" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/redemption_intents/{id}/cancel": { "post": { "operationId": "cancelRedemptionIntent", "summary": "Cancel an open intent", "security": [{ "apiKey": ["redeem"] }], "parameters": [ { "$ref": "#/components/parameters/IntentId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The intent, cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedemptionIntent" } } } }, "400": { "description": "invalid_json, invalid_number, missing_idempotency_key, invalid_idempotency_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "redemption_intent_not_open, idempotency_key_in_use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "idempotency_key_reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/redemption_intents/{id}/reverse": { "post": { "operationId": "reverseRedemptionIntent", "summary": "Give all or part of a confirmed redemption back to the customer's wallet", "security": [{ "apiKey": ["reverse"] }], "parameters": [ { "$ref": "#/components/parameters/IntentId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewReversal" } } } }, "responses": { "200": { "description": "The reversal, pending or completed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Reversal" } } } }, "400": { "description": "invalid_json, invalid_number, invalid_amount, missing_idempotency_key, invalid_idempotency_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode, account_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "redemption_not_reversible, idempotency_key_in_use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "reversal_exceeds_redeemed, idempotency_key_reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/payouts": { "get": { "operationId": "listPayouts", "summary": "Your payouts, newest first, a page at a time", "security": [{ "apiKey": ["read"] }], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of payouts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payouts" } } } }, "400": { "description": "invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createPayout", "summary": "Ask to be paid your available balance to your bank account", "security": [{ "apiKey": ["payout"] }], "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewPayout" } } } }, "responses": { "201": { "description": "The payout, locked and waiting for the bank (pending), or, above the market's approval threshold, waiting for staff approval with nothing locked (processing)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" } } } }, "400": { "description": "invalid_json, invalid_number, invalid_amount, invalid_parameter, missing_idempotency_key, invalid_idempotency_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode, account_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_key_in_use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "idempotency_key_reused, insufficient_balance, balance_in_settlement_hold, bank_account_not_found, bank_account_blocked, currency_mismatch, merchant_not_eligible", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/disputes": { "get": { "operationId": "listDisputes", "summary": "Disputes on purchases whose tokens you received or that were made at your checkout, newest first, a page at a time", "security": [{ "apiKey": ["disputes"] }], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of disputes, for information: nothing here decides or answers one", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Disputes" } } } }, "400": { "description": "invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/api_keys": { "get": { "operationId": "listApiKeys", "summary": "List your API keys, without the keys themselves", "security": [{ "apiKey": ["keys"] }], "responses": { "200": { "description": "Every API key of yours, oldest first, revoked ones included", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeys" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createApiKey", "summary": "Add a new API key alongside your current one", "security": [{ "apiKey": ["keys"] }], "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewApiKey" } } } }, "responses": { "201": { "description": "The new key; the key itself is shown only in this answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedApiKey" } } } }, "400": { "description": "invalid_json, invalid_number, invalid_parameter, missing_idempotency_key, invalid_idempotency_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_key_in_use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "idempotency_key_reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/api_keys/{id}/revoke": { "post": { "operationId": "revokeApiKey", "summary": "Revoke another of your API keys", "security": [{ "apiKey": ["keys"] }], "parameters": [ { "$ref": "#/components/parameters/ApiKeyId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The key, revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "400": { "description": "invalid_json, invalid_number, missing_idempotency_key, invalid_idempotency_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "api_key_in_use, idempotency_key_in_use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "idempotency_key_reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sandbox/events": { "post": { "operationId": "simulateWebhookEvent", "summary": "Deliver a signed sample of a webhook event to your sandbox endpoints", "security": [{ "apiKey": ["read"] }], "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulatedEventRequest" } } } }, "responses": { "201": { "description": "The sample event, queued for each of your active endpoints", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulatedEvent" } } } }, "400": { "description": "invalid_json, invalid_number, invalid_parameter, missing_idempotency_key, invalid_idempotency_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode, sandbox_only", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_key_in_use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "idempotency_key_reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook_endpoints": { "get": { "operationId": "listWebhookEndpoints", "summary": "List your webhook endpoints, without their signing secrets", "security": [{ "apiKey": ["webhooks"] }], "responses": { "200": { "description": "Every webhook endpoint of yours, oldest first, removed ones included", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoints" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "operationId": "createWebhookEndpoint", "summary": "Add a webhook endpoint and choose the event types it receives", "security": [{ "apiKey": ["webhooks"] }], "parameters": [{ "$ref": "#/components/parameters/IdempotencyKey" }], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NewWebhookEndpoint" } } } }, "responses": { "201": { "description": "The new endpoint; its signing secret is shown only in this answer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedWebhookEndpoint" } } } }, "400": { "description": "invalid_json, invalid_number, invalid_parameter, missing_idempotency_key, invalid_idempotency_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_key_in_use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "idempotency_key_reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "service_unavailable: endpoints cannot be added until the webhook worker's key is set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook_endpoints/{id}/remove": { "post": { "operationId": "removeWebhookEndpoint", "summary": "Remove one of your webhook endpoints; nothing more is delivered to it", "security": [{ "apiKey": ["webhooks"] }], "parameters": [ { "$ref": "#/components/parameters/WebhookEndpointId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The endpoint, removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } } }, "400": { "description": "invalid_json, invalid_number, missing_idempotency_key, invalid_idempotency_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_key_in_use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "idempotency_key_reused", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/events": { "get": { "operationId": "listEvents", "summary": "List your webhook events, newest first", "security": [{ "apiKey": ["webhooks"] }], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of your webhook events", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvents" } } } }, "400": { "description": "invalid_parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/events/{id}/replay": { "post": { "operationId": "replayEvent", "summary": "Re-deliver one of your webhook events to the endpoints that chose its type", "description": "Queues the event again for each of your active endpoints that chose its type, even if it was delivered or given up. Events can be replayed for 30 days (D70); an older event is refused with 422 webhook_event_too_old and nothing is queued.", "security": [{ "apiKey": ["webhooks"] }], "parameters": [ { "$ref": "#/components/parameters/EventId" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The event is queued again", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplayedEvent" } } } }, "400": { "description": "invalid_json, invalid_number, missing_idempotency_key, invalid_idempotency_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "missing_api_key, invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, merchant_not_active, api_key_wrong_mode", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_key_in_use", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "payload_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "webhook_event_too_old, idempotency_key_reused: an event more than 30 days old cannot be replayed (D70)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } } }