API schemas
These reusable schemas are rendered directly from the curated OpenAPI artifact. A required-property list is shown when the schema declares one; the complete typed JSON Schema remains available beside it.
AcceptDisputeClaimRequest
Request body for accepting liability on a PayPal dispute claim.
Type: object
Required: note
{ "additionalProperties": false, "description": "Request body for accepting liability on a PayPal dispute claim.", "properties": { "note": { "minLength": 1, "title": "Note", "type": "string" } }, "required": [ "note" ], "title": "AcceptDisputeClaimRequest", "type": "object"}AcknowledgeReturnItemRequest
Request body for acknowledging a PayPal dispute return item.
Type: object
Required: acknowledgement_type
{ "additionalProperties": false, "description": "Request body for acknowledging a PayPal dispute return item.", "properties": { "acknowledgement_type": { "examples": [ "DAMAGED", "EMPTY_PACKAGE_OR_DIFFERENT", "ITEM_NOT_RECEIVED", "ITEM_RECEIVED", "MISSING_ITEMS" ], "minLength": 1, "title": "Acknowledgement Type", "type": "string" }, "note": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Note" } }, "required": [ "acknowledgement_type" ], "title": "AcknowledgeReturnItemRequest", "type": "object"}AppealDisputeRequest
Request body for appealing a resolved PayPal dispute.
Type: object
{ "additionalProperties": false, "description": "Request body for appealing a resolved PayPal dispute.", "properties": { "document_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Text" }, "evidence_type": { "default": "PROOF_OF_FULFILLMENT", "minLength": 1, "title": "Evidence Type", "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" } }, "title": "AppealDisputeRequest", "type": "object"}CaptureOrderRequest
Optional buyer context supplied while capturing an approved order.
Type: object
{ "additionalProperties": false, "description": "Optional buyer context supplied while capturing an approved order.", "properties": { "funding_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Funding Source" }, "paypal_client_metadata_id": { "anyOf": [ { "maxLength": 68, "minLength": 1, "pattern": "^[A-Za-z0-9\\-{}(),]+$", "type": "string" }, { "type": "null" } ], "title": "Paypal Client Metadata Id" } }, "title": "CaptureOrderRequest", "type": "object"}ChannelApiKeyCreateRequest
Name a new key for the calling channel.
A name and nothing else. The environment is taken from the credential
making the call, not from here, so a test key cannot mint a live one; and
the owning channel comes from the credential too, as everywhere else on
this surface — extra="forbid" is what makes a body-supplied
channel_id or environment a 422 rather than a silently ignored
field.
Type: object
Required: name
{ "additionalProperties": false, "description": "Name a new key for the calling channel.\n\nA name and nothing else. The environment is taken from the credential\nmaking the call, not from here, so a test key cannot mint a live one; and\nthe owning channel comes from the credential too, as everywhere else on\nthis surface — ``extra=\"forbid\"`` is what makes a body-supplied\n``channel_id`` or ``environment`` a 422 rather than a silently ignored\nfield.", "properties": { "name": { "maxLength": 100, "minLength": 1, "title": "Name", "type": "string" } }, "required": [ "name" ], "title": "ChannelApiKeyCreateRequest", "type": "object"}ChannelMerchantCreateRequest
Create a merchant under the calling channel.
extra="forbid" is load-bearing, not just tidy validation: it is what
makes a body-supplied channel_id impossible rather than merely
ignored — the field does not exist on this model, so a request carrying
one fails validation (422) before any handler code runs. Ownership always
comes from the authenticated channel credential, never from the request
body. The merchant's country is likewise explicit: omission fails instead
of silently creating a US merchant.
Type: object
Required: business_name, email, country_code
{ "additionalProperties": false, "description": "Create a merchant under the calling channel.\n\n``extra=\"forbid\"`` is load-bearing, not just tidy validation: it is what\nmakes a body-supplied ``channel_id`` impossible rather than merely\nignored — the field does not exist on this model, so a request carrying\none fails validation (422) before any handler code runs. Ownership always\ncomes from the authenticated channel credential, never from the request\nbody. The merchant's country is likewise explicit: omission fails instead\nof silently creating a US merchant.", "properties": { "business_name": { "maxLength": 255, "minLength": 1, "title": "Business Name", "type": "string" }, "country_code": { "title": "Country Code", "type": "string" }, "email": { "format": "email", "title": "Email", "type": "string" } }, "required": [ "business_name", "email", "country_code" ], "title": "ChannelMerchantCreateRequest", "type": "object"}ChannelMerchantCreateResponse
Identifiers for a merchant created under a channel.
Type: object
Required: merchant_id, business_name, email, channel_id, country_code, onboarding_status, created_at
{ "additionalProperties": false, "description": "Identifiers for a merchant created under a channel.", "properties": { "business_name": { "title": "Business Name", "type": "string" }, "channel_id": { "title": "Channel Id", "type": "string" }, "country_code": { "title": "Country Code", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "email": { "title": "Email", "type": "string" }, "merchant_id": { "title": "Merchant Id", "type": "string" }, "onboarding_status": { "title": "Onboarding Status", "type": "string" } }, "required": [ "merchant_id", "business_name", "email", "channel_id", "country_code", "onboarding_status", "created_at" ], "title": "ChannelMerchantCreateResponse", "type": "object"}ChannelMerchantListResponse
One page of the calling channel's merchants, with the size of the book.
An envelope rather than a bare array, matching
ChannelStatementLinesResponse: a channel walking its book needs to know
when to stop, and total — the count under the same filters, not the
length of this page — is the only thing that tells it. The bare-array shape
used by GET /api/channel/statements works there because a channel has a
handful of statements and hundreds of merchants.
Type: object
Required: total, limit, offset
{ "additionalProperties": false, "description": "One page of the calling channel's merchants, with the size of the book.\n\nAn envelope rather than a bare array, matching\n``ChannelStatementLinesResponse``: a channel walking its book needs to know\nwhen to stop, and ``total`` — the count under the same filters, not the\nlength of this page — is the only thing that tells it. The bare-array shape\nused by ``GET /api/channel/statements`` works there because a channel has a\nhandful of statements and hundreds of merchants.", "properties": { "limit": { "title": "Limit", "type": "integer" }, "merchants": { "items": { "$ref": "#/components/schemas/ChannelMerchantSummary" }, "title": "Merchants", "type": "array" }, "offset": { "title": "Offset", "type": "integer" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "total", "limit", "offset" ], "title": "ChannelMerchantListResponse", "type": "object"}ChannelMerchantStatusResponse
Onboarding progress and PayPal capability status for one channel merchant.
Deliberately leaner than the dashboard's MerchantResponse: a channel
does not need Pay Later Messaging config, checkout branding, or shipping
settings to answer "where does my merchant stand" — only whether they are
connected, what (if anything) is blocking them, and which payment
capabilities (Advanced Card Checkout, Venmo/Pay Later platform-fee
checkout, ...) PayPal has actually granted so far. Built from the same
helpers MerchantResponse uses (app.schemas.merchant), so the two
surfaces cannot silently disagree about what "connected" means.
A capability that is not granted yet carries the reason PayPal gave for
it, because "PayPal is still underwriting" and "PayPal asked your merchant
for documents" demand opposite responses from a channel's support team and
the connection-level fields cannot tell them apart.
Type: object
Required: merchant_id, onboarding_status, paypal_connection_status, payments_enabled, checkout_enabled
{ "additionalProperties": false, "description": "Onboarding progress and PayPal capability status for one channel merchant.\n\nDeliberately leaner than the dashboard's ``MerchantResponse``: a channel\ndoes not need Pay Later Messaging config, checkout branding, or shipping\nsettings to answer \"where does my merchant stand\" — only whether they are\nconnected, what (if anything) is blocking them, and which payment\ncapabilities (Advanced Card Checkout, Venmo/Pay Later platform-fee\ncheckout, ...) PayPal has actually granted so far. Built from the same\nhelpers ``MerchantResponse`` uses (``app.schemas.merchant``), so the two\nsurfaces cannot silently disagree about what \"connected\" means.\n\nA capability that is not granted yet carries the reason PayPal gave for\nit, because \"PayPal is still underwriting\" and \"PayPal asked your merchant\nfor documents\" demand opposite responses from a channel's support team and\nthe connection-level fields cannot tell them apart.", "properties": { "checkout_enabled": { "title": "Checkout Enabled", "type": "boolean" }, "merchant_id": { "title": "Merchant Id", "type": "string" }, "onboarding_status": { "title": "Onboarding Status", "type": "string" }, "payments_enabled": { "title": "Payments Enabled", "type": "boolean" }, "paypal_acdc_status": { "anyOf": [ { "enum": [ "unavailable", "in_review", "need_more_data", "denied", "active" ], "type": "string" }, { "type": "null" } ], "title": "Paypal Acdc Status" }, "paypal_apple_pay_status": { "anyOf": [ { "enum": [ "unavailable", "in_review", "need_more_data", "denied", "active" ], "type": "string" }, { "type": "null" } ], "title": "Paypal Apple Pay Status" }, "paypal_connection_status": { "title": "Paypal Connection Status", "type": "string" }, "paypal_google_pay_status": { "anyOf": [ { "enum": [ "unavailable", "in_review", "need_more_data", "denied", "active" ], "type": "string" }, { "type": "null" } ], "title": "Paypal Google Pay Status" }, "paypal_missing_scopes": { "items": { "type": "string" }, "title": "Paypal Missing Scopes", "type": "array" }, "paypal_primary_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Paypal Primary Currency" }, "paypal_scope_feature_status": { "additionalProperties": { "type": "boolean" }, "title": "Paypal Scope Feature Status", "type": "object" }, "paypal_status_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Paypal Status Reason" }, "paypal_status_reason_fresh": { "default": true, "title": "Paypal Status Reason Fresh", "type": "boolean" } }, "required": [ "merchant_id", "onboarding_status", "paypal_connection_status", "payments_enabled", "checkout_enabled" ], "title": "ChannelMerchantStatusResponse", "type": "object"}ChannelMerchantSummary
One merchant as it appears in the calling channel's own listing.
Deliberately narrower than ChannelMerchantStatusResponse: that response
is a *live* read — it calls PayPal to refresh one merchant before answering
— and a listing cannot do that per row without turning one page of fifty
into fifty outbound calls. So this is the stored state, and the two per-
capability maps (paypal_missing_scopes,
paypal_scope_feature_status) are left to the per-merchant read that can
be sure they are current.
What survives the narrowing is what an operator triages on: which merchants
are still moving through onboarding, which ones can take money today, and
the identifying fields (business_name, email) the channel itself
supplied at provisioning, so a merchant can be found again when its id was
the copy that got lost.
Type: object
Required: merchant_id, business_name, email, country_code, onboarding_status, paypal_connection_status, payments_enabled, created_at
{ "additionalProperties": false, "description": "One merchant as it appears in the calling channel's own listing.\n\nDeliberately narrower than ``ChannelMerchantStatusResponse``: that response\nis a *live* read — it calls PayPal to refresh one merchant before answering\n— and a listing cannot do that per row without turning one page of fifty\ninto fifty outbound calls. So this is the stored state, and the two per-\ncapability maps (``paypal_missing_scopes``,\n``paypal_scope_feature_status``) are left to the per-merchant read that can\nbe sure they are current.\n\nWhat survives the narrowing is what an operator triages on: which merchants\nare still moving through onboarding, which ones can take money today, and\nthe identifying fields (``business_name``, ``email``) the channel itself\nsupplied at provisioning, so a merchant can be found again when its id was\nthe copy that got lost.", "properties": { "business_name": { "title": "Business Name", "type": "string" }, "country_code": { "title": "Country Code", "type": "string" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "email": { "title": "Email", "type": "string" }, "merchant_id": { "title": "Merchant Id", "type": "string" }, "onboarding_status": { "title": "Onboarding Status", "type": "string" }, "payments_enabled": { "title": "Payments Enabled", "type": "boolean" }, "paypal_connection_status": { "title": "Paypal Connection Status", "type": "string" }, "paypal_status_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Paypal Status Reason" } }, "required": [ "merchant_id", "business_name", "email", "country_code", "onboarding_status", "paypal_connection_status", "payments_enabled", "created_at" ], "title": "ChannelMerchantSummary", "type": "object"}ChannelStatementLineResponse
One transaction's contribution to a statement, exactly as it was frozen.
Type: object
Required: id, entry_type, transaction_id, merchant_id, merchant_name, provider, provider_capture_id, captured_at, amount_cents, amount_display, platform_fee_accrued_cents, platform_fee_refunded_cents, platform_fee_net_cents, platform_fee_collected_cents, applied_fee_share_basis_points, applied_per_transaction_minor_units, per_transaction_amount_cents, channel_share_cents, channel_share_display
{ "additionalProperties": false, "description": "One transaction's contribution to a statement, exactly as it was frozen.", "properties": { "amount_cents": { "title": "Amount Cents", "type": "integer" }, "amount_display": { "title": "Amount Display", "type": "string" }, "applied_fee_share_basis_points": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Applied Fee Share Basis Points" }, "applied_per_transaction_minor_units": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Applied Per Transaction Minor Units" }, "captured_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Captured At" }, "channel_share_cents": { "title": "Channel Share Cents", "type": "integer" }, "channel_share_display": { "title": "Channel Share Display", "type": "string" }, "entry_type": { "title": "Entry Type", "type": "string" }, "id": { "title": "Id", "type": "string" }, "merchant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Merchant Id" }, "merchant_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Merchant Name" }, "per_transaction_amount_cents": { "title": "Per Transaction Amount Cents", "type": "integer" }, "platform_fee_accrued_cents": { "title": "Platform Fee Accrued Cents", "type": "integer" }, "platform_fee_collected_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Platform Fee Collected Cents" }, "platform_fee_net_cents": { "title": "Platform Fee Net Cents", "type": "integer" }, "platform_fee_refunded_cents": { "title": "Platform Fee Refunded Cents", "type": "integer" }, "provider": { "title": "Provider", "type": "string" }, "provider_capture_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Capture Id" }, "transaction_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transaction Id" } }, "required": [ "id", "entry_type", "transaction_id", "merchant_id", "merchant_name", "provider", "provider_capture_id", "captured_at", "amount_cents", "amount_display", "platform_fee_accrued_cents", "platform_fee_refunded_cents", "platform_fee_net_cents", "platform_fee_collected_cents", "applied_fee_share_basis_points", "applied_per_transaction_minor_units", "per_transaction_amount_cents", "channel_share_cents", "channel_share_display" ], "title": "ChannelStatementLineResponse", "type": "object"}ChannelStatementLinesResponse
A page of statement lines, with the total so a reader knows when to stop. Offset paging is stable here in a way it is not on the live transactions list: an issued statement's lines cannot change, so page two is still page two however long the walk takes.
Type: object
Required: statement_id, currency, total, limit, offset, lines
{ "additionalProperties": false, "description": "A page of statement lines, with the total so a reader knows when to stop.\n\nOffset paging is stable here in a way it is not on the live transactions\nlist: an issued statement's lines cannot change, so page two is still page\ntwo however long the walk takes.", "properties": { "currency": { "title": "Currency", "type": "string" }, "limit": { "title": "Limit", "type": "integer" }, "lines": { "items": { "$ref": "#/components/schemas/ChannelStatementLineResponse" }, "title": "Lines", "type": "array" }, "offset": { "title": "Offset", "type": "integer" }, "statement_id": { "title": "Statement Id", "type": "string" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "statement_id", "currency", "total", "limit", "offset", "lines" ], "title": "ChannelStatementLinesResponse", "type": "object"}ChannelStatementRailSummaryResponse
What one rail contributed to a period, and why it may not have counted.
Type: object
Required: provider, transaction_count, captured_amount_cents, captured_amount_display, platform_fee_accrued_cents, platform_fee_accrued_display, fee_visibility, included_in_settlement, exclusion_reason
{ "additionalProperties": false, "description": "What one rail contributed to a period, and why it may not have counted.", "properties": { "captured_amount_cents": { "title": "Captured Amount Cents", "type": "integer" }, "captured_amount_display": { "title": "Captured Amount Display", "type": "string" }, "exclusion_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Exclusion Reason" }, "fee_visibility": { "title": "Fee Visibility", "type": "string" }, "included_in_settlement": { "title": "Included In Settlement", "type": "boolean" }, "platform_fee_accrued_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Platform Fee Accrued Cents" }, "platform_fee_accrued_display": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Platform Fee Accrued Display" }, "provider": { "title": "Provider", "type": "string" }, "transaction_count": { "title": "Transaction Count", "type": "integer" } }, "required": [ "provider", "transaction_count", "captured_amount_cents", "captured_amount_display", "platform_fee_accrued_cents", "platform_fee_accrued_display", "fee_visibility", "included_in_settlement", "exclusion_reason" ], "title": "ChannelStatementRailSummaryResponse", "type": "object"}ChannelStatementResponse
A statement as issued: what is owed, on what basis, and what was left out.
Type: object
Required: id, channel_id, period_start, period_end, currency, status, volume_basis, share_basis, terms_type, terms_description, terms_fee_share_basis_points, terms_per_transaction_minor_units, terms_per_transaction_currency, accounted_transaction_count, accounted_captured_amount_cents, accounted_captured_amount_display, platform_fee_accrued_cents, platform_fee_accrued_display, platform_fee_refunded_cents, platform_fee_refunded_display, platform_fee_accrued_net_cents, platform_fee_accrued_net_display, platform_fee_collected_cents, platform_fee_collected_display, channel_share_cents, channel_share_display, excluded_transaction_count, excluded_captured_amount_cents, excluded_captured_amount_display, rail_summaries, supersedes_statement_id, superseded_by_statement_id, correction_reason, generated_at
{ "additionalProperties": false, "description": "A statement as issued: what is owed, on what basis, and what was left out.", "properties": { "accounted_captured_amount_cents": { "title": "Accounted Captured Amount Cents", "type": "integer" }, "accounted_captured_amount_display": { "title": "Accounted Captured Amount Display", "type": "string" }, "accounted_transaction_count": { "title": "Accounted Transaction Count", "type": "integer" }, "channel_id": { "title": "Channel Id", "type": "string" }, "channel_share_cents": { "title": "Channel Share Cents", "type": "integer" }, "channel_share_display": { "title": "Channel Share Display", "type": "string" }, "correction_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Correction Reason" }, "currency": { "title": "Currency", "type": "string" }, "excluded_captured_amount_cents": { "title": "Excluded Captured Amount Cents", "type": "integer" }, "excluded_captured_amount_display": { "title": "Excluded Captured Amount Display", "type": "string" }, "excluded_transaction_count": { "title": "Excluded Transaction Count", "type": "integer" }, "generated_at": { "format": "date-time", "title": "Generated At", "type": "string" }, "generated_by": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Generated By" }, "id": { "title": "Id", "type": "string" }, "period_end": { "format": "date", "title": "Period End", "type": "string" }, "period_start": { "format": "date", "title": "Period Start", "type": "string" }, "platform_fee_accrued_cents": { "title": "Platform Fee Accrued Cents", "type": "integer" }, "platform_fee_accrued_display": { "title": "Platform Fee Accrued Display", "type": "string" }, "platform_fee_accrued_net_cents": { "title": "Platform Fee Accrued Net Cents", "type": "integer" }, "platform_fee_accrued_net_display": { "title": "Platform Fee Accrued Net Display", "type": "string" }, "platform_fee_collected_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Platform Fee Collected Cents" }, "platform_fee_collected_display": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Platform Fee Collected Display" }, "platform_fee_refunded_cents": { "title": "Platform Fee Refunded Cents", "type": "integer" }, "platform_fee_refunded_display": { "title": "Platform Fee Refunded Display", "type": "string" }, "rail_summaries": { "items": { "$ref": "#/components/schemas/ChannelStatementRailSummaryResponse" }, "title": "Rail Summaries", "type": "array" }, "share_basis": { "title": "Share Basis", "type": "string" }, "status": { "title": "Status", "type": "string" }, "superseded_by_statement_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Superseded By Statement Id" }, "supersedes_statement_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Supersedes Statement Id" }, "terms_description": { "title": "Terms Description", "type": "string" }, "terms_fee_share_basis_points": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Terms Fee Share Basis Points" }, "terms_per_transaction_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Terms Per Transaction Currency" }, "terms_per_transaction_minor_units": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Terms Per Transaction Minor Units" }, "terms_type": { "title": "Terms Type", "type": "string" }, "volume_basis": { "title": "Volume Basis", "type": "string" } }, "required": [ "id", "channel_id", "period_start", "period_end", "currency", "status", "volume_basis", "share_basis", "terms_type", "terms_description", "terms_fee_share_basis_points", "terms_per_transaction_minor_units", "terms_per_transaction_currency", "accounted_transaction_count", "accounted_captured_amount_cents", "accounted_captured_amount_display", "platform_fee_accrued_cents", "platform_fee_accrued_display", "platform_fee_refunded_cents", "platform_fee_refunded_display", "platform_fee_accrued_net_cents", "platform_fee_accrued_net_display", "platform_fee_collected_cents", "platform_fee_collected_display", "channel_share_cents", "channel_share_display", "excluded_transaction_count", "excluded_captured_amount_cents", "excluded_captured_amount_display", "rail_summaries", "supersedes_statement_id", "superseded_by_statement_id", "correction_reason", "generated_at" ], "title": "ChannelStatementResponse", "type": "object"}ChannelWebhookEndpointUpdateRequest
Partial channel endpoint update with explicit lifecycle and secret changes.
Type: object
{ "additionalProperties": false, "description": "Partial channel endpoint update with explicit lifecycle and secret changes.", "minProperties": 1, "properties": { "description": { "anyOf": [ { "maxLength": 255, "type": "string" }, { "type": "null" } ], "title": "Description" }, "event_types": { "items": { "type": "string" }, "title": "Event Types", "type": "array" }, "rotate_secret": { "default": false, "title": "Rotate Secret", "type": "boolean" }, "url": { "maxLength": 2048, "title": "Url", "type": "string" } }, "title": "ChannelWebhookEndpointUpdateRequest", "type": "object"}ChannelWebhookEndpointUpdateResponse
PATCH response that returns a secret only after explicit atomic rotation.
Type: object
Required: id, url, description, enabled, status, secret_hint, event_types, created_at, updated_at
{ "description": "PATCH response that returns a secret only after explicit atomic rotation.", "properties": { "created_at": { "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "enabled": { "title": "Enabled", "type": "boolean" }, "event_types": { "items": { "type": "string" }, "title": "Event Types", "type": "array" }, "id": { "title": "Id", "type": "string" }, "secret": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Secret" }, "secret_hint": { "title": "Secret Hint", "type": "string" }, "status": { "title": "Status", "type": "string" }, "updated_at": { "title": "Updated At", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "id", "url", "description", "enabled", "status", "secret_hint", "event_types", "created_at", "updated_at" ], "title": "ChannelWebhookEndpointUpdateResponse", "type": "object"}CheckoutBrandingPublic
Type: object
{ "properties": { "brand_color": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Brand Color" }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Logo Url" } }, "title": "CheckoutBrandingPublic", "type": "object"}CheckoutSessionClientTokenResponse
The short-lived PayPal token a checkout page needs to mount Card Fields.
Hand client_token to the PayPal JS SDK as its data-client-token
attribute; without it the SDK renders no card form. It is minted for the
PayPal account of the merchant that owns the checkout session, and it
authorises rendering a card form rather than moving money. Tokens expire
quickly, so mint one per page load instead of caching it.
Type: object
Required: client_token
{ "description": "The short-lived PayPal token a checkout page needs to mount Card Fields.\n\nHand `client_token` to the PayPal JS SDK as its `data-client-token`\nattribute; without it the SDK renders no card form. It is minted for the\nPayPal account of the merchant that owns the checkout session, and it\nauthorises rendering a card form rather than moving money. Tokens expire\nquickly, so mint one per page load instead of caching it.", "properties": { "client_token": { "title": "Client Token", "type": "string" } }, "required": [ "client_token" ], "title": "CheckoutSessionClientTokenResponse", "type": "object"}CheckoutSessionCreateRequest
Buyer-facing checkout session a merchant or channel asks us to open.
Type: object
Required: amount
{ "additionalProperties": false, "description": "Buyer-facing checkout session a merchant or channel asks us to open.", "properties": { "allowed_origins": { "anyOf": [ { "items": { "type": "string" }, "maxItems": 10, "type": "array" }, { "type": "null" } ], "title": "Allowed Origins" }, "amount": { "anyOf": [ { "maximum": 999999.99, "minimum": 0, "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "title": "Amount" }, "buyer_email": { "anyOf": [ { "format": "email", "maxLength": 254, "type": "string" }, { "type": "null" } ], "title": "Buyer Email" }, "cancel_url": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "title": "Cancel Url" }, "currency": { "default": "USD", "pattern": "^[A-Z]{3}$", "title": "Currency", "type": "string" }, "description": { "anyOf": [ { "maxLength": 500, "type": "string" }, { "type": "null" } ], "title": "Description" }, "expires_in_minutes": { "default": 30, "maximum": 1440, "minimum": 5, "title": "Expires In Minutes", "type": "integer" }, "external_order_id": { "anyOf": [ { "maxLength": 120, "type": "string" }, { "type": "null" } ], "title": "External Order Id" }, "items": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OrderItem" }, "maxItems": 100, "type": "array" }, { "type": "null" } ], "title": "Items" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "requires_shipping": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Requires Shipping" }, "shipping_address": { "anyOf": [ { "$ref": "#/components/schemas/CheckoutSessionShippingAddress" }, { "type": "null" } ] }, "shipping_amount_cents": { "anyOf": [ { "minimum": 0, "type": "integer" }, { "type": "null" } ], "description": "Shipping already calculated by the platform, in the currency's minor units. Supply shipping_address with it; zero means supplied free shipping, while null means Maxana's existing shipping behavior applies.", "title": "Shipping Amount Cents" }, "success_url": { "anyOf": [ { "maxLength": 1000, "type": "string" }, { "type": "null" } ], "title": "Success Url" } }, "required": [ "amount" ], "title": "CheckoutSessionCreateRequest", "type": "object"}CheckoutSessionResponse
Merchant-facing result of creating an immutable checkout session.
Type: object
Required: id, checkout_session_id, merchant_name, amount, currency, environment, status, expires_at, checkout_url, embed_url
{ "description": "Merchant-facing result of creating an immutable checkout session.", "properties": { "allowed_origins": { "items": { "type": "string" }, "title": "Allowed Origins", "type": "array" }, "amount": { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Amount", "type": "string" }, "cancel_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cancel Url" }, "checkout_session_id": { "title": "Checkout Session Id", "type": "string" }, "checkout_url": { "title": "Checkout Url", "type": "string" }, "currency": { "title": "Currency", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "embed_url": { "title": "Embed Url", "type": "string" }, "environment": { "title": "Environment", "type": "string" }, "expires_at": { "title": "Expires At", "type": "string" }, "external_order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Order Id" }, "id": { "title": "Id", "type": "string" }, "items": { "items": { "additionalProperties": true, "type": "object" }, "title": "Items", "type": "array" }, "merchant_name": { "title": "Merchant Name", "type": "string" }, "metadata": { "additionalProperties": true, "title": "Metadata", "type": "object" }, "payment_provider": { "default": "ppcp", "description": "Resolved payment provider for this checkout session; defaults to PPCP.", "title": "Payment Provider", "type": "string" }, "shipping_address": { "anyOf": [ { "$ref": "#/components/schemas/CheckoutSessionShippingAddress" }, { "type": "null" } ] }, "shipping_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Shipping Amount Cents" }, "status": { "title": "Status", "type": "string" }, "success_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Success Url" } }, "required": [ "id", "checkout_session_id", "merchant_name", "amount", "currency", "environment", "status", "expires_at", "checkout_url", "embed_url" ], "title": "CheckoutSessionResponse", "type": "object"}CheckoutSessionShippingAddress
Buyer shipping address fixed by the platform when it creates a session.
Type: object
Required: address_line_1, country_code
{ "additionalProperties": false, "description": "Buyer shipping address fixed by the platform when it creates a session.", "properties": { "address_line_1": { "maxLength": 300, "minLength": 1, "title": "Address Line 1", "type": "string" }, "address_line_2": { "anyOf": [ { "maxLength": 300, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Address Line 2" }, "admin_area_1": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Admin Area 1" }, "admin_area_2": { "anyOf": [ { "maxLength": 120, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Admin Area 2" }, "country_code": { "maxLength": 2, "minLength": 2, "pattern": "^[A-Za-z]{2}$", "title": "Country Code", "type": "string" }, "full_name": { "anyOf": [ { "maxLength": 300, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Full Name" }, "postal_code": { "anyOf": [ { "maxLength": 60, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Postal Code" } }, "required": [ "address_line_1", "country_code" ], "title": "CheckoutSessionShippingAddress", "type": "object"}CreateOrderRequest
Request body for creating a provider order through the checkout path.
Type: object
{ "additionalProperties": false, "description": "Request body for creating a provider order through the checkout path.", "examples": [ { "checkout_session_id": "cs_00000000000000000000000000000000" }, { "amount": "10.00", "currency": "USD" } ], "properties": { "amount": { "anyOf": [ { "exclusiveMinimum": 0, "maximum": 999999.99, "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" }, { "type": "null" } ], "title": "Amount" }, "buyer_email": { "anyOf": [ { "format": "email", "maxLength": 254, "type": "string" }, { "type": "null" } ], "title": "Buyer Email" }, "buyer_phone": { "anyOf": [ { "maxLength": 20, "type": "string" }, { "type": "null" } ], "title": "Buyer Phone" }, "checkout_page_url": { "anyOf": [ { "maxLength": 2048, "minLength": 1, "type": "string" }, { "type": "null" } ], "description": "URL of the merchant page hosting the checkout, required with X-Maxana-Checkout-Mode: direct. Its origin must be one of the session's allowed_origins.", "title": "Checkout Page Url" }, "checkout_session_id": { "anyOf": [ { "pattern": "^cs_[a-f0-9]{32}$", "type": "string" }, { "type": "null" } ], "title": "Checkout Session Id" }, "currency": { "default": "USD", "pattern": "^[A-Z]{3}$", "title": "Currency", "type": "string" }, "customer_vault_id": { "anyOf": [ { "maxLength": 255, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Customer Vault Id" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "items": { "anyOf": [ { "items": { "$ref": "#/components/schemas/OrderItem" }, "type": "array" }, { "type": "null" } ], "title": "Items" }, "merchant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Merchant Id" }, "payment_source": { "anyOf": [ { "enum": [ "paypal", "venmo", "card", "apple_pay", "google_pay" ], "type": "string" }, { "type": "null" } ], "title": "Payment Source" }, "payment_token": { "anyOf": [ { "maxLength": 2048, "minLength": 1, "type": "string" }, { "type": "null" } ], "title": "Payment Token" }, "paypal_client_metadata_id": { "anyOf": [ { "maxLength": 68, "minLength": 1, "pattern": "^[A-Za-z0-9\\-{}(),]+$", "type": "string" }, { "type": "null" } ], "title": "Paypal Client Metadata Id" }, "save_payment_method": { "default": false, "title": "Save Payment Method", "type": "boolean" }, "shipping": { "anyOf": [ { "minimum": 0, "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" }, { "type": "null" } ], "title": "Shipping" }, "shipping_address": { "anyOf": [ { "$ref": "#/components/schemas/ShippingAddress" }, { "type": "null" } ] }, "tax": { "anyOf": [ { "minimum": 0, "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" }, { "type": "null" } ], "title": "Tax" } }, "title": "CreateOrderRequest", "type": "object"}CreateOrderResponse
Response for a newly created provider order.
Type: object
Required: provider_order_id, status
{ "description": "Response for a newly created provider order.", "properties": { "checkout_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Checkout Session Id" }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Id" }, "provider_order_id": { "title": "Provider Order Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "provider_order_id", "status" ], "title": "CreateOrderResponse", "type": "object"}CurrencyTotals
Money totals for one currency, never blended with another's.
Type: object
Required: currency, total_revenue, avg_order_value, platform_fees, total_fees, total_refunded
{ "description": "Money totals for one currency, never blended with another's.", "properties": { "avg_order_value": { "title": "Avg Order Value", "type": "number" }, "currency": { "title": "Currency", "type": "string" }, "platform_fees": { "title": "Platform Fees", "type": "number" }, "total_fees": { "title": "Total Fees", "type": "number" }, "total_refunded": { "title": "Total Refunded", "type": "number" }, "total_revenue": { "title": "Total Revenue", "type": "number" } }, "required": [ "currency", "total_revenue", "avg_order_value", "platform_fees", "total_fees", "total_refunded" ], "title": "CurrencyTotals", "type": "object"}DailyRevenue
Daily captured revenue bucket, for one currency.
currency is on every point rather than on the series, so a client that
plots the array cannot lose it — an unlabelled money axis is exactly how
this went wrong before.
Type: object
Required: date, revenue, transactions
{ "description": "Daily captured revenue bucket, for one currency.\n\n`currency` is on every point rather than on the series, so a client that\nplots the array cannot lose it — an unlabelled money axis is exactly how\nthis went wrong before.", "properties": { "currency": { "default": "USD", "title": "Currency", "type": "string" }, "date": { "title": "Date", "type": "string" }, "revenue": { "title": "Revenue", "type": "number" }, "transactions": { "title": "Transactions", "type": "integer" } }, "required": [ "date", "revenue", "transactions" ], "title": "DailyRevenue", "type": "object"}DisputeActionResponse
Response metadata returned after a native PayPal dispute action.
Type: object
Required: status, dispute_id, provider_dispute_id
{ "description": "Response metadata returned after a native PayPal dispute action.", "properties": { "dispute_id": { "title": "Dispute Id", "type": "string" }, "paypal_debug_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Paypal Debug Id" }, "paypal_status": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Paypal Status" }, "provider_dispute_id": { "title": "Provider Dispute Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "status", "dispute_id", "provider_dispute_id" ], "title": "DisputeActionResponse", "type": "object"}DisputeOfferAmount
Typed money contract for a PayPal seller offer amount.
Type: object
Required: currency_code, value
{ "additionalProperties": false, "description": "Typed money contract for a PayPal seller offer amount.", "properties": { "currency_code": { "maxLength": 3, "minLength": 3, "title": "Currency Code", "type": "string" }, "value": { "minLength": 1, "title": "Value", "type": "string" } }, "required": [ "currency_code", "value" ], "title": "DisputeOfferAmount", "type": "object"}EscalateDisputeRequest
Request body for escalating a PayPal dispute.
Type: object
Required: note
{ "additionalProperties": false, "description": "Request body for escalating a PayPal dispute.", "properties": { "note": { "minLength": 1, "title": "Note", "type": "string" } }, "required": [ "note" ], "title": "EscalateDisputeRequest", "type": "object"}FilterOption
One filter value present in the merchant's data, with its weight.
count covers rows of every status, matching the filtered list, while
captured totals captured money only and keeps each currency separate.
Type: object
Required: value, count
{ "description": "One filter value present in the merchant's data, with its weight.\n\n``count`` covers rows of every status, matching the filtered list, while\n``captured`` totals captured money only and keeps each currency separate.", "properties": { "captured": { "default": [], "items": { "$ref": "#/components/schemas/FilterOptionTotal" }, "title": "Captured", "type": "array" }, "count": { "title": "Count", "type": "integer" }, "value": { "title": "Value", "type": "string" } }, "required": [ "value", "count" ], "title": "FilterOption", "type": "object"}FilterOptionTotal
Captured money for one filter option in one currency, never blended.
Type: object
Required: currency, amount
{ "description": "Captured money for one filter option in one currency, never blended.", "properties": { "amount": { "title": "Amount", "type": "number" }, "currency": { "title": "Currency", "type": "string" } }, "required": [ "currency", "amount" ], "title": "FilterOptionTotal", "type": "object"}GravyEmbedTokenRequest
Request to mint a Gr4vy Embed token for an existing checkout session.
Type: object
Required: checkout_session_id
{ "additionalProperties": false, "description": "Request to mint a Gr4vy Embed token for an existing checkout session.", "properties": { "checkout_session_id": { "pattern": "^cs_[a-f0-9]{32}$", "title": "Checkout Session Id", "type": "string" } }, "required": [ "checkout_session_id" ], "title": "GravyEmbedTokenRequest", "type": "object"}GravyEmbedTokenResponse
Frontend-safe Gr4vy Embed token response for a checkout session.
Type: object
Required: token, gr4vy_id, environment, merchant_account_id, amount, currency, checkout_session_id
{ "description": "Frontend-safe Gr4vy Embed token response for a checkout session.", "properties": { "amount": { "title": "Amount", "type": "integer" }, "checkout_session_id": { "title": "Checkout Session Id", "type": "string" }, "currency": { "title": "Currency", "type": "string" }, "environment": { "title": "Environment", "type": "string" }, "gr4vy_id": { "title": "Gr4Vy Id", "type": "string" }, "merchant_account_id": { "title": "Merchant Account Id", "type": "string" }, "token": { "title": "Token", "type": "string" } }, "required": [ "token", "gr4vy_id", "environment", "merchant_account_id", "amount", "currency", "checkout_session_id" ], "title": "GravyEmbedTokenResponse", "type": "object"}HTTPValidationError
Type: object
{ "properties": { "detail": { "items": { "$ref": "#/components/schemas/ValidationError" }, "title": "Detail", "type": "array" } }, "title": "HTTPValidationError", "type": "object"}MakeDisputeOfferRequest
Request body for making a seller offer on a PayPal dispute.
Type: object
Required: note, offer_type
{ "additionalProperties": false, "description": "Request body for making a seller offer on a PayPal dispute.", "properties": { "invoice_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Invoice Id" }, "note": { "minLength": 1, "title": "Note", "type": "string" }, "offer_amount": { "anyOf": [ { "$ref": "#/components/schemas/DisputeOfferAmount" }, { "type": "null" } ] }, "offer_type": { "examples": [ "REFUND", "REFUND_WITH_REPLACEMENT", "REFUND_WITH_RETURN", "REPLACEMENT_WITHOUT_REFUND" ], "minLength": 1, "title": "Offer Type", "type": "string" } }, "required": [ "note", "offer_type" ], "title": "MakeDisputeOfferRequest", "type": "object"}MerchantApiKeyCreateResponse
A created API key including plaintext, also used by bounded recovery.
Type: object
Required: id, name, prefix, environment, status, created_at, key
{ "description": "A created API key including plaintext, also used by bounded recovery.", "properties": { "created_at": { "title": "Created At", "type": "string" }, "environment": { "title": "Environment", "type": "string" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "id": { "title": "Id", "type": "string" }, "key": { "title": "Key", "type": "string" }, "last_used_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Used At" }, "name": { "title": "Name", "type": "string" }, "prefix": { "title": "Prefix", "type": "string" }, "revoked_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revoked At" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "name", "prefix", "environment", "status", "created_at", "key" ], "title": "MerchantApiKeyCreateResponse", "type": "object"}MerchantApiKeyResponse
Non-secret metadata for one merchant- or channel-scoped API key.
Type: object
Required: id, name, prefix, environment, status, created_at
{ "description": "Non-secret metadata for one merchant- or channel-scoped API key.", "properties": { "created_at": { "title": "Created At", "type": "string" }, "environment": { "title": "Environment", "type": "string" }, "expires_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "id": { "title": "Id", "type": "string" }, "last_used_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Last Used At" }, "name": { "title": "Name", "type": "string" }, "prefix": { "title": "Prefix", "type": "string" }, "revoked_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Revoked At" }, "status": { "title": "Status", "type": "string" } }, "required": [ "id", "name", "prefix", "environment", "status", "created_at" ], "title": "MerchantApiKeyResponse", "type": "object"}MerchantDisputeDetail
One dispute in full, as returned when a merchant fetches it by id. Adds the three things the list omits: which response actions the dispute currently accepts, the sanitized payload the provider sent us, and any notes shared with the merchant.
Type: object
Required: id, provider, provider_dispute_id, status
{ "description": "One dispute in full, as returned when a merchant fetches it by id.\n\nAdds the three things the list omits: which response actions the dispute\ncurrently accepts, the sanitized payload the provider sent us, and any notes\nshared with the merchant.", "properties": { "amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Amount" }, "available_actions": { "default": [], "items": { "type": "string" }, "title": "Available Actions", "type": "array" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currency" }, "id": { "title": "Id", "type": "string" }, "lifecycle_stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lifecycle Stage" }, "notes": { "default": [], "items": { "$ref": "#/components/schemas/MerchantDisputeNote" }, "title": "Notes", "type": "array" }, "opened_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opened At" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Outcome" }, "paypal_capture_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Paypal Capture Id" }, "paypal_order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Paypal Order Id" }, "provider": { "title": "Provider", "type": "string" }, "provider_dispute_id": { "title": "Provider Dispute Id", "type": "string" }, "provider_payload": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Provider Payload" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "resolved_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resolved At" }, "response_deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Response Deadline" }, "status": { "title": "Status", "type": "string" }, "transaction_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transaction Id" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" } }, "required": [ "id", "provider", "provider_dispute_id", "status" ], "title": "MerchantDisputeDetail", "type": "object"}MerchantDisputeNote
A note the Maxana operations team has shared with the merchant. Only externally-visible notes are ever returned; internal case notes are filtered out server-side for every caller.
Type: object
Required: id, note
{ "description": "A note the Maxana operations team has shared with the merchant.\n\nOnly externally-visible notes are ever returned; internal case notes are\nfiltered out server-side for every caller.", "properties": { "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "id": { "title": "Id", "type": "string" }, "note": { "title": "Note", "type": "string" } }, "required": [ "id", "note" ], "title": "MerchantDisputeNote", "type": "object"}MerchantDisputeSummary
One dispute as it appears in the merchant's dispute list.
Timestamps are ISO 8601 strings. status, lifecycle_stage and
outcome are normalized provider values — for PayPal, statuses such as
open, waiting_for_seller_response, under_review and resolved,
and the stages inquiry and chargeback.
Type: object
Required: id, provider, provider_dispute_id, status
{ "description": "One dispute as it appears in the merchant's dispute list.\n\nTimestamps are ISO 8601 strings. ``status``, ``lifecycle_stage`` and\n``outcome`` are normalized provider values — for PayPal, statuses such as\n``open``, ``waiting_for_seller_response``, ``under_review`` and ``resolved``,\nand the stages ``inquiry`` and ``chargeback``.", "properties": { "amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Amount" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Created At" }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Currency" }, "id": { "title": "Id", "type": "string" }, "lifecycle_stage": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Lifecycle Stage" }, "opened_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Opened At" }, "outcome": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Outcome" }, "paypal_capture_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Paypal Capture Id" }, "paypal_order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Paypal Order Id" }, "provider": { "title": "Provider", "type": "string" }, "provider_dispute_id": { "title": "Provider Dispute Id", "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reason" }, "resolved_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Resolved At" }, "response_deadline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Response Deadline" }, "status": { "title": "Status", "type": "string" }, "transaction_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Transaction Id" }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Updated At" } }, "required": [ "id", "provider", "provider_dispute_id", "status" ], "title": "MerchantDisputeSummary", "type": "object"}NmiTokenizationKeyRequest
Request the Collect.js tokenization key for an existing checkout session.
Type: object
Required: checkout_session_id
{ "additionalProperties": false, "description": "Request the Collect.js tokenization key for an existing checkout session.", "properties": { "checkout_session_id": { "pattern": "^cs_[a-f0-9]{32}$", "title": "Checkout Session Id", "type": "string" } }, "required": [ "checkout_session_id" ], "title": "NmiTokenizationKeyRequest", "type": "object"}NmiTokenizationKeyResponse
Browser-safe Collect.js configuration for one merchant's card rail. Carries the *public* tokenization key and nothing else that could move money. The merchant's transaction key lives on the same stored credential and is deliberately absent from this shape, so no future edit can widen the response into leaking it without changing the model.
Type: object
Required: tokenization_key, environment, supports_google_pay, supports_apple_pay, checkout_session_id
{ "description": "Browser-safe Collect.js configuration for one merchant's card rail.\n\nCarries the *public* tokenization key and nothing else that could move money.\nThe merchant's transaction key lives on the same stored credential and is\ndeliberately absent from this shape, so no future edit can widen the response\ninto leaking it without changing the model.", "properties": { "checkout_session_id": { "title": "Checkout Session Id", "type": "string" }, "environment": { "title": "Environment", "type": "string" }, "supports_apple_pay": { "title": "Supports Apple Pay", "type": "boolean" }, "supports_google_pay": { "title": "Supports Google Pay", "type": "boolean" }, "tokenization_key": { "title": "Tokenization Key", "type": "string" } }, "required": [ "tokenization_key", "environment", "supports_google_pay", "supports_apple_pay", "checkout_session_id" ], "title": "NmiTokenizationKeyResponse", "type": "object"}OnboardingStartRequest
Whether this start is a reconnection of an already-connected merchant.
Absent or false keeps the default: a merchant that already completed
onboarding is refused with 409, so a machine caller retrying a start it
already made cannot mint a second referral by accident. true is the
deliberate ask — a connected merchant going back to PayPal to grant
missing scopes or move to another account — and leaves the merchant
connected until they actually finish at PayPal.
Type: object
{ "additionalProperties": false, "description": "Whether this start is a reconnection of an already-connected merchant.\n\nAbsent or ``false`` keeps the default: a merchant that already completed\nonboarding is refused with 409, so a machine caller retrying a start it\nalready made cannot mint a second referral by accident. ``true`` is the\ndeliberate ask — a connected merchant going back to PayPal to grant\nmissing scopes or move to another account — and leaves the merchant\nconnected until they actually finish at PayPal.", "properties": { "reconnect": { "default": false, "title": "Reconnect", "type": "boolean" } }, "title": "OnboardingStartRequest", "type": "object"}OnboardingStartResponse
Type: object
Required: action_url
{ "properties": { "action_url": { "title": "Action Url", "type": "string" } }, "required": [ "action_url" ], "title": "OnboardingStartResponse", "type": "object"}OnboardingStatus
Lifecycle states for merchant onboarding.
Type: string
{ "description": "Lifecycle states for merchant onboarding.", "enum": [ "pending", "in_progress", "completed", "revoked" ], "title": "OnboardingStatus", "type": "string"}OrderItem
Line item included in a checkout session or provider order.
Type: object
Required: name, unit_amount
{ "additionalProperties": false, "description": "Line item included in a checkout session or provider order.", "properties": { "category": { "default": "DIGITAL_GOODS", "title": "Category", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "name": { "title": "Name", "type": "string" }, "quantity": { "default": 1, "title": "Quantity", "type": "integer" }, "sku": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Sku" }, "unit_amount": { "anyOf": [ { "exclusiveMinimum": 0, "maximum": 999999.99, "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "title": "Unit Amount" } }, "required": [ "name", "unit_amount" ], "title": "OrderItem", "type": "object"}PaginatedTransactions
Paginated transaction list response.
Type: object
Required: items, total, limit, offset
{ "description": "Paginated transaction list response.", "properties": { "items": { "items": { "$ref": "#/components/schemas/TransactionResponse" }, "title": "Items", "type": "array" }, "limit": { "title": "Limit", "type": "integer" }, "offset": { "title": "Offset", "type": "integer" }, "total": { "title": "Total", "type": "integer" } }, "required": [ "items", "total", "limit", "offset" ], "title": "PaginatedTransactions", "type": "object"}PayLaterMessagingPublic
Type: object
Required: enabled, logo_type, logo_position, text_color, text_size, text_align
{ "properties": { "enabled": { "title": "Enabled", "type": "boolean" }, "logo_position": { "title": "Logo Position", "type": "string" }, "logo_type": { "title": "Logo Type", "type": "string" }, "text_align": { "title": "Text Align", "type": "string" }, "text_color": { "title": "Text Color", "type": "string" }, "text_size": { "title": "Text Size", "type": "integer" } }, "required": [ "enabled", "logo_type", "logo_position", "text_color", "text_size", "text_align" ], "title": "PayLaterMessagingPublic", "type": "object"}ProvideDisputeEvidenceRequest
Request body for submitting seller evidence to PayPal.
Type: object
{ "additionalProperties": false, "description": "Request body for submitting seller evidence to PayPal.", "properties": { "document_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Text" }, "evidence_type": { "default": "PROOF_OF_FULFILLMENT", "title": "Evidence Type", "type": "string" }, "notes": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Notes" }, "tracking_info": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Tracking Info" } }, "title": "ProvideDisputeEvidenceRequest", "type": "object"}ProvideSupportingInfoRequest
Request body for providing PayPal dispute supporting information.
Type: object
Required: notes
{ "additionalProperties": false, "description": "Request body for providing PayPal dispute supporting information.", "properties": { "document_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Document Text" }, "notes": { "minLength": 1, "title": "Notes", "type": "string" } }, "required": [ "notes" ], "title": "ProvideSupportingInfoRequest", "type": "object"}ProviderDetailResponse
What the payment provider reports about one transaction.
available is false when the provider gave us nothing — a PayPal row, or a
Gr4vy payment observed before this record existed. The UI shows the section as
unavailable rather than as empty values, because those say different things.
Type: object
Required: available, provider
{ "description": "What the payment provider reports about one transaction.\n\n``available`` is false when the provider gave us nothing — a PayPal row, or a\nGr4vy payment observed before this record existed. The UI shows the section as\nunavailable rather than as empty values, because those say different things.", "properties": { "authorized_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Authorized Amount Cents" }, "available": { "title": "Available", "type": "boolean" }, "captured_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Captured Amount Cents" }, "external_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Identifier" }, "payload": { "additionalProperties": true, "default": {}, "title": "Payload", "type": "object" }, "payment_service_definition_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payment Service Definition Id" }, "payment_service_display_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payment Service Display Name" }, "provider": { "title": "Provider", "type": "string" }, "provider_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Status" }, "provider_updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Updated At" }, "reconciliation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Reconciliation Id" } }, "required": [ "available", "provider" ], "title": "ProviderDetailResponse", "type": "object"}PublicCaptureResponse
Sanitized public checkout capture response.
Type: object
Required: provider_order_id, status, payment_method, amount, currency, created_at
{ "description": "Sanitized public checkout capture response.", "properties": { "amount": { "title": "Amount", "type": "number" }, "billing_address": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Billing Address" }, "buyer_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Buyer Email" }, "captured_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Captured At" }, "created_at": { "title": "Created At", "type": "string" }, "currency": { "title": "Currency", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "payment_method": { "title": "Payment Method", "type": "string" }, "provider_capture_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Capture Id" }, "provider_order_id": { "title": "Provider Order Id", "type": "string" }, "shipping_address": { "anyOf": [ { "additionalProperties": true, "type": "object" }, { "type": "null" } ], "title": "Shipping Address" }, "status": { "title": "Status", "type": "string" } }, "required": [ "provider_order_id", "status", "payment_method", "amount", "currency", "created_at" ], "title": "PublicCaptureResponse", "type": "object"}PublicCheckoutPaymentStatus
Provider-neutral payment status for a public checkout session.
Type: object
Required: provider_order_id, status
{ "description": "Provider-neutral payment status for a public checkout session.", "properties": { "captured_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Captured At" }, "provider_capture_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Capture Id" }, "provider_order_id": { "title": "Provider Order Id", "type": "string" }, "status": { "title": "Status", "type": "string" } }, "required": [ "provider_order_id", "status" ], "title": "PublicCheckoutPaymentStatus", "type": "object"}PublicCheckoutSessionResponse
Buyer-safe checkout session details used to render a payment surface.
Type: object
Required: id, checkout_session_id, merchant_name, environment, amount, currency, status, expires_at, checkout_url, embed_url
{ "description": "Buyer-safe checkout session details used to render a payment surface.", "properties": { "allowed_origins": { "items": { "type": "string" }, "title": "Allowed Origins", "type": "array" }, "amount": { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "title": "Amount", "type": "string" }, "branding": { "anyOf": [ { "$ref": "#/components/schemas/CheckoutBrandingPublic" }, { "type": "null" } ] }, "cancel_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Cancel Url" }, "checkout_session_id": { "title": "Checkout Session Id", "type": "string" }, "checkout_url": { "title": "Checkout Url", "type": "string" }, "collect_buyer_email": { "default": false, "title": "Collect Buyer Email", "type": "boolean" }, "currency": { "title": "Currency", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "embed_url": { "title": "Embed Url", "type": "string" }, "environment": { "title": "Environment", "type": "string" }, "expires_at": { "title": "Expires At", "type": "string" }, "external_order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Order Id" }, "id": { "title": "Id", "type": "string" }, "items": { "items": { "additionalProperties": true, "type": "object" }, "title": "Items", "type": "array" }, "merchant_name": { "title": "Merchant Name", "type": "string" }, "pay_later_messaging": { "anyOf": [ { "$ref": "#/components/schemas/PayLaterMessagingPublic" }, { "type": "null" } ] }, "payment": { "anyOf": [ { "$ref": "#/components/schemas/PublicCheckoutPaymentStatus" }, { "type": "null" } ] }, "payment_provider": { "default": "ppcp", "description": "Resolved payment provider for the checkout payment rail; defaults to PPCP.", "title": "Payment Provider", "type": "string" }, "paypal_acdc_status": { "anyOf": [ { "enum": [ "unavailable", "in_review", "need_more_data", "denied", "active" ], "type": "string" }, { "type": "null" } ], "title": "Paypal Acdc Status" }, "paypal_apple_pay_status": { "anyOf": [ { "enum": [ "unavailable", "in_review", "need_more_data", "denied", "active" ], "type": "string" }, { "type": "null" } ], "title": "Paypal Apple Pay Status" }, "paypal_client_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "PayPal partner client id to load the PayPal JS SDK with. Public by design — it appears in the SDK script URL of every PayPal page on the internet. It is served here so an integrator loads the SDK with the same PayPal application this backend creates orders under; a mismatch between the two is the cause of the confirm-payment-source 404 that has bitten this checkout before.", "title": "Paypal Client Id" }, "paypal_google_pay_status": { "anyOf": [ { "enum": [ "unavailable", "in_review", "need_more_data", "denied", "active" ], "type": "string" }, { "type": "null" } ], "title": "Paypal Google Pay Status" }, "paypal_merchant_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Paypal Merchant Id" }, "paypal_partner_attribution_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Paypal Partner Attribution Id" }, "preselect_paypal": { "default": false, "title": "Preselect Paypal", "type": "boolean" }, "requires_shipping": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Requires Shipping" }, "shipping_amount_cents": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "title": "Shipping Amount Cents" }, "status": { "title": "Status", "type": "string" }, "success_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Success Url" }, "supported_funding": { "items": { "type": "string" }, "title": "Supported Funding", "type": "array" }, "user_id_token": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "User Id Token" }, "vault_setup": { "default": false, "title": "Vault Setup", "type": "boolean" } }, "required": [ "id", "checkout_session_id", "merchant_name", "environment", "amount", "currency", "status", "expires_at", "checkout_url", "embed_url" ], "title": "PublicCheckoutSessionResponse", "type": "object"}RefundRequest
Optional amount supplied when refunding a captured payment.
Type: object
{ "additionalProperties": false, "description": "Optional amount supplied when refunding a captured payment.", "properties": { "amount": { "anyOf": [ { "exclusiveMinimum": 0, "maximum": 999999.99, "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" }, { "type": "null" } ], "description": "Partial refund amount. Omit for full refund.", "title": "Amount" } }, "title": "RefundRequest", "type": "object"}RefundResponse
Type: object
Required: success
{ "properties": { "success": { "title": "Success", "type": "boolean" } }, "required": [ "success" ], "title": "RefundResponse", "type": "object"}SendDisputeMessageRequest
Request body for posting a seller message to a PayPal dispute.
Type: object
Required: message
{ "additionalProperties": false, "description": "Request body for posting a seller message to a PayPal dispute.", "properties": { "message": { "minLength": 1, "title": "Message", "type": "string" } }, "required": [ "message" ], "title": "SendDisputeMessageRequest", "type": "object"}SendTextToPayRequest
What a merchant supplies to ask one customer for one amount.
Type: object
Required: phone, amount_cents, first_name, last_name, topic, instructions
{ "additionalProperties": false, "description": "What a merchant supplies to ask one customer for one amount.", "properties": { "amount_cents": { "description": "The amount to request, in cents.", "exclusiveMinimum": 0, "maximum": 1000000, "title": "Amount Cents", "type": "integer" }, "external_order_id": { "anyOf": [ { "maxLength": 100, "type": "string" }, { "type": "null" } ], "description": "Your own reference for what is being paid, kept on our side only.", "title": "External Order Id" }, "first_name": { "maxLength": 60, "title": "First Name", "type": "string" }, "instructions": { "description": "A line the customer reads above the payment link.", "maxLength": 500, "minLength": 3, "title": "Instructions", "type": "string" }, "last_name": { "maxLength": 60, "title": "Last Name", "type": "string" }, "phone": { "description": "The customer's US or Canadian mobile number, in any usual writing.", "title": "Phone", "type": "string" }, "topic": { "description": "What the payment is for; appears in the message's call to action.", "maxLength": 120, "title": "Topic", "type": "string" } }, "required": [ "phone", "amount_cents", "first_name", "last_name", "topic", "instructions" ], "title": "SendTextToPayRequest", "type": "object"}ShippingAddress
Postal address supplied for a physical order with an explicit country.
Type: object
Required: country_code
{ "additionalProperties": false, "description": "Postal address supplied for a physical order with an explicit country.", "properties": { "address_line_1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address Line 1" }, "address_line_2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Address Line 2" }, "admin_area_1": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Admin Area 1" }, "admin_area_2": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Admin Area 2" }, "country_code": { "maxLength": 2, "minLength": 2, "pattern": "^[A-Za-z]{2}$", "title": "Country Code", "type": "string" }, "postal_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Postal Code" } }, "required": [ "country_code" ], "title": "ShippingAddress", "type": "object"}TextToPayRequestResponse
One payment request as a merchant sees it.
Type: object
Required: id, status, provider_status, phone, customer_first_name, customer_last_name, amount_cents, currency, topic, instructions, external_order_id, transaction_id, expires_at, resolved_at, last_polled_at, created_at
{ "description": "One payment request as a merchant sees it.", "properties": { "amount_cents": { "title": "Amount Cents", "type": "integer" }, "created_at": { "format": "date-time", "title": "Created At", "type": "string" }, "currency": { "title": "Currency", "type": "string" }, "customer_first_name": { "title": "Customer First Name", "type": "string" }, "customer_last_name": { "title": "Customer Last Name", "type": "string" }, "expires_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Expires At" }, "external_order_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "External Order Id" }, "id": { "format": "uuid", "title": "Id", "type": "string" }, "instructions": { "title": "Instructions", "type": "string" }, "last_polled_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Last Polled At" }, "phone": { "title": "Phone", "type": "string" }, "provider_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Status" }, "resolved_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Resolved At" }, "status": { "title": "Status", "type": "string" }, "topic": { "title": "Topic", "type": "string" }, "transaction_id": { "anyOf": [ { "format": "uuid", "type": "string" }, { "type": "null" } ], "title": "Transaction Id" } }, "required": [ "id", "status", "provider_status", "phone", "customer_first_name", "customer_last_name", "amount_cents", "currency", "topic", "instructions", "external_order_id", "transaction_id", "expires_at", "resolved_at", "last_polled_at", "created_at" ], "title": "TextToPayRequestResponse", "type": "object"}TransactionFilterOptions
Method and processor values this merchant's transactions contain.
Type: object
Required: payment_methods, processors
{ "description": "Method and processor values this merchant's transactions contain.", "properties": { "payment_methods": { "items": { "$ref": "#/components/schemas/FilterOption" }, "title": "Payment Methods", "type": "array" }, "processors": { "items": { "$ref": "#/components/schemas/FilterOption" }, "title": "Processors", "type": "array" } }, "required": [ "payment_methods", "processors" ], "title": "TransactionFilterOptions", "type": "object"}TransactionHistoryFilter
Provider import selection that makes the merchant's visible history partial.
Type: object
Required: provider, methods
{ "description": "Provider import selection that makes the merchant's visible history partial.", "properties": { "backfill_pending": { "default": false, "title": "Backfill Pending", "type": "boolean" }, "methods": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Methods" }, "provider": { "title": "Provider", "type": "string" }, "retained_methods": { "default": [], "items": { "type": "string" }, "title": "Retained Methods", "type": "array" } }, "required": [ "provider", "methods" ], "title": "TransactionHistoryFilter", "type": "object"}TransactionResponse
Merchant-facing transaction response with provider-neutral fields.
Type: object
Required: id, merchant_id, provider, provider_order_id, status, payment_method, amount, currency, platform_fee, created_at
{ "description": "Merchant-facing transaction response with provider-neutral fields.", "properties": { "amount": { "title": "Amount", "type": "number" }, "billing_address": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Billing Address" }, "buyer_email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Buyer Email" }, "captured_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Captured At" }, "checkout_session_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Checkout Session Id" }, "created_at": { "title": "Created At", "type": "string" }, "currency": { "title": "Currency", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "failure_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Failure Code" }, "failure_message": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Failure Message" }, "id": { "title": "Id", "type": "string" }, "merchant_id": { "title": "Merchant Id", "type": "string" }, "net_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Net Amount" }, "payment_method": { "title": "Payment Method", "type": "string" }, "payment_method_raw": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payment Method Raw" }, "payment_method_scheme": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Payment Method Scheme" }, "platform_fee": { "title": "Platform Fee", "type": "number" }, "platform_fee_fixed": { "default": 0, "title": "Platform Fee Fixed", "type": "number" }, "platform_fee_percent": { "default": 0, "title": "Platform Fee Percent", "type": "number" }, "processor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Processor" }, "processor_definition_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Processor Definition Id" }, "provider": { "title": "Provider", "type": "string" }, "provider_capture_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Capture Id" }, "provider_client_metadata_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Provider Client Metadata Id" }, "provider_fee": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Provider Fee" }, "provider_order_id": { "title": "Provider Order Id", "type": "string" }, "refunded_amount_cents": { "default": 0, "title": "Refunded Amount Cents", "type": "integer" }, "refunded_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Refunded At" }, "refunded_platform_fee": { "default": 0, "title": "Refunded Platform Fee", "type": "number" }, "settled": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "title": "Settled" }, "settled_amount": { "anyOf": [ { "type": "number" }, { "type": "null" } ], "title": "Settled Amount" }, "settled_currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Settled Currency" }, "shipping_address": { "anyOf": [ { "additionalProperties": { "type": "string" }, "type": "object" }, { "type": "null" } ], "title": "Shipping Address" }, "status": { "title": "Status", "type": "string" }, "status_raw": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Status Raw" } }, "required": [ "id", "merchant_id", "provider", "provider_order_id", "status", "payment_method", "amount", "currency", "platform_fee", "created_at" ], "title": "TransactionResponse", "type": "object"}TransactionStats
Aggregated merchant transaction statistics.
Counts are currency-independent and stay flat. Money is not: every monetary
field describes the single currency named in currency, and by_currency
carries the rest. A merchant trading in one currency — which is all of them
today — sees exactly what it saw before, now labelled.
Type: object
Required: total_revenue, transaction_count, avg_order_value, platform_fees
{ "description": "Aggregated merchant transaction statistics.\n\nCounts are currency-independent and stay flat. Money is not: every monetary\nfield describes the single currency named in `currency`, and `by_currency`\ncarries the rest. A merchant trading in one currency — which is all of them\ntoday — sees exactly what it saw before, now labelled.", "properties": { "avg_order_value": { "title": "Avg Order Value", "type": "number" }, "by_currency": { "default": [], "items": { "$ref": "#/components/schemas/CurrencyTotals" }, "title": "By Currency", "type": "array" }, "captured_count": { "default": 0, "title": "Captured Count", "type": "integer" }, "currency": { "default": "USD", "title": "Currency", "type": "string" }, "disputed_count": { "default": 0, "title": "Disputed Count", "type": "integer" }, "history_filter": { "anyOf": [ { "$ref": "#/components/schemas/TransactionHistoryFilter" }, { "type": "null" } ] }, "platform_fees": { "title": "Platform Fees", "type": "number" }, "refunded_count": { "default": 0, "title": "Refunded Count", "type": "integer" }, "total_fees": { "default": 0, "title": "Total Fees", "type": "number" }, "total_refunded": { "default": 0, "title": "Total Refunded", "type": "number" }, "total_revenue": { "title": "Total Revenue", "type": "number" }, "transaction_count": { "title": "Transaction Count", "type": "integer" } }, "required": [ "total_revenue", "transaction_count", "avg_order_value", "platform_fees" ], "title": "TransactionStats", "type": "object"}ValidationError
Type: object
Required: loc, msg, type
{ "properties": { "ctx": { "title": "Context", "type": "object" }, "input": { "title": "Input" }, "loc": { "items": { "anyOf": [ { "type": "string" }, { "type": "integer" } ] }, "title": "Location", "type": "array" }, "msg": { "title": "Message", "type": "string" }, "type": { "title": "Error Type", "type": "string" } }, "required": [ "loc", "msg", "type" ], "title": "ValidationError", "type": "object"}VaultChargeRequest
Charge a saved instrument off-session, on the merchant's initiative.
This is a real money-moving path — it builds a PayPal order, captures it,
records a Transaction and resolves the platform fee — so its currency is
validated like every other priced request. It previously carried no
constraint at all, not even three letters, which left the whole point of
that validation (an unrecognised currency matches no PricingConfig and so
waives the fee) open on the one path that charges without a buyer present.
Type: object
Required: customer_ref, amount, idempotency_key
{ "additionalProperties": false, "description": "Charge a saved instrument off-session, on the merchant's initiative.\n\nThis is a real money-moving path — it builds a PayPal order, captures it,\nrecords a `Transaction` and resolves the platform fee — so its currency is\nvalidated like every other priced request. It previously carried no\nconstraint at all, not even three letters, which left the whole point of\nthat validation (an unrecognised currency matches no `PricingConfig` and so\nwaives the fee) open on the one path that charges without a buyer present.", "properties": { "amount": { "anyOf": [ { "exclusiveMinimum": 0, "maximum": 999999.99, "type": "number" }, { "pattern": "^(?!^[-+.]*$)[+-]?0*\\d*\\.?\\d*$", "type": "string" } ], "title": "Amount" }, "currency": { "default": "USD", "title": "Currency", "type": "string" }, "customer_ref": { "maxLength": 255, "minLength": 1, "title": "Customer Ref", "type": "string" }, "description": { "anyOf": [ { "maxLength": 127, "type": "string" }, { "type": "null" } ], "title": "Description" }, "idempotency_key": { "maxLength": 128, "minLength": 1, "title": "Idempotency Key", "type": "string" } }, "required": [ "customer_ref", "amount", "idempotency_key" ], "title": "VaultChargeRequest", "type": "object"}VaultChargeResponse
Identifier of the persisted transaction created or reused for a charge.
Type: object
Required: transaction_id
{ "description": "Identifier of the persisted transaction created or reused for a charge.", "properties": { "transaction_id": { "title": "Transaction Id", "type": "string" } }, "required": [ "transaction_id" ], "title": "VaultChargeResponse", "type": "object"}VaultTokenResponse
Safe metadata for the active instrument a later charge will select.
Type: object
Required: id, customer_ref, source_type, label, created_at
{ "description": "Safe metadata for the active instrument a later charge will select.", "properties": { "created_at": { "anyOf": [ { "format": "date-time", "type": "string" }, { "type": "null" } ], "title": "Created At" }, "customer_ref": { "title": "Customer Ref", "type": "string" }, "id": { "title": "Id", "type": "string" }, "label": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Label" }, "source_type": { "title": "Source Type", "type": "string" } }, "required": [ "id", "customer_ref", "source_type", "label", "created_at" ], "title": "VaultTokenResponse", "type": "object"}WebhookEndpointCreateRequest
Request body for registering a merchant or channel webhook endpoint.
Type: object
Required: url
{ "additionalProperties": false, "description": "Request body for registering a merchant or channel webhook endpoint.", "properties": { "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "enabled": { "default": true, "title": "Enabled", "type": "boolean" }, "event_types": { "anyOf": [ { "items": { "type": "string" }, "type": "array" }, { "type": "null" } ], "title": "Event Types" }, "url": { "title": "Url", "type": "string" } }, "required": [ "url" ], "title": "WebhookEndpointCreateRequest", "type": "object"}WebhookEndpointCreateResponse
Endpoint response that returns newly issued signing material exactly once.
Type: object
Required: id, url, description, enabled, status, secret_hint, event_types, created_at, updated_at, secret
{ "description": "Endpoint response that returns newly issued signing material exactly once.", "properties": { "created_at": { "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "enabled": { "title": "Enabled", "type": "boolean" }, "event_types": { "items": { "type": "string" }, "title": "Event Types", "type": "array" }, "id": { "title": "Id", "type": "string" }, "secret": { "title": "Secret", "type": "string" }, "secret_hint": { "title": "Secret Hint", "type": "string" }, "status": { "title": "Status", "type": "string" }, "updated_at": { "title": "Updated At", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "id", "url", "description", "enabled", "status", "secret_hint", "event_types", "created_at", "updated_at", "secret" ], "title": "WebhookEndpointCreateResponse", "type": "object"}WebhookEndpointResponse
Type: object
Required: id, url, description, enabled, status, secret_hint, event_types, created_at, updated_at
{ "properties": { "created_at": { "title": "Created At", "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "title": "Description" }, "enabled": { "title": "Enabled", "type": "boolean" }, "event_types": { "items": { "type": "string" }, "title": "Event Types", "type": "array" }, "id": { "title": "Id", "type": "string" }, "secret_hint": { "title": "Secret Hint", "type": "string" }, "status": { "title": "Status", "type": "string" }, "updated_at": { "title": "Updated At", "type": "string" }, "url": { "title": "Url", "type": "string" } }, "required": [ "id", "url", "description", "enabled", "status", "secret_hint", "event_types", "created_at", "updated_at" ], "title": "WebhookEndpointResponse", "type": "object"}Current limits
Section titled “Current limits”Schemas define accepted structure and types. They do not establish merchant readiness, provider eligibility, operation ordering, or whether a lifecycle action is currently available; read the operation and relevant resource state as well.