{ "openapi": "3.1.0", "info": { "title": "A2A InstaPay Tenant API", "version": "1.1.0", "description": "Tenant API for A2A InstaPay (Fintechnology Asia Pacific Lanka Ltd, licensed to FINAP USA LLC). Companion to the A2A InstaPay PaaS Tenant Integration Specification v1.0 and the A2A InstaPay Tenant API Reference v1.1. Example values are illustrative and do not reflect pricing.", "contact": { "name": "FINAP USA LLC" } }, "servers": [ { "url": "{baseUrl}", "variables": { "baseUrl": { "default": "https://sandbox.api.invalid", "description": "Base URL issued with the credentials for each environment" } } } ], "security": [ { "oauth2": [ "tenant" ] } ], "tags": [ { "name": "Authentication" }, { "name": "Customers" }, { "name": "Hosted sessions" }, { "name": "Bank linking" }, { "name": "Accounts" }, { "name": "Loads" }, { "name": "Payment requests" }, { "name": "Payments" }, { "name": "Withdrawals" }, { "name": "Refunds" }, { "name": "Disputes" }, { "name": "Webhook events" }, { "name": "Reports" }, { "name": "Sandbox" } ], "paths": { "/oauth/token": { "post": { "operationId": "token", "summary": "Obtain an access token", "description": "Exchanges the Tenant's client credentials for an access token. Send the body as application/x-www-form-urlencoded. Cache the token and request a new one shortly before it expires.", "tags": [ "Authentication" ], "requestBody": { "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "grant_type": { "type": "string", "enum": [ "client_credentials" ], "description": "Always client_credentials.", "examples": [ "client_credentials" ] }, "client_id": { "type": "string", "description": "Client identifier for the environment.", "examples": [ "cli_sbx_example_01" ] }, "client_secret": { "type": "string", "description": "Client secret for the environment.", "examples": [ "sk_sbx_redacted" ] } }, "required": [ "grant_type", "client_id", "client_secret" ] }, "example": { "grant_type": "client_credentials", "client_id": "cli_sbx_example_01", "client_secret": "sk_sbx_redacted" } } } }, "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Token" }, "example": { "access_token": "at_sbx_6c1f0e9b2a7d4e8f9a0b1c2d3e4f5a6b", "token_type": "Bearer", "expires_in": 900, "scope": "tenant" } } } }, "400": { "description": "Invalid request. Error codes: parameter_missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: invalid_client.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "security": [] } }, "/v1/customers": { "post": { "operationId": "create_customer", "summary": "Register a customer", "description": "Registers a consumer or merchant and returns the customer with an onboarding session. Open the session with the SDK to start verification.", "tags": [ "Customers" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "individual", "business" ], "description": "individual for a consumer, business for a merchant.", "examples": [ "individual" ] }, "external_ref": { "type": "string", "description": "The Tenant's own reference, unique within the Tenant, up to 64 characters.", "examples": [ "member-10482" ] }, "email": { "type": "string", "description": "E-mail address.", "examples": [ "member@example.com" ] }, "mobile_number": { "type": "string", "description": "US mobile number in E.164 format.", "examples": [ "+12025550148" ] }, "prefill": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Optional values to prefill the hosted screens: first_name, last_name, or for a business legal_name. Used for an existing operation.", "examples": [ { "first_name": "Avery", "last_name": "Morgan" } ] } }, "required": [ "type", "external_ref", "email", "mobile_number" ] }, "example": { "type": "individual", "external_ref": "member-10482", "email": "member@example.com", "mobile_number": "+12025550148", "prefill": { "first_name": "Avery", "last_name": "Morgan" } } } } }, "responses": { "201": { "description": "Created", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "id": "cus_c9T2kXq4Lm", "object": "customer", "type": "individual", "external_ref": "member-10482", "email": "member@example.com", "mobile_number_last4": "4821", "business": null, "verification": { "status": "created", "updated_at": "2026-10-15T14:03:22Z", "retry_available_at": null }, "account_id": null, "pin_locked": false, "onboarding_session": { "id": "ses_1Kd7Fg3Hj8", "flow": "onboarding", "token": "st_sbx_8a3c1e7f9b2d4a6c", "expires_at": "2026-10-15T14:33:22Z" }, "created_at": "2026-10-15T14:03:22Z", "updated_at": "2026-10-15T14:03:22Z", "version": 1 } } } }, "400": { "description": "Invalid request. Error codes: idempotency_key_missing, parameter_invalid, parameter_missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Not allowed. Error codes: flow_not_enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict. Error codes: duplicate_external_ref, duplicate_mobile_number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "find_customer", "summary": "Find a customer by external reference", "description": "Returns a list containing the customer with the given external_ref, or an empty list.", "tags": [ "Customers" ], "parameters": [ { "name": "external_ref", "in": "query", "required": true, "description": "The Tenant's reference.", "schema": { "type": "string" }, "example": "member-10482" } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerList" }, "example": { "object": "list", "data": [ { "id": "cus_c9T2kXq4Lm", "object": "customer", "type": "individual", "external_ref": "member-10482", "email": "member@example.com", "mobile_number_last4": "4821", "business": null, "verification": { "status": "approved", "updated_at": "2026-10-15T14:04:10Z", "retry_available_at": null }, "account_id": "acct_c3J8vN2Qe6", "pin_locked": false, "created_at": "2026-10-15T14:03:22Z", "updated_at": "2026-10-15T14:04:10Z", "version": 3 } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "Invalid request. Error codes: parameter_missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/customers/{id}": { "get": { "operationId": "get_customer", "summary": "Retrieve a customer", "description": "Returns the customer, including verification status, account identifier and PIN lock status.", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer identifier.", "schema": { "type": "string" }, "example": "cus_c9T2kXq4Lm" } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "id": "cus_c9T2kXq4Lm", "object": "customer", "type": "individual", "external_ref": "member-10482", "email": "member@example.com", "mobile_number_last4": "4821", "business": null, "verification": { "status": "approved", "updated_at": "2026-10-15T14:04:10Z", "retry_available_at": null }, "account_id": "acct_c3J8vN2Qe6", "pin_locked": false, "created_at": "2026-10-15T14:03:22Z", "updated_at": "2026-10-15T14:04:10Z", "version": 3 } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/customers/{id}/owners": { "get": { "operationId": "list_owners", "summary": "List owners of a business", "description": "Returns the owners and control person of a business customer, with their verification status.", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Business customer identifier.", "schema": { "type": "string" }, "example": "cus_m7R5pWz1Hd" } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OwnerList" }, "example": { "object": "list", "data": [ { "id": "own_2Lp9Vc4Mz7", "object": "owner", "customer_id": "cus_m7R5pWz1Hd", "name": "Jordan Ellis", "role": "owner_and_control_person", "ownership_percent": 60, "verification_status": "approved", "invited_at": "2026-10-15T14:03:22Z", "updated_at": "2026-10-15T14:04:10Z" } ], "has_more": false, "next_cursor": null } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict. Error codes: invalid_state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/customers/{id}/documents": { "get": { "operationId": "list_documents", "summary": "List accepted customer documents", "description": "Returns the customer documents the customer has accepted or must accept, with versions and times.", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer identifier.", "schema": { "type": "string" }, "example": "cus_c9T2kXq4Lm" } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentAcceptanceList" }, "example": { "object": "list", "data": [ { "id": "dacc_3Nb6Vc9Xz2", "object": "document_acceptance", "customer_id": "cus_c9T2kXq4Lm", "document_type": "digital_account_terms", "version": "2026.10", "status": "accepted", "accepted_at": "2026-10-15T14:03:22Z", "channel": "onboarding" } ], "has_more": false, "next_cursor": null } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/customers/{id}/close": { "post": { "operationId": "close_customer", "summary": "Request account closure", "description": "Requests closure of the customer's Digital Account. The account moves to closing; the remaining balance is paid to the customer's linked account, or held where a legal or compliance hold applies. account.closed follows.", "tags": [ "Customers" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer identifier.", "schema": { "type": "string" }, "example": "cus_c9T2kXq4Lm" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "reason": { "type": "string", "enum": [ "customer_request", "tenant_request" ], "description": "Who requested the closure.", "examples": [ "customer_request" ] } }, "required": [ "reason" ] }, "example": { "reason": "customer_request" } } } }, "responses": { "202": { "description": "Accepted", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "example": { "id": "cus_c9T2kXq4Lm", "object": "customer", "type": "individual", "external_ref": "member-10482", "email": "member@example.com", "mobile_number_last4": "4821", "business": null, "verification": { "status": "approved", "updated_at": "2026-10-15T14:04:10Z", "retry_available_at": null }, "account_id": "acct_c3J8vN2Qe6", "pin_locked": false, "created_at": "2026-10-15T14:03:22Z", "updated_at": "2026-10-15T14:04:10Z", "version": 7 } } } }, "400": { "description": "Invalid request. Error codes: idempotency_key_missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict. Error codes: invalid_state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/sessions": { "post": { "operationId": "create_session", "summary": "Create a hosted session", "description": "Creates a single-use session for a hosted flow. Use it to start pin_reset, contact_change or terms_acceptance, or to replace an onboarding or payment_confirm session that expired before the customer finished.", "tags": [ "Hosted sessions" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "flow": { "type": "string", "enum": [ "onboarding", "payment_confirm", "pin_reset", "contact_change", "terms_acceptance" ], "description": "Hosted flow.", "examples": [ "pin_reset" ] }, "customer_id": { "type": "string", "description": "Customer identifier.", "examples": [ "cus_c9T2kXq4Lm" ] }, "target": { "anyOf": [ { "$ref": "#/components/schemas/Target" }, { "type": "null" } ], "description": "Record to confirm. Required for payment_confirm." }, "return_url": { "type": [ "string", "null" ], "description": "Registered return address, for mobile browsers.", "examples": [ "https://app.example.com/a2a/return" ] } }, "required": [ "flow", "customer_id" ] }, "example": { "flow": "pin_reset", "customer_id": "cus_c9T2kXq4Lm" } } } }, "responses": { "201": { "description": "Created", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Session" }, "example": { "id": "ses_6Yt2Rw9Qe4", "object": "session", "flow": "pin_reset", "customer_id": "cus_c9T2kXq4Lm", "target": null, "status": "created", "token": "st_sbx_5e1a9c3f7b2d8a4c", "return_url": "https://app.example.com/a2a/return", "expires_at": "2026-10-15T14:18:22Z", "created_at": "2026-10-15T14:03:22Z" } } } }, "400": { "description": "Invalid request. Error codes: idempotency_key_missing, parameter_missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict. Error codes: invalid_state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request cannot be processed. Error codes: account_restricted, session_invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/sessions/exchange": { "post": { "operationId": "exchange_session", "summary": "Exchange a result token", "description": "Exchanges the result token returned by the SDK for the outcome of the flow. Call it from the Tenant's server. A result token can be exchanged once. The webhook for the underlying record remains the source of truth.", "tags": [ "Hosted sessions" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "result_token": { "type": "string", "description": "Result token from the SDK.", "examples": [ "rt_sbx_7d2e9f1a3c5b" ] } }, "required": [ "result_token" ] }, "example": { "result_token": "rt_sbx_7d2e9f1a3c5b" } } } }, "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionOutcome" }, "example": { "object": "session_outcome", "session_id": "ses_8Qw3Ez5Rt2", "flow": "payment_confirm", "status": "completed", "customer_id": "cus_c9T2kXq4Lm", "verification_status": null, "target": { "type": "payment", "id": "pay_3As6Df9Gh2" }, "target_status": "completed", "terms_decision": null } } } }, "400": { "description": "Invalid request. Error codes: parameter_missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request cannot be processed. Error codes: result_token_invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/customers/{id}/link-tokens": { "post": { "operationId": "create_link_token", "summary": "Create a Plaid link token", "description": "Creates a Plaid link token bound to the customer. Open Plaid with it in the Tenant's application.", "tags": [ "Bank linking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer identifier.", "schema": { "type": "string" }, "example": "cus_c9T2kXq4Lm" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "web", "ios", "android" ], "description": "Platform on which Plaid will open: web for web applications and installed web apps, or ios or android for native applications.", "examples": [ "web" ] }, "redirect_uri": { "type": [ "string", "null" ], "description": "Required for web: the Tenant's registered bank-linking return page, to which Plaid returns after a bank's own sign-in. See section 7.", "examples": [ "https://app.example.com/bank-link/return" ] } }, "required": [ "platform" ] }, "example": { "platform": "web", "redirect_uri": "https://app.example.com/bank-link/return" } } } }, "responses": { "201": { "description": "Created", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkToken" }, "example": { "object": "link_token", "link_token": "link-sandbox-7c1f2e3d-4b5a-6c7d-8e9f-0a1b2c3d4e5f", "expiration": "2026-10-15T18:03:22Z" } } } }, "400": { "description": "Invalid request. Error codes: idempotency_key_missing, parameter_invalid, parameter_missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request cannot be processed. Error codes: account_restricted, customer_not_verified.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/customers/{id}/linked-accounts": { "post": { "operationId": "create_linked_account", "summary": "Submit a Plaid public token", "description": "Submits the public token returned by Plaid. A2A InstaPay retrieves the account, runs the ownership, account type, RTP and Request for Payment checks, and returns the linked account with status pending. linked_account.verified or linked_account.failed follows.", "tags": [ "Bank linking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer identifier.", "schema": { "type": "string" }, "example": "cus_c9T2kXq4Lm" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "public_token": { "type": "string", "description": "Public token from Plaid.", "examples": [ "public-sandbox-5a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d" ] }, "plaid_account_id": { "type": [ "string", "null" ], "description": "Account selected in Plaid, where the customer had several.", "examples": [ "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D" ] } }, "required": [ "public_token" ] }, "example": { "public_token": "public-sandbox-5a1b2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d", "plaid_account_id": "vzeNDwK7KQIm4yEog683uElbp9GRLEFXGK98D" } } } }, "responses": { "201": { "description": "Created", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedAccount" }, "example": { "id": "la_5Gh2Xw8Pq1", "object": "linked_account", "customer_id": "cus_c9T2kXq4Lm", "status": "pending", "institution_name": "First Community Bank", "account_type": "checking", "account_mask": "6623", "capabilities": { "withdrawal": false, "load": false, "pay_by_bank": false }, "withdrawal_hold_until": null, "failure_code": null, "created_at": "2026-10-15T14:05:41Z", "updated_at": "2026-10-15T14:05:41Z", "version": 1 } } } }, "400": { "description": "Invalid request. Error codes: idempotency_key_missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict. Error codes: linked_account_exists.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request cannot be processed. Error codes: customer_not_verified, link_token_mismatch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "list_linked_accounts", "summary": "List linked accounts", "description": "Returns the customer's linked accounts, including removed ones, newest first.", "tags": [ "Bank linking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer identifier.", "schema": { "type": "string" }, "example": "cus_c9T2kXq4Lm" } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedAccountList" }, "example": { "object": "list", "data": [ { "id": "la_5Gh2Xw8Pq1", "object": "linked_account", "customer_id": "cus_c9T2kXq4Lm", "status": "verified", "institution_name": "First Community Bank", "account_type": "checking", "account_mask": "6623", "capabilities": { "withdrawal": true, "load": true, "pay_by_bank": true }, "withdrawal_hold_until": "2026-10-16T14:05:41Z", "failure_code": null, "created_at": "2026-10-15T14:05:41Z", "updated_at": "2026-10-15T14:05:41Z", "version": 2 } ], "has_more": false, "next_cursor": null } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/customers/{id}/linked-accounts/{linked_account_id}": { "delete": { "operationId": "remove_linked_account", "summary": "Remove a linked account", "description": "Removes the linked account. Pending withdrawals to it are not affected. linked_account.removed follows.", "tags": [ "Bank linking" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Customer identifier.", "schema": { "type": "string" }, "example": "cus_c9T2kXq4Lm" }, { "name": "linked_account_id", "in": "path", "required": true, "description": "Linked account identifier.", "schema": { "type": "string" }, "example": "la_5Gh2Xw8Pq1" } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LinkedAccount" }, "example": { "id": "la_5Gh2Xw8Pq1", "object": "linked_account", "customer_id": "cus_c9T2kXq4Lm", "status": "removed", "institution_name": "First Community Bank", "account_type": "checking", "account_mask": "6623", "capabilities": { "withdrawal": false, "load": false, "pay_by_bank": false }, "withdrawal_hold_until": null, "failure_code": null, "created_at": "2026-10-15T14:05:41Z", "updated_at": "2026-10-15T14:05:41Z", "version": 3 } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict. Error codes: invalid_state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/accounts": { "get": { "operationId": "find_account", "summary": "Find a customer's Digital Account", "description": "Returns a list containing the customer's Digital Account.", "tags": [ "Accounts" ], "parameters": [ { "name": "customer_id", "in": "query", "required": true, "description": "Customer identifier.", "schema": { "type": "string" }, "example": "cus_c9T2kXq4Lm" } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountList" }, "example": { "object": "list", "data": [ { "id": "acct_c3J8vN2Qe6", "object": "account", "customer_id": "cus_c9T2kXq4Lm", "type": "consumer", "status": "active", "currency": "USD", "opened_at": "2026-10-15T14:04:10Z", "closed_at": null, "updated_at": "2026-10-15T14:04:10Z", "version": 1 } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "Invalid request. Error codes: parameter_missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/accounts/{id}/balance": { "get": { "operationId": "get_balance", "summary": "Retrieve a balance", "description": "Returns the ledger, available, earmarked and pending outgoing amounts.", "tags": [ "Accounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Digital Account identifier.", "schema": { "type": "string" }, "example": "acct_c3J8vN2Qe6" } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" }, "example": { "object": "balance", "account_id": "acct_c3J8vN2Qe6", "currency": "USD", "ledger": 15000, "available": 12000, "earmarked": 2000, "pending_outgoing": 1000, "as_of": "2026-10-15T14:05:41Z" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/accounts/{id}/transactions": { "get": { "operationId": "list_transactions", "summary": "List transactions", "description": "Returns the account's transactions, newest first.", "tags": [ "Accounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Digital Account identifier.", "schema": { "type": "string" }, "example": "acct_c3J8vN2Qe6" }, { "name": "from", "in": "query", "required": false, "description": "Earliest creation time.", "schema": { "type": "string", "format": "date-time" }, "example": "2026-10-01T00:00:00Z" }, { "name": "to", "in": "query", "required": false, "description": "Latest creation time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "type", "in": "query", "required": false, "description": "Transaction type filter.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 100, default 25.", "schema": { "type": "integer", "format": "int64" }, "example": 25 }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionList" }, "example": { "object": "list", "data": [ { "id": "txn_2Qa5Ws8Ed1", "object": "transaction", "account_id": "acct_c3J8vN2Qe6", "type": "payment_sent", "direction": "debit", "amount": 2500, "fee_amount": 0, "net_amount": 2500, "currency": "USD", "status": "posted", "counterparty": { "type": "merchant", "customer_id": "cus_m7R5pWz1Hd", "display_name": "Riverside Coffee" }, "source_type": "payment", "source_id": "pay_3As6Df9Gh2", "description": "Order 55120", "created_at": "2026-10-15T14:04:10Z", "posted_at": "2026-10-15T14:04:10Z" } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "Invalid request. Error codes: parameter_invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/accounts/{id}/statements": { "get": { "operationId": "list_statements", "summary": "List statements", "description": "Returns the account's periodic statements, newest first.", "tags": [ "Accounts" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Digital Account identifier.", "schema": { "type": "string" }, "example": "acct_c3J8vN2Qe6" }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 100, default 25.", "schema": { "type": "integer", "format": "int64" } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StatementList" }, "example": { "object": "list", "data": [ { "id": "stmt_7Rf4Tg1Yh6", "object": "statement", "account_id": "acct_c3J8vN2Qe6", "period_start": "2026-09-01", "period_end": "2026-09-30", "opening_balance": 0, "closing_balance": 15000, "currency": "USD", "download_url": "https://files.example-a2a.test/statements/stmt_7Rf4Tg1Yh6.pdf?sig=redacted", "download_url_expires_at": "2026-10-15T14:20:22Z", "available_at": "2026-10-01T09:00:00Z" } ], "has_more": false, "next_cursor": null } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/loads": { "post": { "operationId": "create_load", "summary": "Create a load", "description": "Creates a load into the customer's Digital Account by Request for Payment to the customer's linked account. The load is returned with status requires_confirmation and a payment_confirm session. Open the session with the SDK; the customer confirms with the PIN or a passkey. A load that is not confirmed before the session expires fails with failure_code confirmation_expired.", "tags": [ "Loads" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "description": "Customer identifier.", "examples": [ "cus_c9T2kXq4Lm" ] }, "amount": { "type": "integer", "format": "int64", "description": "Amount in cents.", "examples": [ 10000 ] } }, "required": [ "customer_id", "amount" ] }, "example": { "customer_id": "cus_c9T2kXq4Lm", "amount": 10000 } } } }, "responses": { "201": { "description": "Created", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Load" }, "example": { "id": "load_7Ty4Ui2Op9", "object": "load", "customer_id": "cus_c9T2kXq4Lm", "account_id": "acct_c3J8vN2Qe6", "linked_account_id": "la_5Gh2Xw8Pq1", "amount": 10000, "currency": "USD", "status": "requires_confirmation", "failure_code": null, "confirmation_session": { "id": "ses_3Lm8Nb2Vc6", "flow": "payment_confirm", "token": "st_sbx_2f9c7a1e5b8d4c3a", "expires_at": "2026-10-15T14:08:22Z" }, "created_at": "2026-10-15T14:03:22Z", "confirmed_at": null, "settled_at": null, "updated_at": "2026-10-15T14:03:22Z", "version": 1 } } } }, "400": { "description": "Invalid request. Error codes: idempotency_key_missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Not allowed. Error codes: flow_not_enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request cannot be processed. Error codes: account_restricted, capability_unavailable, customer_not_verified, limit_exceeded, linked_account_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/loads/{id}": { "get": { "operationId": "get_load", "summary": "Retrieve a load", "description": "Returns the load.", "tags": [ "Loads" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Load identifier.", "schema": { "type": "string" }, "example": "load_7Ty4Ui2Op9" } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Load" }, "example": { "id": "load_7Ty4Ui2Op9", "object": "load", "customer_id": "cus_c9T2kXq4Lm", "account_id": "acct_c3J8vN2Qe6", "linked_account_id": "la_5Gh2Xw8Pq1", "amount": 10000, "currency": "USD", "status": "requires_confirmation", "failure_code": null, "created_at": "2026-10-15T14:03:22Z", "confirmed_at": null, "settled_at": null, "updated_at": "2026-10-15T14:03:22Z", "version": 1 } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/payment-requests": { "post": { "operationId": "create_payment_request", "summary": "Create a payment request", "description": "Creates a dynamic request with an amount, paid once, or a static request for a collection point, on which the payer enters the amount. Encode qr_payload in a QR code or in the Tenant's Link-to-Pay link.", "tags": [ "Payment requests" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "dynamic", "static" ], "description": "Request type.", "examples": [ "dynamic" ] }, "merchant_customer_id": { "type": "string", "description": "Merchant to be paid.", "examples": [ "cus_m7R5pWz1Hd" ] }, "amount": { "type": [ "integer", "null" ], "format": "int64", "description": "Amount in cents. Required for dynamic requests.", "examples": [ 2500 ] }, "order_reference": { "type": [ "string", "null" ], "description": "The Tenant's order reference.", "examples": [ "ORD-55120" ] }, "collection_point": { "anyOf": [ { "$ref": "#/components/schemas/CollectionPoint" }, { "type": "null" } ], "description": "Required for static requests." }, "expires_in": { "type": [ "integer", "null" ], "format": "int64", "description": "Validity of a dynamic request in seconds, up to 604800 (seven days). Defaults to the Tenant configuration.", "examples": [ 900 ] } }, "required": [ "type", "merchant_customer_id" ] }, "example": { "type": "dynamic", "merchant_customer_id": "cus_m7R5pWz1Hd", "amount": 2500, "order_reference": "ORD-55120", "expires_in": 900 } } } }, "responses": { "201": { "description": "Created", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" }, "example": { "id": "pr_1Zx4Cv7Bn5", "object": "payment_request", "type": "dynamic", "merchant_customer_id": "cus_m7R5pWz1Hd", "amount": 2500, "currency": "USD", "order_reference": "ORD-55120", "collection_point": null, "status": "open", "qr_payload": "A2AQR1.pr_1Zx4Cv7Bn5.MEUCIQDf3k9sample", "expires_at": "2026-10-15T14:18:22Z", "paid_payment_id": null, "created_at": "2026-10-15T14:03:22Z", "updated_at": "2026-10-15T14:03:22Z", "version": 1 } } } }, "400": { "description": "Invalid request. Error codes: idempotency_key_missing, parameter_missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Not allowed. Error codes: flow_not_enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request cannot be processed. Error codes: payee_not_eligible.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/payment-requests/{id}": { "get": { "operationId": "get_payment_request", "summary": "Retrieve a payment request", "description": "Returns the payment request.", "tags": [ "Payment requests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment request identifier.", "schema": { "type": "string" }, "example": "pr_1Zx4Cv7Bn5" } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" }, "example": { "id": "pr_1Zx4Cv7Bn5", "object": "payment_request", "type": "dynamic", "merchant_customer_id": "cus_m7R5pWz1Hd", "amount": 2500, "currency": "USD", "order_reference": "ORD-55120", "collection_point": null, "status": "open", "qr_payload": "A2AQR1.pr_1Zx4Cv7Bn5.MEUCIQDf3k9sample", "expires_at": "2026-10-22T14:03:22Z", "paid_payment_id": null, "created_at": "2026-10-15T14:03:22Z", "updated_at": "2026-10-15T14:03:22Z", "version": 1 } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/payment-requests/{id}/cancel": { "post": { "operationId": "cancel_payment_request", "summary": "Cancel a payment request", "description": "Cancels an open payment request. payment_request.canceled follows.", "tags": [ "Payment requests" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment request identifier.", "schema": { "type": "string" }, "example": "pr_1Zx4Cv7Bn5" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" }, "example": { "id": "pr_1Zx4Cv7Bn5", "object": "payment_request", "type": "dynamic", "merchant_customer_id": "cus_m7R5pWz1Hd", "amount": 2500, "currency": "USD", "order_reference": "ORD-55120", "collection_point": null, "status": "canceled", "qr_payload": "A2AQR1.pr_1Zx4Cv7Bn5.MEUCIQDf3k9sample", "expires_at": "2026-10-22T14:03:22Z", "paid_payment_id": null, "created_at": "2026-10-15T14:03:22Z", "updated_at": "2026-10-15T14:03:22Z", "version": 2 } } } }, "400": { "description": "Invalid request. Error codes: idempotency_key_missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict. Error codes: invalid_state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/payments": { "post": { "operationId": "create_payment", "summary": "Create a payment", "description": "Creates a consumer-to-merchant payment from balance or by bank, or a merchant-to-merchant payment from balance. Give either payee_customer_id or qr_payload. The payment is returned with status requires_confirmation and a payment_confirm session for the payer. A payment that is not confirmed before the session expires is canceled.", "tags": [ "Payments" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payer_customer_id": { "type": "string", "description": "Payer.", "examples": [ "cus_c9T2kXq4Lm" ] }, "payee_customer_id": { "type": [ "string", "null" ], "description": "Merchant to pay. Required unless qr_payload is given.", "examples": [ "cus_m7R5pWz1Hd" ] }, "qr_payload": { "type": [ "string", "null" ], "description": "Payload from a QR code or Link-to-Pay link." }, "amount": { "type": [ "integer", "null" ], "format": "int64", "description": "Amount in cents. Required unless a dynamic qr_payload sets it; may be lower than a requested amount but never higher.", "examples": [ 2500 ] }, "source": { "type": "string", "enum": [ "balance", "bank_account" ], "description": "Source of funds. bank_account is pay by bank.", "examples": [ "balance" ] }, "order_reference": { "type": [ "string", "null" ], "description": "The Tenant's order reference.", "examples": [ "ORD-55120" ] }, "invoice_reference": { "type": [ "string", "null" ], "description": "Required for merchant-to-merchant payments." }, "description": { "type": [ "string", "null" ], "description": "Description shown to both parties, up to 140 characters.", "examples": [ "Order 55120" ] } }, "required": [ "payer_customer_id", "source" ] }, "example": { "payer_customer_id": "cus_c9T2kXq4Lm", "payee_customer_id": "cus_m7R5pWz1Hd", "amount": 2500, "source": "balance", "order_reference": "ORD-55120", "description": "Order 55120" } } } }, "responses": { "201": { "description": "Created", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": { "id": "pay_3As6Df9Gh2", "object": "payment", "type": "consumer_to_merchant", "source": "balance", "payer_customer_id": "cus_c9T2kXq4Lm", "payee_customer_id": "cus_m7R5pWz1Hd", "payment_request_id": "pr_1Zx4Cv7Bn5", "amount": 2500, "currency": "USD", "fees": [ { "type": "platform", "amount": 50, "paid_by": "payee" } ], "net_amount": 2450, "refunded_amount": 0, "status": "requires_confirmation", "failure_code": null, "order_reference": "ORD-55120", "invoice_reference": null, "description": "Order 55120", "confirmation_session": { "id": "ses_8Qw3Ez5Rt2", "flow": "payment_confirm", "token": "st_sbx_2f9c7a1e5b8d4c3a", "expires_at": "2026-10-15T14:08:22Z" }, "created_at": "2026-10-15T14:03:22Z", "confirmed_at": null, "completed_at": null, "updated_at": "2026-10-15T14:03:22Z", "version": 1 } } } }, "400": { "description": "Invalid request. Error codes: idempotency_key_missing, parameter_missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Not allowed. Error codes: flow_not_enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request cannot be processed. Error codes: account_restricted, amount_mismatch, capability_unavailable, customer_not_verified, insufficient_funds, limit_exceeded, payee_not_eligible, payment_request_expired, payment_request_invalid, payment_request_paid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/payments/{id}": { "get": { "operationId": "get_payment", "summary": "Retrieve a payment", "description": "Returns the payment.", "tags": [ "Payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment identifier.", "schema": { "type": "string" }, "example": "pay_3As6Df9Gh2" } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": { "id": "pay_3As6Df9Gh2", "object": "payment", "type": "consumer_to_merchant", "source": "balance", "payer_customer_id": "cus_c9T2kXq4Lm", "payee_customer_id": "cus_m7R5pWz1Hd", "payment_request_id": "pr_1Zx4Cv7Bn5", "amount": 2500, "currency": "USD", "fees": [ { "type": "platform", "amount": 50, "paid_by": "payee" } ], "net_amount": 2450, "refunded_amount": 0, "status": "requires_confirmation", "failure_code": null, "order_reference": "ORD-55120", "invoice_reference": null, "description": "Order 55120", "created_at": "2026-10-15T14:03:22Z", "confirmed_at": null, "completed_at": null, "updated_at": "2026-10-15T14:03:22Z", "version": 1 } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/payments/{id}/cancel": { "post": { "operationId": "cancel_payment", "summary": "Cancel a payment", "description": "Cancels a payment that has not been confirmed. payment.canceled follows.", "tags": [ "Payments" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Payment identifier.", "schema": { "type": "string" }, "example": "pay_3As6Df9Gh2" }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "example": { "id": "pay_3As6Df9Gh2", "object": "payment", "type": "consumer_to_merchant", "source": "balance", "payer_customer_id": "cus_c9T2kXq4Lm", "payee_customer_id": "cus_m7R5pWz1Hd", "payment_request_id": "pr_1Zx4Cv7Bn5", "amount": 2500, "currency": "USD", "fees": [ { "type": "platform", "amount": 50, "paid_by": "payee" } ], "net_amount": 2450, "refunded_amount": 0, "status": "canceled", "failure_code": null, "order_reference": "ORD-55120", "invoice_reference": null, "description": "Order 55120", "created_at": "2026-10-15T14:03:22Z", "confirmed_at": null, "completed_at": null, "updated_at": "2026-10-15T14:03:22Z", "version": 2 } } } }, "400": { "description": "Invalid request. Error codes: idempotency_key_missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict. Error codes: invalid_state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/withdrawals": { "post": { "operationId": "create_withdrawal", "summary": "Create a withdrawal", "description": "Creates a withdrawal to the customer's own verified linked account. The withdrawal is returned with status requires_confirmation and a payment_confirm session. A withdrawal that is not confirmed before the session expires fails with failure_code confirmation_expired.", "tags": [ "Withdrawals" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "description": "Customer identifier.", "examples": [ "cus_m7R5pWz1Hd" ] }, "amount": { "type": "integer", "format": "int64", "description": "Amount in cents.", "examples": [ 50000 ] } }, "required": [ "customer_id", "amount" ] }, "example": { "customer_id": "cus_m7R5pWz1Hd", "amount": 50000 } } } }, "responses": { "201": { "description": "Created", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withdrawal" }, "example": { "id": "wd_6Mn3Bv8Cx1", "object": "withdrawal", "customer_id": "cus_m7R5pWz1Hd", "account_id": "acct_m4K1sB7Yt9", "linked_account_id": "la_9Kj3Hg6Fd2", "amount": 50000, "currency": "USD", "status": "requires_confirmation", "failure_code": null, "confirmation_session": { "id": "ses_9Wq4Er7Ty1", "flow": "payment_confirm", "token": "st_sbx_2f9c7a1e5b8d4c3a", "expires_at": "2026-10-15T14:08:22Z" }, "created_at": "2026-10-15T14:03:22Z", "confirmed_at": null, "settled_at": null, "updated_at": "2026-10-15T14:03:22Z", "version": 1 } } } }, "400": { "description": "Invalid request. Error codes: idempotency_key_missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request cannot be processed. Error codes: account_restricted, customer_not_verified, insufficient_funds, limit_exceeded, linked_account_required, withdrawal_hold.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/withdrawals/{id}": { "get": { "operationId": "get_withdrawal", "summary": "Retrieve a withdrawal", "description": "Returns the withdrawal.", "tags": [ "Withdrawals" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Withdrawal identifier.", "schema": { "type": "string" }, "example": "wd_6Mn3Bv8Cx1" } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Withdrawal" }, "example": { "id": "wd_6Mn3Bv8Cx1", "object": "withdrawal", "customer_id": "cus_m7R5pWz1Hd", "account_id": "acct_m4K1sB7Yt9", "linked_account_id": "la_9Kj3Hg6Fd2", "amount": 50000, "currency": "USD", "status": "requires_confirmation", "failure_code": null, "created_at": "2026-10-15T14:03:22Z", "confirmed_at": null, "settled_at": null, "updated_at": "2026-10-15T14:03:22Z", "version": 1 } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/refund-requests": { "post": { "operationId": "create_refund", "summary": "Request a refund", "description": "Requests a refund of a completed payment to the original payer. The refund is returned with status requested and a payment_confirm session for the merchant's authorized user. A refund that is not confirmed before the session expires fails with failure_code confirmation_expired.", "tags": [ "Refunds" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "payment_id": { "type": "string", "description": "Payment to refund.", "examples": [ "pay_3As6Df9Gh2" ] }, "amount": { "type": "integer", "format": "int64", "description": "Refund amount in cents.", "examples": [ 1000 ] }, "reason": { "type": "string", "enum": [ "requested_by_customer", "duplicate", "goods_not_received", "other" ], "description": "Reason.", "examples": [ "requested_by_customer" ] } }, "required": [ "payment_id", "amount", "reason" ] }, "example": { "payment_id": "pay_3As6Df9Gh2", "amount": 1000, "reason": "requested_by_customer" } } } }, "responses": { "201": { "description": "Created", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" }, "example": { "id": "rf_4Lk7Jh2Gf9", "object": "refund", "payment_id": "pay_3As6Df9Gh2", "merchant_customer_id": "cus_m7R5pWz1Hd", "payer_customer_id": "cus_c9T2kXq4Lm", "amount": 1000, "currency": "USD", "reason": "requested_by_customer", "destination": "balance", "status": "requested", "failure_code": null, "confirmation_session": { "id": "ses_2Zx8Cv5Bn3", "flow": "payment_confirm", "token": "st_sbx_2f9c7a1e5b8d4c3a", "expires_at": "2026-10-15T14:08:22Z" }, "created_at": "2026-10-15T14:03:22Z", "completed_at": null, "updated_at": "2026-10-15T14:03:22Z", "version": 1 } } } }, "400": { "description": "Invalid request. Error codes: idempotency_key_missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict. Error codes: invalid_state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "422": { "description": "Request cannot be processed. Error codes: account_restricted, refund_exceeds_payment, refund_window_closed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/refund-requests/{id}": { "get": { "operationId": "get_refund", "summary": "Retrieve a refund", "description": "Returns the refund.", "tags": [ "Refunds" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Refund identifier.", "schema": { "type": "string" }, "example": "rf_4Lk7Jh2Gf9" } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" }, "example": { "id": "rf_4Lk7Jh2Gf9", "object": "refund", "payment_id": "pay_3As6Df9Gh2", "merchant_customer_id": "cus_m7R5pWz1Hd", "payer_customer_id": "cus_c9T2kXq4Lm", "amount": 1000, "currency": "USD", "reason": "requested_by_customer", "destination": "balance", "status": "requested", "failure_code": null, "created_at": "2026-10-15T14:03:22Z", "completed_at": null, "updated_at": "2026-10-15T14:03:22Z", "version": 1 } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/disputes": { "post": { "operationId": "create_dispute", "summary": "Forward a customer notice", "description": "Forwards a customer's notice of an error, an unauthorized transfer or a purchase dispute. Forward every notice within one business day of receiving it, with the time the customer gave it.", "tags": [ "Disputes" ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "customer_id": { "type": "string", "description": "Customer who gave notice.", "examples": [ "cus_c9T2kXq4Lm" ] }, "type": { "type": "string", "enum": [ "error", "unauthorized_transfer", "purchase_dispute" ], "description": "Type of notice.", "examples": [ "unauthorized_transfer" ] }, "payment_id": { "type": [ "string", "null" ], "description": "Payment concerned.", "examples": [ "pay_3As6Df9Gh2" ] }, "transaction_id": { "type": [ "string", "null" ], "description": "Transaction concerned, where there is no payment." }, "description": { "type": "string", "description": "The customer's description, as given, up to 2,000 characters.", "examples": [ "I did not make this payment." ] }, "notice_received_at": { "type": "string", "format": "date-time", "description": "When the customer gave notice to the Tenant.", "examples": [ "2026-10-15T13:40:00Z" ] } }, "required": [ "customer_id", "type", "description", "notice_received_at" ] }, "example": { "customer_id": "cus_c9T2kXq4Lm", "type": "unauthorized_transfer", "payment_id": "pay_3As6Df9Gh2", "description": "I did not make this payment.", "notice_received_at": "2026-10-15T13:40:00Z" } } } }, "responses": { "201": { "description": "Created", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" }, "example": { "id": "dsp_9Po2Iu5Yt3", "object": "dispute", "customer_id": "cus_c9T2kXq4Lm", "type": "unauthorized_transfer", "payment_id": "pay_3As6Df9Gh2", "transaction_id": null, "description": "I did not make this payment.", "regulation_e": true, "notice_received_at": "2026-10-15T13:40:00Z", "status": "received", "provisional_credit_amount": null, "outcome": null, "resolved_at": null, "created_at": "2026-10-15T14:03:22Z", "updated_at": "2026-10-15T14:03:22Z", "version": 1 } } } }, "400": { "description": "Invalid request. Error codes: idempotency_key_missing, parameter_missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } }, "get": { "operationId": "list_disputes", "summary": "List disputes", "description": "Returns disputes, newest first.", "tags": [ "Disputes" ], "parameters": [ { "name": "customer_id", "in": "query", "required": false, "description": "Filter by customer.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "required": false, "description": "Filter by status.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 100, default 25.", "schema": { "type": "integer", "format": "int64" } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeList" }, "example": { "object": "list", "data": [ { "id": "dsp_9Po2Iu5Yt3", "object": "dispute", "customer_id": "cus_c9T2kXq4Lm", "type": "unauthorized_transfer", "payment_id": "pay_3As6Df9Gh2", "transaction_id": null, "description": "I did not make this payment.", "regulation_e": true, "notice_received_at": "2026-10-15T13:40:00Z", "status": "received", "provisional_credit_amount": null, "outcome": null, "resolved_at": null, "created_at": "2026-10-15T14:03:22Z", "updated_at": "2026-10-15T14:03:22Z", "version": 1 } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "Invalid request. Error codes: parameter_invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/webhook-events": { "get": { "operationId": "list_events", "summary": "List webhook events", "description": "Returns events with their delivery status, newest first. Events are kept for 30 days.", "tags": [ "Webhook events" ], "parameters": [ { "name": "type", "in": "query", "required": false, "description": "Filter by event type.", "schema": { "type": "string" } }, { "name": "delivery_status", "in": "query", "required": false, "description": "Filter by delivery status.", "schema": { "type": "string", "enum": [ "pending", "delivered", "retrying", "failed" ] } }, { "name": "from", "in": "query", "required": false, "description": "Earliest event time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "description": "Page size, 1 to 100, default 25.", "schema": { "type": "integer", "format": "int64" } }, { "name": "cursor", "in": "query", "required": false, "description": "next_cursor from the previous page.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEventList" }, "example": { "object": "list", "data": [ { "id": "evt_18Uj8Ik2Ol4", "object": "event", "type": "payment.completed", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "pay_3As6Df9Gh2", "object": "payment", "type": "consumer_to_merchant", "source": "balance", "payer_customer_id": "cus_c9T2kXq4Lm", "payee_customer_id": "cus_m7R5pWz1Hd", "payment_request_id": "pr_1Zx4Cv7Bn5", "amount": 2500, "currency": "USD", "fees": [ { "type": "platform", "amount": 50, "paid_by": "payee" } ], "net_amount": 2450, "refunded_amount": 0, "status": "completed", "failure_code": null, "order_reference": "ORD-55120", "invoice_reference": null, "description": "Order 55120", "created_at": "2026-10-15T14:03:22Z", "confirmed_at": "2026-10-15T14:04:10Z", "completed_at": "2026-10-15T14:04:10Z", "updated_at": "2026-10-15T14:04:10Z", "version": 2 }, "previous_attributes": { "status": "requires_confirmation" } }, "delivery": { "status": "delivered", "attempts": 1, "last_attempt_at": "2026-10-15T14:04:10Z", "last_response_status": 200, "next_attempt_at": null } } ], "has_more": false, "next_cursor": null } } } }, "400": { "description": "Invalid request. Error codes: parameter_invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/webhook-events/{id}/resend": { "post": { "operationId": "resend_event", "summary": "Resend a webhook event", "description": "Queues the event for delivery again with a fresh signature timestamp. The event identifier is unchanged.", "tags": [ "Webhook events" ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Event identifier.", "schema": { "type": "string" }, "example": "evt_5Ujm8Ik2Ol4" } ], "responses": { "202": { "description": "Accepted", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "example": { "id": "evt_18Uj8Ik2Ol4", "object": "event", "type": "payment.completed", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "pay_3As6Df9Gh2", "object": "payment", "type": "consumer_to_merchant", "source": "balance", "payer_customer_id": "cus_c9T2kXq4Lm", "payee_customer_id": "cus_m7R5pWz1Hd", "payment_request_id": "pr_1Zx4Cv7Bn5", "amount": 2500, "currency": "USD", "fees": [ { "type": "platform", "amount": 50, "paid_by": "payee" } ], "net_amount": 2450, "refunded_amount": 0, "status": "completed", "failure_code": null, "order_reference": "ORD-55120", "invoice_reference": null, "description": "Order 55120", "created_at": "2026-10-15T14:03:22Z", "confirmed_at": "2026-10-15T14:04:10Z", "completed_at": "2026-10-15T14:04:10Z", "updated_at": "2026-10-15T14:04:10Z", "version": 2 }, "previous_attributes": { "status": "requires_confirmation" } }, "delivery": { "status": "pending", "attempts": 3, "last_attempt_at": "2026-10-15T14:05:41Z", "last_response_status": 500, "next_attempt_at": "2026-10-15T14:06:00Z" } } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/reports/reconciliation": { "get": { "operationId": "recon_report", "summary": "Retrieve the daily reconciliation report", "description": "Returns the summary for a business date and a time-limited address of the posting-level file. Reports are available from 06:00 Eastern Time the next day.", "tags": [ "Reports" ], "parameters": [ { "name": "date", "in": "query", "required": true, "description": "Business date (Eastern Time), YYYY-MM-DD.", "schema": { "type": "string", "format": "date" }, "example": "2026-10-14" } ], "responses": { "200": { "description": "OK", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReconciliationReport" }, "example": { "object": "reconciliation_report", "date": "2026-10-14", "account_structure": "dedicated_fbo", "currency": "USD", "opening_balance": 1250000, "closing_balance": 1301800, "totals": { "loads": 250000, "payments": 410000, "withdrawals": 180000, "refunds": 12000, "fees": 8200, "adjustments": 0 }, "fee_clearing_swept": 8200, "postings_count": 1342, "file": { "format": "csv", "download_url": "https://files.example-a2a.test/recon/2026-10-14.csv?sig=redacted", "expires_at": "2026-10-15T14:20:22Z" }, "generated_at": "2026-10-15T06:00:00Z" } } } }, "400": { "description": "Invalid request. Error codes: parameter_missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v1/sandbox/simulate/{event}": { "post": { "operationId": "simulate", "summary": "Simulate an event (sandbox only)", "description": "Moves a sandbox record as if the bank, a provider or a reviewer had acted, and sends the resulting webhook.", "tags": [ "Sandbox" ], "parameters": [ { "name": "event", "in": "path", "required": true, "description": "Event to simulate. See the list in section 11.", "schema": { "type": "string" }, "example": "payment.completed" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "object_id": { "type": "string", "description": "Record to act on.", "examples": [ "pay_3As6Df9Gh2" ] }, "failure_code": { "type": [ "string", "null" ], "description": "For failure events, the failure code to apply." } }, "required": [ "object_id" ] }, "example": { "object_id": "pay_3As6Df9Gh2" } } } }, "responses": { "202": { "description": "Accepted", "headers": { "A2A-Request-Id": { "$ref": "#/components/headers/RequestId" }, "RateLimit-Limit": { "$ref": "#/components/headers/RateLimitLimit" }, "RateLimit-Remaining": { "$ref": "#/components/headers/RateLimitRemaining" }, "RateLimit-Reset": { "$ref": "#/components/headers/RateLimitReset" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SimulationResult" }, "example": { "object": "simulation", "event": "payment.completed", "object_id": "pay_3As6Df9Gh2", "status": "accepted" } } } }, "401": { "description": "Authentication failed. Error codes: authentication_required.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Not allowed. Error codes: sandbox_only.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "404": { "description": "Not found. Error codes: not_found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "409": { "description": "Conflict. Error codes: invalid_state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limited. Error codes: rate_limited.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal error. Error codes: internal_error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } } }, "webhooks": { "customer.verification.updated": { "post": { "summary": "A verification status changes", "description": "data.object is a Customer object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_01Uj8Ik2Ol4", "object": "event", "type": "customer.verification.updated", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "cus_c9T2kXq4Lm", "object": "customer", "type": "individual", "external_ref": "member-10482", "email": "member@example.com", "mobile_number_last4": "4821", "business": null, "verification": { "status": "approved", "updated_at": "2026-10-15T14:04:10Z", "retry_available_at": null }, "account_id": "acct_c3J8vN2Qe6", "pin_locked": false, "created_at": "2026-10-15T14:03:22Z", "updated_at": "2026-10-15T14:04:10Z", "version": 4 }, "previous_attributes": { "verification": { "status": "pending" }, "account_id": null } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "customer.updated": { "post": { "summary": "Customer details change, including the PIN being unlocked", "description": "data.object is a Customer object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_02Uj8Ik2Ol4", "object": "event", "type": "customer.updated", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "cus_c9T2kXq4Lm", "object": "customer", "type": "individual", "external_ref": "member-10482", "email": "member@example.com", "mobile_number_last4": "4821", "business": null, "verification": { "status": "approved", "updated_at": "2026-10-15T14:04:10Z", "retry_available_at": null }, "account_id": "acct_c3J8vN2Qe6", "pin_locked": false, "created_at": "2026-10-15T14:03:22Z", "updated_at": "2026-10-15T14:04:10Z", "version": 4 }, "previous_attributes": { "pin_locked": true } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "customer.pin_locked": { "post": { "summary": "The PIN is locked after failed attempts", "description": "data.object is a Customer object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_03Uj8Ik2Ol4", "object": "event", "type": "customer.pin_locked", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "cus_c9T2kXq4Lm", "object": "customer", "type": "individual", "external_ref": "member-10482", "email": "member@example.com", "mobile_number_last4": "4821", "business": null, "verification": { "status": "approved", "updated_at": "2026-10-15T14:04:10Z", "retry_available_at": null }, "account_id": "acct_c3J8vN2Qe6", "pin_locked": true, "created_at": "2026-10-15T14:03:22Z", "updated_at": "2026-10-15T14:04:10Z", "version": 4 }, "previous_attributes": { "pin_locked": false } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "account.created": { "post": { "summary": "A Digital Account is opened", "description": "data.object is a Account object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_04Uj8Ik2Ol4", "object": "event", "type": "account.created", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "acct_c3J8vN2Qe6", "object": "account", "customer_id": "cus_c9T2kXq4Lm", "type": "consumer", "status": "active", "currency": "USD", "opened_at": "2026-10-15T14:04:10Z", "closed_at": null, "updated_at": "2026-10-15T14:04:10Z", "version": 1 }, "previous_attributes": null } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "account.suspended": { "post": { "summary": "An account is suspended", "description": "data.object is a Account object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_05Uj8Ik2Ol4", "object": "event", "type": "account.suspended", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "acct_c3J8vN2Qe6", "object": "account", "customer_id": "cus_c9T2kXq4Lm", "type": "consumer", "status": "suspended", "currency": "USD", "opened_at": "2026-10-15T14:04:10Z", "closed_at": null, "updated_at": "2026-10-15T14:04:10Z", "version": 2 }, "previous_attributes": { "status": "active" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "account.reactivated": { "post": { "summary": "A suspended account is reactivated", "description": "data.object is a Account object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_06Uj8Ik2Ol4", "object": "event", "type": "account.reactivated", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "acct_c3J8vN2Qe6", "object": "account", "customer_id": "cus_c9T2kXq4Lm", "type": "consumer", "status": "active", "currency": "USD", "opened_at": "2026-10-15T14:04:10Z", "closed_at": null, "updated_at": "2026-10-15T14:04:10Z", "version": 2 }, "previous_attributes": { "status": "suspended" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "account.dormant": { "post": { "summary": "An account becomes dormant", "description": "data.object is a Account object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_07Uj8Ik2Ol4", "object": "event", "type": "account.dormant", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "acct_c3J8vN2Qe6", "object": "account", "customer_id": "cus_c9T2kXq4Lm", "type": "consumer", "status": "dormant", "currency": "USD", "opened_at": "2026-10-15T14:04:10Z", "closed_at": null, "updated_at": "2026-10-15T14:04:10Z", "version": 2 }, "previous_attributes": { "status": "active" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "account.closed": { "post": { "summary": "An account is closed", "description": "data.object is a Account object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_08Uj8Ik2Ol4", "object": "event", "type": "account.closed", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "acct_c3J8vN2Qe6", "object": "account", "customer_id": "cus_c9T2kXq4Lm", "type": "consumer", "status": "closed", "currency": "USD", "opened_at": "2026-10-15T14:04:10Z", "closed_at": "2026-10-15T14:05:41Z", "updated_at": "2026-10-15T14:04:10Z", "version": 2 }, "previous_attributes": { "status": "closing" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "linked_account.verified": { "post": { "summary": "A linked account passes its checks", "description": "data.object is a LinkedAccount object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_09Uj8Ik2Ol4", "object": "event", "type": "linked_account.verified", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "la_5Gh2Xw8Pq1", "object": "linked_account", "customer_id": "cus_c9T2kXq4Lm", "status": "verified", "institution_name": "First Community Bank", "account_type": "checking", "account_mask": "6623", "capabilities": { "withdrawal": true, "load": true, "pay_by_bank": true }, "withdrawal_hold_until": "2026-10-16T14:05:41Z", "failure_code": null, "created_at": "2026-10-15T14:05:41Z", "updated_at": "2026-10-15T14:04:10Z", "version": 3 }, "previous_attributes": { "status": "pending" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "linked_account.failed": { "post": { "summary": "A linked account fails its checks", "description": "data.object is a LinkedAccount object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_10Uj8Ik2Ol4", "object": "event", "type": "linked_account.failed", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "la_5Gh2Xw8Pq1", "object": "linked_account", "customer_id": "cus_c9T2kXq4Lm", "status": "failed", "institution_name": "First Community Bank", "account_type": "checking", "account_mask": "6623", "capabilities": { "withdrawal": false, "load": false, "pay_by_bank": false }, "withdrawal_hold_until": null, "failure_code": "ownership_mismatch", "created_at": "2026-10-15T14:05:41Z", "updated_at": "2026-10-15T14:04:10Z", "version": 3 }, "previous_attributes": { "status": "held_for_review" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "linked_account.removed": { "post": { "summary": "A linked account is removed", "description": "data.object is a LinkedAccount object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_11Uj8Ik2Ol4", "object": "event", "type": "linked_account.removed", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "la_5Gh2Xw8Pq1", "object": "linked_account", "customer_id": "cus_c9T2kXq4Lm", "status": "removed", "institution_name": "First Community Bank", "account_type": "checking", "account_mask": "6623", "capabilities": { "withdrawal": false, "load": false, "pay_by_bank": false }, "withdrawal_hold_until": null, "failure_code": null, "created_at": "2026-10-15T14:05:41Z", "updated_at": "2026-10-15T14:04:10Z", "version": 3 }, "previous_attributes": { "status": "verified" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "load.settled": { "post": { "summary": "A load is credited", "description": "data.object is a Load object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_12Uj8Ik2Ol4", "object": "event", "type": "load.settled", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:05:41Z", "data": { "object": { "id": "load_7Ty4Ui2Op9", "object": "load", "customer_id": "cus_c9T2kXq4Lm", "account_id": "acct_c3J8vN2Qe6", "linked_account_id": "la_5Gh2Xw8Pq1", "amount": 10000, "currency": "USD", "status": "settled", "failure_code": null, "created_at": "2026-10-15T14:03:22Z", "confirmed_at": "2026-10-15T14:04:10Z", "settled_at": "2026-10-15T14:05:41Z", "updated_at": "2026-10-15T14:05:41Z", "version": 2 }, "previous_attributes": { "status": "processing" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "load.failed": { "post": { "summary": "A load fails", "description": "data.object is a Load object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_13Uj8Ik2Ol4", "object": "event", "type": "load.failed", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:05:41Z", "data": { "object": { "id": "load_7Ty4Ui2Op9", "object": "load", "customer_id": "cus_c9T2kXq4Lm", "account_id": "acct_c3J8vN2Qe6", "linked_account_id": "la_5Gh2Xw8Pq1", "amount": 10000, "currency": "USD", "status": "failed", "failure_code": "request_expired", "created_at": "2026-10-15T14:03:22Z", "confirmed_at": "2026-10-15T14:04:10Z", "settled_at": null, "updated_at": "2026-10-15T14:05:41Z", "version": 2 }, "previous_attributes": { "status": "processing" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "payment_request.paid": { "post": { "summary": "A dynamic payment request is paid", "description": "data.object is a PaymentRequest object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_14Uj8Ik2Ol4", "object": "event", "type": "payment_request.paid", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "pr_1Zx4Cv7Bn5", "object": "payment_request", "type": "dynamic", "merchant_customer_id": "cus_m7R5pWz1Hd", "amount": 2500, "currency": "USD", "order_reference": "ORD-55120", "collection_point": null, "status": "paid", "qr_payload": "A2AQR1.pr_1Zx4Cv7Bn5.MEUCIQDf3k9sample", "expires_at": "2026-10-22T14:03:22Z", "paid_payment_id": "pay_3As6Df9Gh2", "created_at": "2026-10-15T14:03:22Z", "updated_at": "2026-10-15T14:04:10Z", "version": 2 }, "previous_attributes": { "status": "open" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "payment_request.expired": { "post": { "summary": "A dynamic payment request expires", "description": "data.object is a PaymentRequest object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_15Uj8Ik2Ol4", "object": "event", "type": "payment_request.expired", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "pr_1Zx4Cv7Bn5", "object": "payment_request", "type": "dynamic", "merchant_customer_id": "cus_m7R5pWz1Hd", "amount": 2500, "currency": "USD", "order_reference": "ORD-55120", "collection_point": null, "status": "expired", "qr_payload": "A2AQR1.pr_1Zx4Cv7Bn5.MEUCIQDf3k9sample", "expires_at": "2026-10-22T14:03:22Z", "paid_payment_id": null, "created_at": "2026-10-15T14:03:22Z", "updated_at": "2026-10-15T14:04:10Z", "version": 2 }, "previous_attributes": { "status": "open" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "payment_request.canceled": { "post": { "summary": "A payment request is canceled", "description": "data.object is a PaymentRequest object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_16Uj8Ik2Ol4", "object": "event", "type": "payment_request.canceled", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "pr_1Zx4Cv7Bn5", "object": "payment_request", "type": "dynamic", "merchant_customer_id": "cus_m7R5pWz1Hd", "amount": 2500, "currency": "USD", "order_reference": "ORD-55120", "collection_point": null, "status": "canceled", "qr_payload": "A2AQR1.pr_1Zx4Cv7Bn5.MEUCIQDf3k9sample", "expires_at": "2026-10-22T14:03:22Z", "paid_payment_id": null, "created_at": "2026-10-15T14:03:22Z", "updated_at": "2026-10-15T14:04:10Z", "version": 2 }, "previous_attributes": { "status": "open" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "payment.processing": { "post": { "summary": "A pay by bank payment is confirmed and the Request for Payment is sent", "description": "data.object is a Payment object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_17Uj8Ik2Ol4", "object": "event", "type": "payment.processing", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "pay_3As6Df9Gh2", "object": "payment", "type": "consumer_to_merchant", "source": "bank_account", "payer_customer_id": "cus_c9T2kXq4Lm", "payee_customer_id": "cus_m7R5pWz1Hd", "payment_request_id": "pr_1Zx4Cv7Bn5", "amount": 2500, "currency": "USD", "fees": [ { "type": "platform", "amount": 50, "paid_by": "payee" } ], "net_amount": 2450, "refunded_amount": 0, "status": "processing", "failure_code": null, "order_reference": "ORD-55120", "invoice_reference": null, "description": "Order 55120", "created_at": "2026-10-15T14:03:22Z", "confirmed_at": "2026-10-15T14:04:10Z", "completed_at": null, "updated_at": "2026-10-15T14:04:10Z", "version": 2 }, "previous_attributes": { "status": "requires_confirmation" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "payment.completed": { "post": { "summary": "A payment is completed and the merchant credited", "description": "data.object is a Payment object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_18Uj8Ik2Ol4", "object": "event", "type": "payment.completed", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "pay_3As6Df9Gh2", "object": "payment", "type": "consumer_to_merchant", "source": "balance", "payer_customer_id": "cus_c9T2kXq4Lm", "payee_customer_id": "cus_m7R5pWz1Hd", "payment_request_id": "pr_1Zx4Cv7Bn5", "amount": 2500, "currency": "USD", "fees": [ { "type": "platform", "amount": 50, "paid_by": "payee" } ], "net_amount": 2450, "refunded_amount": 0, "status": "completed", "failure_code": null, "order_reference": "ORD-55120", "invoice_reference": null, "description": "Order 55120", "created_at": "2026-10-15T14:03:22Z", "confirmed_at": "2026-10-15T14:04:10Z", "completed_at": "2026-10-15T14:04:10Z", "updated_at": "2026-10-15T14:04:10Z", "version": 2 }, "previous_attributes": { "status": "requires_confirmation" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "payment.failed": { "post": { "summary": "A payment fails", "description": "data.object is a Payment object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_19Uj8Ik2Ol4", "object": "event", "type": "payment.failed", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "pay_3As6Df9Gh2", "object": "payment", "type": "consumer_to_merchant", "source": "bank_account", "payer_customer_id": "cus_c9T2kXq4Lm", "payee_customer_id": "cus_m7R5pWz1Hd", "payment_request_id": "pr_1Zx4Cv7Bn5", "amount": 2500, "currency": "USD", "fees": [ { "type": "platform", "amount": 50, "paid_by": "payee" } ], "net_amount": 2450, "refunded_amount": 0, "status": "failed", "failure_code": "declined_by_customer", "order_reference": "ORD-55120", "invoice_reference": null, "description": "Order 55120", "created_at": "2026-10-15T14:03:22Z", "confirmed_at": "2026-10-15T14:04:10Z", "completed_at": null, "updated_at": "2026-10-15T14:04:10Z", "version": 2 }, "previous_attributes": { "status": "processing" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "payment.canceled": { "post": { "summary": "A payment is canceled before confirmation", "description": "data.object is a Payment object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_20Uj8Ik2Ol4", "object": "event", "type": "payment.canceled", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "pay_3As6Df9Gh2", "object": "payment", "type": "consumer_to_merchant", "source": "balance", "payer_customer_id": "cus_c9T2kXq4Lm", "payee_customer_id": "cus_m7R5pWz1Hd", "payment_request_id": "pr_1Zx4Cv7Bn5", "amount": 2500, "currency": "USD", "fees": [ { "type": "platform", "amount": 50, "paid_by": "payee" } ], "net_amount": 2450, "refunded_amount": 0, "status": "canceled", "failure_code": "confirmation_expired", "order_reference": "ORD-55120", "invoice_reference": null, "description": "Order 55120", "created_at": "2026-10-15T14:03:22Z", "confirmed_at": null, "completed_at": null, "updated_at": "2026-10-15T14:04:10Z", "version": 2 }, "previous_attributes": { "status": "requires_confirmation" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "payment.refunded": { "post": { "summary": "A payment is refunded in full", "description": "data.object is a Payment object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_21Uj8Ik2Ol4", "object": "event", "type": "payment.refunded", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "pay_3As6Df9Gh2", "object": "payment", "type": "consumer_to_merchant", "source": "balance", "payer_customer_id": "cus_c9T2kXq4Lm", "payee_customer_id": "cus_m7R5pWz1Hd", "payment_request_id": "pr_1Zx4Cv7Bn5", "amount": 2500, "currency": "USD", "fees": [ { "type": "platform", "amount": 50, "paid_by": "payee" } ], "net_amount": 2450, "refunded_amount": 2500, "status": "refunded", "failure_code": null, "order_reference": "ORD-55120", "invoice_reference": null, "description": "Order 55120", "created_at": "2026-10-15T14:03:22Z", "confirmed_at": "2026-10-15T14:04:10Z", "completed_at": "2026-10-15T14:04:10Z", "updated_at": "2026-10-15T14:04:10Z", "version": 2 }, "previous_attributes": { "status": "completed", "refunded_amount": 0 } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "payment.partially_refunded": { "post": { "summary": "Part of a payment is refunded", "description": "data.object is a Payment object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_22Uj8Ik2Ol4", "object": "event", "type": "payment.partially_refunded", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "pay_3As6Df9Gh2", "object": "payment", "type": "consumer_to_merchant", "source": "balance", "payer_customer_id": "cus_c9T2kXq4Lm", "payee_customer_id": "cus_m7R5pWz1Hd", "payment_request_id": "pr_1Zx4Cv7Bn5", "amount": 2500, "currency": "USD", "fees": [ { "type": "platform", "amount": 50, "paid_by": "payee" } ], "net_amount": 2450, "refunded_amount": 1000, "status": "partially_refunded", "failure_code": null, "order_reference": "ORD-55120", "invoice_reference": null, "description": "Order 55120", "created_at": "2026-10-15T14:03:22Z", "confirmed_at": "2026-10-15T14:04:10Z", "completed_at": "2026-10-15T14:04:10Z", "updated_at": "2026-10-15T14:04:10Z", "version": 2 }, "previous_attributes": { "status": "completed", "refunded_amount": 0 } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "withdrawal.settled": { "post": { "summary": "A withdrawal is final", "description": "data.object is a Withdrawal object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_23Uj8Ik2Ol4", "object": "event", "type": "withdrawal.settled", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:05:41Z", "data": { "object": { "id": "wd_6Mn3Bv8Cx1", "object": "withdrawal", "customer_id": "cus_m7R5pWz1Hd", "account_id": "acct_m4K1sB7Yt9", "linked_account_id": "la_9Kj3Hg6Fd2", "amount": 50000, "currency": "USD", "status": "settled", "failure_code": null, "created_at": "2026-10-15T14:03:22Z", "confirmed_at": "2026-10-15T14:04:10Z", "settled_at": "2026-10-15T14:05:41Z", "updated_at": "2026-10-15T14:05:41Z", "version": 2 }, "previous_attributes": { "status": "processing" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "withdrawal.failed": { "post": { "summary": "A withdrawal fails and the reserved amount is released", "description": "data.object is a Withdrawal object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_24Uj8Ik2Ol4", "object": "event", "type": "withdrawal.failed", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:05:41Z", "data": { "object": { "id": "wd_6Mn3Bv8Cx1", "object": "withdrawal", "customer_id": "cus_m7R5pWz1Hd", "account_id": "acct_m4K1sB7Yt9", "linked_account_id": "la_9Kj3Hg6Fd2", "amount": 50000, "currency": "USD", "status": "failed", "failure_code": "rejected_by_bank", "created_at": "2026-10-15T14:03:22Z", "confirmed_at": "2026-10-15T14:04:10Z", "settled_at": null, "updated_at": "2026-10-15T14:05:41Z", "version": 2 }, "previous_attributes": { "status": "processing" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "refund.updated": { "post": { "summary": "A refund status changes", "description": "data.object is a Refund object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_25Uj8Ik2Ol4", "object": "event", "type": "refund.updated", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:05:41Z", "data": { "object": { "id": "rf_4Lk7Jh2Gf9", "object": "refund", "payment_id": "pay_3As6Df9Gh2", "merchant_customer_id": "cus_m7R5pWz1Hd", "payer_customer_id": "cus_c9T2kXq4Lm", "amount": 1000, "currency": "USD", "reason": "requested_by_customer", "destination": "balance", "status": "completed", "failure_code": null, "created_at": "2026-10-15T14:03:22Z", "completed_at": "2026-10-15T14:05:41Z", "updated_at": "2026-10-15T14:05:41Z", "version": 2 }, "previous_attributes": { "status": "processing" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "dispute.updated": { "post": { "summary": "A dispute status changes", "description": "data.object is a Dispute object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_26Uj8Ik2Ol4", "object": "event", "type": "dispute.updated", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "dsp_9Po2Iu5Yt3", "object": "dispute", "customer_id": "cus_c9T2kXq4Lm", "type": "unauthorized_transfer", "payment_id": "pay_3As6Df9Gh2", "transaction_id": null, "description": "I did not make this payment.", "regulation_e": true, "notice_received_at": "2026-10-15T13:40:00Z", "status": "provisional_credit", "provisional_credit_amount": 2500, "outcome": null, "resolved_at": null, "created_at": "2026-10-15T14:03:22Z", "updated_at": "2026-10-15T14:04:10Z", "version": 2 }, "previous_attributes": { "status": "investigating" } } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } }, "statement.available": { "post": { "summary": "A periodic statement is available", "description": "data.object is a Statement object.", "parameters": [ { "name": "A2A-Signature", "in": "header", "required": true, "description": "t=,v1=[,v1=]", "schema": { "type": "string" } }, { "name": "A2A-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } }, { "name": "A2A-Event-Type", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "example": { "id": "evt_27Uj8Ik2Ol4", "object": "event", "type": "statement.available", "api_version": "v1", "environment": "sandbox", "created_at": "2026-10-15T14:04:10Z", "data": { "object": { "id": "stmt_7Rf4Tg1Yh6", "object": "statement", "account_id": "acct_c3J8vN2Qe6", "period_start": "2026-09-01", "period_end": "2026-09-30", "opening_balance": 0, "closing_balance": 15000, "currency": "USD", "download_url": "https://files.example-a2a.test/statements/stmt_7Rf4Tg1Yh6.pdf?sig=redacted", "download_url_expires_at": "2026-10-15T14:20:22Z", "available_at": "2026-10-01T09:00:00Z" }, "previous_attributes": null } } } } }, "responses": { "200": { "description": "Event accepted or already received. Any 2xx response is treated as delivered." } } } } }, "components": { "schemas": { "Error": { "type": "object", "properties": { "code": { "type": "string", "description": "Stable error code from the error catalog. Code against this value.", "examples": [ "limit_exceeded" ] }, "message": { "type": "string", "description": "Readable description for logs and support. Do not show it to customers or parse it.", "examples": [ "The payment exceeds the daily amount limit for this customer." ] }, "param": { "type": [ "string", "null" ], "description": "The request field the error relates to, where there is one.", "examples": [ "amount" ] }, "request_id": { "type": "string", "description": "Identifier of the request, also returned in the A2A-Request-Id header. Quote it to support.", "examples": [ "req_4Hk8Lm2Np6" ] }, "details": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Additional structured information for some errors, described in the catalog.", "examples": [ { "limit": "daily_amount" } ] } }, "required": [ "code", "message", "request_id" ], "description": "Error" }, "ErrorResponse": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/Error", "description": "The error." } }, "required": [ "error" ], "description": "ErrorResponse" }, "Token": { "type": "object", "properties": { "access_token": { "type": "string", "description": "Bearer token for the Authorization header.", "examples": [ "at_sbx_6c1f0e9b2a7d4e8f9a0b1c2d3e4f5a6b" ] }, "token_type": { "type": "string", "enum": [ "Bearer" ], "description": "Always Bearer.", "examples": [ "Bearer" ] }, "expires_in": { "type": "integer", "format": "int64", "description": "Lifetime of the token in seconds.", "examples": [ 900 ] }, "scope": { "type": "string", "description": "Scope granted to the client.", "examples": [ "tenant" ] } }, "required": [ "access_token", "token_type", "expires_in", "scope" ], "description": "Token" }, "ConfirmationSession": { "type": "object", "properties": { "id": { "type": "string", "description": "Session identifier.", "examples": [ "ses_8Qw3Ez5Rt2" ] }, "flow": { "type": "string", "enum": [ "onboarding", "payment_confirm", "pin_reset", "contact_change", "terms_acceptance" ], "description": "Hosted flow the session opens.", "examples": [ "payment_confirm" ] }, "token": { "type": "string", "description": "Single-use session token to pass to the SDK. Treat it as a secret and do not log it.", "examples": [ "st_sbx_2f9c7a1e5b8d4c3a" ] }, "expires_at": { "type": "string", "format": "date-time", "description": "Time after which the token can no longer be opened.", "examples": [ "2026-10-15T14:08:22Z" ] } }, "required": [ "id", "flow", "expires_at" ], "description": "ConfirmationSession" }, "Target": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "payment", "load", "withdrawal", "refund" ], "description": "Type of record the customer confirms.", "examples": [ "payment" ] }, "id": { "type": "string", "description": "Identifier of that record.", "examples": [ "pay_3As6Df9Gh2" ] } }, "required": [ "type", "id" ], "description": "Target" }, "Session": { "type": "object", "properties": { "id": { "type": "string", "description": "Session identifier.", "examples": [ "ses_8Qw3Ez5Rt2" ] }, "object": { "type": "string", "enum": [ "session" ], "description": "Object type.", "examples": [ "session" ] }, "flow": { "type": "string", "enum": [ "onboarding", "payment_confirm", "pin_reset", "contact_change", "terms_acceptance" ], "description": "Hosted flow.", "examples": [ "payment_confirm" ] }, "customer_id": { "type": "string", "description": "Customer the session is bound to.", "examples": [ "cus_c9T2kXq4Lm" ] }, "target": { "anyOf": [ { "$ref": "#/components/schemas/Target" }, { "type": "null" } ], "description": "Record to confirm. Present for payment_confirm only." }, "status": { "type": "string", "enum": [ "created", "completed", "canceled", "expired" ], "description": "Session status.", "examples": [ "created" ] }, "token": { "type": [ "string", "null" ], "description": "Single-use session token. Returned only when the session is created.", "examples": [ "st_sbx_2f9c7a1e5b8d4c3a" ] }, "return_url": { "type": [ "string", "null" ], "description": "Registered return address used for redirects on mobile browsers.", "examples": [ "https://app.example.com/a2a/return" ] }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiry of the session token.", "examples": [ "2026-10-15T14:08:22Z" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Creation time.", "examples": [ "2026-10-15T14:03:22Z" ] } }, "required": [ "id", "object", "flow", "customer_id", "status", "expires_at", "created_at" ], "description": "Session" }, "SessionOutcome": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "session_outcome" ], "description": "Object type.", "examples": [ "session_outcome" ] }, "session_id": { "type": "string", "description": "Session identifier.", "examples": [ "ses_8Qw3Ez5Rt2" ] }, "flow": { "type": "string", "enum": [ "onboarding", "payment_confirm", "pin_reset", "contact_change", "terms_acceptance" ], "description": "Hosted flow.", "examples": [ "payment_confirm" ] }, "status": { "type": "string", "enum": [ "completed", "canceled", "expired" ], "description": "How the customer left the flow.", "examples": [ "completed" ] }, "customer_id": { "type": "string", "description": "Customer identifier.", "examples": [ "cus_c9T2kXq4Lm" ] }, "verification_status": { "type": [ "string", "null" ], "enum": [ "created", "pending", "in_review", "approved", "rejected", null ], "description": "For onboarding: the customer's verification status when the flow ended." }, "target": { "anyOf": [ { "$ref": "#/components/schemas/Target" }, { "type": "null" } ], "description": "For payment_confirm: the confirmed record." }, "target_status": { "type": [ "string", "null" ], "description": "For payment_confirm: status of the confirmed record after confirmation, for example processing or completed.", "examples": [ "completed" ] }, "terms_decision": { "type": [ "string", "null" ], "enum": [ "accepted", "declined", null ], "description": "For terms_acceptance: the customer's decision." } }, "required": [ "object", "session_id", "flow", "status", "customer_id" ], "description": "SessionOutcome" }, "Verification": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "created", "pending", "in_review", "approved", "rejected" ], "description": "Verification status. See the Tenant Integration Specification, section 9.", "examples": [ "approved" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Time of the last status change.", "examples": [ "2026-10-15T14:04:10Z" ] }, "retry_available_at": { "type": [ "string", "null" ], "format": "date-time", "description": "For rejected customers: when a new application may be started." } }, "required": [ "status", "updated_at" ], "description": "Verification" }, "BusinessProfile": { "type": "object", "properties": { "legal_name": { "type": [ "string", "null" ], "description": "Verified legal name. Present once captured on the hosted screen.", "examples": [ "Riverside Coffee Co LLC" ] }, "trading_name": { "type": [ "string", "null" ], "description": "Trading name shown to payers.", "examples": [ "Riverside Coffee" ] }, "industry": { "type": [ "string", "null" ], "description": "Industry from the program's industry list.", "examples": [ "Coffee shops and cafes" ] }, "owners_status": { "type": "string", "enum": [ "not_started", "pending", "complete" ], "description": "Progress of owner and control person verification.", "examples": [ "complete" ] } }, "required": [ "owners_status" ], "description": "BusinessProfile" }, "Customer": { "type": "object", "properties": { "id": { "type": "string", "description": "Customer identifier.", "examples": [ "cus_c9T2kXq4Lm" ] }, "object": { "type": "string", "enum": [ "customer" ], "description": "Object type.", "examples": [ "customer" ] }, "type": { "type": "string", "enum": [ "individual", "business" ], "description": "Consumer (individual) or merchant (business).", "examples": [ "individual" ] }, "external_ref": { "type": "string", "description": "The Tenant's own reference for the customer, unique within the Tenant.", "examples": [ "member-10482" ] }, "email": { "type": "string", "description": "E-mail address supplied by the Tenant, or as changed on the contact_change screen.", "examples": [ "member@example.com" ] }, "mobile_number_last4": { "type": "string", "description": "Last four digits of the verified mobile number.", "examples": [ "4821" ] }, "business": { "anyOf": [ { "$ref": "#/components/schemas/BusinessProfile" }, { "type": "null" } ], "description": "Business details. Present for business customers only." }, "verification": { "$ref": "#/components/schemas/Verification", "description": "Verification status." }, "account_id": { "type": [ "string", "null" ], "description": "Digital Account identifier. Present once the customer is approved.", "examples": [ "acct_c3J8vN2Qe6" ] }, "pin_locked": { "type": "boolean", "description": "True while the PIN is locked after failed attempts.", "examples": [ false ] }, "onboarding_session": { "anyOf": [ { "$ref": "#/components/schemas/ConfirmationSession" }, { "type": "null" } ], "description": "Onboarding session. Returned only when the customer is created." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation time.", "examples": [ "2026-10-15T14:03:22Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Time of the last change.", "examples": [ "2026-10-15T14:04:10Z" ] }, "version": { "type": "integer", "format": "int64", "description": "Increases by one on every change. Use it to discard out-of-date webhook events.", "examples": [ 3 ] } }, "required": [ "id", "object", "type", "external_ref", "email", "mobile_number_last4", "verification", "pin_locked", "created_at", "updated_at", "version" ], "description": "Customer" }, "Owner": { "type": "object", "properties": { "id": { "type": "string", "description": "Owner identifier.", "examples": [ "own_2Lp9Vc4Mz7" ] }, "object": { "type": "string", "enum": [ "owner" ], "description": "Object type.", "examples": [ "owner" ] }, "customer_id": { "type": "string", "description": "Business customer the person belongs to.", "examples": [ "cus_m7R5pWz1Hd" ] }, "name": { "type": "string", "description": "Name of the person as entered by the merchant.", "examples": [ "Jordan Ellis" ] }, "role": { "type": "string", "enum": [ "owner", "control_person", "owner_and_control_person" ], "description": "Role in the business.", "examples": [ "owner_and_control_person" ] }, "ownership_percent": { "type": [ "integer", "null" ], "format": "int64", "description": "Ownership percentage, for owners.", "examples": [ 60 ] }, "verification_status": { "type": "string", "enum": [ "invited", "pending", "in_review", "approved", "rejected" ], "description": "Verification status of the person.", "examples": [ "approved" ] }, "invited_at": { "type": [ "string", "null" ], "format": "date-time", "description": "When a verification link was sent to the person.", "examples": [ "2026-10-15T14:03:22Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Time of the last change.", "examples": [ "2026-10-15T14:04:10Z" ] } }, "required": [ "id", "object", "customer_id", "name", "role", "verification_status", "updated_at" ], "description": "Owner" }, "DocumentAcceptance": { "type": "object", "properties": { "id": { "type": "string", "description": "Acceptance record identifier.", "examples": [ "dacc_3Nb6Vc9Xz2" ] }, "object": { "type": "string", "enum": [ "document_acceptance" ], "description": "Object type.", "examples": [ "document_acceptance" ] }, "customer_id": { "type": "string", "description": "Customer identifier.", "examples": [ "cus_c9T2kXq4Lm" ] }, "document_type": { "type": "string", "enum": [ "digital_account_terms", "esign_consent", "privacy_notice", "cip_notice", "merchant_services_agreement", "acceptable_use_policy" ], "description": "Customer document.", "examples": [ "digital_account_terms" ] }, "version": { "type": "string", "description": "Document version accepted.", "examples": [ "2026.10" ] }, "status": { "type": "string", "enum": [ "accepted", "superseded", "pending_acceptance" ], "description": "Status of the acceptance. pending_acceptance means a new version awaits acceptance on the terms_acceptance screen.", "examples": [ "accepted" ] }, "accepted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of acceptance.", "examples": [ "2026-10-15T14:03:22Z" ] }, "channel": { "type": [ "string", "null" ], "enum": [ "onboarding", "terms_acceptance", null ], "description": "Hosted flow in which the document was accepted.", "examples": [ "onboarding" ] } }, "required": [ "id", "object", "customer_id", "document_type", "version", "status" ], "description": "DocumentAcceptance" }, "LinkToken": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "link_token" ], "description": "Object type.", "examples": [ "link_token" ] }, "link_token": { "type": "string", "description": "Plaid link token to open Plaid in the Tenant's application.", "examples": [ "link-sandbox-7c1f2e3d-4b5a-6c7d-8e9f-0a1b2c3d4e5f" ] }, "expiration": { "type": "string", "format": "date-time", "description": "Expiry of the link token.", "examples": [ "2026-10-15T18:03:22Z" ] } }, "required": [ "object", "link_token", "expiration" ], "description": "LinkToken" }, "Capabilities": { "type": "object", "properties": { "withdrawal": { "type": "boolean", "description": "The bank can receive RTP credit transfers, so withdrawals are available.", "examples": [ true ] }, "load": { "type": "boolean", "description": "The bank can receive a Request for Payment, so loads are available.", "examples": [ true ] }, "pay_by_bank": { "type": "boolean", "description": "The bank can receive a Request for Payment, so pay by bank is available.", "examples": [ true ] } }, "required": [ "withdrawal", "load", "pay_by_bank" ], "description": "Capabilities" }, "LinkedAccount": { "type": "object", "properties": { "id": { "type": "string", "description": "Linked account identifier.", "examples": [ "la_5Gh2Xw8Pq1" ] }, "object": { "type": "string", "enum": [ "linked_account" ], "description": "Object type.", "examples": [ "linked_account" ] }, "customer_id": { "type": "string", "description": "Customer identifier.", "examples": [ "cus_c9T2kXq4Lm" ] }, "status": { "type": "string", "enum": [ "pending", "held_for_review", "verified", "failed", "removed" ], "description": "Status of the link.", "examples": [ "verified" ] }, "institution_name": { "type": "string", "description": "Name of the bank.", "examples": [ "First Community Bank" ] }, "account_type": { "type": "string", "enum": [ "checking", "savings" ], "description": "Account type.", "examples": [ "checking" ] }, "account_mask": { "type": "string", "description": "Last four digits of the account number.", "examples": [ "6623" ] }, "capabilities": { "$ref": "#/components/schemas/Capabilities", "description": "What the account can be used for. All false until verified." }, "withdrawal_hold_until": { "type": [ "string", "null" ], "format": "date-time", "description": "Withdrawals to a newly linked account are held until this time.", "examples": [ "2026-10-16T14:05:41Z" ] }, "failure_code": { "type": [ "string", "null" ], "enum": [ "ownership_mismatch", "unsupported_account_type", "already_linked", "not_rtp_reachable", "bank_connection_error", null ], "description": "Reason for a failed link." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation time.", "examples": [ "2026-10-15T14:05:41Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Time of the last change.", "examples": [ "2026-10-15T14:05:41Z" ] }, "version": { "type": "integer", "format": "int64", "description": "Increases by one on every change.", "examples": [ 2 ] } }, "required": [ "id", "object", "customer_id", "status", "institution_name", "account_type", "account_mask", "capabilities", "created_at", "updated_at", "version" ], "description": "LinkedAccount" }, "Account": { "type": "object", "properties": { "id": { "type": "string", "description": "Digital Account identifier.", "examples": [ "acct_c3J8vN2Qe6" ] }, "object": { "type": "string", "enum": [ "account" ], "description": "Object type.", "examples": [ "account" ] }, "customer_id": { "type": "string", "description": "Customer identifier.", "examples": [ "cus_c9T2kXq4Lm" ] }, "type": { "type": "string", "enum": [ "consumer", "merchant" ], "description": "Account type.", "examples": [ "consumer" ] }, "status": { "type": "string", "enum": [ "active", "suspended", "dormant", "closing", "closed" ], "description": "Account status.", "examples": [ "active" ] }, "currency": { "type": "string", "enum": [ "USD" ], "description": "Currency.", "examples": [ "USD" ] }, "opened_at": { "type": "string", "format": "date-time", "description": "Opening time.", "examples": [ "2026-10-15T14:04:10Z" ] }, "closed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Closing time." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time of the last change.", "examples": [ "2026-10-15T14:04:10Z" ] }, "version": { "type": "integer", "format": "int64", "description": "Increases by one on every change.", "examples": [ 1 ] } }, "required": [ "id", "object", "customer_id", "type", "status", "currency", "opened_at", "updated_at", "version" ], "description": "Account" }, "Balance": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "balance" ], "description": "Object type.", "examples": [ "balance" ] }, "account_id": { "type": "string", "description": "Digital Account identifier.", "examples": [ "acct_c3J8vN2Qe6" ] }, "currency": { "type": "string", "enum": [ "USD" ], "description": "Currency.", "examples": [ "USD" ] }, "ledger": { "type": "integer", "format": "int64", "description": "Total balance in cents.", "examples": [ 15000 ] }, "available": { "type": "integer", "format": "int64", "description": "Amount that can be spent or withdrawn now: ledger less earmarked and pending outgoing amounts.", "examples": [ 12000 ] }, "earmarked": { "type": "integer", "format": "int64", "description": "Amount reserved for open refunds or disputes.", "examples": [ 2000 ] }, "pending_outgoing": { "type": "integer", "format": "int64", "description": "Amount reserved for payments and withdrawals in progress.", "examples": [ 1000 ] }, "as_of": { "type": "string", "format": "date-time", "description": "Time of the balance.", "examples": [ "2026-10-15T14:05:41Z" ] } }, "required": [ "object", "account_id", "currency", "ledger", "available", "earmarked", "pending_outgoing", "as_of" ], "description": "Balance" }, "Counterparty": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "consumer", "merchant", "bank_account" ], "description": "Counterparty type.", "examples": [ "merchant" ] }, "customer_id": { "type": [ "string", "null" ], "description": "Counterparty customer identifier, for consumers and merchants of the same Tenant.", "examples": [ "cus_m7R5pWz1Hd" ] }, "display_name": { "type": "string", "description": "Name to show in the transaction history.", "examples": [ "Riverside Coffee" ] } }, "required": [ "type", "display_name" ], "description": "Counterparty" }, "Transaction": { "type": "object", "properties": { "id": { "type": "string", "description": "Transaction identifier.", "examples": [ "txn_2Qa5Ws8Ed1" ] }, "object": { "type": "string", "enum": [ "transaction" ], "description": "Object type.", "examples": [ "transaction" ] }, "account_id": { "type": "string", "description": "Digital Account identifier.", "examples": [ "acct_c3J8vN2Qe6" ] }, "type": { "type": "string", "enum": [ "load", "payment_sent", "payment_received", "withdrawal", "refund_sent", "refund_received", "dispute_credit", "dispute_reversal", "adjustment" ], "description": "Transaction type.", "examples": [ "payment_sent" ] }, "direction": { "type": "string", "enum": [ "credit", "debit" ], "description": "Effect on the account.", "examples": [ "debit" ] }, "amount": { "type": "integer", "format": "int64", "description": "Gross amount in cents.", "examples": [ 2500 ] }, "fee_amount": { "type": "integer", "format": "int64", "description": "Fees deducted from this account for the transaction, in cents.", "examples": [ 0 ] }, "net_amount": { "type": "integer", "format": "int64", "description": "Amount credited or debited after fees, in cents.", "examples": [ 2500 ] }, "currency": { "type": "string", "enum": [ "USD" ], "description": "Currency.", "examples": [ "USD" ] }, "status": { "type": "string", "enum": [ "pending", "posted", "reversed" ], "description": "Posting status.", "examples": [ "posted" ] }, "counterparty": { "anyOf": [ { "$ref": "#/components/schemas/Counterparty" }, { "type": "null" } ], "description": "The other party." }, "source_type": { "type": "string", "enum": [ "load", "payment", "withdrawal", "refund", "dispute", "adjustment" ], "description": "Record that created the transaction.", "examples": [ "payment" ] }, "source_id": { "type": "string", "description": "Identifier of that record.", "examples": [ "pay_3As6Df9Gh2" ] }, "description": { "type": [ "string", "null" ], "description": "Description shown to the customer.", "examples": [ "Order 55120" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Creation time.", "examples": [ "2026-10-15T14:04:10Z" ] }, "posted_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Posting time.", "examples": [ "2026-10-15T14:04:10Z" ] } }, "required": [ "id", "object", "account_id", "type", "direction", "amount", "fee_amount", "net_amount", "currency", "status", "source_type", "source_id", "created_at" ], "description": "Transaction" }, "Statement": { "type": "object", "properties": { "id": { "type": "string", "description": "Statement identifier.", "examples": [ "stmt_7Rf4Tg1Yh6" ] }, "object": { "type": "string", "enum": [ "statement" ], "description": "Object type.", "examples": [ "statement" ] }, "account_id": { "type": "string", "description": "Digital Account identifier.", "examples": [ "acct_c3J8vN2Qe6" ] }, "period_start": { "type": "string", "format": "date", "description": "First day of the period.", "examples": [ "2026-09-01" ] }, "period_end": { "type": "string", "format": "date", "description": "Last day of the period.", "examples": [ "2026-09-30" ] }, "opening_balance": { "type": "integer", "format": "int64", "description": "Opening balance in cents.", "examples": [ 0 ] }, "closing_balance": { "type": "integer", "format": "int64", "description": "Closing balance in cents.", "examples": [ 15000 ] }, "currency": { "type": "string", "enum": [ "USD" ], "description": "Currency.", "examples": [ "USD" ] }, "download_url": { "type": "string", "description": "Time-limited address of the PDF statement. Request the statement again for a fresh address.", "examples": [ "https://files.example-a2a.test/statements/stmt_7Rf4Tg1Yh6.pdf?sig=redacted" ] }, "download_url_expires_at": { "type": "string", "format": "date-time", "description": "Expiry of the download address.", "examples": [ "2026-10-15T14:20:22Z" ] }, "available_at": { "type": "string", "format": "date-time", "description": "When the statement became available.", "examples": [ "2026-10-01T09:00:00Z" ] } }, "required": [ "id", "object", "account_id", "period_start", "period_end", "opening_balance", "closing_balance", "currency", "download_url", "download_url_expires_at", "available_at" ], "description": "Statement" }, "Load": { "type": "object", "properties": { "id": { "type": "string", "description": "Load identifier.", "examples": [ "load_7Ty4Ui2Op9" ] }, "object": { "type": "string", "enum": [ "load" ], "description": "Object type.", "examples": [ "load" ] }, "customer_id": { "type": "string", "description": "Customer identifier.", "examples": [ "cus_c9T2kXq4Lm" ] }, "account_id": { "type": "string", "description": "Digital Account credited.", "examples": [ "acct_c3J8vN2Qe6" ] }, "linked_account_id": { "type": "string", "description": "Bank account the Request for Payment is sent to.", "examples": [ "la_5Gh2Xw8Pq1" ] }, "amount": { "type": "integer", "format": "int64", "description": "Amount in cents.", "examples": [ 10000 ] }, "currency": { "type": "string", "enum": [ "USD" ], "description": "Currency.", "examples": [ "USD" ] }, "status": { "type": "string", "enum": [ "requires_confirmation", "processing", "settled", "failed" ], "description": "Load status.", "examples": [ "requires_confirmation" ] }, "failure_code": { "type": [ "string", "null" ], "enum": [ "confirmation_expired", "declined_by_customer", "request_expired", "rejected_by_bank", "limit_exceeded", "account_restricted", null ], "description": "Reason for a failed load." }, "confirmation_session": { "anyOf": [ { "$ref": "#/components/schemas/ConfirmationSession" }, { "type": "null" } ], "description": "payment_confirm session. Returned only when the load is created." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation time.", "examples": [ "2026-10-15T14:03:22Z" ] }, "confirmed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer confirmed." }, "settled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the funds were credited." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time of the last change.", "examples": [ "2026-10-15T14:03:22Z" ] }, "version": { "type": "integer", "format": "int64", "description": "Increases by one on every change.", "examples": [ 1 ] } }, "required": [ "id", "object", "customer_id", "account_id", "linked_account_id", "amount", "currency", "status", "created_at", "updated_at", "version" ], "description": "Load" }, "CollectionPoint": { "type": "object", "properties": { "reference": { "type": "string", "description": "The Tenant's reference for the store, counter or machine.", "examples": [ "store-12-counter-2" ] }, "name": { "type": "string", "description": "Name shown to the payer on the confirmation screen.", "examples": [ "Riverside Coffee, Main St counter 2" ] } }, "required": [ "reference", "name" ], "description": "CollectionPoint" }, "PaymentRequest": { "type": "object", "properties": { "id": { "type": "string", "description": "Payment request identifier.", "examples": [ "pr_1Zx4Cv7Bn5" ] }, "object": { "type": "string", "enum": [ "payment_request" ], "description": "Object type.", "examples": [ "payment_request" ] }, "type": { "type": "string", "enum": [ "dynamic", "static" ], "description": "dynamic carries an amount and is paid once; static identifies a collection point and the payer enters the amount.", "examples": [ "dynamic" ] }, "merchant_customer_id": { "type": "string", "description": "Merchant to be paid.", "examples": [ "cus_m7R5pWz1Hd" ] }, "amount": { "type": [ "integer", "null" ], "format": "int64", "description": "Requested amount in cents. Present for dynamic requests.", "examples": [ 2500 ] }, "currency": { "type": "string", "enum": [ "USD" ], "description": "Currency.", "examples": [ "USD" ] }, "order_reference": { "type": [ "string", "null" ], "description": "The Tenant's order reference.", "examples": [ "ORD-55120" ] }, "collection_point": { "anyOf": [ { "$ref": "#/components/schemas/CollectionPoint" }, { "type": "null" } ], "description": "Collection point. Present for static requests." }, "status": { "type": "string", "enum": [ "open", "paid", "expired", "canceled" ], "description": "Request status. A static request stays open until canceled.", "examples": [ "open" ] }, "qr_payload": { "type": "string", "description": "Payload signed by A2A InstaPay, to encode in the QR code or in the Tenant's Link-to-Pay link.", "examples": [ "A2AQR1.pr_1Zx4Cv7Bn5.MEUCIQDf3k9sample" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Expiry of a dynamic request.", "examples": [ "2026-10-22T14:03:22Z" ] }, "paid_payment_id": { "type": [ "string", "null" ], "description": "Payment that paid a dynamic request." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation time.", "examples": [ "2026-10-15T14:03:22Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Time of the last change.", "examples": [ "2026-10-15T14:03:22Z" ] }, "version": { "type": "integer", "format": "int64", "description": "Increases by one on every change.", "examples": [ 1 ] } }, "required": [ "id", "object", "type", "merchant_customer_id", "currency", "status", "qr_payload", "created_at", "updated_at", "version" ], "description": "PaymentRequest" }, "Fee": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "platform", "tenant" ], "description": "Fee type.", "examples": [ "platform" ] }, "amount": { "type": "integer", "format": "int64", "description": "Fee in cents.", "examples": [ 50 ] }, "paid_by": { "type": "string", "enum": [ "payer", "payee" ], "description": "Party whose amount the fee is taken from.", "examples": [ "payee" ] } }, "required": [ "type", "amount", "paid_by" ], "description": "Fee" }, "Payment": { "type": "object", "properties": { "id": { "type": "string", "description": "Payment identifier.", "examples": [ "pay_3As6Df9Gh2" ] }, "object": { "type": "string", "enum": [ "payment" ], "description": "Object type.", "examples": [ "payment" ] }, "type": { "type": "string", "enum": [ "consumer_to_merchant", "merchant_to_merchant" ], "description": "Payment type.", "examples": [ "consumer_to_merchant" ] }, "source": { "type": "string", "enum": [ "balance", "bank_account" ], "description": "Source of funds.", "examples": [ "balance" ] }, "payer_customer_id": { "type": "string", "description": "Payer.", "examples": [ "cus_c9T2kXq4Lm" ] }, "payee_customer_id": { "type": "string", "description": "Merchant paid.", "examples": [ "cus_m7R5pWz1Hd" ] }, "payment_request_id": { "type": [ "string", "null" ], "description": "Payment request paid, where the payment came from a QR code or link.", "examples": [ "pr_1Zx4Cv7Bn5" ] }, "amount": { "type": "integer", "format": "int64", "description": "Amount in cents.", "examples": [ 2500 ] }, "currency": { "type": "string", "enum": [ "USD" ], "description": "Currency.", "examples": [ "USD" ] }, "fees": { "type": "array", "items": { "$ref": "#/components/schemas/Fee" }, "description": "Fees on the payment." }, "net_amount": { "type": "integer", "format": "int64", "description": "Amount credited to the merchant after fees, in cents.", "examples": [ 2450 ] }, "refunded_amount": { "type": "integer", "format": "int64", "description": "Total refunded so far, in cents.", "examples": [ 0 ] }, "status": { "type": "string", "enum": [ "requires_confirmation", "processing", "completed", "failed", "canceled", "refunded", "partially_refunded" ], "description": "Payment status.", "examples": [ "requires_confirmation" ] }, "failure_code": { "type": [ "string", "null" ], "enum": [ "confirmation_expired", "insufficient_funds", "limit_exceeded", "account_restricted", "declined_by_customer", "request_expired", "rejected_by_bank", null ], "description": "Reason for a failed payment." }, "order_reference": { "type": [ "string", "null" ], "description": "The Tenant's order reference.", "examples": [ "ORD-55120" ] }, "invoice_reference": { "type": [ "string", "null" ], "description": "Invoice reference. Required for merchant-to-merchant payments." }, "description": { "type": [ "string", "null" ], "description": "Description shown to both parties.", "examples": [ "Order 55120" ] }, "confirmation_session": { "anyOf": [ { "$ref": "#/components/schemas/ConfirmationSession" }, { "type": "null" } ], "description": "payment_confirm session. Returned only when the payment is created." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation time.", "examples": [ "2026-10-15T14:03:22Z" ] }, "confirmed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the payer confirmed." }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the merchant was credited." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time of the last change.", "examples": [ "2026-10-15T14:03:22Z" ] }, "version": { "type": "integer", "format": "int64", "description": "Increases by one on every change.", "examples": [ 1 ] } }, "required": [ "id", "object", "type", "source", "payer_customer_id", "payee_customer_id", "amount", "currency", "fees", "net_amount", "refunded_amount", "status", "created_at", "updated_at", "version" ], "description": "Payment" }, "Withdrawal": { "type": "object", "properties": { "id": { "type": "string", "description": "Withdrawal identifier.", "examples": [ "wd_6Mn3Bv8Cx1" ] }, "object": { "type": "string", "enum": [ "withdrawal" ], "description": "Object type.", "examples": [ "withdrawal" ] }, "customer_id": { "type": "string", "description": "Customer identifier.", "examples": [ "cus_m7R5pWz1Hd" ] }, "account_id": { "type": "string", "description": "Digital Account debited.", "examples": [ "acct_m4K1sB7Yt9" ] }, "linked_account_id": { "type": "string", "description": "Bank account credited.", "examples": [ "la_9Kj3Hg6Fd2" ] }, "amount": { "type": "integer", "format": "int64", "description": "Amount in cents.", "examples": [ 50000 ] }, "currency": { "type": "string", "enum": [ "USD" ], "description": "Currency.", "examples": [ "USD" ] }, "status": { "type": "string", "enum": [ "requires_confirmation", "processing", "settled", "failed" ], "description": "Withdrawal status.", "examples": [ "requires_confirmation" ] }, "failure_code": { "type": [ "string", "null" ], "enum": [ "confirmation_expired", "canceled_by_customer", "insufficient_funds", "limit_exceeded", "withdrawal_hold", "rejected_by_bank", "account_restricted", null ], "description": "Reason for a failed withdrawal. A failed withdrawal releases the reserved amount." }, "confirmation_session": { "anyOf": [ { "$ref": "#/components/schemas/ConfirmationSession" }, { "type": "null" } ], "description": "payment_confirm session. Returned only when the withdrawal is created." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation time.", "examples": [ "2026-10-15T14:03:22Z" ] }, "confirmed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the customer confirmed." }, "settled_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the transfer was final." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time of the last change.", "examples": [ "2026-10-15T14:03:22Z" ] }, "version": { "type": "integer", "format": "int64", "description": "Increases by one on every change.", "examples": [ 1 ] } }, "required": [ "id", "object", "customer_id", "account_id", "linked_account_id", "amount", "currency", "status", "created_at", "updated_at", "version" ], "description": "Withdrawal" }, "Refund": { "type": "object", "properties": { "id": { "type": "string", "description": "Refund identifier.", "examples": [ "rf_4Lk7Jh2Gf9" ] }, "object": { "type": "string", "enum": [ "refund" ], "description": "Object type.", "examples": [ "refund" ] }, "payment_id": { "type": "string", "description": "Payment refunded.", "examples": [ "pay_3As6Df9Gh2" ] }, "merchant_customer_id": { "type": "string", "description": "Merchant issuing the refund.", "examples": [ "cus_m7R5pWz1Hd" ] }, "payer_customer_id": { "type": "string", "description": "Consumer refunded.", "examples": [ "cus_c9T2kXq4Lm" ] }, "amount": { "type": "integer", "format": "int64", "description": "Refund amount in cents.", "examples": [ 1000 ] }, "currency": { "type": "string", "enum": [ "USD" ], "description": "Currency.", "examples": [ "USD" ] }, "reason": { "type": "string", "enum": [ "requested_by_customer", "duplicate", "goods_not_received", "other" ], "description": "Reason given by the merchant.", "examples": [ "requested_by_customer" ] }, "destination": { "type": "string", "enum": [ "balance", "bank_account" ], "description": "Where the refund is sent: the consumer's Digital Account, or the consumer's linked account for pay by bank.", "examples": [ "balance" ] }, "status": { "type": "string", "enum": [ "requested", "pending_funds", "processing", "completed", "failed" ], "description": "Refund status.", "examples": [ "requested" ] }, "failure_code": { "type": [ "string", "null" ], "enum": [ "confirmation_expired", "rejected_by_bank", "account_restricted", null ], "description": "Reason for a failed refund." }, "confirmation_session": { "anyOf": [ { "$ref": "#/components/schemas/ConfirmationSession" }, { "type": "null" } ], "description": "payment_confirm session for the merchant. Returned only when the refund is requested." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation time.", "examples": [ "2026-10-15T14:03:22Z" ] }, "completed_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the refund was applied." }, "updated_at": { "type": "string", "format": "date-time", "description": "Time of the last change.", "examples": [ "2026-10-15T14:03:22Z" ] }, "version": { "type": "integer", "format": "int64", "description": "Increases by one on every change.", "examples": [ 1 ] } }, "required": [ "id", "object", "payment_id", "merchant_customer_id", "payer_customer_id", "amount", "currency", "reason", "destination", "status", "created_at", "updated_at", "version" ], "description": "Refund" }, "Dispute": { "type": "object", "properties": { "id": { "type": "string", "description": "Dispute identifier.", "examples": [ "dsp_9Po2Iu5Yt3" ] }, "object": { "type": "string", "enum": [ "dispute" ], "description": "Object type.", "examples": [ "dispute" ] }, "customer_id": { "type": "string", "description": "Customer who gave notice.", "examples": [ "cus_c9T2kXq4Lm" ] }, "type": { "type": "string", "enum": [ "error", "unauthorized_transfer", "purchase_dispute" ], "description": "Type of notice.", "examples": [ "unauthorized_transfer" ] }, "payment_id": { "type": [ "string", "null" ], "description": "Payment concerned, where there is one.", "examples": [ "pay_3As6Df9Gh2" ] }, "transaction_id": { "type": [ "string", "null" ], "description": "Transaction concerned, where there is one." }, "description": { "type": "string", "description": "The customer's description, as given.", "examples": [ "I did not make this payment." ] }, "regulation_e": { "type": "boolean", "description": "True where the notice is handled under Regulation E error resolution.", "examples": [ true ] }, "notice_received_at": { "type": "string", "format": "date-time", "description": "When the customer first gave notice, to the Tenant or to A2A InstaPay.", "examples": [ "2026-10-15T13:40:00Z" ] }, "status": { "type": "string", "enum": [ "received", "investigating", "provisional_credit", "resolved", "closed" ], "description": "Dispute status.", "examples": [ "received" ] }, "provisional_credit_amount": { "type": [ "integer", "null" ], "format": "int64", "description": "Provisional credit given, in cents." }, "outcome": { "type": [ "string", "null" ], "enum": [ "error_found", "no_error_found", null ], "description": "Result of the investigation." }, "resolved_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time the investigation was completed." }, "created_at": { "type": "string", "format": "date-time", "description": "Creation time.", "examples": [ "2026-10-15T14:03:22Z" ] }, "updated_at": { "type": "string", "format": "date-time", "description": "Time of the last change.", "examples": [ "2026-10-15T14:03:22Z" ] }, "version": { "type": "integer", "format": "int64", "description": "Increases by one on every change.", "examples": [ 1 ] } }, "required": [ "id", "object", "customer_id", "type", "description", "regulation_e", "notice_received_at", "status", "created_at", "updated_at", "version" ], "description": "Dispute" }, "EventData": { "type": "object", "properties": { "object": { "type": "object", "additionalProperties": true, "description": "The full object after the change, in the same form the API returns." }, "previous_attributes": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Values of the changed fields before the change." } }, "required": [ "object" ], "description": "EventData" }, "Event": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier. Use it to discard duplicate deliveries.", "examples": [ "evt_5Ujm8Ik2Ol4" ] }, "object": { "type": "string", "enum": [ "event" ], "description": "Object type.", "examples": [ "event" ] }, "type": { "type": "string", "description": "Event type, from the event catalog.", "examples": [ "payment.completed" ] }, "api_version": { "type": "string", "enum": [ "v1" ], "description": "API version of the object in data.", "examples": [ "v1" ] }, "environment": { "type": "string", "enum": [ "sandbox", "production" ], "description": "Environment that sent the event.", "examples": [ "sandbox" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Time of the change.", "examples": [ "2026-10-15T14:04:10Z" ] }, "data": { "$ref": "#/components/schemas/EventData", "description": "The changed object." } }, "required": [ "id", "object", "type", "api_version", "environment", "created_at", "data" ], "description": "Event" }, "Delivery": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "pending", "delivered", "retrying", "failed" ], "description": "Delivery status to the Tenant's endpoint.", "examples": [ "delivered" ] }, "attempts": { "type": "integer", "format": "int64", "description": "Number of delivery attempts.", "examples": [ 1 ] }, "last_attempt_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the last attempt.", "examples": [ "2026-10-15T14:04:10Z" ] }, "last_response_status": { "type": [ "integer", "null" ], "format": "int64", "description": "HTTP status returned by the Tenant on the last attempt.", "examples": [ 200 ] }, "next_attempt_at": { "type": [ "string", "null" ], "format": "date-time", "description": "Time of the next attempt, while retrying." } }, "required": [ "status", "attempts" ], "description": "Delivery" }, "WebhookEvent": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique event identifier. Use it to discard duplicate deliveries.", "examples": [ "evt_5Ujm8Ik2Ol4" ] }, "object": { "type": "string", "enum": [ "event" ], "description": "Object type.", "examples": [ "event" ] }, "type": { "type": "string", "description": "Event type, from the event catalog.", "examples": [ "payment.completed" ] }, "api_version": { "type": "string", "enum": [ "v1" ], "description": "API version of the object in data.", "examples": [ "v1" ] }, "environment": { "type": "string", "enum": [ "sandbox", "production" ], "description": "Environment that sent the event.", "examples": [ "sandbox" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Time of the change.", "examples": [ "2026-10-15T14:04:10Z" ] }, "data": { "$ref": "#/components/schemas/EventData", "description": "The changed object." }, "delivery": { "$ref": "#/components/schemas/Delivery", "description": "Delivery record." } }, "required": [ "id", "object", "type", "api_version", "environment", "created_at", "data", "delivery" ], "description": "WebhookEvent" }, "ReconTotals": { "type": "object", "properties": { "loads": { "type": "integer", "format": "int64", "description": "Total loads credited, in cents.", "examples": [ 250000 ] }, "payments": { "type": "integer", "format": "int64", "description": "Total payments between Digital Accounts and by bank, in cents.", "examples": [ 410000 ] }, "withdrawals": { "type": "integer", "format": "int64", "description": "Total withdrawals, in cents.", "examples": [ 180000 ] }, "refunds": { "type": "integer", "format": "int64", "description": "Total refunds, in cents.", "examples": [ 12000 ] }, "fees": { "type": "integer", "format": "int64", "description": "Total fees posted to the fee clearing position, in cents.", "examples": [ 8200 ] }, "adjustments": { "type": "integer", "format": "int64", "description": "Total dispute credits, reversals and other adjustments, in cents.", "examples": [ 0 ] } }, "required": [ "loads", "payments", "withdrawals", "refunds", "fees", "adjustments" ], "description": "ReconTotals" }, "FileLink": { "type": "object", "properties": { "format": { "type": "string", "enum": [ "csv" ], "description": "File format.", "examples": [ "csv" ] }, "download_url": { "type": "string", "description": "Time-limited address of the file.", "examples": [ "https://files.example-a2a.test/recon/2026-10-14.csv?sig=redacted" ] }, "expires_at": { "type": "string", "format": "date-time", "description": "Expiry of the address.", "examples": [ "2026-10-15T14:20:22Z" ] } }, "required": [ "format", "download_url", "expires_at" ], "description": "FileLink" }, "ReconciliationReport": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "reconciliation_report" ], "description": "Object type.", "examples": [ "reconciliation_report" ] }, "date": { "type": "string", "format": "date", "description": "Business date (Eastern Time).", "examples": [ "2026-10-14" ] }, "account_structure": { "type": "string", "enum": [ "dedicated_fbo", "tenant_scheme" ], "description": "Account structure of the Tenant.", "examples": [ "dedicated_fbo" ] }, "currency": { "type": "string", "enum": [ "USD" ], "description": "Currency.", "examples": [ "USD" ] }, "opening_balance": { "type": "integer", "format": "int64", "description": "Sum of the Tenant's customer balances at the start of the day, in cents.", "examples": [ 1250000 ] }, "closing_balance": { "type": "integer", "format": "int64", "description": "Sum of the Tenant's customer balances at the end of the day, in cents.", "examples": [ 1301800 ] }, "totals": { "$ref": "#/components/schemas/ReconTotals", "description": "Totals by movement type." }, "fee_clearing_swept": { "type": "integer", "format": "int64", "description": "Fees swept from the fee clearing position to operating accounts during the day, in cents.", "examples": [ 8200 ] }, "postings_count": { "type": "integer", "format": "int64", "description": "Number of postings in the file.", "examples": [ 1342 ] }, "file": { "$ref": "#/components/schemas/FileLink", "description": "The posting-level file." }, "generated_at": { "type": "string", "format": "date-time", "description": "Time the report was produced.", "examples": [ "2026-10-15T06:00:00Z" ] } }, "required": [ "object", "date", "account_structure", "currency", "opening_balance", "closing_balance", "totals", "fee_clearing_swept", "postings_count", "file", "generated_at" ], "description": "ReconciliationReport" }, "SimulationResult": { "type": "object", "properties": { "object": { "type": "string", "enum": [ "simulation" ], "description": "Object type.", "examples": [ "simulation" ] }, "event": { "type": "string", "description": "Simulated event.", "examples": [ "payment.completed" ] }, "object_id": { "type": "string", "description": "Record the simulation acted on.", "examples": [ "pay_3As6Df9Gh2" ] }, "status": { "type": "string", "enum": [ "accepted" ], "description": "The simulation was accepted; the resulting webhook follows.", "examples": [ "accepted" ] } }, "required": [ "object", "event", "object_id", "status" ], "description": "SimulationResult" }, "CustomerList": { "type": "object", "required": [ "object", "data", "has_more" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "OwnerList": { "type": "object", "required": [ "object", "data", "has_more" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Owner" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "DocumentAcceptanceList": { "type": "object", "required": [ "object", "data", "has_more" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DocumentAcceptance" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "LinkedAccountList": { "type": "object", "required": [ "object", "data", "has_more" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LinkedAccount" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "AccountList": { "type": "object", "required": [ "object", "data", "has_more" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Account" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "TransactionList": { "type": "object", "required": [ "object", "data", "has_more" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "StatementList": { "type": "object", "required": [ "object", "data", "has_more" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Statement" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "DisputeList": { "type": "object", "required": [ "object", "data", "has_more" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Dispute" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } }, "WebhookEventList": { "type": "object", "required": [ "object", "data", "has_more" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEvent" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } } } }, "securitySchemes": { "oauth2": { "type": "oauth2", "description": "OAuth 2.0 client credentials. One client per Tenant per environment.", "flows": { "clientCredentials": { "tokenUrl": "/oauth/token", "scopes": { "tenant": "Tenant access" } } } } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": true, "description": "Unique key for this request, up to 255 characters. A repeated key within 24 hours returns the original result.", "schema": { "type": "string", "maxLength": 255 } } }, "headers": { "RequestId": { "description": "Identifier of the request. Quote it to support.", "schema": { "type": "string" } }, "RateLimitLimit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer" } }, "RateLimitRemaining": { "description": "Requests remaining in the current window.", "schema": { "type": "integer" } }, "RateLimitReset": { "description": "Seconds until the window resets.", "schema": { "type": "integer" } } } } }