{ "openapi": "3.0.3", "info": { "title": "Kaskade Payment Solution API", "version": "2.0.0", "description": "Kaskade API v2: payouts with explicit network-fee authorisation, permanent per-customer deposit addresses, recipients, disbursements and bulk disbursements. v1 (docs/api/openapi.json) keeps running unchanged. Every v2 write requires an Idempotency-Key; amounts are exact decimal strings; lists return { data, hasMore }. Customer addresses, recipients and disbursements are switched on per account." }, "servers": [ { "url": "https://kaskade.com/api/v2", "description": "Production" } ], "security": [ { "bearerAuth": [] }, { "apiKeyHeader": [] }, { "signedRequest": [] } ], "tags": [ { "name": "Payouts" }, { "name": "Customer addresses" }, { "name": "Public addresses", "description": "Your own permanent address per coin, for anyone to pay to." }, { "name": "Recipients" }, { "name": "Disbursements" }, { "name": "Bulk disbursements" } ], "paths": { "/payouts/quote": { "post": { "tags": [ "Payouts" ], "operationId": "quotePayoutV2", "summary": "Quote a payout", "description": "Reads only — reserves and sends nothing. Requires the payouts:write scope. The quote is single use and expires after about 180 seconds.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "currency": { "type": "string" }, "amount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Exact decimal string." }, "destinationId": { "type": "string", "nullable": true, "description": "An approved payout destination. Omit for your settlement wallet." }, "feeAsset": { "type": "string", "nullable": true, "description": "Asset the network fee is settled in. Defaults to the payout asset." } }, "required": [ "currency", "amount" ] } } } }, "responses": { "201": { "description": "Quoted", "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "$ref": "#/components/schemas/PayoutQuote" } } } } } }, "400": { "description": "Validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope (payouts:write), kyc_required or payouts_restricted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "The payout is not available (rail, destination, balance).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/payouts": { "post": { "tags": [ "Payouts" ], "operationId": "createPayoutV2", "summary": "Create a payout against a quote", "description": "Requires the payouts:write scope and an Idempotency-Key. Revalidates the quote, rail, destination, KYC, the fee re-priced now, the spendable balance (principal + fee reserve) and limits, then reserves in one transaction.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required on every v2 write. The same key with the same body replays the first response for 24 hours; with a different body it returns 409 idempotency_conflict." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "type": "string" }, "currency": { "type": "string" }, "amount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Exact decimal string." }, "destinationId": { "type": "string", "nullable": true }, "feeAsset": { "type": "string", "nullable": true }, "reference": { "type": "string", "maxLength": 500 }, "feeAuthorization": { "$ref": "#/components/schemas/FeeAuthorization" } }, "required": [ "quoteId", "currency", "amount", "feeAuthorization" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "payout": { "$ref": "#/components/schemas/PayoutV2" } } } } } }, "400": { "description": "invalid_request, idempotency_key_required or invalid_fee_authorization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "insufficient_scope, kyc_required or payouts_restricted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "quote_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "FEE_REQUOTE_REQUIRED (fee above maxFee or quote expired), quote_consumed, quote_mismatch, insufficient_balance, destination_* or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Payouts" ], "operationId": "listPayoutsV2", "summary": "Not supported — list with GET /api/v1/payouts", "description": "Always answers 405 not_supported. Use GET /api/v1/payouts to list, or GET /api/v2/payouts/{id}.", "responses": { "405": { "description": "not_supported.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/payouts/{id}": { "get": { "tags": [ "Payouts" ], "operationId": "getPayoutV2", "summary": "Retrieve a payout with its network fee", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Object id." } ], "responses": { "200": { "description": "The payout", "content": { "application/json": { "schema": { "type": "object", "properties": { "payout": { "$ref": "#/components/schemas/PayoutV2" } } } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/customer-addresses": { "post": { "tags": [ "Customer addresses" ], "operationId": "createCustomerAddress", "summary": "Get or create a customer's permanent address", "description": "Switched on per account (403 customer_addresses_not_enabled until then). Returns 201 when created, 200 when the customer already has one for that coin (same address).", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required on every v2 write. The same key with the same body replays the first response for 24 hours; with a different body it returns 409 idempotency_conflict." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string", "pattern": "^[A-Za-z0-9._:@-]{1,100}$" }, "payCurrency": { "type": "string" }, "label": { "type": "string", "maxLength": 100 } }, "required": [ "customerId", "payCurrency" ] } } } }, "responses": { "200": { "description": "Existing address", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerAddress": { "$ref": "#/components/schemas/CustomerAddress" } } } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerAddress": { "$ref": "#/components/schemas/CustomerAddress" } } } } } }, "400": { "description": "validation_error, currency_not_available or idempotency_key_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "customer_addresses_not_enabled or payments_disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "direct_settlement or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "unavailable — retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "unavailable — retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Customer addresses" ], "operationId": "listCustomerAddresses", "summary": "List customer addresses", "parameters": [ { "name": "customerId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this customer's addresses." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "1–100, default 50." }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "An id from the previous page." } ], "responses": { "200": { "description": "Newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerAddress" } }, "hasMore": { "type": "boolean" } } } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "customer_addresses_not_enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/customer-addresses/{id}": { "get": { "tags": [ "Customer addresses" ], "operationId": "getCustomerAddress", "summary": "Retrieve a customer address", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Object id." } ], "responses": { "200": { "description": "The address", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerAddress": { "$ref": "#/components/schemas/CustomerAddress" } } } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/public-addresses": { "post": { "tags": [ "Public addresses" ], "operationId": "createPublicAddress", "summary": "Get or create your public address for a coin", "description": "Your own permanent address per coin, for anyone to pay to. Every account has them (no switch). Returns 201 when created, 200 when you already have one for that coin (same address). Each transfer becomes its own payment with publicAddressId set and customerId null; transfers below the coin's payment minimum are not credited.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required on every v2 write. The same key with the same body replays the first response for 24 hours; with a different body it returns 409 idempotency_conflict." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payCurrency": { "type": "string" } }, "required": [ "payCurrency" ] } } } }, "responses": { "200": { "description": "Existing address", "content": { "application/json": { "schema": { "type": "object", "properties": { "publicAddress": { "$ref": "#/components/schemas/PublicAddress" } } } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "publicAddress": { "$ref": "#/components/schemas/PublicAddress" } } } } } }, "400": { "description": "validation_error, currency_not_available or idempotency_key_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "payments_disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "direct_settlement or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "unavailable — retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "unavailable — retry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Public addresses" ], "operationId": "listPublicAddresses", "summary": "List your public addresses", "responses": { "200": { "description": "Oldest first, one per coin", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/PublicAddress" } } } } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "payments_disabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recipients": { "post": { "tags": [ "Recipients" ], "operationId": "createRecipient", "summary": "Create a recipient", "description": "Scope recipients:write. 201 when created; 200 when the same reference already exists with identical details; 409 recipient_exists when the details differ.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required on every v2 write. The same key with the same body replays the first response for 24 hours; with a different body it returns 409 idempotency_conflict." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "merchantRecipientRef": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,128}$" }, "type": { "type": "string", "enum": [ "INDIVIDUAL", "BUSINESS" ] }, "name": { "type": "string" }, "email": { "type": "string" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2." }, "metadata": { "type": "object", "additionalProperties": true, "description": "Up to 2 KB, stored verbatim." } }, "required": [ "merchantRecipientRef", "type" ] } } } }, "responses": { "200": { "description": "Already exists, identical", "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient": { "$ref": "#/components/schemas/Recipient" } } } } } }, "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient": { "$ref": "#/components/schemas/Recipient" } } } } } }, "400": { "description": "Validation failed or idempotency_key_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "recipients_not_enabled or insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "recipient_exists or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Recipients" ], "operationId": "listRecipients", "summary": "List recipients", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "1–100, default 25." }, { "name": "starting_after", "in": "query", "required": false, "schema": { "type": "string" }, "description": "An id from the previous page." }, { "name": "ref", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Find by merchantRecipientRef." } ], "responses": { "200": { "description": "Newest first; addresses not included", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Recipient" } }, "hasMore": { "type": "boolean" } } } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "recipients_not_enabled or insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recipients/{id}": { "get": { "tags": [ "Recipients" ], "operationId": "getRecipient", "summary": "Retrieve a recipient with its addresses", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Object id." } ], "responses": { "200": { "description": "The recipient", "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient": { "$ref": "#/components/schemas/Recipient" } } } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "recipients_not_enabled or insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/recipients/{id}/addresses": { "post": { "tags": [ "Recipients" ], "operationId": "addRecipientAddress", "summary": "Add an address to a recipient", "description": "Scope recipients:write. Validated like a payout destination. Starts as REVIEW_REQUIRED.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Object id." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required on every v2 write. The same key with the same body replays the first response for 24 hours; with a different body it returns 409 idempotency_conflict." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "coin": { "type": "string" }, "address": { "type": "string" }, "tag": { "type": "string", "nullable": true }, "metadataRequirement": { "type": "string", "nullable": true, "enum": [ "metadata_not_required", null ], "description": "Say so explicitly when a tag/memo chain wallet has no tag." }, "ownershipType": { "type": "string", "enum": [ "MERCHANT_OWNED", "CUSTOMER_OWNED", "THIRD_PARTY", "VENDOR", "UNKNOWN" ] }, "label": { "type": "string" } }, "required": [ "coin", "address", "ownershipType" ] } } } }, "responses": { "200": { "description": "Already on file", "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/RecipientAddress" } } } } } }, "201": { "description": "Added", "content": { "application/json": { "schema": { "type": "object", "properties": { "address": { "$ref": "#/components/schemas/RecipientAddress" } } } } } }, "400": { "description": "invalid_address, invalid_destination_tag, a tag decision code, or idempotency_key_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "recipients_not_enabled or insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/disbursements/quote": { "post": { "tags": [ "Disbursements" ], "operationId": "quoteDisbursement", "summary": "Quote a disbursement", "description": "Scope disbursements:write. Reads only; single use; about 180 seconds.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipientAddressId": { "type": "string" }, "amount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Exact decimal string." }, "feeAsset": { "type": "string", "nullable": true } }, "required": [ "recipientAddressId", "amount" ] } } } }, "responses": { "201": { "description": "Quoted", "content": { "application/json": { "schema": { "type": "object", "properties": { "quote": { "$ref": "#/components/schemas/PayoutQuote" } } } } } }, "400": { "description": "invalid_request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "disbursements_not_enabled or insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "unknown_recipient_address.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "recipient_address_in_review, recipient_address_pending or recipient_address_not_payable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/disbursements": { "post": { "tags": [ "Disbursements" ], "operationId": "createDisbursement", "summary": "Create a disbursement against a quote", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required on every v2 write. The same key with the same body replays the first response for 24 hours; with a different body it returns 409 idempotency_conflict." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "quoteId": { "type": "string" }, "recipientAddressId": { "type": "string" }, "amount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Exact decimal string." }, "feeAuthorization": { "$ref": "#/components/schemas/FeeAuthorization" }, "reference": { "type": "string", "maxLength": 500 } }, "required": [ "quoteId", "recipientAddressId", "amount", "feeAuthorization" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "disbursement": { "$ref": "#/components/schemas/Disbursement" } } } } } }, "400": { "description": "invalid_request or idempotency_key_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "disbursements_not_enabled, insufficient_scope or kyc_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "unknown_recipient_address or quote_not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "FEE_REQUOTE_REQUIRED, quote_consumed, quote_mismatch, insufficient_balance, recipient_address_* or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Disbursements" ], "operationId": "listDisbursements", "summary": "List disbursements", "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100 }, "description": "1–100." }, { "name": "startingAfter", "in": "query", "required": false, "schema": { "type": "string" }, "description": "A disbursement id from the previous page (note the camelCase name)." }, { "name": "batchId", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this batch's disbursements." } ], "responses": { "200": { "description": "Newest first", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Disbursement" } }, "hasMore": { "type": "boolean" } } } } } }, "400": { "description": "invalid_cursor.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "disbursements_not_enabled or insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/disbursements/{id}": { "get": { "tags": [ "Disbursements" ], "operationId": "getDisbursement", "summary": "Retrieve a disbursement", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Object id." } ], "responses": { "200": { "description": "The disbursement", "content": { "application/json": { "schema": { "type": "object", "properties": { "disbursement": { "$ref": "#/components/schemas/Disbursement" } } } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "disbursements_not_enabled or insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/disbursements/batches": { "post": { "tags": [ "Bulk disbursements" ], "operationId": "createDisbursementBatch", "summary": "Create a bulk batch", "description": "Creates and validates the batch. Nothing is reserved or sent.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required on every v2 write. The same key with the same body replays the first response for 24 hours; with a different body it returns 409 idempotency_conflict." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "rows": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/BatchRowInput" } }, "reference": { "type": "string" } }, "required": [ "rows" ] } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "type": "object", "properties": { "batch": { "$ref": "#/components/schemas/DisbursementBatch" } } } } } }, "400": { "description": "invalid_request or idempotency_key_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "disbursements_not_enabled or insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Bulk disbursements" ], "operationId": "listDisbursementBatches", "summary": "List bulk batches", "responses": { "200": { "description": "Your batches", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/DisbursementBatch" } } } } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "disbursements_not_enabled or insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/disbursements/batches/{id}": { "get": { "tags": [ "Bulk disbursements" ], "operationId": "getDisbursementBatch", "summary": "Retrieve a batch and its rows", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Object id." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only rows in this status." }, { "name": "afterRow", "in": "query", "required": false, "schema": { "type": "integer" }, "description": "Rows after this row number." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 500 }, "description": "Rows per page, 1–500, default 100." } ], "responses": { "200": { "description": "Batch and rows", "content": { "application/json": { "schema": { "type": "object", "properties": { "batch": { "$ref": "#/components/schemas/DisbursementBatch" }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/DisbursementBatchRow" } } } } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/disbursements/batches/{id}/validate": { "post": { "tags": [ "Bulk disbursements" ], "operationId": "validateDisbursementBatch", "summary": "Continue validating a large batch", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Object id." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required on every v2 write. The same key with the same body replays the first response for 24 hours; with a different body it returns 409 idempotency_conflict." } ], "responses": { "200": { "description": "The batch", "content": { "application/json": { "schema": { "type": "object", "properties": { "batch": { "$ref": "#/components/schemas/DisbursementBatch" } } } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "disbursements_not_enabled or insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/disbursements/batches/{id}/approve": { "post": { "tags": [ "Bulk disbursements" ], "operationId": "approveDisbursementBatch", "summary": "Approve a batch (automatic API approval only)", "description": "Only for accounts where Kaskade allowed automatic API approval and the merchant chose it in the dashboard; otherwise 403 approval_requires_panel. Same checks as a person's approval: the reviewed batchHash, a fee cap per asset, and the whole batch within the spendable balance.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Object id." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required on every v2 write. The same key with the same body replays the first response for 24 hours; with a different body it returns 409 idempotency_conflict." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "batchHash": { "type": "string" }, "mode": { "type": "string", "enum": [ "send_ready_now", "wait_for_all" ] }, "feeCaps": { "type": "object", "additionalProperties": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Exact decimal string." }, "description": "Maximum network fee per row, per asset: { \"usdttrc20\": \"2.5\" }." } }, "required": [ "batchHash", "mode", "feeCaps" ] } } } }, "responses": { "200": { "description": "Approved", "content": { "application/json": { "schema": { "type": "object", "properties": { "batch": { "$ref": "#/components/schemas/DisbursementBatch" } } } } } }, "400": { "description": "fee_cap_required or invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "approval_requires_panel, disbursements_not_enabled or insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "batch_changed, insufficient_balance or idempotency conflict.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/disbursements/batches/{id}/cancel": { "post": { "tags": [ "Bulk disbursements" ], "operationId": "cancelDisbursementBatch", "summary": "Cancel the batch's unsent rows", "description": "Rows already turned into disbursements are not recalled.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Object id." }, { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required on every v2 write. The same key with the same body replays the first response for 24 hours; with a different body it returns 409 idempotency_conflict." } ], "responses": { "200": { "description": "The batch", "content": { "application/json": { "schema": { "type": "object", "properties": { "batch": { "$ref": "#/components/schemas/DisbursementBatch" } } } } } }, "401": { "description": "Missing, unknown or revoked credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "disbursements_not_enabled or insufficient_scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Authorization: Bearer ks_live_YOUR_API_KEY" }, "apiKeyHeader": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Alternative to the Authorization header. Same key." }, "signedRequest": { "type": "apiKey", "in": "header", "name": "X-Kaskade-Signature", "description": "HMAC request signing. Send X-Kaskade-Client (your key's Public ID), X-Kaskade-Timestamp (ISO-8601 UTC, within 5 minutes of server time) and X-Kaskade-Signature = base64(HMAC-SHA256(clientSecret, canonical)), where canonical = U+FEFF + METHOD + full URL + clientId + timestamp + rawBody." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "schema": { "type": "string", "maxLength": 255 }, "description": "Required on every v2 write. The same key with the same body replays the first response for 24 hours; with a different body it returns 409 idempotency_conflict." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string", "description": "Human-readable sentence. Present on every error since V1 launched." }, "code": { "$ref": "#/components/schemas/ErrorCode" }, "field": { "type": "string", "description": "The request field the refusal is about, for example `orderId` or `amountUsd`. Present on validation failures from POST /payments and POST /invoices; absent on every other error." } }, "description": "`error` is the original field and is always present. `code` is additive; older responses may omit it. `field` is additive too and appears only on validation failures." }, "NetworkFee": { "type": "object", "properties": { "paidBy": { "type": "string", "enum": [ "merchant" ], "description": "The network fee is always the merchant's; the recipient receives the full principal." }, "settlementAsset": { "type": "string", "nullable": true }, "reserved": { "type": "string", "nullable": true, "description": "Fee reserved with the payout (decimal string)." }, "actual": { "type": "string", "nullable": true, "description": "Fee actually charged, once settled." }, "settled": { "type": "boolean" } } }, "PayoutQuote": { "type": "object", "properties": { "quoteId": { "type": "string" }, "quoteVersion": { "type": "integer" }, "principal": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Exact decimal string." }, "payoutAsset": { "type": "string" }, "network": { "type": "string", "nullable": true }, "destinationId": { "type": "string", "nullable": true }, "recipientAddressId": { "type": "string", "description": "Disbursement quotes only." }, "feeSettlementAsset": { "type": "string" }, "estimatedFee": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Exact decimal string." }, "maximumAuthorizedFee": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Exact decimal string." }, "feeReserve": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Exact decimal string." }, "totalRequiredBalance": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string" }, "amount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Exact decimal string." } } } }, "recipientReceives": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Always equal to principal." }, "networkCost": { "type": "object", "properties": { "asset": { "type": "string" }, "amount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Exact decimal string." } } }, "fx": { "type": "object", "nullable": true, "properties": { "rate": { "type": "string" }, "source": { "type": "string" }, "quotedAt": { "type": "string", "format": "date-time" } } }, "railReadiness": { "type": "object", "properties": { "payoutsEnabled": { "type": "boolean" }, "status": { "type": "string", "nullable": true }, "productionProven": { "type": "boolean" } } }, "createdAt": { "type": "string", "format": "date-time" }, "expiresAt": { "type": "string", "format": "date-time", "description": "Single use; expires after about 180 seconds." } } }, "PayoutV2": { "allOf": [ { "$ref": "#/components/schemas/Payout" }, { "type": "object", "properties": { "quoteId": { "type": "string", "nullable": true }, "networkFee": { "$ref": "#/components/schemas/NetworkFee" } } } ] }, "FeeAuthorization": { "type": "object", "properties": { "accepted": { "type": "boolean", "enum": [ true ] }, "maxFee": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "The most network fee you authorise, in the fee asset. A higher fee at creation answers FEE_REQUOTE_REQUIRED and nothing is reserved." } }, "required": [ "accepted", "maxFee" ] }, "CustomerAddress": { "type": "object", "properties": { "id": { "type": "string" }, "customerId": { "type": "string", "description": "Your id for the customer." }, "payCurrency": { "type": "string" }, "network": { "type": "string", "nullable": true }, "address": { "type": "string" }, "tag": { "type": "string", "nullable": true, "description": "Memo / destination tag on chains that route by one; null otherwise." }, "label": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "ACTIVE" ], "description": "Additive enum." }, "createdAt": { "type": "string", "format": "date-time" } } }, "PublicAddress": { "type": "object", "properties": { "id": { "type": "string" }, "payCurrency": { "type": "string" }, "network": { "type": "string", "nullable": true }, "address": { "type": "string" }, "tag": { "type": "string", "nullable": true, "description": "Memo / destination tag on chains that route by one; null otherwise." }, "status": { "type": "string", "enum": [ "ACTIVE" ], "description": "Additive enum." }, "createdAt": { "type": "string", "format": "date-time" } }, "description": "Your own permanent deposit address for one coin (anyone can pay to it)." }, "RecipientAddress": { "type": "object", "properties": { "id": { "type": "string" }, "recipientId": { "type": "string" }, "coin": { "type": "string" }, "network": { "type": "string", "nullable": true }, "address": { "type": "string" }, "tag": { "type": "string", "nullable": true }, "ownershipType": { "type": "string", "enum": [ "MERCHANT_OWNED", "CUSTOMER_OWNED", "THIRD_PARTY", "VENDOR", "UNKNOWN" ] }, "label": { "type": "string", "nullable": true }, "status": { "type": "string", "enum": [ "REVIEW_REQUIRED", "APPROVED", "REJECTED", "ARCHIVED" ] }, "rejectReason": { "type": "string", "nullable": true }, "screening": { "type": "string" }, "payable": { "type": "boolean", "description": "Whether a disbursement to this address is accepted now." }, "firstUsedAt": { "type": "string", "format": "date-time", "nullable": true }, "lastUsedAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "Recipient": { "type": "object", "properties": { "id": { "type": "string" }, "merchantRecipientRef": { "type": "string" }, "type": { "type": "string", "enum": [ "INDIVIDUAL", "BUSINESS" ] }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true }, "metadata": { "type": "object", "nullable": true, "additionalProperties": true }, "status": { "type": "string" }, "createdAt": { "type": "string", "format": "date-time" }, "updatedAt": { "type": "string", "format": "date-time" }, "addresses": { "type": "array", "items": { "$ref": "#/components/schemas/RecipientAddress" }, "description": "Only on GET /recipients/{id}." } } }, "Disbursement": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "disbursement" ] }, "status": { "type": "string", "enum": [ "PENDING", "BLOCKED", "SUBMITTED", "COMPLETED", "FAILED" ] }, "recipientAddressId": { "type": "string" }, "recipientId": { "type": "string", "nullable": true }, "merchantRecipientRef": { "type": "string", "nullable": true }, "asset": { "type": "string" }, "amount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Exact decimal string." }, "recipientReceives": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Exact decimal string." }, "address": { "type": "string" }, "reference": { "type": "string", "nullable": true }, "txHash": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true }, "quoteId": { "type": "string", "nullable": true }, "batch": { "type": "object", "nullable": true, "properties": { "id": { "type": "string" }, "rowNumber": { "type": "integer" } } }, "networkFee": { "$ref": "#/components/schemas/NetworkFee" }, "createdAt": { "type": "string", "format": "date-time" }, "completedAt": { "type": "string", "format": "date-time", "nullable": true } } }, "BatchRowInput": { "type": "object", "properties": { "coin": { "type": "string" }, "address": { "type": "string" }, "amount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Exact decimal string." }, "tag": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "recipientRef": { "type": "string", "nullable": true }, "recipientName": { "type": "string", "nullable": true }, "recipientType": { "type": "string", "enum": [ "INDIVIDUAL", "BUSINESS" ] } }, "required": [ "coin", "address", "amount" ] }, "DisbursementBatch": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "disbursement_batch" ] }, "status": { "type": "string", "enum": [ "DRAFT", "VALIDATING", "VALIDATED", "APPROVED", "PROCESSING", "COMPLETED", "PARTIALLY_COMPLETED", "CANCELLED" ] }, "createdVia": { "type": "string" }, "reference": { "type": "string", "nullable": true }, "sourceFileName": { "type": "string", "nullable": true }, "sourceFileHash": { "type": "string", "nullable": true }, "rowCount": { "type": "integer" }, "rows": { "type": "object", "additionalProperties": { "type": "integer" }, "description": "Row count per row status." }, "assets": { "type": "array", "items": { "type": "object", "properties": { "asset": { "type": "string" }, "rows": { "type": "integer" }, "totalPrincipal": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Exact decimal string." }, "estimatedFeePerRow": { "type": "string", "nullable": true }, "suggestedFeeCapPerRow": { "type": "string", "nullable": true }, "approvedFeeCapPerRow": { "type": "string", "nullable": true }, "totalRequired": { "type": "string", "nullable": true }, "spendable": { "type": "string", "nullable": true }, "sufficient": { "type": "boolean", "nullable": true } } } }, "batchHash": { "type": "string", "nullable": true, "description": "Hash of the canonical payable rows. Send it back on approval." }, "mode": { "type": "string", "nullable": true, "enum": [ "send_ready_now", "wait_for_all", null ] }, "approvedAt": { "type": "string", "format": "date-time", "nullable": true }, "approvalExpiresAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" } } }, "DisbursementBatchRow": { "type": "object", "properties": { "rowNumber": { "type": "integer" }, "status": { "type": "string", "enum": [ "DRAFT", "INVALID", "READY", "WAITING_ADDRESS_REVIEW", "REJECTED_ADDRESS", "QUEUED", "CREATING", "CREATED", "FAILED", "CANCELLED" ] }, "asset": { "type": "string" }, "address": { "type": "string" }, "tag": { "type": "string", "nullable": true }, "amount": { "type": "string", "pattern": "^\\d+(\\.\\d+)?$", "description": "Exact decimal string." }, "reference": { "type": "string", "nullable": true }, "recipientRef": { "type": "string", "nullable": true }, "recipientAddressId": { "type": "string", "nullable": true }, "estimatedFee": { "type": "string", "nullable": true }, "disbursementId": { "type": "string", "nullable": true }, "errorCode": { "type": "string", "nullable": true }, "error": { "type": "string", "nullable": true } } }, "Payout": { "type": "object", "description": "A payout as the public API renders it. Emitted identically by POST /payouts, both GET routes and the payout.updated webhook.", "properties": { "id": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "approved", "submitted", "paid", "rejected", "failed" ], "description": "pending, approved and submitted are in flight. paid, rejected and failed are terminal. Only paid means money moved." }, "currency": { "type": "string", "description": "Coin/network being withdrawn, e.g. usdttrc20." }, "amount": { "type": "number", "description": "Amount in that coin." }, "address": { "type": "string", "description": "Destination wallet address the funds are sent to." }, "destinationId": { "type": "string", "nullable": true, "description": "The allowlisted payout destination used. Null means your settlement wallet for the coin." }, "destination": { "type": "string", "nullable": true, "description": "That destination's label, copied at request time so it survives the destination being deleted." }, "txHash": { "type": "string", "nullable": true, "description": "On-chain transaction hash. Null until broadcast." }, "error": { "type": "string", "nullable": true, "description": "Why it did not proceed, sanitised for publication. Null unless something went wrong." }, "reference": { "type": "string", "nullable": true, "description": "Your own free-text reference, echoed back. Not an idempotency key." }, "createdAt": { "type": "string", "format": "date-time" }, "paidAt": { "type": "string", "format": "date-time", "nullable": true, "description": "Set only once status is paid." } } }, "ErrorCode": { "type": "string", "description": "Stable machine-readable code. Treat an unrecognised value defensively.", "enum": [ "invalid_api_key", "forbidden", "validation_error", "unsupported_asset", "not_found", "payment_not_found", "payout_not_available", "kyc_required", "idempotency_conflict", "idempotency_in_progress", "upstream_unavailable", "internal_error", "invalid_request", "invalid_amount", "invalid_currency", "invalid_amount_precision", "idempotency_recovery_required", "idempotency_unavailable" ] } } }, "x-webhooks": { "recipient.address.review_required": { "post": { "summary": "recipient.address.review_required", "description": "An address was added and waits for review. Signed with x-kaskade-signature (hex HMAC-SHA256 of the raw body). Up to 9 delivery attempts, at least once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable per object and transition — de-duplicate on it." }, "event": { "type": "string", "enum": [ "recipient.address.review_required" ] }, "created": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "recipientAddress": { "$ref": "#/components/schemas/RecipientAddress" }, "recipient": { "type": "object", "properties": { "id": { "type": "string" }, "merchantRecipientRef": { "type": "string" } } } } } }, "required": [ "id", "event", "created", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx." } } } }, "recipient.address.approved": { "post": { "summary": "recipient.address.approved", "description": "The address may be paid. Signed with x-kaskade-signature (hex HMAC-SHA256 of the raw body). Up to 9 delivery attempts, at least once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable per object and transition — de-duplicate on it." }, "event": { "type": "string", "enum": [ "recipient.address.approved" ] }, "created": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "recipientAddress": { "$ref": "#/components/schemas/RecipientAddress" }, "recipient": { "type": "object", "properties": { "id": { "type": "string" }, "merchantRecipientRef": { "type": "string" } } } } } }, "required": [ "id", "event", "created", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx." } } } }, "recipient.address.rejected": { "post": { "summary": "recipient.address.rejected", "description": "The address will not be paid (rejectReason says why). Signed with x-kaskade-signature (hex HMAC-SHA256 of the raw body). Up to 9 delivery attempts, at least once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable per object and transition — de-duplicate on it." }, "event": { "type": "string", "enum": [ "recipient.address.rejected" ] }, "created": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "recipientAddress": { "$ref": "#/components/schemas/RecipientAddress" }, "recipient": { "type": "object", "properties": { "id": { "type": "string" }, "merchantRecipientRef": { "type": "string" } } } } } }, "required": [ "id", "event", "created", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx." } } } }, "disbursement.created": { "post": { "summary": "disbursement.created", "description": "Accepted; principal and fee reserved. Signed with x-kaskade-signature (hex HMAC-SHA256 of the raw body). Up to 9 delivery attempts, at least once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable per object and transition — de-duplicate on it." }, "event": { "type": "string", "enum": [ "disbursement.created" ] }, "created": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "disbursement": { "$ref": "#/components/schemas/Disbursement" } } } }, "required": [ "id", "event", "created", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx." } } } }, "disbursement.blocked": { "post": { "summary": "disbursement.blocked", "description": "The risk policy refused it; it will not be sent. Signed with x-kaskade-signature (hex HMAC-SHA256 of the raw body). Up to 9 delivery attempts, at least once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable per object and transition — de-duplicate on it." }, "event": { "type": "string", "enum": [ "disbursement.blocked" ] }, "created": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "disbursement": { "$ref": "#/components/schemas/Disbursement" } } } }, "required": [ "id", "event", "created", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx." } } } }, "disbursement.submitted": { "post": { "summary": "disbursement.submitted", "description": "Handed for sending. Signed with x-kaskade-signature (hex HMAC-SHA256 of the raw body). Up to 9 delivery attempts, at least once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable per object and transition — de-duplicate on it." }, "event": { "type": "string", "enum": [ "disbursement.submitted" ] }, "created": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "disbursement": { "$ref": "#/components/schemas/Disbursement" } } } }, "required": [ "id", "event", "created", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx." } } } }, "disbursement.completed": { "post": { "summary": "disbursement.completed", "description": "On chain. Signed with x-kaskade-signature (hex HMAC-SHA256 of the raw body). Up to 9 delivery attempts, at least once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable per object and transition — de-duplicate on it." }, "event": { "type": "string", "enum": [ "disbursement.completed" ] }, "created": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "disbursement": { "$ref": "#/components/schemas/Disbursement" } } } }, "required": [ "id", "event", "created", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx." } } } }, "disbursement.failed": { "post": { "summary": "disbursement.failed", "description": "Not sent; the reservation is released. Signed with x-kaskade-signature (hex HMAC-SHA256 of the raw body). Up to 9 delivery attempts, at least once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable per object and transition — de-duplicate on it." }, "event": { "type": "string", "enum": [ "disbursement.failed" ] }, "created": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "disbursement": { "$ref": "#/components/schemas/Disbursement" } } } }, "required": [ "id", "event", "created", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx." } } } }, "disbursement.batch.validated": { "post": { "summary": "disbursement.batch.validated", "description": "Every row has a verdict. Signed with x-kaskade-signature (hex HMAC-SHA256 of the raw body). Up to 9 delivery attempts, at least once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable per object and transition — de-duplicate on it." }, "event": { "type": "string", "enum": [ "disbursement.batch.validated" ] }, "created": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "batch": { "$ref": "#/components/schemas/DisbursementBatch" } } } }, "required": [ "id", "event", "created", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx." } } } }, "disbursement.batch.approved": { "post": { "summary": "disbursement.batch.approved", "description": "The batch was approved. Signed with x-kaskade-signature (hex HMAC-SHA256 of the raw body). Up to 9 delivery attempts, at least once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable per object and transition — de-duplicate on it." }, "event": { "type": "string", "enum": [ "disbursement.batch.approved" ] }, "created": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "batch": { "$ref": "#/components/schemas/DisbursementBatch" } } } }, "required": [ "id", "event", "created", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx." } } } }, "disbursement.batch.completed": { "post": { "summary": "disbursement.batch.completed", "description": "Every row became a disbursement or ended (also sent for PARTIALLY_COMPLETED). Signed with x-kaskade-signature (hex HMAC-SHA256 of the raw body). Up to 9 delivery attempts, at least once.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable per object and transition — de-duplicate on it." }, "event": { "type": "string", "enum": [ "disbursement.batch.completed" ] }, "created": { "type": "string", "format": "date-time" }, "data": { "type": "object", "properties": { "batch": { "$ref": "#/components/schemas/DisbursementBatch" } } } }, "required": [ "id", "event", "created", "data" ] } } } }, "responses": { "200": { "description": "Acknowledge with any 2xx." } } } } } }