{"openapi":"3.1.0","info":{"title":"Pleezpay Merchant API","version":"1.5.0","description":"Create payment sessions and refunds, and read payments, settlements and disputes, on api.pleezpay.com. Pleezpay routes each payment to the provider most likely to approve it; your integration stays the same whichever provider takes it. Send your API key as a bearer token: its prefix (`pz_sandbox_` or `pz_live_`) decides whether a request uses test data or live money. Amounts are integers in the currency’s minor units: `\"amountMinorUnits\": 12840, \"currency\": \"EUR\"` is 128.40 EUR."},"servers":[{"url":"https://api.pleezpay.com","description":"Live money and test data on one host: your API key prefix (pz_sandbox_ or pz_live_) selects the environment."}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","description":"Merchant API key, passed as a bearer token."}},"schemas":{"PaymentSessionResponse":{"type":"object","properties":{"paymentSessionId":{"type":"string","minLength":1,"maxLength":255},"paymentId":{"type":"string","minLength":1,"maxLength":255},"checkoutUrl":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"},"status":{"type":"string","enum":["created","requires_payment_method","requires_action","processing","authorized","captured","failed","cancelled","partially_refunded","refunded","disputed"]}},"required":["paymentSessionId","paymentId","checkoutUrl","expiresAt","status"],"additionalProperties":false},"ErrorEnvelope":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","example":"validation_error"},"message":{"type":"string","example":"amount must be a positive integer"},"requestId":{"type":"string"},"details":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"message":{"type":"string"}},"required":["path","message"]}}},"required":["code","message"]}},"required":["error"]},"PaymentSessionCreateRequest":{"type":"object","properties":{"storeId":{"type":"string","minLength":1,"maxLength":255,"description":"Approved store that will own this payment session. Required when the merchant has more than one approved store. When omitted, Pleezpay automatically selects the merchant's only approved store; omission fails when there are zero or multiple approved stores."},"orderReference":{"type":"string","minLength":1,"maxLength":255,"example":"order_8f3c1a","description":"Merchant-supplied order reference. Required and unique within the merchant-defined policy (PRD §14.2)."},"amountMinorUnits":{"type":"integer","exclusiveMinimum":0,"example":1999},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR"},"returnUrl":{"type":"string","maxLength":2048,"format":"uri","description":"Where the customer is sent after a successful payment. Required. Must be an https URL of at most 2048 characters, must contain no '{' or '}' (reserved: Pleezpay does not substitute template placeholders) and no embedded credentials, and must match one of the owning store's approved return-URL allowlist entries (scheme + host + port exact, path prefix on a /-boundary). Pleezpay appends a single `pleezpay_session_id` query parameter at redirect time; no status or signature parameter is ever added."},"cancelUrl":{"type":"string","maxLength":2048,"format":"uri","description":"Where the customer is sent after a failed or cancelled payment. Optional — when omitted, `returnUrl` is used for those outcomes too. Same shape and allowlist rules as `returnUrl`."},"expiresAt":{"type":"string","format":"date-time"},"preferredMethod":{"type":"string","maxLength":64,"description":"The payment method this session concerns. REQUIRED, and validated against Pleezpay's payment-method catalog, when `presentation` is present — it is then the method the payer is taken straight to. Sent ALONE (without `presentation`) it keeps its historical behaviour exactly: accepted but ignored by payment processing, not persisted, not returned by read endpoints, and not validated against the catalog. Its value participates in Idempotency-Key request-body matching either way.","deprecated":true},"checkoutRowId":{"type":"string","minLength":1,"maxLength":64,"description":"The checkout ROW (tile) the customer chose, as returned by GET /v1/integrations/woocommerce/config in `checkout.rows[].id`. Optional, and only meaningful for a storefront that renders Pleezpay's rows itself. A row may be pinned by Pleezpay operations to one provider account, and sending its id is what lets that pin bind at charge time — two tiles sharing a method code are otherwise indistinguishable. An id this store does not have, one whose pin no longer resolves, or a value that is not a Pleezpay-minted row id at all (Pleezpay-minted ids match `chr_` + 24 hex characters; anything else is accepted for compatibility) is IGNORED: the payment routes normally rather than failing, because by then the customer has already chosen a method. Participates in Idempotency-Key request-body matching."},"presentation":{"type":"string","enum":["direct_redirect","embedded_card"],"description":"Omit for the ordinary hosted method picker. Send `direct_redirect` to ask Pleezpay to skip the picker and take the payer straight to `preferredMethod`, which then becomes required and must be a method in Pleezpay's catalog. Send `embedded_card` when your checkout is collecting the card in Pleezpay's framed card document on your own page; it requires `preferredMethod: \"card\"`. Either way this is a BEST-EFFORT REQUEST, not a guarantee: when the request cannot be served at that moment — a spent daily limit, an unhealthy account, a routing change, a mount your storefront never obtained — the session is still CREATED and the request recorded, and the hosted page presents its ordinary method picker with a note naming any method that is unavailable. Do not treat a 201 as proof of how the payer will be presented. Rejected with 422 only for `direct_redirect`, and only when that capability is disabled for your account (`direct_redirect_disabled`) or the method is not one the hosted page can present (`method_not_available`) — both integration errors rather than runtime conditions. Participates in Idempotency-Key request-body matching."},"customer":{"type":"object","properties":{"reference":{"type":"string","maxLength":255},"email":{"type":"string","format":"email"},"name":{"type":"string","maxLength":255},"firstName":{"type":"string","minLength":1,"maxLength":255},"lastName":{"type":"string","minLength":1,"maxLength":255},"phone":{"type":["string","null"],"maxLength":32}},"additionalProperties":false,"description":"Customer context stored with the payment session and used for session-creation risk evaluation (currently email) and provider checkout dispatch. Send `firstName`/`lastName` rather than relying on `name` when you hold the two halves separately: a single name string has to be split before it reaches a card acquirer, and the split is a guess. Card acquirers may require first name, last name, email, phone and a full billing address together, and refuse the sale as an ordinary decline when any one is missing — so sending all of them measurably raises card approval rates. Not returned by merchant read endpoints."},"billing":{"type":"object","properties":{"line1":{"type":"string","maxLength":255},"line2":{"type":"string","maxLength":255},"city":{"type":"string","maxLength":255},"postalCode":{"type":"string","maxLength":32},"countryCode":{"type":"string","pattern":"^[A-Z]{2}$"},"stateOrRegion":{"type":"string","maxLength":255}},"required":["line1","city","postalCode","countryCode"],"additionalProperties":false,"description":"The cardholder's billing address. Used as an input to session-creation risk evaluation (currently countryCode), stored with the payment session, and sent to the provider at checkout dispatch. Card acquirers commonly require a full billing address and refuse the sale as an ordinary decline when it is missing, so sending it measurably raises card approval rates. Not returned by merchant read endpoints."},"items":{"type":"array","items":{"type":"object","properties":{"reference":{"type":"string","maxLength":255},"name":{"type":"string","maxLength":255},"quantity":{"type":"integer","exclusiveMinimum":0},"unitAmountMinorUnits":{"type":"integer","exclusiveMinimum":0,"example":1999}},"required":["name","quantity","unitAmountMinorUnits"],"additionalProperties":false},"maxItems":500,"description":"Deprecated compatibility field. Currently accepted but ignored by payment processing: line items are not persisted or returned by read endpoints. Their value still participates in Idempotency-Key request-body matching.","deprecated":true},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":512},"description":"Deprecated compatibility field. Currently accepted but ignored by payment processing: metadata is not persisted or returned by read endpoints. Its value still participates in Idempotency-Key request-body matching.","deprecated":true},"sourceContext":{"$ref":"#/components/schemas/SourceContext"}},"required":["orderReference","amountMinorUnits","currency","returnUrl"],"additionalProperties":false,"description":"Requires an Idempotency-Key header (PRD §14.2). Not expressible in the JSON body schema — enforced by core-api request validation. An active orderReference must be unique within the authenticated application and selected store; sandbox and live applications may safely reuse the same value."},"SourceContext":{"type":"object","properties":{"landingUrl":{"type":"string","maxLength":2048},"referrer":{"type":"string","maxLength":2048},"utm":{"type":"object","properties":{"source":{"type":"string","maxLength":255},"medium":{"type":"string","maxLength":255},"campaign":{"type":"string","maxLength":255},"term":{"type":"string","maxLength":255},"content":{"type":"string","maxLength":255}},"additionalProperties":false},"clickIds":{"type":"object","properties":{"gclid":{"type":"string","maxLength":512},"fbclid":{"type":"string","maxLength":512},"msclkid":{"type":"string","maxLength":512},"ttclid":{"type":"string","maxLength":512},"gbraid":{"type":"string","maxLength":512},"wbraid":{"type":"string","maxLength":512}},"additionalProperties":false},"browserIds":{"type":"object","properties":{"fbp":{"type":"string","maxLength":256},"fbc":{"type":"string","maxLength":512},"ttp":{"type":"string","maxLength":256},"ttclid":{"type":"string","maxLength":512},"gclAw":{"type":"string","maxLength":512},"gclGb":{"type":"string","maxLength":512}},"additionalProperties":false},"client":{"type":"object","properties":{"ip":{"anyOf":[{"type":"string","format":"ip"},{"type":"string","format":"ip"}]},"userAgent":{"type":"string","maxLength":512}},"additionalProperties":false},"merchantOrderId":{"type":"string","minLength":1,"maxLength":64},"consent":{"type":"object","properties":{"marketing":{"type":"string","enum":["granted","denied","unknown"]},"adUserData":{"type":"string","enum":["granted","denied","unknown"]},"adPersonalization":{"type":"string","enum":["granted","denied","unknown"]},"source":{"type":"string","maxLength":64}},"required":["marketing"],"additionalProperties":false},"cart":{"type":"object","properties":{"itemCount":{"type":"integer","minimum":0,"maximum":10000},"valueMinorUnits":{"type":"integer","minimum":0},"items":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":64},"quantity":{"type":"integer","exclusiveMinimum":0,"maximum":10000},"unitPriceMinorUnits":{"type":"integer","minimum":0}},"required":["id","quantity"],"additionalProperties":false},"maxItems":20}},"additionalProperties":false},"customer":{"type":"object","properties":{"isGuest":{"type":"boolean"},"priorOrderCount":{"type":"integer","minimum":0,"maximum":1000000},"accountAgeDays":{"type":"integer","minimum":0,"maximum":100000}},"additionalProperties":false},"reportedBy":{"type":"string","maxLength":64},"capturedAt":{"type":"integer","minimum":0}},"additionalProperties":false,"description":"How this customer arrived at your checkout: campaign parameters, the landing URL, the referrer as YOUR site saw it, cart shape and the customer's history with your store. Optional, and never required. Pleezpay cannot observe any of this itself — browsers strip the referrer path on the cross-origin hop to the hosted checkout, so your server is the only component that ever saw it. Stored as REPORTED data, kept strictly apart from what Pleezpay observed about the request itself, and returned on the payer-context endpoint. Subject to the same 13-month rolling retention and erasure as your order data. Participates in Idempotency-Key request-body matching."},"RefundRequestList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RefundRequest"}},"nextCursor":{"type":"null"}},"required":["data","nextCursor"],"additionalProperties":false},"RefundRequest":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":255},"paymentId":{"type":"string","minLength":1,"maxLength":255},"status":{"type":"string","enum":["requested","needs_review","processing","completed","failed_action_required","rejected"]},"amountMinorUnits":{"type":"integer","exclusiveMinimum":0,"example":1999},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR"},"reason":{"type":["string","null"],"maxLength":500},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"usdEquivalent":{"type":["object","null"],"properties":{"amountMinorUnits":{"type":"string","pattern":"^-?\\d{1,30}$","description":"Signed integer string of USD minor units (cents). Added in 1.9.0.","example":"731866"},"currency":{"type":"string","enum":["USD"]},"rate":{"type":"string","maxLength":64},"rateDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The ECB reference-rate observation date actually used (YYYY-MM-DD).","example":"2026-08-27"},"source":{"type":"string","enum":["ecb_reference"]},"basis":{"type":"string","enum":["transaction_date","latest","identity"],"description":"transaction_date = converted at the charge date's ECB rate; latest = at the newest cached rate; identity = the amount was already USD."}},"required":["amountMinorUnits","currency","rate","rateDate","source","basis"],"additionalProperties":false,"description":"USD settlement-display figure for `amountMinorUnits`, converted at the request's creation date. Added in 1.9.0."}},"required":["id","paymentId","status","amountMinorUnits","currency","reason","createdAt","updatedAt"],"additionalProperties":false},"Payment":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":255},"orderReference":{"type":"string","minLength":1,"maxLength":255,"example":"order_8f3c1a","description":"Merchant-supplied order reference. Required and unique within the merchant-defined policy (PRD §14.2)."},"status":{"type":"string","enum":["created","requires_payment_method","requires_action","processing","authorized","captured","failed","cancelled","partially_refunded","refunded","disputed"]},"amountMinorUnits":{"type":"integer","exclusiveMinimum":0,"example":1999},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR"},"refundedAmountMinorUnits":{"type":"integer","minimum":0,"example":0},"method":{"type":["string","null"],"maxLength":64,"description":"Normalized payment method — one of card, ideal, bancontact, klarna, apple_pay, google_pay, mb_way, multibanco, afterpay, cash_app, interac, paypal, revolut, pleezpay_ramp. Never a processor's name — `paypal` and `revolut` name the payer's own wallet scheme, which may share a processor's name; see pleezpay-platform docs/adr/0016-provider-hand-off-hosts.md. Null until the payment has an attempt.","example":"ideal"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"},"usdEquivalent":{"type":["object","null"],"properties":{"amountMinorUnits":{"type":"string","pattern":"^-?\\d{1,30}$","description":"Signed integer string of USD minor units (cents). Added in 1.9.0.","example":"731866"},"currency":{"type":"string","enum":["USD"]},"rate":{"type":"string","maxLength":64},"rateDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The ECB reference-rate observation date actually used (YYYY-MM-DD).","example":"2026-08-27"},"source":{"type":"string","enum":["ecb_reference"]},"basis":{"type":"string","enum":["transaction_date","latest","identity"],"description":"transaction_date = converted at the charge date's ECB rate; latest = at the newest cached rate; identity = the amount was already USD."}},"required":["amountMinorUnits","currency","rate","rateDate","source","basis"],"additionalProperties":false,"description":"USD settlement-display figure for `amountMinorUnits`, converted at the charge date's ECB rate. Present only when USD settlement display is enabled; null when enabled but not computable. Added in 1.9.0."},"offsiteConfirmation":{"$ref":"#/components/schemas/PaymentOffsiteConfirmation"},"lastDecline":{"type":["object","null"],"properties":{"reason":{"type":"string","pattern":"^[a-z][a-z_]{0,63}$","description":"Why the attempt was declined — one of incorrect_cvc, incorrect_number, expired_card, incorrect_billing_details, insufficient_funds, method_not_supported, declined_generic, authentication_failed, risk_blocked, processing_error, missing_customer_details. Branch on this value. More values may be added; treat one you do not recognise as declined_generic.","example":"incorrect_cvc"},"group":{"type":"string","pattern":"^[a-z][a-z_]{0,63}$","description":"The kind of decline — one of shopper_error, declined, authentication, risk, technical. shopper_error: a detail the shopper typed was wrong and they can correct it. declined: the card or payment method was refused. authentication: the shopper did not pass an extra verification step. risk: a risk check blocked the payment. technical: a fault on the payment side, not the shopper's.","example":"shopper_error"},"message":{"type":"string","minLength":1,"maxLength":300,"description":"A short English sentence describing the decline, suitable for an order log. Display text only: its wording can change at any time, so never branch on it.","example":"Shopper error: the card's security code (CVC) was entered incorrectly."},"declinedAt":{"type":"string","format":"date-time","description":"When the declined attempt was resolved.","example":"2026-10-02T14:02:11.000Z"}},"required":["reason","group","message","declinedAt"],"additionalProperties":false,"description":"Why the most recent declined attempt on this payment was declined. Present only when decline reasons are enabled; null when enabled and no attempt was declined — a payment that then fails was usually not finished by the shopper, and occasionally had an attempt whose outcome was never confirmed. It stays on a payment that is paid later, describing the earlier declined attempt. A payer cancelling, and an attempt Pleezpay never got an answer for, are not declines and are not reported here. It is for your own records and support: do not show the reason, group or message to the shopper, a risk block in particular. Added in 1.39.0."},"billingDescriptor":{"type":["string","null"],"minLength":1,"maxLength":64,"description":"The name the shopper's card or bank statement shows for this payment. Present only when billing descriptors are enabled; null when enabled and the statement text is not known for this payment — it is not captured, or the text is not confirmed for how it was paid. A payment captured before its statement text was known can carry it later. Display text: compare it with what a shopper reports, never branch on it. Added in 1.40.0.","example":"ACME GOODS LTD"}},"required":["id","orderReference","status","amountMinorUnits","currency","refundedAmountMinorUnits","method","createdAt","updatedAt"],"additionalProperties":false},"PaymentOffsiteConfirmation":{"type":"object","properties":{"pendingUntil":{"type":"string","format":"date-time","description":"The latest instant Pleezpay keeps waiting for the payment partner to confirm this payment. Until then, keep the order open. After it Pleezpay closes the attempt; a payment the partner still confirms later is reported as `payment.late_capture`.","example":"2026-09-29T14:05:00.000Z"}},"required":["pendingUntil"],"additionalProperties":false,"description":"Present only while the payer is finishing this payment on a payment partner's page and Pleezpay will confirm the outcome itself — the payer is not returned to your site. Do not cancel the order for non-payment before `pendingUntil`. Absent otherwise. Added in 1.38.0."},"PaymentList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"nextCursor":{"type":["string","null"],"maxLength":1024}},"required":["data","nextCursor"],"additionalProperties":false},"FulfillmentList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Fulfillment"}},"nextCursor":{"type":["string","null"],"maxLength":1024}},"required":["data","nextCursor"],"additionalProperties":false},"Fulfillment":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":255},"paymentId":{"type":"string","minLength":1,"maxLength":255},"orderReference":{"type":"string","minLength":1,"maxLength":255,"example":"order_8f3c1a","description":"Merchant-supplied order reference. Required and unique within the merchant-defined policy (PRD §14.2)."},"store":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":255},"name":{"type":"string","minLength":1}},"required":["id","name"],"additionalProperties":false},"environment":{"type":"string","enum":["sandbox","live"]},"capturedAt":{"type":"string","format":"date-time"},"sla":{"type":"object","properties":{"enforced":{"type":"boolean"},"policyVersion":{"type":"string","minLength":1,"maxLength":64},"timeZone":{"type":["string","null"],"minLength":1,"maxLength":255},"dueAt":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","enum":["not_monitored","configuration_required","awaiting_tracking","due_soon","overdue","submitted_on_time","submitted_late","waived","cancelled"]},"firstSubmittedAt":{"type":["string","null"],"format":"date-time"}},"required":["enforced","policyVersion","timeZone","dueAt","status","firstSubmittedAt"],"additionalProperties":false},"tracking":{"$ref":"#/components/schemas/FulfillmentTracking"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","paymentId","orderReference","store","environment","capturedAt","sla","tracking","createdAt","updatedAt"],"additionalProperties":false},"FulfillmentTracking":{"type":["object","null"],"properties":{"carrier":{"type":"string","minLength":1,"maxLength":80},"trackingNumber":{"type":"string","minLength":1,"maxLength":128},"trackingUrl":{"type":["string","null"],"maxLength":2048,"format":"uri"},"revision":{"type":"integer","exclusiveMinimum":0},"submittedAt":{"type":"string","format":"date-time"},"source":{"type":"string","enum":["api_key","dashboard_user"]}},"required":["carrier","trackingNumber","trackingUrl","revision","submittedAt","source"],"additionalProperties":false},"FulfillmentSummary":{"type":"object","properties":{"configurationRequired":{"type":"integer","minimum":0},"awaitingTracking":{"type":"integer","minimum":0},"dueSoon":{"type":"integer","minimum":0},"overdue":{"type":"integer","minimum":0},"submittedOnTime":{"type":"integer","minimum":0},"submittedLate":{"type":"integer","minimum":0},"waived":{"type":"integer","minimum":0},"notMonitored":{"type":"integer","minimum":0},"cancelled":{"type":"integer","minimum":0,"description":"Fulfillments whose payment was refunded (in full, or partially with the storefront order cancelled) before any tracking was submitted. Excluded from the SLA: never counted as overdue and outside `onTimeRate`. Added in 1.30.0; optional so a rolling core/dashboard deployment stays compatible."},"onTimeRate":{"type":["number","null"],"minimum":0,"maximum":1},"windowDays":{"anyOf":[{"type":"number","enum":[7]},{"type":"number","enum":[30]},{"type":"number","enum":[90]}]}},"required":["configurationRequired","awaitingTracking","dueSoon","overdue","submittedOnTime","submittedLate","waived","notMonitored","onTimeRate","windowDays"],"additionalProperties":false},"TrackingWriteRequest":{"type":"object","properties":{"carrier":{"type":"string","minLength":1,"maxLength":80},"trackingNumber":{"type":"string","minLength":1,"maxLength":128},"trackingUrl":{"type":["string","null"],"maxLength":2048},"expectedRevision":{"type":"integer","minimum":0}},"required":["carrier","trackingNumber","expectedRevision"],"additionalProperties":false},"IntegrationInstallationResponse":{"type":"object","properties":{"installation":{"$ref":"#/components/schemas/IntegrationInstallation"},"webhook":{"type":"object","properties":{"endpointId":{"type":"string","format":"uuid"},"url":{"type":"string","minLength":1,"maxLength":2048},"secret":{"type":["string","null"],"minLength":1}},"required":["endpointId","url","secret"],"additionalProperties":false},"store":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","minLength":1},"status":{"type":"string","minLength":1}},"required":["id","name","status"],"additionalProperties":false},"returnUrl":{"$ref":"#/components/schemas/IntegrationReturnUrlState"},"hashSalt":{"type":["string","null"]},"config":{"$ref":"#/components/schemas/IntegrationConfigResponse"},"configVersion":{"type":"integer","minimum":0},"configEtag":{"type":"string","minLength":1}},"required":["installation","webhook","store","returnUrl","hashSalt","config","configVersion","configEtag"],"additionalProperties":false},"IntegrationInstallation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"environment":{"type":"string","enum":["sandbox","live"]},"platform":{"type":"string","enum":["woocommerce"]},"siteUrl":{"type":"string","minLength":1,"maxLength":2048},"siteHost":{"type":"string","minLength":1,"maxLength":253},"status":{"type":"string","enum":["active","revoked"]},"returnUrlStatus":{"type":"string","enum":["auto_approved","pending","approved","rejected"]},"pluginVersion":{"type":["string","null"]},"wooVersion":{"type":["string","null"]},"wpVersion":{"type":["string","null"]},"phpVersion":{"type":["string","null"]},"capabilities":{"$ref":"#/components/schemas/WooCommerceIntegrationCapabilities"},"webhookEndpointId":{"type":["string","null"],"format":"uuid"},"lastSeenAt":{"type":["string","null"],"format":"date-time"},"lastOrderSyncAt":{"type":["string","null"],"format":"date-time"},"syncRequestedAt":{"type":["string","null"],"format":"date-time"},"storefront":{"$ref":"#/components/schemas/IntegrationStorefrontReadState"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}},"required":["id","storeId","environment","platform","siteUrl","siteHost","status","returnUrlStatus","pluginVersion","wooVersion","wpVersion","phpVersion","capabilities","webhookEndpointId","lastSeenAt","lastOrderSyncAt","syncRequestedAt","createdAt","updatedAt"],"additionalProperties":false},"WooCommerceIntegrationCapabilities":{"type":"object","properties":{"blocks":{"type":"boolean"},"hpos":{"type":"boolean"},"headless":{"type":"boolean"},"gatewayPolicy":{"type":"boolean"},"embeddedCard":{"type":"boolean"},"instalments":{"type":"boolean"},"geoPolicy":{"type":"boolean"},"adAttribution":{"type":"boolean"}},"additionalProperties":false},"IntegrationStorefrontReadState":{"type":"object","properties":{"configReadAt":{"type":["string","null"],"format":"date-time"},"configReadVersion":{"type":["integer","null"],"minimum":0},"methodsReadAt":{"type":["string","null"],"format":"date-time"}},"required":["configReadAt","configReadVersion","methodsReadAt"],"additionalProperties":false},"IntegrationReturnUrlState":{"type":"object","properties":{"status":{"type":"string","enum":["auto_approved","pending","approved","rejected"]},"allowlist":{"type":"array","items":{"type":"string","maxLength":2048}}},"required":["status","allowlist"],"additionalProperties":false},"IntegrationConfigResponse":{"type":"object","properties":{"storeId":{"type":"string","format":"uuid"},"environment":{"type":"string","enum":["sandbox","live"]},"checkout":{"$ref":"#/components/schemas/CheckoutSettingsView"},"sync":{"type":"object","properties":{"intervalMinutes":{"type":"integer","minimum":60,"maximum":10080,"example":1440},"batchSize":{"type":"integer","minimum":10,"maximum":100,"example":100},"requestedAt":{"type":["string","null"],"format":"date-time"}},"required":["intervalMinutes","batchSize","requestedAt"],"additionalProperties":false},"returnUrl":{"$ref":"#/components/schemas/IntegrationReturnUrlState"},"adTracking":{"$ref":"#/components/schemas/IntegrationAdTrackingConfig"},"version":{"type":"integer","minimum":0},"updatedAt":{"type":["string","null"],"format":"date-time"}},"required":["storeId","environment","checkout","sync","returnUrl","version","updatedAt"],"additionalProperties":false},"CheckoutSettingsView":{"type":"object","properties":{"methods":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutMethodView"},"maxItems":20},"rows":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutRowView"},"maxItems":20},"paymentsEnabled":{"type":"boolean"},"paymentsEnabledVersion":{"type":"integer","minimum":0},"express":{"$ref":"#/components/schemas/CheckoutExpressView"},"gatewayPolicy":{"$ref":"#/components/schemas/CheckoutGatewayPolicy"},"hostedLanding":{"$ref":"#/components/schemas/CheckoutHostedLanding"},"geoPolicy":{"$ref":"#/components/schemas/CheckoutGeoPolicy"},"orderStatusAfterCapture":{"type":"string","enum":["processing","completed","on-hold"]},"currencies":{"type":"array","items":{"type":"string","minLength":3,"maxLength":3},"description":"Allowed ISO-4217 currency codes. EMPTY means no restriction — Pleezpay does not express a per-store currency allowlist today.","example":[]}},"required":["methods","orderStatusAfterCapture","currencies"],"additionalProperties":false},"CheckoutMethodView":{"type":"object","properties":{"code":{"type":"string","enum":["card","ideal","bancontact","klarna","apple_pay","google_pay","mb_way","multibanco","afterpay","cash_app","interac","paypal","revolut","pleezpay_ramp"],"example":"card"},"enabled":{"type":"boolean"},"label":{"type":"string","minLength":1,"maxLength":40,"example":"Card"},"order":{"type":"integer","exclusiveMinimum":0},"directRedirect":{"type":"boolean"}},"required":["code","enabled","label","order","directRedirect"],"additionalProperties":false},"CheckoutRowView":{"type":"object","properties":{"id":{"type":"string","pattern":"^chr_[0-9a-f]{24}$","example":"chr_9f3c1a20b7d84e6f5a2c1d0e"},"legacyGatewayId":{"type":"string","minLength":1,"maxLength":64},"code":{"type":"string","pattern":"^[a-z0-9_]{2,32}$","example":"card"},"enabled":{"type":"boolean"},"order":{"type":"integer","exclusiveMinimum":0},"preselect":{"type":"boolean"},"directRedirect":{"type":"boolean"},"title":{"type":"string","minLength":1,"maxLength":40,"example":"Card"},"label":{"type":"string","minLength":1,"maxLength":40},"subtitle":{"type":["string","null"],"minLength":1,"maxLength":80},"badge":{"$ref":"#/components/schemas/CheckoutRowBadge"},"description":{"type":["string","null"],"minLength":1,"maxLength":200},"marks":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9_]{2,32}$","example":"visa"},"maxItems":4},"mark":{"type":"string","enum":["generic_card","generic_bank","generic_wallet","generic_voucher","generic_installments","none"]},"routable":{"type":"boolean"},"unavailableReason":{"type":["string","null"],"enum":["not_routable_here",null]},"cardEntry":{"type":"string","enum":["hosted","embedded"]},"siteMessaging":{"$ref":"#/components/schemas/CheckoutRowSiteMessaging"}},"required":["id","code","enabled","order","preselect","directRedirect","title","label","subtitle","badge","description","marks","mark","routable","unavailableReason"],"additionalProperties":false},"CheckoutRowBadge":{"oneOf":[{"type":"object","properties":{"kind":{"type":"string","enum":["recommended"]}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["fastest"]}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["no_fee"]}},"required":["kind"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["adjustment"]},"basisPoints":{"type":"integer","minimum":-5000,"maximum":5000,"example":300}},"required":["kind","basisPoints"],"additionalProperties":false},{"type":"object","properties":{"kind":{"type":"string","enum":["custom"]},"text":{"type":"string","minLength":1,"maxLength":24}},"required":["kind","text"],"additionalProperties":false},{"type":"null"}]},"CheckoutRowSiteMessaging":{"type":"object","properties":{"productPage":{"type":"boolean"},"cartPage":{"type":"boolean"}},"required":["productPage","cartPage"],"additionalProperties":false},"CheckoutExpressView":{"type":["object","null"],"properties":{"enabled":{"type":"boolean"},"wallets":{"type":"array","items":{"type":"string","enum":["apple_pay","google_pay"]},"maxItems":2},"rowId":{"type":["string","null"],"pattern":"^chr_[0-9a-f]{24}$","example":"chr_9f3c1a20b7d84e6f5a2c1d0e"},"layout":{"type":"string","enum":["combined","stacked"]},"theme":{"type":"string","enum":["dark","light","outline"]},"radius":{"type":"string","enum":["none","s","m","l","pill"]},"height":{"type":"string","enum":["compact","standard","tall"]},"fullWidth":{"type":"boolean"},"placement":{"type":"string","enum":["below_methods","above_methods"]},"caption":{"type":["string","null"],"minLength":1,"maxLength":80},"ribbon":{"type":"object","properties":{"show":{"type":"boolean"},"recommended":{"type":"boolean"},"feeBasisPoints":{"type":["integer","null"],"minimum":-5000,"maximum":5000}},"required":["show","recommended","feeBasisPoints"],"additionalProperties":false}},"required":["enabled","wallets","rowId","layout","theme","radius","height","fullWidth","placement","caption","ribbon"],"additionalProperties":false},"CheckoutGatewayPolicy":{"type":["object","null"],"properties":{"order":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9_-]{1,64}$/i","example":"cod"},"maxItems":40},"hidden":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9_-]{1,64}$/i","example":"cod"},"maxItems":40}},"required":["order","hidden"],"additionalProperties":false},"CheckoutHostedLanding":{"type":"string","enum":["route","picker"],"description":"How Pleezpay's hosted checkout lands a payer whose session named no method. `route`: the published route's direct-redirect accounts may skip the method picker. `picker`: the payer always sees the method picker first.","example":"picker"},"CheckoutGeoPolicy":{"type":"object","properties":{"mode":{"$ref":"#/components/schemas/CheckoutGeoPolicyMode"},"hideForCountries":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$","example":"CA"},"maxItems":50,"example":["CN","HK","MO"]}},"required":["mode","hideForCountries"],"additionalProperties":false},"CheckoutGeoPolicyMode":{"type":"string","enum":["off","observe","enforce"],"description":"What the storefront does for a shopper whose country is listed. `off`: nothing (the default). `observe`: hide nothing, log what enforce would hide. `enforce`: offer no Pleezpay payment option.","example":"observe"},"IntegrationAdTrackingConfig":{"type":"object","properties":{"forwardAttribution":{"type":"boolean"},"productDetails":{"type":"boolean"}},"required":["forwardAttribution","productDetails"],"additionalProperties":false},"IntegrationInstallationCreateRequest":{"type":"object","properties":{"platform":{"type":"string","enum":["woocommerce"]},"storeId":{"type":"string","format":"uuid"},"siteUrl":{"type":"string","minLength":1,"maxLength":2048,"example":"https://shop.example"},"webhookUrl":{"type":"string","minLength":1,"maxLength":2048,"example":"https://shop.example/wp-json/pleezpay/v1/webhook"},"returnUrl":{"type":"string","minLength":1,"maxLength":2048,"example":"https://shop.example/checkout/order-received/"},"cancelUrl":{"type":"string","minLength":1,"maxLength":2048},"pluginVersion":{"type":"string","minLength":1,"maxLength":32,"example":"0.1.0"},"wooVersion":{"type":"string","minLength":1,"maxLength":32,"example":"9.8.1"},"wpVersion":{"type":"string","minLength":1,"maxLength":32,"example":"6.8.2"},"phpVersion":{"type":"string","minLength":1,"maxLength":32,"example":"8.3.14"},"capabilities":{"$ref":"#/components/schemas/WooCommerceIntegrationCapabilities"},"observedGateways":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationObservedGateway"},"maxItems":30},"rotateSecret":{"type":"boolean","default":false}},"required":["platform","siteUrl","webhookUrl","returnUrl","pluginVersion","wooVersion","wpVersion","phpVersion"],"additionalProperties":false},"IntegrationObservedGateway":{"type":"object","properties":{"id":{"type":"string","pattern":"^[a-z0-9_-]{1,64}$/i","example":"cod"},"title":{"type":"string","minLength":1,"maxLength":80},"nativeEnabled":{"type":"boolean"},"position":{"type":"integer","minimum":0}},"required":["id","title","nativeEnabled","position"],"additionalProperties":false},"IntegrationHeartbeatResponse":{"type":"object","properties":{"installation":{"$ref":"#/components/schemas/IntegrationInstallation"},"config":{"$ref":"#/components/schemas/IntegrationConfigResponse"},"configVersion":{"type":"integer","minimum":0},"configEtag":{"type":"string","minLength":1}},"required":["installation","config","configVersion","configEtag"],"additionalProperties":false},"IntegrationInstallationHeartbeatRequest":{"type":"object","properties":{"pluginVersion":{"type":"string","minLength":1,"maxLength":32},"wooVersion":{"type":"string","minLength":1,"maxLength":32},"wpVersion":{"type":"string","minLength":1,"maxLength":32},"phpVersion":{"type":"string","minLength":1,"maxLength":32},"capabilities":{"$ref":"#/components/schemas/WooCommerceIntegrationCapabilities"},"observedGateways":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationObservedGateway"},"maxItems":30}},"additionalProperties":false},"IntegrationRevokeResponse":{"type":"object","properties":{"installation":{"$ref":"#/components/schemas/IntegrationInstallation"}},"required":["installation"],"additionalProperties":false},"AvailableMethodsResponse":{"type":"object","properties":{"storeId":{"type":"string","format":"uuid"},"environment":{"type":"string","enum":["sandbox","live"]},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR"},"methods":{"type":"array","items":{"$ref":"#/components/schemas/AvailableMethod"}},"evaluatedAt":{"type":"string","format":"date-time"}},"required":["storeId","environment","currency","methods","evaluatedAt"],"additionalProperties":false},"AvailableMethod":{"type":"object","properties":{"code":{"type":"string","enum":["card","ideal","bancontact","klarna","apple_pay","google_pay","mb_way","multibanco","afterpay","cash_app","interac","paypal","revolut","pleezpay_ramp"],"example":"card"},"label":{"type":"string","minLength":1,"example":"Card"},"eligible":{"type":"boolean"},"directRedirectCapable":{"type":"boolean"},"embeddedCardCapable":{"type":"boolean"},"amountRange":{"$ref":"#/components/schemas/AvailableMethodAmountRange"},"payerCountryRule":{"$ref":"#/components/schemas/AvailableMethodPayerCountryRule"}},"required":["code","label","eligible","directRedirectCapable","embeddedCardCapable"],"additionalProperties":false},"AvailableMethodAmountRange":{"type":"object","properties":{"minMinorUnits":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":9007199254740991},"maxMinorUnits":{"type":["integer","null"],"exclusiveMinimum":0,"maximum":9007199254740991}},"required":["minMinorUnits","maxMinorUnits"],"additionalProperties":false},"AvailableMethodPayerCountryRule":{"type":"object","properties":{"mode":{"type":"string","enum":["allow","block"],"description":"`allow`: the method can be paid only from the listed countries. `block`: it can be paid from anywhere except them.","example":"allow"},"countries":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$","example":"CA"},"minItems":1,"maxItems":250,"example":["AT","BE","DE","FR","NL"]}},"required":["mode","countries"],"additionalProperties":false},"EmbeddedCardMountResponse":{"type":"object","properties":{"mountUrl":{"type":"string","maxLength":2048,"format":"uri","description":"Absolute https URL to frame. Valid until `expiresAt`; request a new one rather than reusing it past that.","example":"https://pay.pleezpay.com/e/0GxV…"},"expiresAt":{"type":"string","format":"date-time","description":"When this mount stops being accepted. Re-request shortly before it, not after: a shopper who reaches Place order with an expired mount falls back to the hosted checkout page."},"storeId":{"type":"string","minLength":1,"maxLength":255}},"required":["mountUrl","expiresAt","storeId"],"additionalProperties":false},"EmbeddedCardMountRequest":{"type":"object","properties":{"origin":{"type":"string","minLength":9,"maxLength":266,"example":"https://shop.example","description":"The browser origin of the checkout page that will frame the card document — scheme and host only, https, no port, path, query or credentials. It must be one the store has already told Pleezpay about: its primary domain, `www.` of it, or the origin of an approved return URL. Exact host match; a subdomain of an allowed host is NOT allowed."},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR","description":"The currency the order will be taken in, ISO-4217 uppercase. Eligibility is currency-scoped, and so is the refusal: a store may be able to embed in one currency and not another."}},"required":["origin","currency"],"additionalProperties":false},"GeoPolicyEventsReportResponse":{"type":"object","properties":{"accepted":{"type":"integer","minimum":0},"dropped":{"type":"integer","minimum":0}},"required":["accepted","dropped"],"additionalProperties":false},"GeoPolicyEventsReportRequest":{"type":"object","properties":{"storeId":{"type":"string","format":"uuid"},"events":{"type":"array","items":{"$ref":"#/components/schemas/GeoPolicyEvent"},"minItems":1,"maxItems":100}},"required":["events"],"additionalProperties":false},"GeoPolicyEvent":{"type":"object","properties":{"mode":{"$ref":"#/components/schemas/GeoPolicyEventMode"},"country":{"type":"string","pattern":"^[A-Z]{2}$","example":"CN"},"source":{"$ref":"#/components/schemas/GeoPolicyEventSource"},"clientIp":{"anyOf":[{"type":"string","format":"ip"},{"type":"string","format":"ip"}],"example":"203.0.113.5"},"userAgent":{"type":["string","null"],"maxLength":256},"occurredAt":{"type":"string","format":"date-time"}},"required":["mode","country","source","clientIp","userAgent","occurredAt"],"additionalProperties":false},"GeoPolicyEventMode":{"type":"string","enum":["observe","enforce"],"description":"The policy mode in force when the storefront decided. `observe`: nothing was hidden, this shopper WOULD have been. `enforce`: this shopper was offered no Pleezpay option.","example":"observe"},"GeoPolicyEventSource":{"type":"string","enum":["cf_header","wc_geolocation"],"example":"cf_header"},"CheckoutSettingsWriteResponse":{"type":"object","properties":{"config":{"$ref":"#/components/schemas/IntegrationConfigResponse"},"availableMethods":{"$ref":"#/components/schemas/AvailableMethodsResponse"}},"required":["config","availableMethods"],"additionalProperties":false},"CheckoutSettingsMerchantWrite":{"type":"object","properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR"},"storeId":{"type":"string","format":"uuid"},"methods":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutMethodWrite"},"minItems":1,"maxItems":20},"rows":{"type":"array","items":{"$ref":"#/components/schemas/CheckoutRowWrite"},"minItems":1,"maxItems":20},"paymentsEnabled":{"type":"boolean"},"express":{"$ref":"#/components/schemas/CheckoutExpressWrite"},"orderStatusAfterCapture":{"type":"string","enum":["processing","completed","on-hold"]},"syncIntervalMinutes":{"type":"integer","minimum":60,"maximum":10080,"example":1440},"syncBatchSize":{"type":"integer","minimum":10,"maximum":100,"example":100},"expectedVersion":{"type":"integer","minimum":0}},"required":["currency","orderStatusAfterCapture","syncIntervalMinutes","expectedVersion"],"additionalProperties":false},"CheckoutMethodWrite":{"type":"object","properties":{"code":{"type":"string","enum":["card","ideal","bancontact","klarna","apple_pay","google_pay","mb_way","multibanco","afterpay","cash_app","interac","paypal","revolut","pleezpay_ramp"]},"enabled":{"type":"boolean"},"order":{"type":"integer","exclusiveMinimum":0,"maximum":20},"label":{"type":"string","minLength":1,"maxLength":40},"directRedirect":{"type":"boolean","default":false}},"required":["code","enabled","order"],"additionalProperties":false},"CheckoutRowWrite":{"type":"object","properties":{"id":{"type":"string","pattern":"^chr_[0-9a-f]{24}$","example":"chr_9f3c1a20b7d84e6f5a2c1d0e"},"code":{"type":"string","pattern":"^[a-z0-9_]{2,32}$","example":"card"},"enabled":{"type":"boolean"},"order":{"type":"integer","exclusiveMinimum":0,"maximum":20},"preselect":{"type":"boolean"},"directRedirect":{"type":"boolean"},"removed":{"type":"boolean","default":false},"title":{"type":["string","null"],"maxLength":40},"subtitle":{"type":["string","null"],"maxLength":80},"description":{"type":["string","null"],"maxLength":200},"badge":{"$ref":"#/components/schemas/CheckoutRowBadge"},"marks":{"type":"array","items":{"type":"string","pattern":"^[a-z0-9_]{2,32}$","example":"visa"},"maxItems":4},"mark":{"type":"string","enum":["generic_card","generic_bank","generic_wallet","generic_voucher","generic_installments","none"]},"siteMessaging":{"allOf":[{"$ref":"#/components/schemas/CheckoutRowSiteMessaging"},{"type":["object","null"]}]}},"required":["code","enabled","order"],"additionalProperties":false},"CheckoutExpressWrite":{"type":["object","null"],"properties":{"enabled":{"type":"boolean","default":false},"wallets":{"type":"array","items":{"type":"string","enum":["apple_pay","google_pay"]},"maxItems":2,"default":[]},"rowId":{"anyOf":[{"type":"string","pattern":"^chr_[0-9a-f]{24}$","example":"chr_9f3c1a20b7d84e6f5a2c1d0e"},{"type":"string","enum":[""]},{"type":"null"}],"default":null},"layout":{"type":"string","enum":["combined","stacked"],"default":"combined"},"theme":{"type":"string","enum":["dark","light","outline"],"default":"dark"},"radius":{"type":"string","enum":["none","s","m","l","pill"],"default":"pill"},"height":{"type":"string","enum":["compact","standard","tall"],"default":"standard"},"fullWidth":{"type":"boolean","default":true},"placement":{"type":"string","enum":["below_methods","above_methods"],"default":"below_methods"},"caption":{"type":["string","null"],"maxLength":80,"default":null},"ribbon":{"type":"object","properties":{"show":{"type":"boolean","default":false},"recommended":{"type":"boolean","default":false},"feeBasisPoints":{"type":["integer","null"],"minimum":-5000,"maximum":5000,"default":null}},"default":{"show":false,"recommended":false,"feeBasisPoints":null},"additionalProperties":false}},"additionalProperties":false},"IntegrationListEnvelope":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/IntegrationInstallation"}}},"required":["data"],"additionalProperties":false},"StoreOrderUpsertResponse":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"storeId":{"type":"string","format":"uuid"},"externalOrderId":{"type":"string","minLength":1,"maxLength":128,"example":"1042"},"status":{"type":"string","minLength":1,"maxLength":40,"example":"processing"},"created":{"type":"boolean"},"changed":{"type":"boolean"},"payment":{"$ref":"#/components/schemas/StoreOrderPaymentLink"},"tracking":{"$ref":"#/components/schemas/StoreOrderTrackingResult"}},"required":["id","storeId","externalOrderId","status","created","changed","payment","tracking"],"additionalProperties":false},"StoreOrderPaymentLink":{"type":"object","properties":{"paymentId":{"type":["string","null"],"format":"uuid"},"paymentSessionId":{"type":["string","null"],"format":"uuid"}},"required":["paymentId","paymentSessionId"],"additionalProperties":false},"StoreOrderTrackingResult":{"type":"object","properties":{"applied":{"type":"boolean"},"revision":{"type":["integer","null"],"minimum":0}},"required":["applied","revision"],"additionalProperties":false},"StoreOrderUpsertRequest":{"type":"object","properties":{"orderNumber":{"type":"string","minLength":1,"maxLength":64},"orderReference":{"type":"string","minLength":1,"maxLength":255},"status":{"type":"string","minLength":1,"maxLength":40,"example":"processing"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR"},"totals":{"$ref":"#/components/schemas/StoreOrderTotals"},"itemCount":{"type":"integer","minimum":0},"items":{"type":"array","items":{"$ref":"#/components/schemas/StoreOrderItem"},"maxItems":200},"customer":{"$ref":"#/components/schemas/StoreOrderCustomer"},"billing":{"$ref":"#/components/schemas/StoreOrderAddressBlock"},"shipping":{"$ref":"#/components/schemas/StoreOrderAddressBlock"},"placedAt":{"type":"string","format":"date-time"},"sourceUpdatedAt":{"type":"string","format":"date-time"},"snapshot":{"$ref":"#/components/schemas/StoreOrderSnapshot"},"tracking":{"$ref":"#/components/schemas/StoreOrderTracking"}},"required":["status","currency","totals","itemCount","items","customer","placedAt","snapshot"],"additionalProperties":false},"StoreOrderTotals":{"type":"object","properties":{"totalMinorUnits":{"type":"integer","minimum":0,"example":0},"subtotalMinorUnits":{"type":"integer","minimum":0,"example":0},"taxMinorUnits":{"type":"integer","minimum":0,"example":0},"shippingMinorUnits":{"type":"integer","minimum":0,"example":0},"discountMinorUnits":{"type":"integer","minimum":0,"example":0},"refundedMinorUnits":{"type":"integer","minimum":0,"example":0}},"required":["totalMinorUnits","subtotalMinorUnits","taxMinorUnits","shippingMinorUnits","discountMinorUnits","refundedMinorUnits"],"additionalProperties":false},"StoreOrderItem":{"type":"object","properties":{"lineIndex":{"type":"integer","minimum":0},"productId":{"type":"string","maxLength":64},"variationId":{"type":"string","maxLength":64},"sku":{"type":"string","maxLength":64},"name":{"type":"string","minLength":1,"maxLength":255},"quantity":{"type":"integer","exclusiveMinimum":0},"unitAmountMinorUnits":{"type":"integer","minimum":0,"example":0},"lineTotalMinorUnits":{"type":"integer","minimum":0,"example":0},"taxMinorUnits":{"type":"integer","minimum":0,"example":0}},"required":["lineIndex","name","quantity","unitAmountMinorUnits","lineTotalMinorUnits","taxMinorUnits"],"additionalProperties":false},"StoreOrderCustomer":{"type":"object","properties":{"email":{"type":"string","maxLength":320,"format":"email"},"name":{"type":"string","maxLength":255},"phone":{"type":"string","maxLength":64},"isGuest":{"type":"boolean"}},"required":["isGuest"],"additionalProperties":false},"StoreOrderAddressBlock":{"type":"object","properties":{"address":{"$ref":"#/components/schemas/StoreOrderAddress"}},"required":["address"],"additionalProperties":false},"StoreOrderAddress":{"type":"object","properties":{"firstName":{"type":"string","maxLength":255},"lastName":{"type":"string","maxLength":255},"company":{"type":"string","maxLength":255},"line1":{"type":"string","maxLength":255},"line2":{"type":"string","maxLength":255},"city":{"type":"string","maxLength":255},"state":{"type":"string","maxLength":255},"postcode":{"type":"string","maxLength":32},"country":{"type":"string","maxLength":64},"email":{"type":"string","maxLength":320,"format":"email"},"phone":{"type":"string","maxLength":64}},"additionalProperties":false},"StoreOrderSnapshot":{"type":"object","description":"The full storefront order. An open object; bounded to 32 KiB serialised."},"StoreOrderTracking":{"type":"object","properties":{"carrier":{"type":"string","minLength":1,"maxLength":80},"trackingNumber":{"type":"string","minLength":1,"maxLength":128},"trackingUrl":{"type":"string","maxLength":2048},"shippedAt":{"type":"string","format":"date-time"}},"required":["carrier","trackingNumber"],"additionalProperties":false},"StoreOrderBatchResponse":{"type":"object","properties":{"results":{"type":"array","items":{"$ref":"#/components/schemas/StoreOrderBatchResult"}},"counts":{"$ref":"#/components/schemas/StoreOrderBatchCounts"},"runId":{"type":"string","format":"uuid"}},"required":["results","counts","runId"],"additionalProperties":false},"StoreOrderBatchResult":{"type":"object","properties":{"externalOrderId":{"type":"string","minLength":1,"maxLength":128,"example":"1042"},"outcome":{"type":"string","enum":["created","updated","unchanged","rejected"]},"errorCode":{"type":"string","maxLength":64}},"required":["externalOrderId","outcome"],"additionalProperties":false},"StoreOrderBatchCounts":{"type":"object","properties":{"received":{"type":"integer","minimum":0},"created":{"type":"integer","minimum":0},"updated":{"type":"integer","minimum":0},"unchanged":{"type":"integer","minimum":0},"rejected":{"type":"integer","minimum":0}},"required":["received","created","updated","unchanged","rejected"],"additionalProperties":false},"StoreOrderBatchRequest":{"type":"object","properties":{"orders":{"type":"array","items":{"$ref":"#/components/schemas/StoreOrderBatchItem"},"minItems":1,"maxItems":100},"kind":{"type":"string","enum":["backfill","scheduled","manual","realtime"],"default":"scheduled"}},"required":["orders"],"additionalProperties":false},"StoreOrderBatchItem":{"type":"object","properties":{"externalOrderId":{"type":"string","minLength":1,"maxLength":128,"example":"1042"},"orderNumber":{"type":"string","minLength":1,"maxLength":64},"orderReference":{"type":"string","minLength":1,"maxLength":255},"status":{"type":"string","minLength":1,"maxLength":40,"example":"processing"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR"},"totals":{"$ref":"#/components/schemas/StoreOrderTotals"},"itemCount":{"type":"integer","minimum":0},"items":{"type":"array","items":{"$ref":"#/components/schemas/StoreOrderItem"},"maxItems":200},"customer":{"$ref":"#/components/schemas/StoreOrderCustomer"},"billing":{"$ref":"#/components/schemas/StoreOrderAddressBlock"},"shipping":{"$ref":"#/components/schemas/StoreOrderAddressBlock"},"placedAt":{"type":"string","format":"date-time"},"sourceUpdatedAt":{"type":"string","format":"date-time"},"snapshot":{"$ref":"#/components/schemas/StoreOrderSnapshot"},"tracking":{"$ref":"#/components/schemas/StoreOrderTracking"}},"required":["externalOrderId","status","currency","totals","itemCount","items","customer","placedAt","snapshot"],"additionalProperties":false},"StoreOrderErasureResponse":{"type":"object","properties":{"externalOrderId":{"type":"string","minLength":1,"maxLength":128,"example":"1042"},"anonymized":{"type":"boolean"},"anonymizedAt":{"type":["string","null"],"format":"date-time"}},"required":["externalOrderId","anonymized","anonymizedAt"],"additionalProperties":false},"RefundRequestCreate":{"type":"object","properties":{"paymentId":{"type":"string","minLength":1,"maxLength":255},"amountMinorUnits":{"type":"integer","exclusiveMinimum":0,"example":1999,"description":"Omit for a full refund of the remaining refundable amount. When present, cumulative requested plus completed refunds must not exceed the captured amount (PRD RFD-02)."},"reason":{"type":"string","maxLength":500},"customerNote":{"type":"string","maxLength":1000}},"required":["paymentId"],"additionalProperties":false,"description":"Requires an Idempotency-Key header; a duplicate key returns the original request (PRD RFD-02)."},"SettlementList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Settlement"}},"nextCursor":{"type":["string","null"],"maxLength":1024,"description":"Keyset cursor for the next page, or null on the last page. Widened from always-null in 1.22.0; a settlement history longer than one page was previously unreachable, which also capped the CSV export at a single page."}},"required":["data","nextCursor"],"additionalProperties":false},"Settlement":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":255},"status":{"type":"string","enum":["pending_approval","approved","paid","rejected"]},"method":{"type":"string","enum":["bank_eur","bank_usd","usdt","usdc"]},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR"},"grossAmountMinorUnits":{"type":"integer","minimum":0,"example":0},"feesAmountMinorUnits":{"type":"integer","minimum":0,"example":0},"setupFeeRecoveredMinorUnits":{"type":"integer","minimum":0,"example":0},"netPayoutAmountMinorUnits":{"type":"integer"},"runDate":{"type":["string","null"],"format":"date"},"periodStart":{"type":"string","format":"date-time"},"periodEnd":{"type":"string","format":"date-time"},"bankReference":{"type":["string","null"],"maxLength":200},"blockchainTxHash":{"type":["string","null"],"maxLength":200},"paidAt":{"type":["string","null"],"format":"date-time"},"payoutTransfers":{"type":"array","items":{"$ref":"#/components/schemas/SettlementPayoutTransfer"}},"createdAt":{"type":"string","format":"date-time"},"usdEquivalent":{"type":["object","null"],"properties":{"amountMinorUnits":{"type":"string","pattern":"^-?\\d{1,30}$","description":"Signed integer string of USD minor units (cents). Added in 1.9.0.","example":"731866"},"currency":{"type":"string","enum":["USD"]},"rate":{"type":"string","maxLength":64},"rateDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The ECB reference-rate observation date actually used (YYYY-MM-DD).","example":"2026-08-27"},"source":{"type":"string","enum":["ecb_reference"]},"basis":{"type":"string","enum":["transaction_date","latest","identity"],"description":"transaction_date = converted at the charge date's ECB rate; latest = at the newest cached rate; identity = the amount was already USD."}},"required":["amountMinorUnits","currency","rate","rateDate","source","basis"],"additionalProperties":false,"description":"USD settlement-display figure for `netPayoutAmountMinorUnits`, converted at the statement's creation date. Added in 1.9.0."}},"required":["id","status","method","currency","grossAmountMinorUnits","feesAmountMinorUnits","setupFeeRecoveredMinorUnits","netPayoutAmountMinorUnits","periodStart","periodEnd","bankReference","blockchainTxHash","paidAt","createdAt"],"additionalProperties":false},"SettlementPayoutTransfer":{"type":"object","properties":{"network":{"type":"string","enum":["ERC20","TRC20"]},"asset":{"type":"string","enum":["USDT","USDC"]},"amountMinorUnits":{"type":"integer","minimum":0,"example":0},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR"},"txHash":{"type":"string","maxLength":200},"address":{"type":"string","maxLength":128},"paidAt":{"type":"string","format":"date-time"},"explorerUrl":{"type":"string","maxLength":300,"format":"uri"}},"required":["network","asset","amountMinorUnits","currency","txHash","address","paidAt","explorerUrl"],"additionalProperties":false},"SettlementDetail":{"allOf":[{"$ref":"#/components/schemas/Settlement"},{"type":"object","properties":{"lineItems":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","enum":["capture","refund","chargeback","fee","reserve_hold","reserve_release","setup_fee_recovery","fx_adjustment"]},"amountMinorUnits":{"type":"integer"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR"},"referenceId":{"type":"string","minLength":1,"maxLength":255},"description":{"type":"string","maxLength":500}},"required":["type","amountMinorUnits","currency"],"additionalProperties":false}},"statement":{"$ref":"#/components/schemas/SettlementStatement"}},"required":["lineItems"],"additionalProperties":false}]},"SettlementStatement":{"type":"object","properties":{"number":{"type":["integer","null"],"minimum":1},"runDate":{"type":["string","null"],"format":"date"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR"},"sections":{"type":"array","items":{"$ref":"#/components/schemas/SettlementStatementSection"}},"combined":{"type":"object","properties":{"transactionCount":{"type":"integer","minimum":0},"lines":{"type":"array","items":{"$ref":"#/components/schemas/SettlementStatementLine"}}},"required":["transactionCount","lines"],"additionalProperties":false},"transactions":{"type":"array","items":{"$ref":"#/components/schemas/SettlementStatementTransaction"}},"heldCaptures":{"type":"null"}},"required":["number","runDate","currency","sections","combined","transactions","heldCaptures"],"additionalProperties":false},"SettlementStatementSection":{"type":"object","properties":{"key":{"type":"string","maxLength":32},"label":{"type":"string","maxLength":200},"method":{"type":["string","null"],"maxLength":64},"periodStart":{"type":"string","format":"date-time"},"periodEnd":{"type":"string","format":"date-time"},"settlementDelayDays":{"type":"integer","minimum":0},"settlementDelayBasis":{"type":"string","enum":["calendar","business"]},"transactionCount":{"type":"integer","minimum":0},"lines":{"type":"array","items":{"$ref":"#/components/schemas/SettlementStatementLine"}}},"required":["key","label","method","periodStart","periodEnd","settlementDelayDays","settlementDelayBasis","transactionCount","lines"],"additionalProperties":false},"SettlementStatementLine":{"type":"object","properties":{"key":{"type":"string","enum":["turnover","mdr_fee","pleezpay_fee","transaction_fee","rolling_reserve","refund_principal","refund_fee","chargeback_principal","chargeback_fee","net_after_processing","setup_fee_recovery","total_before_crypto_fee","crypto_settlement_fee","reserve_release","adjustment","advance_already_paid","remaining_payout","net_payout"]},"label":{"type":"string","maxLength":200},"amountMinorUnits":{"type":"integer"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR"},"rateBps":{"type":["integer","null"],"minimum":0,"maximum":10000},"note":{"type":["string","null"],"maxLength":500}},"required":["key","label","amountMinorUnits","currency","rateBps","note"],"additionalProperties":false},"SettlementStatementTransaction":{"type":"object","properties":{"ordinal":{"type":"integer","minimum":1},"capturedAt":{"type":"string","format":"date-time"},"orderReference":{"type":["string","null"],"maxLength":200},"method":{"type":"string","maxLength":64},"transactionReference":{"type":["string","null"],"minLength":1,"maxLength":255},"turnoverMinorUnits":{"type":"integer"},"mdrFeeMinorUnits":{"type":"integer"},"pleezpayFeeMinorUnits":{"type":"integer"},"transactionFeeMinorUnits":{"type":"integer"},"reserveMinorUnits":{"type":"integer"},"netProcessingMinorUnits":{"type":"integer"},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR"}},"required":["ordinal","capturedAt","orderReference","method","transactionReference","turnoverMinorUnits","mdrFeeMinorUnits","pleezpayFeeMinorUnits","transactionFeeMinorUnits","reserveMinorUnits","netProcessingMinorUnits","currency"],"additionalProperties":false},"Balances":{"type":"object","properties":{"balances":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR"},"grossAmountMinorUnits":{"type":"integer","minimum":0,"example":0},"pendingAmountMinorUnits":{"type":"integer","minimum":0,"example":0},"feesAmountMinorUnits":{"type":"integer","minimum":0,"example":0},"reserveHeldAmountMinorUnits":{"type":"integer","minimum":0,"example":0},"reserveScheduledForReleaseAmountMinorUnits":{"type":"integer","minimum":0,"example":0},"availableAmountMinorUnits":{"type":"integer","description":"May be negative when valid refunds exceed available funds (PRD §11 LED-08 / negative merchant balance)."},"pendingSettlementAmountMinorUnits":{"type":"integer","minimum":0,"example":0},"paidAmountMinorUnits":{"type":"integer","minimum":0,"example":0},"refundExposureAmountMinorUnits":{"type":"integer","minimum":0,"example":0},"disputeExposureAmountMinorUnits":{"type":"integer","minimum":0,"example":0},"negativeBalanceAmountMinorUnits":{"type":"integer","minimum":0,"example":0,"description":"Absolute value of any negative available balance being recovered from reserve or future processing."}},"required":["currency","grossAmountMinorUnits","pendingAmountMinorUnits","feesAmountMinorUnits","reserveHeldAmountMinorUnits","reserveScheduledForReleaseAmountMinorUnits","availableAmountMinorUnits","pendingSettlementAmountMinorUnits","paidAmountMinorUnits","refundExposureAmountMinorUnits","disputeExposureAmountMinorUnits","negativeBalanceAmountMinorUnits"],"additionalProperties":false}},"usdSettlement":{"type":["object","null"],"properties":{"combined":{"type":["object","null"],"properties":{"grossAmountMinorUnits":{"type":"string","pattern":"^-?\\d{1,30}$","description":"Signed integer string of USD minor units (cents). Added in 1.9.0.","example":"731866"},"pendingAmountMinorUnits":{"type":"string","pattern":"^-?\\d{1,30}$","description":"Signed integer string of USD minor units (cents). Added in 1.9.0.","example":"731866"},"feesAmountMinorUnits":{"type":"string","pattern":"^-?\\d{1,30}$","description":"Signed integer string of USD minor units (cents). Added in 1.9.0.","example":"731866"},"reserveHeldAmountMinorUnits":{"type":"string","pattern":"^-?\\d{1,30}$","description":"Signed integer string of USD minor units (cents). Added in 1.9.0.","example":"731866"},"reserveScheduledForReleaseAmountMinorUnits":{"type":"string","pattern":"^-?\\d{1,30}$","description":"Signed integer string of USD minor units (cents). Added in 1.9.0.","example":"731866"},"availableAmountMinorUnits":{"type":"string","pattern":"^-?\\d{1,30}$","description":"Signed integer string of USD minor units (cents). Added in 1.9.0.","example":"731866"},"pendingSettlementAmountMinorUnits":{"type":"string","pattern":"^-?\\d{1,30}$","description":"Signed integer string of USD minor units (cents). Added in 1.9.0.","example":"731866"},"paidAmountMinorUnits":{"type":"string","pattern":"^-?\\d{1,30}$","description":"Signed integer string of USD minor units (cents). Added in 1.9.0.","example":"731866"},"refundExposureAmountMinorUnits":{"type":"string","pattern":"^-?\\d{1,30}$","description":"Signed integer string of USD minor units (cents). Added in 1.9.0.","example":"731866"},"disputeExposureAmountMinorUnits":{"type":"string","pattern":"^-?\\d{1,30}$","description":"Signed integer string of USD minor units (cents). Added in 1.9.0.","example":"731866"},"negativeBalanceAmountMinorUnits":{"type":"string","pattern":"^-?\\d{1,30}$","description":"Signed integer string of USD minor units (cents). Added in 1.9.0.","example":"731866"}},"required":["grossAmountMinorUnits","pendingAmountMinorUnits","feesAmountMinorUnits","reserveHeldAmountMinorUnits","reserveScheduledForReleaseAmountMinorUnits","availableAmountMinorUnits","pendingSettlementAmountMinorUnits","paidAmountMinorUnits","refundExposureAmountMinorUnits","disputeExposureAmountMinorUnits","negativeBalanceAmountMinorUnits"],"additionalProperties":false},"rates":{"type":"array","items":{"type":"object","properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR"},"rate":{"type":"string","maxLength":64},"rateDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The ECB reference-rate observation date actually used (YYYY-MM-DD).","example":"2026-08-27"}},"required":["currency","rate","rateDate"],"additionalProperties":false}},"source":{"type":"string","enum":["ecb_reference"]},"basis":{"type":"string","enum":["latest"]},"excludedCurrencies":{"type":"array","items":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR"}}},"required":["combined","rates","source","basis","excludedCurrencies"],"additionalProperties":false,"description":"Combined USD settlement view of `balances`. Present only when USD settlement display is enabled; null when enabled but not computable. Added in 1.9.0."}},"required":["balances"],"additionalProperties":false},"MerchantStoreList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MerchantStore"}}},"required":["data"],"additionalProperties":false},"MerchantStore":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":255},"name":{"type":"string","minLength":1},"primaryDomain":{"type":"string","minLength":1,"maxLength":253,"description":"The store's reviewed primary hostname.","example":"shop.example.com"},"status":{"type":"string","enum":["pending_review","approved","suspended"]}},"required":["id","name","primaryDomain","status"],"additionalProperties":false},"MerchantEventList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/MerchantEvent"}},"nextCursor":{"type":["string","null"],"maxLength":512}},"required":["data","nextCursor"],"additionalProperties":false},"MerchantEvent":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":255},"type":{"type":"string","enum":["payment.processing","payment.captured","payment.failed","payment.late_capture","refund.requested","refund.completed","refund.failed_action_required","settlement.created","settlement.paid","reserve.released","dispute.opened","dispute.updated","chargeback_alert.opened","chargeback_alert.updated","checkout_settings.updated","plugin_update.offered"]},"createdAt":{"type":"string","format":"date-time"},"object":{"type":"object","additionalProperties":{},"description":"The same event-specific payload delivered to webhook endpoints, including the additive orderReference and storeId keys on every payment.* and refund.* event, lastDecline on payment.failed, and billingDescriptor on payment.captured and payment.late_capture."}},"required":["id","type","createdAt","object"],"additionalProperties":false},"ChargebackAlertMerchantList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ChargebackAlertMerchant"}}},"required":["data"],"additionalProperties":false},"ChargebackAlertMerchant":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":255},"paymentId":{"type":"string","minLength":1,"maxLength":255},"kind":{"$ref":"#/components/schemas/ChargebackAlertKind"},"status":{"$ref":"#/components/schemas/ChargebackAlertStatus"},"issuerReason":{"$ref":"#/components/schemas/ChargebackAlertIssuerReason"},"amountMinorUnits":{"type":["integer","null"],"minimum":0,"example":0},"currency":{"type":["string","null"],"pattern":"^[A-Z]{3}$","example":"EUR"},"orderReference":{"type":["string","null"],"maxLength":255},"reportedAt":{"type":"string","format":"date-time"},"statusChangedAt":{"type":"string","format":"date-time"}},"required":["id","paymentId","kind","status","issuerReason","amountMinorUnits","currency","orderReference","reportedAt","statusChangedAt"],"additionalProperties":false},"ChargebackAlertKind":{"type":"string","enum":["fraud_warning"]},"ChargebackAlertStatus":{"type":"string","enum":["open","refunded","disputed","closed"],"description":"`open`: the payment can still be refunded to avoid a chargeback. `refunded`: it was refunded in full. `disputed`: a chargeback was filed anyway. `closed`: nothing further can be done about the alert."},"ChargebackAlertIssuerReason":{"type":["string","null"],"enum":["unauthorized_use_of_card","made_with_stolen_card","made_with_lost_card","made_with_counterfeit_card","card_never_received","fraudulent_card_application","misc",null]},"ChargebackAlertMerchantResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ChargebackAlertMerchant"}},"required":["data"],"additionalProperties":false},"DisputeMerchantList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/DisputeMerchant"}}},"required":["data"],"additionalProperties":false},"DisputeMerchant":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":255},"paymentId":{"type":"string","minLength":1,"maxLength":255},"status":{"type":"string","enum":["open","under_review","evidence_submitted","won","lost","accepted"]},"amountMinorUnits":{"type":"integer","minimum":0,"example":0},"currency":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR"},"merchantReason":{"type":["string","null"],"maxLength":500},"dueAt":{"type":"string","format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"usdEquivalent":{"type":["object","null"],"properties":{"amountMinorUnits":{"type":"string","pattern":"^-?\\d{1,30}$","description":"Signed integer string of USD minor units (cents). Added in 1.9.0.","example":"731866"},"currency":{"type":"string","enum":["USD"]},"rate":{"type":"string","maxLength":64},"rateDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$","description":"The ECB reference-rate observation date actually used (YYYY-MM-DD).","example":"2026-08-27"},"source":{"type":"string","enum":["ecb_reference"]},"basis":{"type":"string","enum":["transaction_date","latest","identity"],"description":"transaction_date = converted at the charge date's ECB rate; latest = at the newest cached rate; identity = the amount was already USD."}},"required":["amountMinorUnits","currency","rate","rateDate","source","basis"],"additionalProperties":false,"description":"USD settlement-display figure for `amountMinorUnits`, converted at the dispute's creation date. Added in 1.9.0."}},"required":["id","paymentId","status","amountMinorUnits","currency","dueAt","createdAt"],"additionalProperties":false},"DisputeMerchantResponse":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DisputeMerchant"}},"required":["data"],"additionalProperties":false},"WebhookEndpointList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}},"required":["data"],"additionalProperties":false},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":255},"storeId":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Null for an account-wide endpoint; otherwise the endpoint is scoped to this store."},"url":{"type":"string","maxLength":2048,"format":"uri"},"status":{"type":"string","enum":["active","disabled"]},"description":{"type":["string","null"],"maxLength":500},"rotatedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"enabledEvents":{"$ref":"#/components/schemas/WebhookEnabledEvents"},"source":{"$ref":"#/components/schemas/WebhookEndpointSource"},"disabledReason":{"$ref":"#/components/schemas/WebhookEndpointDisabledReason"},"environment":{"type":"string","enum":["sandbox","live"]},"deliveryStats":{"type":"object","properties":{"deliveredLast24h":{"type":"integer","minimum":0},"failingLast24h":{"type":"integer","minimum":0},"lastDeliveredAt":{"type":["string","null"],"format":"date-time"},"lastFailedAt":{"type":["string","null"],"format":"date-time"}},"required":["deliveredLast24h","failingLast24h","lastDeliveredAt","lastFailedAt"],"additionalProperties":false}},"required":["id","storeId","url","status","description","rotatedAt","createdAt"],"additionalProperties":false},"WebhookEnabledEvents":{"type":["array","null"],"items":{"$ref":"#/components/schemas/WebhookSubscribableEventType"},"minItems":1,"maxItems":64,"description":"Null: the endpoint receives every event type, including types added later. Otherwise the event types it receives."},"WebhookSubscribableEventType":{"type":"string","enum":["payment.processing","payment.captured","payment.failed","payment.late_capture","refund.requested","refund.completed","refund.failed_action_required","settlement.created","settlement.paid","reserve.released","dispute.opened","dispute.updated","chargeback_alert.opened","chargeback_alert.updated"],"description":"An event type an endpoint can subscribe to. The store-integration pings (checkout_settings.updated, plugin_update.offered) are not subscribable: only an endpoint registered by a storefront plugin receives them."},"WebhookEndpointSource":{"type":"string","enum":["staff","plugin","merchant"]},"WebhookEndpointDisabledReason":{"type":["string","null"],"enum":["consecutive_failures","staff","merchant",null]},"WebhookTestDeliveryResponse":{"type":"object","properties":{"result":{"type":"object","properties":{"delivered":{"type":"boolean"},"statusCode":{"type":["integer","null"]},"error":{"type":["string","null"]}},"required":["delivered","statusCode","error"],"additionalProperties":false}},"required":["result"],"additionalProperties":false},"WebhookTestEventResponse":{"type":"object","properties":{"result":{"$ref":"#/components/schemas/WebhookTestEventResult"}},"required":["result"],"additionalProperties":false},"WebhookTestEventResult":{"type":"object","properties":{"delivered":{"type":"boolean"},"statusCode":{"type":["integer","null"]},"error":{"$ref":"#/components/schemas/WebhookTestEventError"},"latencyMs":{"type":"integer","minimum":0},"eventId":{"type":"string","minLength":1,"maxLength":255},"type":{"$ref":"#/components/schemas/WebhookSubscribableEventType"},"requestBody":{"type":"string"}},"required":["delivered","statusCode","error","latencyMs","eventId","type","requestBody"],"additionalProperties":false},"WebhookTestEventError":{"type":["string","null"],"enum":["timeout","destination_refused","connection_failed",null]},"WebhookTestEventRequest":{"type":"object","properties":{"type":{"$ref":"#/components/schemas/WebhookSubscribableEventType"}},"required":["type"],"additionalProperties":false},"WebhookDeliveryList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}}},"required":["data"],"additionalProperties":false},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string","minLength":1,"maxLength":255},"eventId":{"type":"string","minLength":1,"maxLength":255},"eventType":{"type":"string","enum":["payment.processing","payment.captured","payment.failed","payment.late_capture","refund.requested","refund.completed","refund.failed_action_required","settlement.created","settlement.paid","reserve.released","dispute.opened","dispute.updated","chargeback_alert.opened","chargeback_alert.updated","checkout_settings.updated","plugin_update.offered"]},"attemptCount":{"type":"integer","minimum":0},"nextAttemptAt":{"type":["string","null"],"format":"date-time"},"status":{"type":"string","enum":["pending","delivered","exhausted","disabled"]},"lastResponseCode":{"type":["integer","null"]},"deliveredAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}},"required":["id","eventId","eventType","attemptCount","nextAttemptAt","status","lastResponseCode","deliveredAt","createdAt"],"additionalProperties":false},"AuthTestResponse":{"oneOf":[{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"mode":{"type":"string","enum":["api_key"]},"environment":{"type":"string","enum":["sandbox","live"],"description":"The environment the presented key's own application belongs to — authoritative, never the value claimed by the key string itself."},"keyPrefix":{"type":"string","description":"The key's first 12 characters, which are not secret and identify it in your key list (e.g. `pz_sandbox_7` or `pz_live_7Kq2`). Never the key or its hash.","example":"pz_sandbox_7"},"scopes":{"type":"array","items":{"type":"string"}},"merchantId":{"type":"string","minLength":1,"maxLength":255},"organizationId":{"type":["string","null"],"minLength":1,"maxLength":255,"description":"Null when the key's merchant row cannot be resolved — reported honestly rather than as an error, since that is itself a misconfiguration worth surfacing."}},"required":["ok","mode","environment","keyPrefix","scopes","merchantId","organizationId"],"additionalProperties":false},{"type":"object","properties":{"ok":{"type":"boolean","enum":[true]},"mode":{"type":"string","enum":["user"]},"userId":{"type":"string","minLength":1,"maxLength":255},"organizationIds":{"type":"array","items":{"type":"string","minLength":1,"maxLength":255},"description":"Every organization this user holds a role binding in. May be empty: an authenticated session bound to nothing still answers 200, because that is exactly the diagnostic such a caller needs."}},"required":["ok","mode","userId","organizationIds"],"additionalProperties":false}]}},"parameters":{}},"paths":{"/v1/payment-sessions":{"post":{"operationId":"createPaymentSession","summary":"Create an HPP session","tags":["Payment sessions"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Required when creating a payment session or refund request, and reused when retrying that same request."},"required":true,"description":"Required when creating a payment session or refund request, and reused when retrying that same request.","name":"Idempotency-Key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSessionCreateRequest"}}}},"responses":{"201":{"description":"Session created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSessionResponse"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"The idempotency key conflicts with another body or the original request is still in progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"The requested store cannot be resolved or is not eligible for payment processing, or another payment policy rejected the session. Also returned when a requested direct-redirect presentation is refused outright: the capability is disabled for your account (`direct_redirect_disabled`), or `preferredMethod` is not a method the hosted page can present (`method_not_available`). NOT returned when the method simply cannot be served at that moment — that creates the session and presents the hosted picker instead.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/refund-requests":{"get":{"operationId":"listRefundRequests","summary":"List refund requests","description":"Returns the merchant's newest refund requests. This list is limit-only today.","tags":["Refunds"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"}],"responses":{"200":{"description":"Refund-request list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequestList"}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"post":{"operationId":"createRefundRequest","summary":"Request full or partial refund","tags":["Refunds"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255,"description":"Required when creating a payment session or refund request, and reused when retrying that same request."},"required":true,"description":"Required when creating a payment session or refund request, and reused when retrying that same request.","name":"Idempotency-Key","in":"header"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequestCreate"}}}},"responses":{"201":{"description":"Refund request accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequest"}}}},"400":{"description":"Validation or eligibility error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The payment does not exist or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"The idempotency key conflicts with another body or the original request is still in progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"The payment has no usable capture evidence","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/payment-sessions/{id}":{"get":{"operationId":"getPaymentSession","summary":"Read session and current payment status","tags":["Payment sessions"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Session found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentSessionResponse"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/payments/{id}":{"get":{"operationId":"getPayment","summary":"Retrieve normalized payment details","tags":["Payments"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Payment found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/payments":{"get":{"operationId":"listPayments","summary":"Search merchant payments","tags":["Payments"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","maxLength":255},"required":false,"name":"orderReference","in":"query"},{"schema":{"type":"string","enum":["created","requires_payment_method","requires_action","processing","authorized","captured","failed","cancelled","partially_refunded","refunded","disputed"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"createdAfter","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"createdBefore","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":1024},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Matching payments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentList"}}}},"400":{"description":"Request body, query parameters, or cursor failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/fulfillments":{"get":{"operationId":"listFulfillments","summary":"List payment fulfillment obligations","description":"Requires the fulfillments:read API-key scope.","tags":["Fulfillment"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["actionable","all"],"default":"actionable"},"required":false,"name":"queue","in":"query"},{"schema":{"type":"string","enum":["not_monitored","configuration_required","awaiting_tracking","due_soon","overdue","submitted_on_time","submitted_late","waived","cancelled"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":false,"name":"storeId","in":"query"},{"schema":{"type":"string","enum":["sandbox","live"]},"required":false,"name":"environment","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":false,"name":"orderReference","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":80},"required":false,"name":"carrier","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":false,"name":"q","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"capturedAfter","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"capturedBefore","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"dueAfter","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"dueBefore","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":1024},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Fulfillment obligation page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentList"}}}},"400":{"description":"Request body, query parameters, or cursor failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/fulfillments/summary":{"get":{"operationId":"getFulfillmentSummary","summary":"Read fulfillment SLA counts and compliance","description":"Requires the fulfillments:read API-key scope.","tags":["Fulfillment"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","default":30},"required":false,"name":"windowDays","in":"query"}],"responses":{"200":{"description":"Fulfillment summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentSummary"}}}},"400":{"description":"Request body, query parameters, or cursor failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/payments/{paymentId}/fulfillment":{"get":{"operationId":"getPaymentFulfillment","summary":"Read fulfillment for a captured payment","description":"Requires the fulfillments:read API-key scope.","tags":["Fulfillment"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"paymentId","in":"path"}],"responses":{"200":{"description":"Payment fulfillment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fulfillment"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The payment does not exist or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/payments/{paymentId}/tracking":{"put":{"operationId":"putPaymentTracking","summary":"Create or correct a payment tracking number","description":"Requires the fulfillments:write API-key scope. expectedRevision provides compare-and-set concurrency; an identical replay is a no-op.","tags":["Fulfillment"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"paymentId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TrackingWriteRequest"}}}},"responses":{"200":{"description":"Existing tracking replayed or corrected","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fulfillment"}}}},"201":{"description":"First tracking number recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Fulfillment"}}}},"400":{"description":"Request body, query parameters, or cursor failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The payment does not exist or belongs to another merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"Payment not captured, fulfillment waived, or expectedRevision is stale","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"Fulfillment writes are temporarily disabled by the rollout control","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/integrations/woocommerce/installations":{"post":{"operationId":"registerWooCommerceInstallation","summary":"Register (or refresh) a storefront installation","description":"One-key setup. Resolves the store, creates or reuses a store-scoped webhook endpoint and returns its signing secret EXACTLY ONCE, and either auto-allowlists the return URL (only when its host matches the store's registered primary domain, or that domain with a www. prefix) or files it for staff review. Re-sending the same body converges on the same installation and the same endpoint, so no Idempotency-Key is required. Requires the integrations:manage API-key scope.","tags":["Integrations"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationInstallationCreateRequest"}}}},"responses":{"200":{"description":"An existing installation was refreshed. webhook.secret is null unless rotateSecret was accepted.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationInstallationResponse"}}}},"201":{"description":"The installation was created. webhook.secret carries the signing secret and is never shown again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationInstallationResponse"}}}},"400":{"description":"validation_error, invalid_webhook_url, ssrf_blocked, webhook_url_host_mismatch or invalid_return_url","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"store_not_found — no store of yours matched","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"store_selection_required, installation_limit_reached or webhook_url_store_conflict (the webhook URL, or the (application, site) installation, already belongs to a different store)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"store_not_approved — the store cannot take payments yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"registration_rate_limited — too many new registrations for this account, or a secret rotation too soon after the last. Honour Retry-After. (The platform-wide request rate limit also answers 429.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/integrations/woocommerce/installations/{id}":{"patch":{"operationId":"heartbeatWooCommerceInstallation","summary":"Report a storefront heartbeat","description":"Refreshes the reported plugin/platform versions, the capability flags and last-seen time, and returns the current configuration alongside. Requires the integrations:manage API-key scope.","tags":["Integrations"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"id","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationInstallationHeartbeatRequest"}}}},"responses":{"200":{"description":"Heartbeat recorded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationHeartbeatResponse"}}}},"400":{"description":"Request body, query parameters, or cursor failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The installation does not exist or belongs to another credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"operationId":"revokeWooCommerceInstallation","summary":"Uninstall a storefront","description":"Revokes the installation and disables its webhook endpoint. The store's return-URL allowlist is deliberately left alone: an allowlist entry is a reviewed decision about where a payer may be sent, and an uninstall click is not a review. Requires the integrations:manage API-key scope.","tags":["Integrations"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"The installation is revoked (repeating the call is a no-op success)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationRevokeResponse"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"The installation does not exist or belongs to another credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/integrations/woocommerce/config":{"get":{"operationId":"getWooCommerceConfig","summary":"Read the Pleezpay-managed checkout configuration","description":"The configuration a storefront renders and must never edit locally. directRedirect is already the server's answer — your stored intent AND the platform control — so a plugin renders what it is told; learn direct CAPABILITY from GET /v1/integrations/woocommerce/available-methods (directRedirectCapable). Send the returned ETag back as If-None-Match to get a 304. Requires the integrations:read API-key scope.","tags":["Integrations"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","format":"uuid"},"required":false,"name":"storeId","in":"query"}],"responses":{"200":{"description":"Current configuration. ETag and Cache-Control: private, max-age=300 are set.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationConfigResponse"}}}},"304":{"description":"The If-None-Match validator still matches; no body is sent."},"400":{"description":"Request body, query parameters, or cursor failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"installation_not_found — no active installation for this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"installation_selection_required — this credential has more than one active installation; send storeId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"put":{"operationId":"putWooCommerceConfig","summary":"Write the store's checkout configuration","description":"Stores the checkout configuration, order status and sync cadence under an optimistic compare-and-set (expectedVersion; 0 creates the first row). Send `rows` (addressed by the row id this endpoint's GET returns), `methods` (addressed by method code), or BOTH — when both are sent `rows` is applied and `methods` is ignored, so a storefront that must work against any Pleezpay version can state the row-addressed truth alongside the legacy projection of it. A `methods`-only body keeps working indefinitely; it is not deprecated. Either way the write is a PATCH, not a replacement: rows it names are updated, rows it does not name are left exactly as they are — so an editor that can only render part of the list no longer destroys the rest of it. Because omission means 'leave alone', DELETING a row is explicit: send it with removed:true and the id it removes (a `methods` write cannot delete at all). directRedirect:true on a method whose route cannot present direct at the given currency/environment is refused 422 direct_redirect_not_available naming each offender; a method merely not eligible at this currency is accepted and stored. Returns the new configuration (exactly the GET /config shape) AND the available-methods probe for the written currency, with the config ETag, so a client seeds both caches in one round trip. Requires the integrations:manage API-key scope.","tags":["Integrations"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSettingsMerchantWrite"}}}},"responses":{"200":{"description":"Configuration written. The config ETag is set on the response.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CheckoutSettingsWriteResponse"}}}},"400":{"description":"validation_error (the body failed the strict schema — including a repeated row id, a repeated order or a second preselected row) or unknown_checkout_row_id (a row id this write names no longer exists; your cached configuration is stale — re-read and re-apply)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"installation_not_found — no active installation for this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"installation_selection_required (more than one active installation; send storeId), checkout_settings_version_conflict (expectedVersion is stale), checkout_rows_limit_reached (the rows this write CREATES, added to the rows it did not name, exceed the per-store maximum) or checkout_rows_empty (the removals in this write would leave the store with no rows at all, which takes the checkout dark — set paymentsEnabled:false instead, which is reversible and recorded)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"unknown_method_code (a row names a method Pleezpay cannot present; details[] names each offending code — a row code is validated for shape by this contract and for membership by the server, so the accepted set can grow without a contract release), presentation_only_method_code (a row names a method Pleezpay can present but cannot take payments with yet; such tiles are configured by Pleezpay only — details[] names each offending code, and removing such a row remains allowed), brand_mark_not_permitted (a row states a brand chip that names a payment brand of its own — `afterpay`, `klarna` and `bancontact` today — on a row that dispatches a different method; the chip may only ride the row it dispatches, and details[] names the chip, the row and the row's code), instalment_text_not_permitted (a row subtitle carries the {instalment} token on a row whose method is not paid in instalments — `afterpay` is the only such method today), site_messaging_not_permitted (a row switches on product/cart page instalment messaging for a method that is not paid in instalments), storefront_update_required (the write introduces {instalment} into a subtitle while an active WooCommerce installation on the store has not declared capabilities.instalments; restating an existing subtitle is never refused) or direct_redirect_not_available (directRedirect:true was requested for a method whose route cannot present direct at this currency/environment; details[] names each offending code)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/integrations/woocommerce/available-methods":{"get":{"operationId":"getWooCommerceAvailableMethods","summary":"Probe which methods are eligible and direct-redirect-capable","description":"The currency/environment-aware answer to which catalog methods this store can be routed for right now, and which can present as a direct redirect. Every catalog method Pleezpay currently offers is always returned, in catalog order — key entries by code, because a method Pleezpay has not yet launched platform-wide is omitted rather than reported ineligible; 'nothing routable' is every method eligible:false. An eligible method may carry amountRange and payerCountryRule: hide it for a cart outside the range, or for a payer whose country you KNOW the rule excludes; when the country is unknown, show it and let the hosted page decide. This is the ONLY place direct CAPABILITY is learned — the config read reports stored intent, this reports whether that intent can take effect. Currency is required. Cache-Control: private, max-age=60. Requires the integrations:read API-key scope.","tags":["Integrations"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","pattern":"^[A-Z]{3}$","example":"EUR"},"required":true,"name":"currency","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":false,"name":"storeId","in":"query"}],"responses":{"200":{"description":"The probe result for the resolved installation. ETag is NOT set (time-varying).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AvailableMethodsResponse"}}}},"400":{"description":"Request body, query parameters, or cursor failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"installation_not_found — no active installation for this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"installation_selection_required — this credential has more than one active installation; send storeId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/integrations/woocommerce/embedded-card/mounts":{"post":{"operationId":"createWooCommerceEmbeddedCardMount","summary":"Get a URL for Pleezpay's card fields on your own checkout page","description":"Asks whether this store may collect the card inside your checkout page — in Pleezpay's own framed document, under your Card row — and returns the URL to frame when it may. A mount is a capability to RENDER and carries no payment: it names the store, the environment, the currency and the ONE browser origin the document may be framed by, and it is valid for 60 minutes. The payment is created afterwards, by POST /v1/payment-sessions with presentation:\"embedded_card\", once your order exists; no payment attempt is made until the shopper presses Place order. Cache the mount for the shopper's session and re-request shortly before it expires. ANY refusal is a 422 embedded_card_not_available — render the Card row exactly as you always have (redirecting to Pleezpay's hosted checkout page), which is the working path this feature sits on top of. Requires the payments:manage API-key scope.","tags":["Integrations"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddedCardMountRequest"}}}},"responses":{"201":{"description":"A mount this store may frame at the requested origin. Cache-Control: no-store — the URL is single-store, single-origin and time-limited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmbeddedCardMountResponse"}}}},"400":{"description":"Request body, query parameters, or cursor failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"installation_not_found — no active installation for this credential","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"installation_selection_required — this credential has more than one active installation; send storeId on the config read to discover them","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"422":{"description":"embedded_card_not_available — the card cannot be collected on your page for this store, origin and currency right now. details[0].reason is one of: disabled (the capability is off for this deployment), store_not_enabled (Pleezpay has not switched this store's card row to embedded entry, or the store is not approved), plugin_capability (this installation did not declare capabilities.embeddedCard), origin_not_allowed (the origin you sent is not one of this store's known origins — its primary domain, www. of it, or an approved return URL's origin; exact host match), presentment (a currency-presentment policy applies, so the amount inside the frame would not be the amount charged) or no_eligible_account (nothing can serve Pleezpay's card fields for this store, currency and environment). Every one of them has the same correct client behaviour: fall back to the hosted checkout page.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/integrations/woocommerce/geo-policy-events":{"post":{"operationId":"reportWooCommerceGeoPolicyEvents","summary":"Report shoppers the store's geo policy matched","description":"The storefront's record of who its geo policy touched: under observe the shoppers it WOULD have hidden Pleezpay from, under enforce the shoppers it DID. One event per matched shopper — mode, country and its source, the connecting address and user agent, and the storefront's clock — in batches of up to 100. Stored for 180 days and served to Pleezpay operators only; never on a merchant surface. Accepted with 202 whether or not the store's policy is still on: a storefront flushing a queue it filled before an operator switched the policy off is reporting what it saw. Requires the integrations:manage API-key scope.","tags":["Integrations"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoPolicyEventsReportRequest"}}}},"responses":{"202":{"description":"Stored. `dropped` counts events whose address the server could not store; the same body would drop them again, so do not retry them.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeoPolicyEventsReportResponse"}}}},"400":{"description":"Request body, query parameters, or cursor failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"installation_not_found — this key has no active installation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"installation_selection_required — send storeId","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/integrations":{"get":{"operationId":"listIntegrations","summary":"List your storefront installations","description":"Every installation belonging to the authenticated merchant, with no secrets. Requires the integrations:read API-key scope.","tags":["Integrations"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Installation list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationListEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/stores/{storeId}/orders/{externalOrderId}":{"put":{"operationId":"upsertStoreOrder","summary":"Push (upsert) one storefront order","description":"Stores or refreshes the FULL order snapshot for one storefront order (decision D9). Natural idempotency: an unchanged order (matching content hash) writes nothing and returns 200 with changed=false; a new order returns 201; a snapshot older than the stored one is refused 409 stale_order_snapshot. payment_id is resolved SERVER-SIDE from orderReference and is never accepted from the body. If tracking is present and the order resolves to a captured payment, the tracking rides into the existing fulfillment tracking. Requires the orders:write API-key scope. No Idempotency-Key.","tags":["Store orders"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"storeId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"externalOrderId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreOrderUpsertRequest"}}}},"responses":{"200":{"description":"The order already existed. changed=false when nothing was written.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreOrderUpsertResponse"}}}},"201":{"description":"The order was created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreOrderUpsertResponse"}}}},"400":{"description":"Request body, query parameters, or cursor failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"store_not_found — the store is not this credential's, or does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"stale_order_snapshot — the pushed sourceUpdatedAt is older than the stored one","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"store_orders_disabled — the order-sync surface is turned off by the rollout control","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/stores/{storeId}/orders/batch":{"post":{"operationId":"upsertStoreOrderBatch","summary":"Push (upsert) up to 100 storefront orders","description":"The path a scheduled or backfill sync uses. Always 200: each order carries its own outcome (created/updated/unchanged/rejected) so one bad order never fails the batch. Opens and closes a sync-run row and returns its runId. A per-application soft cap is enforced with 429 order_sync_rate_limited + Retry-After. Requires the orders:write API-key scope.","tags":["Store orders"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"storeId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreOrderBatchRequest"}}}},"responses":{"200":{"description":"Per-order outcomes, aggregate counts and the sync-run id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreOrderBatchResponse"}}}},"400":{"description":"Request body, query parameters, or cursor failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"store_not_found — the store is not this credential's, or does not exist","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"order_sync_rate_limited — too many orders synced for this account in the window. Honour Retry-After. (The platform-wide request rate limit also answers 429.)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"store_orders_disabled — the order-sync surface is turned off by the rollout control","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/stores/{storeId}/orders/{externalOrderId}/erasure":{"post":{"operationId":"eraseStoreOrder","summary":"Anonymise an order's personal data","description":"For a WooCommerce privacy eraser. Scrubs the customer, billing, shipping and any line-item names from the order in place, keeping the financial skeleton, and sets anonymizedAt. Idempotent: a second call returns the original anonymizedAt. Requires the orders:write API-key scope.","tags":["Store orders"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"storeId","in":"path"},{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"externalOrderId","in":"path"}],"responses":{"200":{"description":"The order is anonymised (or already was)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StoreOrderErasureResponse"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"store_not_found (the store is not this credential's) or store_order_not_found (no such order for this store)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"503":{"description":"store_orders_disabled — the order-sync surface is turned off by the rollout control","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/refund-requests/{id}":{"get":{"operationId":"getRefundRequest","summary":"Read refund-request status","tags":["Refunds"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Refund request found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequest"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/settlements":{"get":{"operationId":"listSettlements","summary":"List settlement history","tags":["Settlements"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":1024},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Settlement list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementList"}}}},"400":{"description":"Request body, query parameters, or cursor failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/settlements/{id}":{"get":{"operationId":"getSettlement","summary":"Retrieve statement and line items","tags":["Settlements"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"id","in":"path"}],"responses":{"200":{"description":"Settlement detail","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SettlementDetail"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/balances":{"get":{"operationId":"getBalances","summary":"Retrieve currency/asset balance components","tags":["Balances"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Balances","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Balances"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/stores":{"get":{"operationId":"listStores","summary":"List merchant stores","description":"Returns the stores visible to the authenticated merchant. Use this read to identify store IDs and approval state, then pass storeId when creating a session for a merchant with multiple approved stores.","tags":["Stores"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Merchant store list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantStoreList"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/events":{"get":{"operationId":"listEvents","summary":"List merchant events","description":"Cursor-paginated pull feed of the same event occurrences delivered to webhook endpoints, newest first.","tags":["Events"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","enum":["payment.processing","payment.captured","payment.failed","payment.late_capture","refund.requested","refund.completed","refund.failed_action_required","settlement.created","settlement.paid","reserve.released","dispute.opened","dispute.updated","chargeback_alert.opened","chargeback_alert.updated","checkout_settings.updated","plugin_update.offered"]},"required":false,"name":"type","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"createdAfter","in":"query"},{"schema":{"type":"string","format":"date-time"},"required":false,"name":"createdBefore","in":"query"},{"schema":{"type":"integer","exclusiveMinimum":0,"maximum":100,"default":20},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":512},"required":false,"name":"cursor","in":"query"}],"responses":{"200":{"description":"Merchant event page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MerchantEventList"}}}},"400":{"description":"Invalid query parameters or cursor","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/chargeback-alerts":{"get":{"operationId":"listChargebackAlerts","summary":"List chargeback alerts","description":"Returns the merchant's chargeback alerts, newest first: card issuers' reports on the merchant's payments that a chargeback may follow (early fraud warnings). No money has moved on an alert; refunding the payment while the alert is `open` avoids the chargeback and its fee.","tags":["Chargeback alerts"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Merchant chargeback alert list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChargebackAlertMerchantList"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/chargeback-alerts/{alertId}":{"get":{"operationId":"getChargebackAlert","summary":"Retrieve one chargeback alert","description":"Returns one chargeback alert. An alert belonging to another merchant answers 404, not 403, so the response never confirms that an id exists.","tags":["Chargeback alerts"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"alertId","in":"path"}],"responses":{"200":{"description":"Merchant chargeback alert","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChargebackAlertMerchantResponse"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such alert for this merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/disputes":{"get":{"operationId":"listDisputes","summary":"List merchant disputes","description":"Returns the sanitized, read-only dispute view for the authenticated merchant.","tags":["Disputes"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Merchant dispute list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisputeMerchantList"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/disputes/{disputeId}":{"get":{"operationId":"getDispute","summary":"Retrieve one dispute","description":"Returns the sanitized, read-only view of one dispute. A dispute belonging to another merchant answers 404, not 403, so the response never confirms that an id exists.","tags":["Disputes"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"disputeId","in":"path"}],"responses":{"200":{"description":"Merchant dispute","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisputeMerchantResponse"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The credential is invalid, revoked, for the wrong environment, or lacks permission","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"No such dispute for this merchant","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/webhook-endpoints":{"get":{"operationId":"listWebhookEndpoints","summary":"List configured webhook endpoints","description":"Lists endpoints provisioned by Pleezpay support. Requires the webhooks:read API-key scope. Endpoint registration, secret rotation and disablement are support-managed and are not part of this public contract.","tags":["Webhooks"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"Configured webhook endpoints","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointList"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key does not have webhooks:read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/webhook-endpoints/{endpointId}/test-delivery":{"post":{"operationId":"sendWebhookTestDelivery","summary":"Send a webhook test delivery","description":"Sends one signed diagnostic event to an endpoint already provisioned for this application. Requires the webhooks:manage API-key scope.","tags":["Webhooks"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"endpointId","in":"path"}],"responses":{"200":{"description":"The delivery attempt completed; inspect result.delivered for its outcome","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestDeliveryResponse"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key does not have webhooks:manage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"A test delivery is already in progress","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/webhook-endpoints/{endpointId}/test-events":{"post":{"operationId":"sendWebhookTestEvent","summary":"Send a sample event","description":"Sends one signed SAMPLE of a real event type to an active endpoint of this application, built from invented ids that match no real payment or order and marked object.test = true. Nothing is recorded as an event or a delivery. Payment and refund samples are refused for an endpoint a storefront plugin registered, because the plugin applies those events to orders. Requires the webhooks:manage API-key scope.","tags":["Webhooks"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"endpointId","in":"path"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestEventRequest"}}}},"responses":{"200":{"description":"The sample was sent; inspect result.delivered for its outcome","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookTestEventResponse"}}}},"400":{"description":"validation_error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key does not have webhooks:manage","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"409":{"description":"sample_not_allowed_for_plugin_endpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"A test is already in progress for this endpoint, or the hourly test limit was reached","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/webhook-endpoints/{endpointId}/deliveries":{"get":{"operationId":"listWebhookDeliveries","summary":"List webhook delivery history","description":"Returns the most recent delivery lineages for one support-provisioned endpoint. Requires the webhooks:read API-key scope.","tags":["Webhooks"],"security":[{"ApiKeyAuth":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"required":true,"name":"endpointId","in":"path"}],"responses":{"200":{"description":"Webhook delivery history","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDeliveryList"}}}},"401":{"description":"No usable credential was supplied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"The API key does not have webhooks:read","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Webhook endpoint not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/auth/test":{"get":{"operationId":"verifyCredential","summary":"Verify a credential and report what it resolved to","description":"Answers 'is my credential reaching the server, and is it valid?' in isolation from any business route's own authorization. Accepts either a merchant API key or an authenticated user session, and returns only facts the presented credential already encodes.","tags":["Authentication"],"security":[{"ApiKeyAuth":[]}],"responses":{"200":{"description":"The credential is valid; the body reports what it resolved to.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthTestResponse"}}}},"401":{"description":"No usable credential was presented.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"A credential was presented but is not valid or grants no platform access.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Request rate limit exceeded; honor Retry-After before retrying","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}},"webhooks":{},"tags":[{"name":"Payment sessions","description":"Create a hosted checkout session for a payment, then read the session with its payment’s current status."},{"name":"Payments","description":"Read one payment, or search your payments, in one shape whichever provider took them."},{"name":"Refunds","description":"Request a full or partial refund of a payment, and follow the request until it completes."},{"name":"Fulfillment","description":"Record tracking numbers for captured payments, and read what still needs one."},{"name":"Integrations","description":"Register a storefront, report its heartbeat, and read or write the checkout configuration it shows."},{"name":"Store orders","description":"Push your storefront’s orders so payments can be matched to them, and anonymise an order on request."},{"name":"Settlements","description":"Read your settlement history, and each statement with its line items."},{"name":"Balances","description":"Read your balance components per currency or settlement asset."},{"name":"Stores","description":"List the stores on your account."},{"name":"Events","description":"Page through the events recorded for your account."},{"name":"Chargeback alerts","description":"Read the warnings a card issuer raised on your payments, while a refund can still head off a chargeback."},{"name":"Disputes","description":"List the disputes on your payments, and read one with its deadline and status."},{"name":"Webhooks","description":"List your webhook endpoints and their delivery history, and send a test delivery or a sample event."},{"name":"Authentication","description":"Verify an API key and see what it resolved to: its environment, its scopes and its account."}]}