{ "openapi": "3.0.3", "info": { "title": "Zahlo Merchant API", "version": "1.0.0", "description": "Neutral API contract for Zahlo merchant payments, checkout, commerce, subscriptions, and webhooks." }, "servers": [ { "url": "https://merchant.zahlo.eu", "description": "Production" }, { "url": "https://merchant-demo.zahlo.eu", "description": "Demo" } ], "tags": [ { "name": "Payments", "description": "Payments, methods, transactions, balances, and refunds" }, { "name": "Checkout", "description": "Hosted and embedded checkout sessions" }, { "name": "Customers", "description": "Merchant-owned customer records" }, { "name": "Catalog", "description": "Products, prices, discounts, shipping, and tax" }, { "name": "Payment Links", "description": "Shareable hosted payment pages" }, { "name": "Subscriptions", "description": "Recurring customer billing" }, { "name": "Billing", "description": "Invoices and customer self-service" }, { "name": "Webhooks", "description": "Signed event delivery" }, { "name": "Reporting", "description": "Merchant reporting and balances" }, { "name": "Risk", "description": "Fraud rules checked before a payment starts" } ], "paths": { "/api/v1/payment-methods": { "get": { "operationId": "listPaymentMethods", "summary": "List payment methods enabled for the merchant", "description": "List payment methods enabled for the merchant. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Payments" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "currency", "in": "query", "description": "Any supported currency (see Limits). Returns only the methods that take it; omit to list every enabled method with its `currencies`.", "schema": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } }, { "name": "amountMinor", "in": "query", "description": "Checkout amount in minor units (optional, echoed back).", "schema": { "type": "integer", "minimum": 1, "example": 4990 } }, { "name": "country", "in": "query", "description": "Customer billing country used for eligibility.", "schema": { "type": "string", "minLength": 2, "maxLength": 2, "example": "DE" } }, { "name": "mode", "in": "query", "description": "Checkout mode used for capability filtering.", "schema": { "type": "string", "enum": [ "hosted", "embedded" ], "default": "hosted" } }, { "name": "scope", "in": "query", "description": "`nonbank` leaves out bank methods (what checkout can offer).", "schema": { "type": "string", "enum": [ "nonbank" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodList" }, "examples": { "default": { "value": { "currency": "EUR", "environment": "sandbox", "mode": "hosted", "merchantReady": true, "methods": [ { "id": "card", "name": "Card", "description": "Pay with Visa, Mastercard, and other cards", "brands": [ "mastercard", "visa" ], "currencies": [ "CAD", "CHF", "DKK", "EUR", "GBP", "JPY", "PLN", "RON", "USD" ] } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/payment-methods/defaults": { "get": { "operationId": "retrievePaymentMethodDefaults", "summary": "Retrieve the merchant's default checkout payment methods", "description": "Retrieve the merchant's default checkout payment methods. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Payments" ], "security": [ { "merchantApiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodDefaults" }, "examples": { "default": { "value": { "paymentMethodTypes": [ "card", "apple_pay", "google_pay" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "patch": { "operationId": "updatePaymentMethodDefaults", "summary": "Set the default checkout payment methods (empty = all available)", "description": "Set the default checkout payment methods (empty = all available). Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Payments" ], "security": [ { "merchantApiKey": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodDefaults" }, "examples": { "default": { "value": { "paymentMethodTypes": [ "card", "apple_pay", "google_pay" ] } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentMethodDefaults" }, "examples": { "default": { "value": { "paymentMethodTypes": [ "card", "apple_pay", "google_pay" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/checkout-sessions": { "get": { "operationId": "listCheckoutSessions", "summary": "List checkout sessions", "description": "List checkout sessions. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Checkout" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return records after this id (newest first).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return records before this id.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Only sessions in this status.", "schema": { "type": "string", "enum": [ "open", "complete", "expired" ] } }, { "name": "customerId", "in": "query", "description": "Only sessions for this customer.", "schema": { "type": "string" } }, { "name": "createdGte", "in": "query", "description": "Only sessions created at or after this time.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSession" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "post": { "operationId": "createCheckoutSession", "summary": "Create a hosted or embedded checkout session", "description": "Create a hosted or embedded checkout session. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Checkout" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSessionCreateRequest" }, "examples": { "default": { "value": { "mode": "hosted", "lineItems": [ { "priceId": "price_demo_1001", "quantity": 1 } ], "successUrl": "https://store.example/checkout/success?session={CHECKOUT_SESSION_ID}", "cancelUrl": "https://store.example/checkout/cancel", "customerEmail": "customer@example.com", "metadata": { "orderId": "order_1001" } } } } } } }, "responses": { "201": { "description": "Checkout session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" }, "examples": { "default": { "value": { "id": "demo_session_1001", "object": "checkout_session", "type": "payment", "mode": "hosted", "status": "open", "paymentStatus": "unpaid", "url": "https://merchant.zahlo.eu/pay/demo_session_1001", "clientToken": null, "embedUrl": null, "expiresAt": "2026-11-02T12:00:00Z", "currency": "EUR", "amountSubtotal": 4990, "amountDiscount": 0, "amountShipping": 0, "amountTotal": 4990, "shippingOptions": [], "shippingCost": null, "customFields": [], "lineItems": [ { "name": "Team plan", "quantity": 1, "unitAmountMinor": 4990, "amountMinor": 4990, "priceId": "price_demo_1001" } ], "paymentMethodTypes": [ "card", "apple_pay", "google_pay" ], "locale": "auto", "metadata": { "orderId": "order_1001" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/checkout-sessions/{id}": { "get": { "operationId": "retrieveCheckoutSession", "summary": "Retrieve a checkout session", "description": "Retrieve a checkout session. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Checkout" ], "security": [ { "clientToken": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" }, "examples": { "default": { "value": { "id": "demo_session_1001", "object": "checkout_session", "type": "payment", "mode": "hosted", "status": "open", "paymentStatus": "unpaid", "url": "https://merchant.zahlo.eu/pay/demo_session_1001", "clientToken": null, "embedUrl": null, "expiresAt": "2026-11-02T12:00:00Z", "currency": "EUR", "amountSubtotal": 4990, "amountDiscount": 0, "amountShipping": 0, "amountTotal": 4990, "shippingOptions": [], "shippingCost": null, "customFields": [], "lineItems": [ { "name": "Team plan", "quantity": 1, "unitAmountMinor": 4990, "amountMinor": 4990, "priceId": "price_demo_1001" } ], "paymentMethodTypes": [ "card", "apple_pay", "google_pay" ], "locale": "auto", "metadata": { "orderId": "order_1001" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/checkout-sessions/{id}/expire": { "post": { "operationId": "expireCheckoutSession", "summary": "Expire an open checkout session", "description": "Expire an open checkout session. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Checkout" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Checkout session expired", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" }, "examples": { "default": { "value": { "id": "demo_session_1001", "object": "checkout_session", "type": "payment", "mode": "hosted", "status": "open", "paymentStatus": "unpaid", "url": "https://merchant.zahlo.eu/pay/demo_session_1001", "clientToken": null, "embedUrl": null, "expiresAt": "2026-11-02T12:00:00Z", "currency": "EUR", "amountSubtotal": 4990, "amountDiscount": 0, "amountShipping": 0, "amountTotal": 4990, "shippingOptions": [], "shippingCost": null, "customFields": [], "lineItems": [ { "name": "Team plan", "quantity": 1, "unitAmountMinor": 4990, "amountMinor": 4990, "priceId": "price_demo_1001" } ], "paymentMethodTypes": [ "card", "apple_pay", "google_pay" ], "locale": "auto", "metadata": { "orderId": "order_1001" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/checkout-domains": { "get": { "operationId": "listCheckoutDomain", "summary": "List checkout domains", "description": "List checkout domains. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Checkout" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return records after this id (newest first).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return records before this id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutDomain" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "post": { "operationId": "createCheckoutDomain", "summary": "Create checkout domain", "description": "Create checkout domain. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Checkout" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutDomainCreateRequest" }, "examples": { "default": { "value": { "domain": "shop.example.com", "applePay": true } } } } } }, "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutDomain" }, "examples": { "default": { "value": { "id": "cdom_demo_1001", "object": "checkout_domain", "domain": "shop.example.com", "applePay": { "status": "active", "lastError": null } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/checkout-domains/{id}": { "get": { "operationId": "retrieveCheckoutDomain", "summary": "Retrieve a checkout domain", "description": "Retrieve a checkout domain. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Checkout" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutDomain" }, "examples": { "default": { "value": { "id": "cdom_demo_1001", "object": "checkout_domain", "domain": "shop.example.com", "applePay": { "status": "active", "lastError": null } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "delete": { "operationId": "deleteCheckoutDomain", "summary": "Delete a checkout domain", "description": "Delete a checkout domain. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Checkout" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Resource deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/checkout-settings": { "get": { "operationId": "listCheckoutSettings", "summary": "List checkout settings", "description": "List checkout settings. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Checkout" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return records after this id (newest first).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return records before this id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSettings" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "post": { "operationId": "createCheckoutSettings", "summary": "Create checkout setting", "description": "Create checkout setting. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Checkout" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSettingsRequest" }, "examples": { "default": { "value": { "locale": "en", "allowedOrigins": [ "https://store.example" ], "paymentMethods": [ "card", "apple_pay", "google_pay" ] } } } } } }, "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSettings" }, "examples": { "default": { "value": { "locale": "en", "allowedOrigins": [ "https://store.example" ], "paymentMethods": [ "card", "apple_pay", "google_pay" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/checkout-settings/{id}": { "get": { "operationId": "retrieveCheckoutSettings", "summary": "Retrieve a checkout setting", "description": "Retrieve a checkout setting. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Checkout" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSettings" }, "examples": { "default": { "value": { "locale": "en", "allowedOrigins": [ "https://store.example" ], "paymentMethods": [ "card", "apple_pay", "google_pay" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "patch": { "operationId": "updateCheckoutSettings", "summary": "Update a checkout setting", "description": "Update a checkout setting. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Checkout" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSettingsRequest" }, "examples": { "default": { "value": { "locale": "en", "allowedOrigins": [ "https://store.example" ], "paymentMethods": [ "card", "apple_pay", "google_pay" ] } } } } } }, "responses": { "200": { "description": "Resource updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSettings" }, "examples": { "default": { "value": { "locale": "en", "allowedOrigins": [ "https://store.example" ], "paymentMethods": [ "card", "apple_pay", "google_pay" ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "delete": { "operationId": "deleteCheckoutSettings", "summary": "Delete a checkout setting", "description": "Delete a checkout setting. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Checkout" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Resource deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/payments": { "get": { "operationId": "listPayments", "summary": "List payments", "description": "List payments. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Payments" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return records after this id (newest first).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return records before this id.", "schema": { "type": "string" } }, { "name": "customerId", "in": "query", "description": "Only payments of this customer.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "post": { "operationId": "createOffSessionPayment", "summary": "Charge a saved card off-session", "description": "Charges a card saved at checkout without the customer present. Requires an Idempotency-Key. 201: succeeded; 202: the outcome is still unknown, `payment.confirmed` or `payment.failed` follows; 402 `card_declined` or `authentication_required` (bring the customer back to Checkout).", "tags": [ "Payments" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OffSessionPaymentRequest" }, "examples": { "default": { "value": { "customerId": "cus_0a1b2c3d4e5f60718293a4b5", "paymentMethodId": "pm_0a1b2c3d4e5f60718293a4b5", "amountMinor": 4990, "currency": "EUR", "reference": "order_1002", "offSession": true } } } } } }, "responses": { "201": { "description": "The succeeded payment", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "examples": { "default": { "value": { "id": "pay_demo_1001", "object": "payment", "livemode": false, "createdAt": "2026-09-02T12:00:00.000Z", "status": "succeeded", "amountMinor": 4990, "amountRefundedMinor": 0, "refunded": false, "currency": "EUR", "paymentMethod": { "type": "card" }, "outcome": { "threeDSecure": null, "riskLevel": null, "providerReason": null }, "customerId": "cus_demo_1001", "subscriptionId": null, "checkoutSessionId": "pay_demo_1001", "paymentLinkId": null, "receiptNumber": null, "receiptUrl": null, "reference": "order_1001", "metadata": { "orderId": "order_1001" }, "disputed": false } } } } } }, "202": { "description": "The payment, still pending", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "examples": { "default": { "value": { "id": "pay_demo_1001", "object": "payment", "livemode": false, "createdAt": "2026-09-02T12:00:00.000Z", "status": "succeeded", "amountMinor": 4990, "amountRefundedMinor": 0, "refunded": false, "currency": "EUR", "paymentMethod": { "type": "card" }, "outcome": { "threeDSecure": null, "riskLevel": null, "providerReason": null }, "customerId": "cus_demo_1001", "subscriptionId": null, "checkoutSessionId": "pay_demo_1001", "paymentLinkId": null, "receiptNumber": null, "receiptUrl": null, "reference": "order_1001", "metadata": { "orderId": "order_1001" }, "disputed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/payments/{id}": { "get": { "operationId": "retrievePayment", "summary": "Retrieve a payment", "description": "Retrieve a payment. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Payments" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "examples": { "default": { "value": { "id": "pay_demo_1001", "object": "payment", "livemode": false, "createdAt": "2026-09-02T12:00:00.000Z", "status": "succeeded", "amountMinor": 4990, "amountRefundedMinor": 0, "refunded": false, "currency": "EUR", "paymentMethod": { "type": "card" }, "outcome": { "threeDSecure": null, "riskLevel": null, "providerReason": null }, "customerId": "cus_demo_1001", "subscriptionId": null, "checkoutSessionId": "pay_demo_1001", "paymentLinkId": null, "receiptNumber": null, "receiptUrl": null, "reference": "order_1001", "metadata": { "orderId": "order_1001" }, "disputed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "patch": { "operationId": "updatePayment", "summary": "Update a payment's metadata", "description": "Replaces the payment's metadata. Amount, status and every other field stay as the provider reported them.", "tags": [ "Payments" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentUpdateRequest" }, "examples": { "default": { "value": { "metadata": { "orderId": "order_1001", "shipped": "true" } } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payment" }, "examples": { "default": { "value": { "id": "pay_demo_1001", "object": "payment", "livemode": false, "createdAt": "2026-09-02T12:00:00.000Z", "status": "succeeded", "amountMinor": 4990, "amountRefundedMinor": 0, "refunded": false, "currency": "EUR", "paymentMethod": { "type": "card" }, "outcome": { "threeDSecure": null, "riskLevel": null, "providerReason": null }, "customerId": "cus_demo_1001", "subscriptionId": null, "checkoutSessionId": "pay_demo_1001", "paymentLinkId": null, "receiptNumber": null, "receiptUrl": null, "reference": "order_1001", "metadata": { "orderId": "order_1001" }, "disputed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/transactions": { "get": { "operationId": "listTransactions", "summary": "List payment transactions", "description": "List payment transactions. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Payments" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "offset", "in": "query", "description": "Number of records to skip.", "schema": { "type": "integer", "minimum": 0, "default": 0 } }, { "name": "q", "in": "query", "description": "Search the payment reference and id (up to 100 characters).", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Only transactions in this status.", "schema": { "type": "string", "enum": [ "confirmed", "pending", "cancelled" ] } }, { "name": "excludePaymentLinks", "in": "query", "description": "`1` leaves out payments made through payment links.", "schema": { "type": "string", "enum": [ "1" ] } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Transaction" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/transactions/{id}": { "get": { "operationId": "retrieveTransaction", "summary": "Retrieve a transaction", "description": "Retrieve a transaction. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Payments" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "default": { "value": { "id": "txn_demo_1001", "paymentId": "pay_demo_1001", "status": "pending", "method": "card", "reference": "order_1001", "amount": { "amountMinor": 4990, "currency": "EUR" }, "createdAt": "2026-09-02T12:00:00Z", "occurredAt": "2026-09-02T12:00:00Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/balance": { "get": { "operationId": "retrieveBalance", "summary": "Retrieve the merchant balance", "description": "Retrieve the merchant balance. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Reporting" ], "security": [ { "merchantApiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" }, "examples": { "default": { "value": { "available": { "amountMinor": 0, "currency": "EUR" }, "pending": { "amountMinor": 4990, "currency": "EUR" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/balance-transactions": { "get": { "operationId": "listBalanceTransactions", "summary": "List balance transactions", "description": "List balance transactions. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Reporting" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return records after this id (newest first).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return records before this id.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Only movements of this type.", "schema": { "type": "string", "enum": [ "payment", "refund", "dispute", "payout", "payout_failure" ] } }, { "name": "payout", "in": "query", "description": "Only the movements this payout settled, as Zahlo matched them (see `Payout.reconciliationStatus`).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/BalanceTransaction" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/balance-transactions/export": { "get": { "operationId": "exportBalanceTransactions", "summary": "Export the payout reconciliation CSV", "description": "One CSV row per balance movement with the payout that settled it: `payout_id, payout_status, payout_arrival, balance_transaction_id, type, source_id, reference, gross, fee, net, currency, effective_at` (amounts in major units). Pass `payout` for one payout, or `from`/`to` (ISO dates, at most 366 days; default the last 30 days). Movements no payout claimed yet have an empty `payout_id`.", "tags": [ "Reporting" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "payout", "in": "query", "description": "One payout's movements.", "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Start of the range (inclusive).", "schema": { "type": "string", "format": "date-time" } }, { "name": "to", "in": "query", "description": "End of the range (exclusive).", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "The CSV report", "content": { "text/csv": { "schema": { "type": "string" }, "example": "payout_id,payout_status,payout_arrival,balance_transaction_id,type,source_id,reference,gross,fee,net,currency,effective_at\npo_demo_1001,booked,2026-08-03T09:00:00.000Z,txn_demo_1001,payment,pay_demo_1001,Order 7,49.90,1.20,48.70,EUR,2026-08-01T10:00:00.000Z\n" } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/payouts": { "get": { "operationId": "listPayouts", "summary": "List payouts", "description": "List payouts. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Reporting" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return records after this id (newest first).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return records before this id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payout" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/payouts/{id}": { "get": { "operationId": "retrievePayout", "summary": "Retrieve a payout", "description": "Retrieve a payout. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Reporting" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Payout" }, "examples": { "default": { "value": { "id": "po_demo_1001", "object": "payout", "livemode": false, "createdAt": "2026-08-03T09:00:00.000Z", "amountMinor": 48700, "feeMinor": 50, "currency": "EUR", "status": "pending", "arrivalDate": null, "automatic": true, "reconciliationStatus": "matched" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/disputes": { "get": { "operationId": "listDisputes", "summary": "List payment disputes", "description": "List payment disputes. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Payments" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return records after this id (newest first).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return records before this id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Dispute" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/disputes/{id}": { "get": { "operationId": "retrieveDispute", "summary": "Retrieve a payment dispute", "description": "Retrieve a payment dispute. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Payments" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" }, "examples": { "default": { "value": { "id": "PSP-DEMO-1001", "paymentId": "pay_demo_1001", "status": "needs_response", "amount": { "amountMinor": 4990, "currency": "EUR" }, "reason": "Goods not received", "evidenceDueAt": "2026-08-05T00:00:00" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/disputes/{id}/respond": { "post": { "operationId": "respondToDispute", "summary": "Submit evidence for a payment dispute", "description": "Submit evidence for a payment dispute. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Payments" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DisputeEvidenceRequest" }, "examples": { "default": { "value": { "evidence": { "defenseReasonCode": "GoodsOrServicesProvided", "documents": [ { "defenseDocumentTypeCode": "DeliveryConfirmation", "fileName": "delivery.pdf", "contentType": "application/pdf", "contentBase64": "JVBERi0xLjQK" } ] } } } } } } }, "responses": { "200": { "description": "Dispute evidence submitted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" }, "examples": { "default": { "value": { "id": "PSP-DEMO-1001", "paymentId": "pay_demo_1001", "status": "needs_response", "amount": { "amountMinor": 4990, "currency": "EUR" }, "reason": "Goods not received", "evidenceDueAt": "2026-08-05T00:00:00" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/fraud-rules": { "get": { "operationId": "listFraudRule", "summary": "List fraud rules", "description": "List fraud rules. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Risk" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return records after this id (newest first).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return records before this id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/FraudRule" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "post": { "operationId": "createFraudRule", "summary": "Create fraud rule", "description": "Create fraud rule. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Risk" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudRuleCreateRequest" }, "examples": { "default": { "value": { "kind": "max_amount", "value": "50000", "currency": "EUR" } } } } } }, "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudRule" }, "examples": { "default": { "value": { "id": "clx0fraudrule01", "object": "fraud_rule", "livemode": false, "createdAt": "2026-11-01T10:00:00.000Z", "kind": "max_amount", "value": "50000", "currency": "EUR", "enabled": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/fraud-rules/{id}": { "get": { "operationId": "retrieveFraudRule", "summary": "Retrieve a fraud rule", "description": "Retrieve a fraud rule. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Risk" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudRule" }, "examples": { "default": { "value": { "id": "clx0fraudrule01", "object": "fraud_rule", "livemode": false, "createdAt": "2026-11-01T10:00:00.000Z", "kind": "max_amount", "value": "50000", "currency": "EUR", "enabled": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "patch": { "operationId": "updateFraudRule", "summary": "Update a fraud rule", "description": "Update a fraud rule. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Risk" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudRuleUpdateRequest" }, "examples": { "default": { "value": { "enabled": false } } } } } }, "responses": { "200": { "description": "Resource updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FraudRule" }, "examples": { "default": { "value": { "id": "clx0fraudrule01", "object": "fraud_rule", "livemode": false, "createdAt": "2026-11-01T10:00:00.000Z", "kind": "max_amount", "value": "50000", "currency": "EUR", "enabled": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "delete": { "operationId": "deleteFraudRule", "summary": "Delete a fraud rule", "description": "Delete a fraud rule. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Risk" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Resource deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/refunds": { "get": { "operationId": "listRefunds", "summary": "List refunds", "description": "List refunds. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Payments" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return records after this id (newest first).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return records before this id.", "schema": { "type": "string" } }, { "name": "paymentId", "in": "query", "description": "Only refunds of this payment.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Refund" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "post": { "operationId": "createRefund", "summary": "Create a refund", "description": "Create a refund. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Payments" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundCreateRequest" }, "examples": { "default": { "value": { "paymentId": "pay_demo_1001", "amountMinor": 4990, "reason": "requested_by_customer" } } } } } }, "responses": { "201": { "description": "Refund created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" }, "examples": { "default": { "value": { "id": "re_demo_1001", "object": "refund", "livemode": false, "createdAt": "2026-08-01T10:00:00.000Z", "paymentId": "pay_demo_1001", "amountMinor": 4990, "currency": "EUR", "status": "succeeded", "reason": "requested_by_customer", "metadata": { "orderId": "order_1001" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/refunds/{id}": { "get": { "operationId": "retrieveRefund", "summary": "Retrieve a refund", "description": "Retrieve a refund. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Payments" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" }, "examples": { "default": { "value": { "id": "re_demo_1001", "object": "refund", "livemode": false, "createdAt": "2026-08-01T10:00:00.000Z", "paymentId": "pay_demo_1001", "amountMinor": 4990, "currency": "EUR", "status": "succeeded", "reason": "requested_by_customer", "metadata": { "orderId": "order_1001" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/customers": { "get": { "operationId": "listCustomer", "summary": "List customers", "description": "List customers. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Customers" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Number of objects to return, 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return objects after this id (next page).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return objects before this id (previous page).", "schema": { "type": "string" } }, { "name": "email", "in": "query", "description": "Only customers with this email (case-insensitive).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of customers", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Customer" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "post": { "operationId": "createCustomer", "summary": "Create a customer", "description": "Create a customer. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Customers" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerCreateRequest" }, "examples": { "default": { "value": { "email": "buyer@example.com", "name": "Example Buyer", "metadata": { "accountId": "account_1001" } } } } } } }, "responses": { "200": { "description": "The customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "examples": { "default": { "value": { "id": "cus_0a1b2c3d4e5f60718293a4b5", "object": "customer", "livemode": false, "createdAt": "2026-10-29T10:00:00.000Z", "email": "buyer@example.com", "name": "Example Buyer", "phone": null, "address": null, "preferredLocale": "de", "defaultPaymentMethodId": null, "metadata": { "accountId": "account_1001" }, "taxIds": [ { "type": "eu_vat", "value": "DE123456789", "verification": { "status": "verified", "verifiedName": "Acme GmbH" } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/customers/{id}": { "get": { "operationId": "retrieveCustomer", "summary": "Retrieve a customer", "description": "Retrieve a customer. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Customers" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "examples": { "default": { "value": { "id": "cus_0a1b2c3d4e5f60718293a4b5", "object": "customer", "livemode": false, "createdAt": "2026-10-29T10:00:00.000Z", "email": "buyer@example.com", "name": "Example Buyer", "phone": null, "address": null, "preferredLocale": "de", "defaultPaymentMethodId": null, "metadata": { "accountId": "account_1001" }, "taxIds": [ { "type": "eu_vat", "value": "DE123456789", "verification": { "status": "verified", "verifiedName": "Acme GmbH" } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "patch": { "operationId": "updateCustomer", "summary": "Update a customer", "description": "Update a customer. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Customers" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerUpdateRequest" }, "examples": { "default": { "value": { "name": "Example Buyer GmbH" } } } } } }, "responses": { "200": { "description": "The updated customer", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" }, "examples": { "default": { "value": { "id": "cus_0a1b2c3d4e5f60718293a4b5", "object": "customer", "livemode": false, "createdAt": "2026-10-29T10:00:00.000Z", "email": "buyer@example.com", "name": "Example Buyer", "phone": null, "address": null, "preferredLocale": "de", "defaultPaymentMethodId": null, "metadata": { "accountId": "account_1001" }, "taxIds": [ { "type": "eu_vat", "value": "DE123456789", "verification": { "status": "verified", "verifiedName": "Acme GmbH" } } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "delete": { "operationId": "deleteCustomer", "summary": "Delete a customer (soft delete; subscriptions are not cancelled)", "description": "Delete a customer (soft delete; subscriptions are not cancelled). Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Customers" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeletedCustomer" }, "examples": { "default": { "value": { "id": "cus_0a1b2c3d4e5f60718293a4b5", "object": "customer", "deleted": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/customers/{id}/payment-methods": { "get": { "operationId": "listCustomerPaymentMethods", "summary": "List a customer's saved cards", "description": "List a customer's saved cards. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Customers" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The customer's attached cards, newest first", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CustomerPaymentMethod" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/customers/{id}/payment-methods/{paymentMethodId}": { "get": { "operationId": "retrieveCustomerPaymentMethod", "summary": "Retrieve a saved card", "description": "Retrieve a saved card. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Customers" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } }, { "name": "paymentMethodId", "in": "path", "required": true, "description": "The saved card's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPaymentMethod" }, "examples": { "default": { "value": { "id": "pm_0a1b2c3d4e5f60718293a4b5", "object": "payment_method", "livemode": false, "createdAt": "2026-11-01T10:00:00.000Z", "customerId": "cus_0a1b2c3d4e5f60718293a4b5", "checkoutSessionId": "cs_0a1b2c3d4e5f60718293a4b5", "type": "card", "card": { "brand": "Visa", "last4": "4242", "expMonth": 12, "expYear": 2030 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "delete": { "operationId": "detachCustomerPaymentMethod", "summary": "Detach a saved card; it can no longer be charged", "description": "Detach a saved card; it can no longer be charged. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Customers" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } }, { "name": "paymentMethodId", "in": "path", "required": true, "description": "The saved card's id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The detached card", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPaymentMethod" }, "examples": { "default": { "value": { "id": "pm_0a1b2c3d4e5f60718293a4b5", "object": "payment_method", "livemode": false, "createdAt": "2026-11-01T10:00:00.000Z", "customerId": "cus_0a1b2c3d4e5f60718293a4b5", "checkoutSessionId": "cs_0a1b2c3d4e5f60718293a4b5", "type": "card", "card": { "brand": "Visa", "last4": "4242", "expMonth": 12, "expYear": 2030 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/products": { "get": { "operationId": "listProduct", "summary": "List products", "description": "List products. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Catalog" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return records after this id (newest first).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return records before this id.", "schema": { "type": "string" } }, { "name": "active", "in": "query", "description": "Only active (`true`) or archived (`false`) objects.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Product" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "post": { "operationId": "createProduct", "summary": "Create product", "description": "Create product. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Catalog" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCreateRequest" }, "examples": { "default": { "value": { "name": "Example plan", "description": "Access for one team", "active": true } } } } } }, "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "examples": { "default": { "value": { "id": "prod_demo_1001", "name": "Example plan", "active": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/products/{id}": { "get": { "operationId": "retrieveProduct", "summary": "Retrieve a product", "description": "Retrieve a product. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Catalog" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "examples": { "default": { "value": { "id": "prod_demo_1001", "name": "Example plan", "active": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "patch": { "operationId": "updateProduct", "summary": "Update a product", "description": "Update a product. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Catalog" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProductCreateRequest" }, "examples": { "default": { "value": { "name": "Example plan", "description": "Access for one team", "active": true } } } } } }, "responses": { "200": { "description": "Resource updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Product" }, "examples": { "default": { "value": { "id": "prod_demo_1001", "name": "Example plan", "active": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "delete": { "operationId": "deleteProduct", "summary": "Delete a product", "description": "Delete a product. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Catalog" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Resource deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/prices": { "get": { "operationId": "listPrice", "summary": "List prices", "description": "List prices. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Catalog" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return records after this id (newest first).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return records before this id.", "schema": { "type": "string" } }, { "name": "active", "in": "query", "description": "Only active (`true`) or archived (`false`) objects.", "schema": { "type": "boolean" } }, { "name": "lookupKey", "in": "query", "description": "Only the price with this lookup key.", "schema": { "type": "string" } }, { "name": "productId", "in": "query", "description": "Only this product's prices.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Price" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "post": { "operationId": "createPrice", "summary": "Create price", "description": "Create price. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Catalog" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceCreateRequest" }, "examples": { "default": { "value": { "productId": "prod_demo_1001", "unitAmountMinor": 1900, "currency": "EUR" } } } } } }, "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Price" }, "examples": { "default": { "value": { "id": "price_demo_1001", "object": "price", "productId": "prod_demo_1001", "unitAmountMinor": 1900, "currency": "EUR", "type": "one_time", "recurring": null, "active": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/prices/{id}": { "get": { "operationId": "retrievePrice", "summary": "Retrieve a price", "description": "Retrieve a price. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Catalog" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Price" }, "examples": { "default": { "value": { "id": "price_demo_1001", "object": "price", "productId": "prod_demo_1001", "unitAmountMinor": 1900, "currency": "EUR", "type": "one_time", "recurring": null, "active": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "patch": { "operationId": "updatePrice", "summary": "Update a price", "description": "Update a price. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Catalog" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PriceUpdateRequest" }, "examples": { "default": { "value": {} } } } } }, "responses": { "200": { "description": "Resource updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Price" }, "examples": { "default": { "value": { "id": "price_demo_1001", "object": "price", "productId": "prod_demo_1001", "unitAmountMinor": 1900, "currency": "EUR", "type": "one_time", "recurring": null, "active": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/coupons": { "get": { "operationId": "listCoupon", "summary": "List coupons", "description": "List coupons. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Catalog" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Number of objects to return, 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return objects after this id (next page).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return objects before this id (previous page).", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of coupons", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Coupon" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "post": { "operationId": "createCoupon", "summary": "Create a coupon", "description": "Create a coupon. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Catalog" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponCreateRequest" }, "examples": { "default": { "value": { "name": "Spring sale", "percentOff": 20, "duration": "repeating", "durationInMonths": 3, "code": "SPRING20" } } } } } }, "responses": { "200": { "description": "The coupon", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" }, "examples": { "default": { "value": { "id": "coupon_0a1b2c3d4e5f60718293a4b5", "object": "coupon", "livemode": false, "createdAt": "2026-10-29T10:00:00.000Z", "name": "Spring sale", "percentOff": 20, "amountOffMinor": null, "currency": null, "duration": "repeating", "durationInMonths": 3, "code": "SPRING20", "maxRedemptions": 100, "timesRedeemed": 0, "redeemBy": null, "active": true, "metadata": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/coupons/{id}": { "get": { "operationId": "retrieveCoupon", "summary": "Retrieve a coupon", "description": "Retrieve a coupon. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Catalog" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" }, "examples": { "default": { "value": { "id": "coupon_0a1b2c3d4e5f60718293a4b5", "object": "coupon", "livemode": false, "createdAt": "2026-10-29T10:00:00.000Z", "name": "Spring sale", "percentOff": 20, "amountOffMinor": null, "currency": null, "duration": "repeating", "durationInMonths": 3, "code": "SPRING20", "maxRedemptions": 100, "timesRedeemed": 0, "redeemBy": null, "active": true, "metadata": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "patch": { "operationId": "updateCoupon", "summary": "Update a coupon's name, metadata or active flag (terms are immutable)", "description": "Update a coupon's name, metadata or active flag (terms are immutable). Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Catalog" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CouponUpdateRequest" }, "examples": { "default": { "value": { "active": false } } } } } }, "responses": { "200": { "description": "The updated coupon", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" }, "examples": { "default": { "value": { "id": "coupon_0a1b2c3d4e5f60718293a4b5", "object": "coupon", "livemode": false, "createdAt": "2026-10-29T10:00:00.000Z", "name": "Spring sale", "percentOff": 20, "amountOffMinor": null, "currency": null, "duration": "repeating", "durationInMonths": 3, "code": "SPRING20", "maxRedemptions": 100, "timesRedeemed": 0, "redeemBy": null, "active": true, "metadata": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "delete": { "operationId": "deleteCoupon", "summary": "Deactivate a coupon (subscriptions already using it keep their discount)", "description": "Deactivate a coupon (subscriptions already using it keep their discount). Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Catalog" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The deactivated coupon", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Coupon" }, "examples": { "default": { "value": { "id": "coupon_0a1b2c3d4e5f60718293a4b5", "object": "coupon", "livemode": false, "createdAt": "2026-10-29T10:00:00.000Z", "name": "Spring sale", "percentOff": 20, "amountOffMinor": null, "currency": null, "duration": "repeating", "durationInMonths": 3, "code": "SPRING20", "maxRedemptions": 100, "timesRedeemed": 0, "redeemBy": null, "active": true, "metadata": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/shipping-rates": { "get": { "operationId": "listShippingRate", "summary": "List shipping rates", "description": "List shipping rates. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Catalog" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Number of objects to return, 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return objects after this id (next page).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return objects before this id (previous page).", "schema": { "type": "string" } }, { "name": "active", "in": "query", "description": "Only active (`true`) or archived (`false`) objects.", "schema": { "type": "boolean" } }, { "name": "currency", "in": "query", "description": "Only rates in this ISO 4217 currency.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of shipping rates", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingRate" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "post": { "operationId": "createShippingRate", "summary": "Create a shipping rate", "description": "Create a shipping rate. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Catalog" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRateCreateRequest" }, "examples": { "default": { "value": { "displayName": "Standard shipping", "fixedAmount": { "amount": 495, "currency": "EUR" }, "deliveryEstimate": { "minimum": { "unit": "business_day", "value": 2 }, "maximum": { "unit": "business_day", "value": 4 } } } } } } } }, "responses": { "200": { "description": "The shipping rate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRate" }, "examples": { "default": { "value": { "id": "shr_0a1b2c3d4e5f60718293a4b5", "object": "shipping_rate", "livemode": false, "createdAt": "2026-11-03T10:00:00.000Z", "active": true, "displayName": "Standard shipping", "type": "fixed_amount", "fixedAmount": { "amount": 495, "currency": "EUR" }, "deliveryEstimate": { "minimum": { "unit": "business_day", "value": 2 }, "maximum": { "unit": "business_day", "value": 4 } }, "metadata": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/shipping-rates/{id}": { "get": { "operationId": "retrieveShippingRate", "summary": "Retrieve a shipping rate", "description": "Retrieve a shipping rate. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Catalog" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRate" }, "examples": { "default": { "value": { "id": "shr_0a1b2c3d4e5f60718293a4b5", "object": "shipping_rate", "livemode": false, "createdAt": "2026-11-03T10:00:00.000Z", "active": true, "displayName": "Standard shipping", "type": "fixed_amount", "fixedAmount": { "amount": 495, "currency": "EUR" }, "deliveryEstimate": { "minimum": { "unit": "business_day", "value": 2 }, "maximum": { "unit": "business_day", "value": 4 } }, "metadata": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "patch": { "operationId": "updateShippingRate", "summary": "Update a shipping rate's active flag or metadata (the amount is fixed; there is no delete)", "description": "Update a shipping rate's active flag or metadata (the amount is fixed; there is no delete). Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Catalog" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRateUpdateRequest" }, "examples": { "default": { "value": { "active": false } } } } } }, "responses": { "200": { "description": "The updated shipping rate", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRate" }, "examples": { "default": { "value": { "id": "shr_0a1b2c3d4e5f60718293a4b5", "object": "shipping_rate", "livemode": false, "createdAt": "2026-11-03T10:00:00.000Z", "active": true, "displayName": "Standard shipping", "type": "fixed_amount", "fixedAmount": { "amount": 495, "currency": "EUR" }, "deliveryEstimate": { "minimum": { "unit": "business_day", "value": 2 }, "maximum": { "unit": "business_day", "value": 4 } }, "metadata": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/payment-links": { "get": { "operationId": "listPaymentLink", "summary": "List payment links", "description": "List payment links. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Payment Links" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return records after this id (newest first).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return records before this id.", "schema": { "type": "string" } }, { "name": "active", "in": "query", "description": "Only active (`true`) or archived (`false`) objects.", "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLink" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "post": { "operationId": "createPaymentLink", "summary": "Create payment link", "description": "Create payment link. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Payment Links" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkCreateRequest" }, "examples": { "default": { "value": { "lineItems": [ { "priceId": "price_demo_1001", "quantity": 1 } ], "allowPromotionCodes": true } } } } } }, "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" }, "examples": { "default": { "value": { "id": "plink_demo_1001", "url": "https://pay.zahlo.eu/plink_demo_1001", "active": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/payment-links/{id}": { "get": { "operationId": "retrievePaymentLink", "summary": "Retrieve a payment link", "description": "Retrieve a payment link. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Payment Links" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" }, "examples": { "default": { "value": { "id": "plink_demo_1001", "url": "https://pay.zahlo.eu/plink_demo_1001", "active": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "patch": { "operationId": "updatePaymentLink", "summary": "Update a payment link", "description": "Update a payment link. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Payment Links" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLinkCreateRequest" }, "examples": { "default": { "value": { "lineItems": [ { "priceId": "price_demo_1001", "quantity": 1 } ], "allowPromotionCodes": true } } } } } }, "responses": { "200": { "description": "Resource updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" }, "examples": { "default": { "value": { "id": "plink_demo_1001", "url": "https://pay.zahlo.eu/plink_demo_1001", "active": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/payment-links/{id}/deactivate": { "post": { "operationId": "deactivatePaymentLink", "summary": "Deactivate a payment link", "description": "Deactivate a payment link. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Payment Links" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" }, "examples": { "default": { "value": { "id": "plink_demo_1001", "url": "https://pay.zahlo.eu/plink_demo_1001", "active": true } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/subscriptions": { "get": { "operationId": "listSubscription", "summary": "List subscriptions", "description": "List subscriptions. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Subscriptions" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Number of objects to return, 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return objects after this id (next page).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return objects before this id (previous page).", "schema": { "type": "string" } }, { "name": "customerId", "in": "query", "description": "Only this customer's subscriptions.", "schema": { "type": "string" } }, { "name": "priceId", "in": "query", "description": "Only subscriptions on this price.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Only subscriptions in this status.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of subscriptions", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Subscription" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "post": { "operationId": "createSubscription", "summary": "Create a subscription for a customer with a saved payment method", "description": "Create a subscription for a customer with a saved payment method. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Subscriptions" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCreateRequest" }, "examples": { "default": { "value": { "customerId": "cus_0a1b2c3d4e5f60718293a4b5", "priceId": "price_0a1b2c3d4e5f60718293a4b5", "trialDays": 14 } } } } } }, "responses": { "200": { "description": "The subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "examples": { "default": { "value": { "id": "sub_0a1b2c3d4e5f60718293a4b5", "object": "subscription", "livemode": false, "createdAt": "2026-10-29T10:00:00.000Z", "customerId": "cus_0a1b2c3d4e5f60718293a4b5", "priceId": "price_0a1b2c3d4e5f60718293a4b5", "quantity": 1, "status": "trialing", "currency": "EUR", "amountMinor": 1200, "couponId": null, "discountEndsAt": null, "paymentMethodId": "pm_0a1b2c3d4e5f60718293a4b5", "rail": "card", "trialEnd": "2026-11-12T10:00:00.000Z", "currentPeriodStart": "2026-10-29T10:00:00.000Z", "currentPeriodEnd": "2026-11-12T10:00:00.000Z", "cancelAtPeriodEnd": false, "cancelledAt": null, "cancellationReason": null, "pastDueSince": null, "latestPaymentId": null, "pendingUpdate": null, "prorationMinor": 0, "addOns": [], "metadata": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/subscriptions/{id}": { "get": { "operationId": "retrieveSubscription", "summary": "Retrieve a subscription", "description": "Retrieve a subscription. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Subscriptions" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "examples": { "default": { "value": { "id": "sub_0a1b2c3d4e5f60718293a4b5", "object": "subscription", "livemode": false, "createdAt": "2026-10-29T10:00:00.000Z", "customerId": "cus_0a1b2c3d4e5f60718293a4b5", "priceId": "price_0a1b2c3d4e5f60718293a4b5", "quantity": 1, "status": "trialing", "currency": "EUR", "amountMinor": 1200, "couponId": null, "discountEndsAt": null, "paymentMethodId": "pm_0a1b2c3d4e5f60718293a4b5", "rail": "card", "trialEnd": "2026-11-12T10:00:00.000Z", "currentPeriodStart": "2026-10-29T10:00:00.000Z", "currentPeriodEnd": "2026-11-12T10:00:00.000Z", "cancelAtPeriodEnd": false, "cancelledAt": null, "cancellationReason": null, "pastDueSince": null, "latestPaymentId": null, "pendingUpdate": null, "prorationMinor": 0, "addOns": [], "metadata": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "patch": { "operationId": "updateSubscription", "summary": "Update a subscription (upgrades now with proration, downgrades and interval switches at the period end)", "description": "Update a subscription (upgrades now with proration, downgrades and interval switches at the period end). Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Subscriptions" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionUpdateRequest" }, "examples": { "default": { "value": { "quantity": 3 } } } } } }, "responses": { "200": { "description": "The updated subscription", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "examples": { "default": { "value": { "id": "sub_0a1b2c3d4e5f60718293a4b5", "object": "subscription", "livemode": false, "createdAt": "2026-10-29T10:00:00.000Z", "customerId": "cus_0a1b2c3d4e5f60718293a4b5", "priceId": "price_0a1b2c3d4e5f60718293a4b5", "quantity": 1, "status": "trialing", "currency": "EUR", "amountMinor": 1200, "couponId": null, "discountEndsAt": null, "paymentMethodId": "pm_0a1b2c3d4e5f60718293a4b5", "rail": "card", "trialEnd": "2026-11-12T10:00:00.000Z", "currentPeriodStart": "2026-10-29T10:00:00.000Z", "currentPeriodEnd": "2026-11-12T10:00:00.000Z", "cancelAtPeriodEnd": false, "cancelledAt": null, "cancellationReason": null, "pastDueSince": null, "latestPaymentId": null, "pendingUpdate": null, "prorationMinor": 0, "addOns": [], "metadata": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/subscriptions/{id}/cancel": { "post": { "operationId": "cancelSubscription", "summary": "Cancel a subscription", "description": "Cancel a subscription. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Subscriptions" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionCancelRequest" }, "examples": { "default": { "value": { "atPeriodEnd": true } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "examples": { "default": { "value": { "id": "sub_0a1b2c3d4e5f60718293a4b5", "object": "subscription", "livemode": false, "createdAt": "2026-10-29T10:00:00.000Z", "customerId": "cus_0a1b2c3d4e5f60718293a4b5", "priceId": "price_0a1b2c3d4e5f60718293a4b5", "quantity": 1, "status": "trialing", "currency": "EUR", "amountMinor": 1200, "couponId": null, "discountEndsAt": null, "paymentMethodId": "pm_0a1b2c3d4e5f60718293a4b5", "rail": "card", "trialEnd": "2026-11-12T10:00:00.000Z", "currentPeriodStart": "2026-10-29T10:00:00.000Z", "currentPeriodEnd": "2026-11-12T10:00:00.000Z", "cancelAtPeriodEnd": false, "cancelledAt": null, "cancellationReason": null, "pastDueSince": null, "latestPaymentId": null, "pendingUpdate": null, "prorationMinor": 0, "addOns": [], "metadata": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/subscriptions/{id}/pause": { "post": { "operationId": "pauseSubscription", "summary": "Pause a subscription", "description": "Pause a subscription. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Subscriptions" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "examples": { "default": { "value": { "id": "sub_0a1b2c3d4e5f60718293a4b5", "object": "subscription", "livemode": false, "createdAt": "2026-10-29T10:00:00.000Z", "customerId": "cus_0a1b2c3d4e5f60718293a4b5", "priceId": "price_0a1b2c3d4e5f60718293a4b5", "quantity": 1, "status": "trialing", "currency": "EUR", "amountMinor": 1200, "couponId": null, "discountEndsAt": null, "paymentMethodId": "pm_0a1b2c3d4e5f60718293a4b5", "rail": "card", "trialEnd": "2026-11-12T10:00:00.000Z", "currentPeriodStart": "2026-10-29T10:00:00.000Z", "currentPeriodEnd": "2026-11-12T10:00:00.000Z", "cancelAtPeriodEnd": false, "cancelledAt": null, "cancellationReason": null, "pastDueSince": null, "latestPaymentId": null, "pendingUpdate": null, "prorationMinor": 0, "addOns": [], "metadata": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/subscriptions/{id}/resume": { "post": { "operationId": "resumeSubscription", "summary": "Resume a paused subscription or withdraw a cancel at period end", "description": "Resume a paused subscription or withdraw a cancel at period end. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Subscriptions" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "examples": { "default": { "value": { "id": "sub_0a1b2c3d4e5f60718293a4b5", "object": "subscription", "livemode": false, "createdAt": "2026-10-29T10:00:00.000Z", "customerId": "cus_0a1b2c3d4e5f60718293a4b5", "priceId": "price_0a1b2c3d4e5f60718293a4b5", "quantity": 1, "status": "trialing", "currency": "EUR", "amountMinor": 1200, "couponId": null, "discountEndsAt": null, "paymentMethodId": "pm_0a1b2c3d4e5f60718293a4b5", "rail": "card", "trialEnd": "2026-11-12T10:00:00.000Z", "currentPeriodStart": "2026-10-29T10:00:00.000Z", "currentPeriodEnd": "2026-11-12T10:00:00.000Z", "cancelAtPeriodEnd": false, "cancelledAt": null, "cancellationReason": null, "pastDueSince": null, "latestPaymentId": null, "pendingUpdate": null, "prorationMinor": 0, "addOns": [], "metadata": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/subscriptions/{id}/usage-records": { "post": { "operationId": "createUsageRecord", "summary": "Report usage of a metered add-on", "description": "Usage is billed in arrears: the charge that starts the next period adds the usage of the period it occurred in. amount_exceeds_subscription_limit when unbilled usage would take that charge over the per-charge cap; 409 state_conflict on a cancelled subscription or one ending at the period end.", "tags": [ "Subscriptions" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageRecordCreateRequest" }, "examples": { "default": { "value": { "quantity": 1200 } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsageRecord" }, "examples": { "default": { "value": { "id": "ur_0a1b2c3d4e5f60718293a4b5", "object": "usage_record", "livemode": false, "createdAt": "2026-11-01T10:00:00.000Z", "subscriptionId": "sub_0a1b2c3d4e5f60718293a4b5", "priceId": "price_0a1b2c3d4e5f60718293a4b6", "quantity": 1200, "occurredAt": "2026-11-01T10:00:00.000Z", "billed": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/test-helpers/subscriptions/{id}/advance": { "post": { "operationId": "advanceTestSubscription", "summary": "Sandbox only: advance a subscription to its next billing event", "description": "Moves the subscription's own dates like a test clock and feeds a synthetic outcome to the real billing handlers, so the real subscription events and customer notices follow. Nothing is charged and no Payment is written. 404 resource_not_available outside the sandbox.", "tags": [ "Subscriptions" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubscriptionAdvanceRequest" }, "examples": { "default": { "value": { "to": "renewal_failed" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Subscription" }, "examples": { "default": { "value": { "id": "sub_0a1b2c3d4e5f60718293a4b5", "object": "subscription", "livemode": false, "createdAt": "2026-10-29T10:00:00.000Z", "customerId": "cus_0a1b2c3d4e5f60718293a4b5", "priceId": "price_0a1b2c3d4e5f60718293a4b5", "quantity": 1, "status": "trialing", "currency": "EUR", "amountMinor": 1200, "couponId": null, "discountEndsAt": null, "paymentMethodId": "pm_0a1b2c3d4e5f60718293a4b5", "rail": "card", "trialEnd": "2026-11-12T10:00:00.000Z", "currentPeriodStart": "2026-10-29T10:00:00.000Z", "currentPeriodEnd": "2026-11-12T10:00:00.000Z", "cancelAtPeriodEnd": false, "cancelledAt": null, "cancellationReason": null, "pastDueSince": null, "latestPaymentId": null, "pendingUpdate": null, "prorationMinor": 0, "addOns": [], "metadata": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/invoices": { "get": { "operationId": "listInvoice", "summary": "List invoices", "description": "One invoice per paid payment, newest first. While no invoice VAT rate is set in the dashboard (Settings → Customer emails and portal), the documents are receipts (`kind: \"receipt\"`, `tax: null`).", "tags": [ "Billing" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Number of objects to return, 1–100.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return objects after this id (next page).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return objects before this id (previous page).", "schema": { "type": "string" } }, { "name": "customerId", "in": "query", "description": "Only this customer's invoices.", "schema": { "type": "string" } }, { "name": "subscriptionId", "in": "query", "description": "Only this subscription's invoices.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A list of invoices", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/invoices/{id}": { "get": { "operationId": "retrieveInvoice", "summary": "Retrieve an invoice", "description": "Retrieve an invoice. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Billing" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" }, "examples": { "default": { "value": { "id": "rcpt_0a1b2c3d4e5f60718293a4b5", "object": "invoice", "livemode": false, "createdAt": "2026-11-01T00:05:00.000Z", "kind": "invoice", "status": "paid", "number": "ACME-000042", "customerId": "cus_0a1b2c3d4e5f60718293a4b5", "subscriptionId": "cmh0a1b2c3d4e5f6g7h8i9j0", "paymentId": "cmh1a2b3c4d5e6f7g8h9i0j1", "currency": "EUR", "amountSubtotalMinor": 1190, "amountDiscountMinor": 0, "amountPaidMinor": 1190, "tax": { "rateBps": 1900, "netMinor": 1000, "taxMinor": 190 }, "customerTaxIds": [ "DE987654321" ], "lines": [ { "name": "Pro plan", "quantity": 1, "unitAmountMinor": 1190, "amountMinor": 1190 } ], "periodStart": "2026-11-01T00:00:00.000Z", "periodEnd": "2026-12-01T00:00:00.000Z", "paidAt": "2026-11-01T00:04:58.000Z", "hostedInvoiceUrl": "https://merchant.zahlo.eu/receipts/9Qm0nE2lZb7hH8yNw0d3v1Y1t5cFZ0qUXc6m3k2sV2A", "invoicePdfUrl": "https://merchant.zahlo.eu/receipts/9Qm0nE2lZb7hH8yNw0d3v1Y1t5cFZ0qUXc6m3k2sV2A?format=pdf" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/customer-portal/configuration": { "get": { "operationId": "retrieveCustomerPortalConfiguration", "summary": "Retrieve the customer portal configuration", "description": "Returns your no-code portal link. Put it on your site or in emails: a customer enters their email address there and gets a single-use portal link by email, with no code on your side.", "tags": [ "Billing" ], "security": [ { "merchantApiKey": [] } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPortalConfiguration" }, "examples": { "default": { "value": { "object": "customer_portal_configuration", "noCodePortalUrl": "https://merchant.zahlo.eu/billing-portal/m/cmh0a1b2c3d4e5f6g7h8i9j0" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/customer-portal/sessions": { "post": { "operationId": "createCustomerPortalSession", "summary": "Create a customer self-service portal session", "description": "Returns a single-use URL valid for one hour. Open it in the customer's browser; it shows their subscriptions, payment history and receipts, and lets them cancel, update the card or pay what is outstanding as your portal settings allow.", "tags": [ "Billing" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPortalSessionRequest" }, "examples": { "default": { "value": { "customerId": "cus_demo_1001", "returnUrl": "https://app.example.com/settings/billing" } } } } } }, "responses": { "200": { "description": "Portal session created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CustomerPortalSession" }, "examples": { "default": { "value": { "id": "bps_0a1b2c3d4e5f60718293a4b5", "object": "billing_portal_session", "livemode": false, "createdAt": "2026-10-29T12:30:00.000Z", "customerId": "cus_demo_1001", "url": "https://merchant.zahlo.eu/billing-portal/9Qm0nE2lZb7hH8yNw0d3v1Y1t5cFZ0qUXc6m3k2sV2A", "returnUrl": "https://app.example.com/settings/billing", "expiresAt": "2026-10-29T13:30:00.000Z" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/webhook-endpoints": { "get": { "operationId": "listWebhookEndpoint", "summary": "List webhook endpoints", "description": "List webhook endpoints. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Webhooks" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return records after this id (newest first).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return records before this id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookEndpoint" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "post": { "operationId": "createWebhookEndpoint", "summary": "Create webhook endpoint", "description": "Create webhook endpoint. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Webhooks" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreateRequest" }, "examples": { "default": { "value": { "url": "https://store.example/api/zahlo/events", "enabledEvents": [ "payment.confirmed", "refund.succeeded" ], "description": "Order fulfilment" } } } } } }, "responses": { "201": { "description": "Resource created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "examples": { "default": { "value": { "id": "cm_webhook_1001", "object": "webhook_endpoint", "livemode": false, "createdAt": "2026-10-30T12:00:00Z", "url": "https://store.example/api/zahlo/events", "enabledEvents": [ "payment.confirmed", "refund.succeeded" ], "status": "enabled", "description": null, "metadata": { "team": "fulfilment" }, "failingSince": null, "disabledReason": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/webhook-endpoints/{id}": { "get": { "operationId": "retrieveWebhookEndpoint", "summary": "Retrieve a webhook endpoint", "description": "Retrieve a webhook endpoint. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Webhooks" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "examples": { "default": { "value": { "id": "cm_webhook_1001", "object": "webhook_endpoint", "livemode": false, "createdAt": "2026-10-30T12:00:00Z", "url": "https://store.example/api/zahlo/events", "enabledEvents": [ "payment.confirmed", "refund.succeeded" ], "status": "enabled", "description": null, "metadata": { "team": "fulfilment" }, "failingSince": null, "disabledReason": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "patch": { "operationId": "updateWebhookEndpoint", "summary": "Update a webhook endpoint", "description": "Update a webhook endpoint. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Webhooks" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpointCreateRequest" }, "examples": { "default": { "value": { "url": "https://store.example/api/zahlo/events", "enabledEvents": [ "payment.confirmed", "refund.succeeded" ], "description": "Order fulfilment" } } } } } }, "responses": { "200": { "description": "Resource updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "examples": { "default": { "value": { "id": "cm_webhook_1001", "object": "webhook_endpoint", "livemode": false, "createdAt": "2026-10-30T12:00:00Z", "url": "https://store.example/api/zahlo/events", "enabledEvents": [ "payment.confirmed", "refund.succeeded" ], "status": "enabled", "description": null, "metadata": { "team": "fulfilment" }, "failingSince": null, "disabledReason": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } }, "delete": { "operationId": "deleteWebhookEndpoint", "summary": "Delete a webhook endpoint", "description": "Delete a webhook endpoint. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Webhooks" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "204": { "description": "Resource deleted" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/webhook-endpoints/{id}/rotate-secret": { "post": { "operationId": "rotateWebhookEndpointSecret", "summary": "Rotate a webhook endpoint's signing secret", "description": "Rotate a webhook endpoint's signing secret. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Webhooks" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The endpoint with its new secret (shown once)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" }, "examples": { "default": { "value": { "id": "cm_webhook_1001", "object": "webhook_endpoint", "livemode": false, "createdAt": "2026-10-30T12:00:00Z", "url": "https://store.example/api/zahlo/events", "enabledEvents": [ "payment.confirmed", "refund.succeeded" ], "status": "enabled", "description": null, "metadata": { "team": "fulfilment" }, "failingSince": null, "disabledReason": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/webhook-endpoints/{id}/test": { "post": { "operationId": "sendWebhookTestEvent", "summary": "Send a test event to an endpoint", "description": "Send a test event to an endpoint. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Webhooks" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestRequest" }, "examples": { "default": { "value": { "type": "payment.confirmed" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookTestResult" }, "examples": { "default": { "value": { "eventId": "evt_test_1001", "ok": true, "responseStatus": 200, "error": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/webhook-endpoints/{id}/deliveries": { "get": { "operationId": "listWebhookDeliveries", "summary": "List an endpoint's deliveries", "description": "List an endpoint's deliveries. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Webhooks" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return records after this id (newest first).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return records before this id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDelivery" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/webhook-endpoints/{id}/deliveries/{deliveryId}/attempts": { "get": { "operationId": "listWebhookDeliveryAttempts", "summary": "List a delivery's attempts", "description": "List a delivery's attempts. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Webhooks" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } }, { "name": "deliveryId", "in": "path", "required": true, "description": "The delivery identifier from the deliveries list.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return records after this id (newest first).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return records before this id.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Every counted send, newest first", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/WebhookDeliveryAttempt" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/webhook-endpoints/{id}/deliveries/{deliveryId}/retry": { "post": { "operationId": "retryWebhookDelivery", "summary": "Retry a webhook delivery", "description": "Retry a webhook delivery. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Webhooks" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } }, { "name": "deliveryId", "in": "path", "required": true, "description": "The delivery identifier from the deliveries list.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "responses": { "200": { "description": "The delivery, queued for one more attempt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" }, "examples": { "default": { "value": { "id": "cm_delivery_1001", "object": "webhook_delivery", "livemode": false, "createdAt": "2026-10-30T12:00:00Z", "endpointId": "cm_webhook_1001", "eventId": "evt_1001", "eventType": "payment.confirmed", "status": "succeeded", "attempts": 1, "lastAttemptAt": "2026-10-30T12:00:01Z", "lastResponseStatus": 200, "lastResponseBody": "ok", "lastError": null, "nextAttemptAt": null } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/events": { "get": { "operationId": "listEvents", "summary": "List events (kept 30 days)", "description": "List events (kept 30 days). Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Webhooks" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of records to return.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "startingAfter", "in": "query", "description": "Return records after this id (newest first).", "schema": { "type": "string" } }, { "name": "endingBefore", "in": "query", "description": "Return records before this id.", "schema": { "type": "string" } }, { "name": "type", "in": "query", "description": "Only events of this catalog type.", "schema": { "type": "string" } }, { "name": "createdGte", "in": "query", "description": "Only events created at or after this time.", "schema": { "type": "string", "format": "date-time" } }, { "name": "createdLte", "in": "query", "description": "Only events created at or before this time.", "schema": { "type": "string", "format": "date-time" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "required": [ "object", "data", "hasMore" ], "properties": { "object": { "type": "string", "enum": [ "list" ] }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } }, "hasMore": { "type": "boolean" } } }, "examples": { "default": { "value": { "object": "list", "data": [], "hasMore": false } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/events/{id}": { "get": { "operationId": "retrieveEvent", "summary": "Retrieve an event", "description": "Retrieve an event. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Webhooks" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" }, "examples": { "default": { "value": { "id": "evt_1001", "object": "event", "type": "payment.confirmed", "livemode": false, "createdAt": "2026-10-30T12:00:00Z", "data": { "object": { "id": "pay_1001", "object": "payment" } } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/events/{id}/resend": { "post": { "operationId": "resendEvent", "summary": "Resend an event to an endpoint", "description": "Resend an event to an endpoint. Use the response status and request ID to decide whether to retry, reconcile, or ask the customer for action.", "tags": [ "Webhooks" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } }, { "$ref": "#/components/parameters/IdempotencyKey" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EventResendRequest" }, "examples": { "default": { "value": { "endpointId": "cm_webhook_1001" } } } } } }, "responses": { "200": { "description": "The endpoint's delivery of this event after one immediate attempt", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookDelivery" }, "examples": { "default": { "value": { "data": [] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/test-helpers/payments/{id}/outcome": { "post": { "operationId": "settleTestPayment", "summary": "Sandbox only: settle a pending payment", "description": "Marks a pending payment paid or declined, so payment.confirmed or payment.failed and checkout.session.completed follow without a browser. Do not also finish the payment on the hosted page. The provider never sees this outcome; the real handlers apply it, so the real events follow. 404 resource_not_available outside the sandbox; 409 state_conflict when the object is past this step.", "tags": [ "Payments" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestOutcomeRequest" }, "examples": { "default": { "value": { "outcome": "failed" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Transaction" }, "examples": { "default": { "value": { "data": [] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/test-helpers/refunds/{id}/outcome": { "post": { "operationId": "settleTestRefund", "summary": "Sandbox only: settle a pending refund", "description": "Settles a pending refund as succeeded or failed; refund.succeeded or refund.failed follows. The provider never sees this outcome; the real handlers apply it, so the real events follow. 404 resource_not_available outside the sandbox; 409 state_conflict when the object is past this step.", "tags": [ "Payments" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestOutcomeRequest" }, "examples": { "default": { "value": { "outcome": "failed" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" }, "examples": { "default": { "value": { "id": "re_demo_1001", "object": "refund", "livemode": false, "createdAt": "2026-08-01T10:00:00.000Z", "paymentId": "pay_demo_1001", "amountMinor": 4990, "currency": "EUR", "status": "succeeded", "reason": "requested_by_customer", "metadata": { "orderId": "order_1001" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } }, "/api/v1/test-helpers/payments/{id}/dispute": { "post": { "operationId": "disputeTestPayment", "summary": "Sandbox only: open or move a dispute on a paid payment", "description": "The first call opens one synthetic chargeback (dispute.created); later calls move it (dispute.updated, or dispute.closed for won and lost). Responding to it with evidence is not simulated. The provider never sees this outcome; the real handlers apply it, so the real events follow. 404 resource_not_available outside the sandbox; 409 state_conflict when the object is past this step.", "tags": [ "Payments" ], "security": [ { "merchantApiKey": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "description": "The resource identifier returned by the merchant API.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TestDisputeRequest" }, "examples": { "default": { "value": { "status": "needs_response" } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dispute" }, "examples": { "default": { "value": { "id": "PSP-DEMO-1001", "paymentId": "pay_demo_1001", "status": "needs_response", "amount": { "amountMinor": 4990, "currency": "EUR" }, "reason": "Goods not received", "evidenceDueAt": "2026-08-05T00:00:00" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" } } } } }, "components": { "securitySchemes": { "merchantApiKey": { "type": "apiKey", "in": "header", "name": "x-api-key", "description": "Server-side merchant API key. Never expose it in browser code." }, "clientToken": { "type": "http", "scheme": "bearer", "description": "Short-lived checkout client token for browser session access." } }, "parameters": { "IdempotencyKey": { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string" }, "description": "Retry-safe key for create operations." } }, "responses": { "BadRequest": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "default": { "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "amountMinor: must be positive", "param": "amountMinor", "docUrl": "https://docs.zahlo.eu/operations/errors#parameter_invalid" }, "requestId": "req_demo_1001" } } } } } }, "Unauthorized": { "description": "Authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "default": { "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "amountMinor: must be positive", "param": "amountMinor", "docUrl": "https://docs.zahlo.eu/operations/errors#parameter_invalid" }, "requestId": "req_demo_1001" } } } } } }, "NotFound": { "description": "Resource not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "default": { "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "amountMinor: must be positive", "param": "amountMinor", "docUrl": "https://docs.zahlo.eu/operations/errors#parameter_invalid" }, "requestId": "req_demo_1001" } } } } } }, "Conflict": { "description": "Request conflicts with existing state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "examples": { "default": { "value": { "error": { "type": "invalid_request_error", "code": "parameter_invalid", "message": "amountMinor: must be positive", "param": "amountMinor", "docUrl": "https://docs.zahlo.eu/operations/errors#parameter_invalid" }, "requestId": "req_demo_1001" } } } } } } }, "schemas": { "Error": { "type": "object", "required": [ "error", "requestId" ], "properties": { "error": { "type": "object", "required": [ "type", "code", "message", "docUrl" ], "properties": { "type": { "type": "string" }, "code": { "type": "string" }, "message": { "type": "string" }, "param": { "type": "string" }, "docUrl": { "type": "string", "format": "uri" } } }, "requestId": { "type": "string" } } }, "Money": { "type": "object", "required": [ "amountMinor", "currency" ], "properties": { "amountMinor": { "type": "integer", "minimum": 0, "description": "Amount in the smallest currency unit" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR" } } }, "PaymentStatus": { "type": "string", "enum": [ "created", "pending", "confirmed", "partially_refunded", "refunded", "cancelled", "expired" ] }, "Payment": { "type": "object", "description": "A payment attempt from a checkout session, payment link or subscription period; the same object the payment.* events carry. Its id is also the checkout session id.", "required": [ "id", "object", "livemode", "createdAt", "status", "amountMinor", "amountRefundedMinor", "refunded", "currency", "metadata", "disputed" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "payment" ] }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed", "cancelled" ] }, "amountMinor": { "type": "integer" }, "amountRefundedMinor": { "type": "integer" }, "refunded": { "type": "boolean" }, "currency": { "type": "string" }, "paymentMethod": { "type": "object", "nullable": true, "properties": { "type": { "type": "string" } } }, "outcome": { "type": "object", "properties": { "threeDSecure": { "type": "string", "nullable": true }, "riskLevel": { "type": "string", "nullable": true }, "providerReason": { "type": "string", "nullable": true } } }, "customerId": { "type": "string", "nullable": true }, "subscriptionId": { "type": "string", "nullable": true }, "checkoutSessionId": { "type": "string", "nullable": true }, "paymentLinkId": { "type": "string", "nullable": true }, "receiptNumber": { "type": "string", "nullable": true }, "receiptUrl": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } }, "disputed": { "type": "boolean" } } }, "PaymentCreateRequest": { "type": "object", "required": [ "amountMinor", "currency" ], "properties": { "amountMinor": { "type": "integer", "minimum": 1, "description": "Amount in the smallest currency unit" }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "default": "EUR" }, "paymentMethodTypes": { "type": "array", "items": { "type": "string", "enum": [ "card", "apple_pay", "google_pay" ] }, "description": "Eligible method families to consider" }, "reference": { "type": "string" }, "description": { "type": "string" }, "customerEmail": { "type": "string", "format": "email" }, "redirectUrl": { "type": "string", "format": "uri" }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "PaymentList": { "type": "object", "required": [ "data", "hasMore" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } }, "hasMore": { "type": "boolean" }, "nextOffset": { "type": "integer" } } }, "CustomFieldDefinition": { "type": "object", "additionalProperties": false, "required": [ "key", "label", "type" ], "description": "A question Zahlo's page asks before payment (Stripe `custom_fields`). `dropdown` is required for type dropdown; `text` is optional for type text.", "properties": { "key": { "type": "string", "maxLength": 200, "pattern": "^[A-Za-z0-9]+$", "description": "Unique within the list." }, "label": { "type": "object", "additionalProperties": false, "required": [ "type", "custom" ], "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "string", "minLength": 1, "maxLength": 100 } } }, "type": { "type": "string", "enum": [ "dropdown", "text" ] }, "optional": { "type": "boolean", "default": false }, "dropdown": { "type": "object", "additionalProperties": false, "required": [ "options" ], "properties": { "options": { "type": "array", "minItems": 1, "maxItems": 200, "items": { "type": "object", "additionalProperties": false, "required": [ "label", "value" ], "properties": { "label": { "type": "string", "minLength": 1, "maxLength": 100 }, "value": { "type": "string", "maxLength": 100, "pattern": "^[A-Za-z0-9]+$", "description": "Unique within the options." } } } }, "defaultValue": { "type": "string", "description": "One of the option values." } } }, "text": { "type": "object", "additionalProperties": false, "properties": { "minimumLength": { "type": "integer", "minimum": 0, "maximum": 255 }, "maximumLength": { "type": "integer", "minimum": 1, "maximum": 255 }, "defaultValue": { "type": "string", "maxLength": 255 } } } } }, "CustomField": { "type": "object", "required": [ "key", "label", "type", "optional", "dropdown", "text" ], "description": "A custom field with the payer's answer in `dropdown.value` or `text.value` (null until given).", "properties": { "key": { "type": "string" }, "label": { "type": "object", "required": [ "type", "custom" ], "properties": { "type": { "type": "string", "enum": [ "custom" ] }, "custom": { "type": "string" } } }, "type": { "type": "string", "enum": [ "dropdown", "text" ] }, "optional": { "type": "boolean" }, "dropdown": { "type": "object", "nullable": true, "required": [ "options", "defaultValue", "value" ], "properties": { "options": { "type": "array", "items": { "type": "object", "required": [ "label", "value" ], "properties": { "label": { "type": "string" }, "value": { "type": "string" } } } }, "defaultValue": { "type": "string", "nullable": true }, "value": { "type": "string", "nullable": true } } }, "text": { "type": "object", "nullable": true, "required": [ "minimumLength", "maximumLength", "defaultValue", "value" ], "properties": { "minimumLength": { "type": "integer", "nullable": true }, "maximumLength": { "type": "integer", "nullable": true }, "defaultValue": { "type": "string", "nullable": true }, "value": { "type": "string", "nullable": true } } } } }, "PaymentMethod": { "type": "object", "required": [ "id", "name", "description" ], "properties": { "id": { "type": "string", "enum": [ "card", "sepa_direct_debit", "klarna", "ideal", "bancontact", "apple_pay", "google_pay" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "brands": { "type": "array", "items": { "type": "string" } } } }, "PaymentMethodList": { "type": "object", "required": [ "currency", "environment", "mode", "merchantReady", "methods" ], "properties": { "currency": { "type": "string", "example": "EUR" }, "environment": { "type": "string", "enum": [ "sandbox", "production" ] }, "mode": { "type": "string", "enum": [ "hosted", "embedded" ] }, "merchantReady": { "type": "boolean" }, "methods": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentMethod" } } } }, "PaymentMethodDefaults": { "type": "object", "required": [ "paymentMethodTypes" ], "properties": { "paymentMethodTypes": { "type": "array", "items": { "type": "string", "enum": [ "card", "sepa_direct_debit", "klarna", "ideal", "bancontact", "apple_pay", "google_pay", "paypal" ] } } } }, "CheckoutSessionStatus": { "type": "string", "enum": [ "open", "complete", "expired", "failed" ] }, "CheckoutSession": { "type": "object", "required": [ "id", "object", "type", "mode", "status", "paymentStatus", "expiresAt", "currency", "amountTotal", "lineItems" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "checkout_session" ] }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "type": { "type": "string", "enum": [ "payment", "setup", "subscription" ] }, "mode": { "type": "string", "enum": [ "hosted", "embedded" ] }, "status": { "$ref": "#/components/schemas/CheckoutSessionStatus" }, "paymentStatus": { "type": "string", "enum": [ "unpaid", "paid", "no_payment_required" ] }, "url": { "type": "string", "format": "uri", "nullable": true, "description": "Hosted only, while open: redirect the customer here." }, "clientToken": { "type": "string", "nullable": true, "description": "Embedded only, while open: pass it to the browser SDK." }, "detailsRequired": { "type": "boolean", "description": "Embedded only: true until the payer completed Zahlo's details step (the browser SDK mounts it first); embedUrl is null meanwhile." }, "embedUrl": { "type": "string", "format": "uri", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time" }, "currency": { "type": "string" }, "amountSubtotal": { "type": "integer" }, "amountDiscount": { "type": "integer" }, "amountShipping": { "type": "integer", "description": "The chosen shipping option, inside amountTotal; 0 without one." }, "amountTotal": { "type": "integer" }, "shippingOptions": { "type": "array", "description": "The offered shipping rates with their amount at session create, in order.", "items": { "type": "object", "required": [ "shippingRate", "shippingAmount" ], "properties": { "shippingRate": { "type": "string" }, "shippingAmount": { "type": "integer" } } } }, "shippingCost": { "type": "object", "nullable": true, "description": "The chosen shipping option. amountTax is 0: VAT is inside the amount. Discounts never apply to shipping.", "required": [ "amountSubtotal", "amountTax", "amountTotal", "shippingRate" ], "properties": { "amountSubtotal": { "type": "integer" }, "amountTax": { "type": "integer" }, "amountTotal": { "type": "integer" }, "shippingRate": { "type": "string" } } }, "lineItems": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "quantity": { "type": "integer" }, "unitAmountMinor": { "type": "integer" }, "amountMinor": { "type": "integer" }, "priceId": { "type": "string", "nullable": true }, "adjustableQuantity": { "type": "object", "description": "Present when the payer may change this line's quantity.", "properties": { "enabled": { "type": "boolean" }, "minimum": { "type": "integer" }, "maximum": { "type": "integer" } } } } } }, "customerId": { "type": "string", "nullable": true }, "setupFutureUsage": { "type": "string", "enum": [ "off_session" ], "nullable": true, "description": "Set when the session saves the card for off-session charges." }, "customerEmail": { "type": "string", "nullable": true }, "couponId": { "type": "string", "nullable": true }, "paymentId": { "type": "string", "nullable": true }, "subscriptionId": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "customFields": { "type": "array", "items": { "$ref": "#/components/schemas/CustomField" }, "description": "The session's custom fields with the payer's answers; empty when it asks none." }, "phoneNumberCollection": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } }, "description": "The details page asks for a phone number." }, "nameCollection": { "type": "object", "required": [ "individual", "business" ], "properties": { "individual": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } }, "business": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } } }, "description": "The details page asks for a full name and/or a business name." }, "consentCollection": { "type": "object", "required": [ "promotions", "termsOfService" ], "properties": { "promotions": { "type": "string", "enum": [ "auto", "none" ] }, "termsOfService": { "type": "string", "enum": [ "required", "none" ] } } }, "allowPromotionCodes": { "type": "boolean" }, "submitType": { "type": "string", "enum": [ "auto", "pay", "book", "donate" ] }, "brandingSettings": { "type": "object", "nullable": true, "description": "This session's branding override; null fields fall back to Account → Branding.", "properties": { "brandColor": { "type": "string", "nullable": true }, "logoUrl": { "type": "string", "nullable": true }, "displayName": { "type": "string", "nullable": true } } }, "taxIdCollection": { "type": "object", "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } }, "customerDetails": { "type": "object", "required": [ "email", "phone", "individualName", "businessName" ], "description": "What the payer entered on the details page; null until then.", "properties": { "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "individualName": { "type": "string", "nullable": true }, "businessName": { "type": "string", "nullable": true } } }, "consent": { "type": "object", "required": [ "promotions", "termsOfService" ], "properties": { "promotions": { "type": "string", "enum": [ "opt_in", "opt_out" ], "nullable": true }, "termsOfService": { "type": "string", "enum": [ "accepted" ], "nullable": true } } }, "shippingDetails": { "type": "object", "nullable": true, "description": "The shipping address the payer entered on Zahlo's page, for a payment link or a session with `shippingAddressCollection`.", "required": [ "name", "address" ], "properties": { "name": { "type": "string" }, "address": { "type": "object", "required": [ "line1", "line2", "city", "postalCode", "country" ], "properties": { "line1": { "type": "string" }, "line2": { "type": "string", "nullable": true }, "city": { "type": "string" }, "postalCode": { "type": "string" }, "country": { "type": "string", "description": "ISO 3166-1 alpha-2" } } } } }, "successUrl": { "type": "string" }, "cancelUrl": { "type": "string" }, "locale": { "type": "string" }, "paymentMethodTypes": { "type": "array", "items": { "type": "string" } }, "appearance": { "$ref": "#/components/schemas/CheckoutAppearance" }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "CheckoutSessionCreateRequest": { "type": "object", "description": "Send exactly one of lineItems or amountMinor.", "properties": { "mode": { "type": "string", "enum": [ "hosted", "embedded" ], "default": "hosted" }, "lineItems": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "oneOf": [ { "type": "object", "required": [ "priceId", "quantity" ], "properties": { "priceId": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 }, "adjustableQuantity": { "type": "object", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "minimum": { "type": "integer", "minimum": 1, "maximum": 999, "default": 1 }, "maximum": { "type": "integer", "minimum": 1, "maximum": 999, "default": 99 } }, "description": "One-time sessions: the payer may change this line's quantity on Zahlo's details page; the total and the payment link are re-made." } } }, { "type": "object", "required": [ "name", "unitAmountMinor", "quantity" ], "properties": { "name": { "type": "string" }, "unitAmountMinor": { "type": "integer", "minimum": 0 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 }, "imageUrl": { "type": "string", "format": "uri" }, "adjustableQuantity": { "type": "object", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" }, "minimum": { "type": "integer", "minimum": 1, "maximum": 999, "default": 1 }, "maximum": { "type": "integer", "minimum": 1, "maximum": 999, "default": 99 } }, "description": "One-time sessions: the payer may change this line's quantity on Zahlo's details page; the total and the payment link are re-made." } } } ] } }, "amountMinor": { "type": "integer", "minimum": 1, "description": "Simple mode: one total, no line items." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "EUR", "description": "Required with amountMinor or ad-hoc line items; defaults to the prices' currency." }, "description": { "type": "string" }, "reference": { "type": "string", "maxLength": 450 }, "customerEmail": { "type": "string", "format": "email" }, "customerId": { "type": "string", "description": "An existing customer. Required with setupFutureUsage and type setup." }, "setupFutureUsage": { "type": "string", "enum": [ "off_session" ], "description": "Save the card to customerId for later off-session charges (type payment, card only). You must have shown the customer your terms for later charges." }, "paymentMethodTypes": { "type": "array", "items": { "type": "string", "enum": [ "card", "sepa_direct_debit", "klarna", "ideal", "bancontact", "apple_pay", "google_pay", "paypal" ] }, "description": "Default: the merchant's default methods, else everything enabled for the currency." }, "method": { "type": "string", "enum": [ "card", "sepa_direct_debit", "klarna", "ideal", "bancontact", "apple_pay", "google_pay", "paypal" ], "description": "Deprecated single-method form of paymentMethodTypes." }, "locale": { "type": "string", "enum": [ "auto", "cz", "de", "en", "es", "fr", "hr", "hu", "il", "it", "kr", "lt", "pl", "ro", "ru", "tr" ] }, "expiresInSeconds": { "type": "integer", "minimum": 1800, "maximum": 86400, "default": 86400 }, "successUrl": { "type": "string", "format": "uri", "description": "May contain {CHECKOUT_SESSION_ID}; must be on a registered checkout domain." }, "failureUrl": { "type": "string", "format": "uri" }, "cancelUrl": { "type": "string", "format": "uri" }, "type": { "type": "string", "enum": [ "payment", "setup", "subscription" ], "description": "subscription: a recurring price (the first one), further recurring prices as add-ons billed with it every period, and optional one-time prices charged once with the first period (setup fees, never discounted), paymentMethodTypes [\"card\"] and customerEmail. A price with a trial charges nothing now (paymentStatus no_payment_required). setup: saves a card to customerId without charging it; no lineItems or amountMinor." }, "couponId": { "type": "string", "description": "Applies to lineItems; on a subscription it discounts the periods its duration covers." }, "promotionCode": { "type": "string", "maxLength": 64, "description": "A coupon's code as the customer typed it (case-insensitive), instead of couponId. Applies to lineItems; an unknown code is 404 resource_missing." }, "taxIdCollection": { "type": "object", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } }, "description": "Card and wallet sessions. A hosted `url` (or the embedded checkout, before `embedUrl` is given) first shows a Zahlo page that asks for the billing name, address and an optional VAT ID, then continues to payment; on a subscription the details are saved on the customer and printed on receipts." }, "phoneNumberCollection": { "type": "object", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } }, "description": "Card and wallet sessions, hosted or embedded: the details page asks for a phone number (6 to 20 digits, optional +); it comes back in `customerDetails.phone`." }, "nameCollection": { "type": "object", "additionalProperties": false, "properties": { "individual": { "type": "object", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } }, "business": { "type": "object", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } } }, "description": "Card and wallet sessions, hosted or embedded: a full name field and/or a business name field (optional next to the full name); they come back in `customerDetails`." }, "consentCollection": { "type": "object", "additionalProperties": false, "properties": { "promotions": { "type": "string", "enum": [ "auto", "none" ], "description": "`auto`: an optional marketing checkbox; the answer is `consent.promotions` (`opt_in` or `opt_out`)." }, "termsOfService": { "type": "string", "enum": [ "required", "none" ], "description": "`required`: a checkbox the payer must tick, linking the terms of service in Checkout → Store policies (400 when none is set); `consent.termsOfService` is `accepted`." } }, "description": "Card and wallet sessions, hosted or embedded." }, "allowPromotionCodes": { "type": "boolean", "description": "One-time sessions with lineItems, hosted or embedded: the details page shows a promotion code field with an Apply button and a live total; the total and the payment link are re-made. Not with promotionCode or couponId." }, "submitType": { "type": "string", "enum": [ "auto", "pay", "book", "donate" ], "description": "The details page's button label: `auto` Continue to payment, `pay`, `book` or `donate`." }, "brandingSettings": { "type": "object", "additionalProperties": false, "properties": { "brandColor": { "type": "string", "pattern": "^#[0-9a-fA-F]{6}$" }, "logoUrl": { "type": "string", "format": "uri", "description": "https only." }, "displayName": { "type": "string", "maxLength": 80 } }, "description": "Overrides Account → Branding on Zahlo pages (and `appearance`) for this session." }, "shippingAddressCollection": { "type": "object", "additionalProperties": false, "required": [ "allowedCountries" ], "properties": { "allowedCountries": { "type": "array", "minItems": 1, "maxItems": 250, "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "ISO 3166-1 alpha-2 codes the payer may ship to." } }, "description": "Card and wallet sessions, hosted or embedded. A Zahlo page (the hosted `url`, or the embedded checkout's first step) asks for a shipping name and address in one of these countries, then continues to payment; the address comes back as `shippingDetails`." }, "shippingOptions": { "type": "array", "minItems": 1, "maxItems": 5, "items": { "type": "object", "additionalProperties": false, "description": "Exactly one of shippingRate or shippingRateData.", "properties": { "shippingRate": { "type": "string", "description": "An active shipping rate in the session currency." }, "shippingRateData": { "$ref": "#/components/schemas/ShippingRateCreateRequest" } } }, "description": "One-time sessions with lineItems and shippingAddressCollection. Zahlo's page lists the options, the first preselected, and the payer may switch; the chosen rate is added to the total and never discounted." }, "customFields": { "type": "array", "maxItems": 3, "items": { "$ref": "#/components/schemas/CustomFieldDefinition" }, "description": "Up to 3 questions. Card and wallet sessions, hosted or embedded: a Zahlo page (the hosted `url`, or the embedded checkout's first step) asks them, then continues to payment. The answers come back in `customFields` and on `checkout.session.completed`." }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "CheckoutDomain": { "type": "object", "required": [ "id", "object", "domain", "applePay" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "checkout_domain" ] }, "domain": { "type": "string" }, "applePay": { "type": "object", "required": [ "status", "lastError" ], "properties": { "status": { "type": "string", "enum": [ "not_requested", "active", "failed" ] }, "lastError": { "type": "string", "nullable": true } } } } }, "CheckoutDomainCreateRequest": { "type": "object", "required": [ "domain" ], "properties": { "domain": { "type": "string", "description": "Hostname or URL, reduced to its origin. Sandbox also accepts localhost:." }, "applePay": { "type": "boolean", "description": "Register the host for Apple Pay in embedded checkout." } } }, "CheckoutAppearance": { "type": "object", "properties": { "theme": { "type": "string", "enum": [ "light", "dark", "auto" ] }, "logoUrl": { "type": "string", "format": "uri" }, "iconUrl": { "type": "string", "format": "uri" }, "fontFamily": { "type": "string" }, "colors": { "type": "object", "additionalProperties": { "type": "string" } }, "spacing": { "type": "string", "enum": [ "compact", "normal", "comfortable" ] }, "customCss": { "type": "string" } } }, "CheckoutSettings": { "type": "object", "properties": { "theme": { "type": "object", "additionalProperties": true }, "appearance": { "$ref": "#/components/schemas/CheckoutAppearance" }, "locale": { "type": "string" }, "allowedOrigins": { "type": "array", "items": { "type": "string", "format": "uri" } }, "paymentMethods": { "type": "array", "items": { "type": "string", "enum": [ "card", "apple_pay", "google_pay" ] } }, "customCss": { "type": "string" } } }, "CheckoutSettingsRequest": { "type": "object", "properties": { "theme": { "type": "object", "additionalProperties": true }, "appearance": { "$ref": "#/components/schemas/CheckoutAppearance" }, "locale": { "type": "string" }, "allowedOrigins": { "type": "array", "items": { "type": "string", "format": "uri" } }, "paymentMethods": { "type": "array", "items": { "type": "string", "enum": [ "card", "apple_pay", "google_pay" ] } }, "customCss": { "type": "string" } } }, "PaymentUpdateRequest": { "type": "object", "required": [ "metadata" ], "additionalProperties": false, "properties": { "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "OffSessionPaymentRequest": { "type": "object", "required": [ "customerId", "paymentMethodId", "amountMinor", "currency", "offSession" ], "additionalProperties": false, "properties": { "customerId": { "type": "string" }, "paymentMethodId": { "type": "string", "description": "A card saved with setupFutureUsage or a setup session." }, "amountMinor": { "type": "integer", "minimum": 1 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "reference": { "type": "string", "maxLength": 450 }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "offSession": { "type": "boolean", "enum": [ true ] } } }, "TransactionStatus": { "type": "string", "enum": [ "pending", "confirmed", "failed", "cancelled", "expired" ] }, "TransactionMethod": { "type": "string", "enum": [ "card", "sepa_direct_debit", "klarna", "ideal", "bancontact", "apple_pay", "google_pay", "paypal", "unknown" ] }, "Transaction": { "type": "object", "required": [ "id", "paymentId", "status", "amount", "createdAt", "occurredAt" ], "description": "A merchant-scoped transaction projected from Zahlo's persisted payment record. Provider refresh is best effort; status and timeline fields remain stable when a provider is unavailable.", "properties": { "id": { "type": "string" }, "paymentId": { "type": "string", "description": "The payment id (`GET /api/v1/payments/{id}`)." }, "status": { "$ref": "#/components/schemas/TransactionStatus" }, "method": { "$ref": "#/components/schemas/TransactionMethod" }, "reference": { "type": "string", "nullable": true }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } }, "amount": { "$ref": "#/components/schemas/Money" }, "fee": { "$ref": "#/components/schemas/Money" }, "createdAt": { "type": "string", "format": "date-time" }, "occurredAt": { "type": "string", "format": "date-time" } } }, "Balance": { "type": "object", "required": [ "available", "pending" ], "properties": { "available": { "$ref": "#/components/schemas/Money" }, "pending": { "$ref": "#/components/schemas/Money" } } }, "BalanceTransaction": { "type": "object", "description": "One movement of the merchant balance: a settled payment (gross, with the processing fee), a refund, a payout (with its payout fee) or a failed payout's return.", "required": [ "id", "object", "livemode", "createdAt", "effectiveAt", "type", "amountMinor", "feeMinor", "netMinor", "currency", "payoutId", "source" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "balance_transaction" ] }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "effectiveAt": { "type": "string", "format": "date-time" }, "type": { "type": "string", "enum": [ "payment", "refund", "dispute", "payout", "payout_failure" ] }, "amountMinor": { "type": "integer", "description": "Negative for refunds, payouts and lost disputes; a reversed dispute returns it." }, "feeMinor": { "type": "integer", "description": "The processing fee (quoted until the transfer is booked) or the payout fee; negative when a failed payout returns it." }, "netMinor": { "type": "integer" }, "currency": { "type": "string" }, "payoutId": { "type": "string", "nullable": true, "description": "The payout that settled this movement. The processor reports no such link, so Zahlo infers it; null until matched." }, "source": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "payment", "refund", "dispute", "payout" ] }, "id": { "type": "string", "nullable": true } } } } }, "Payout": { "type": "object", "description": "A transfer of the available balance to the merchant's bank account: a dashboard withdrawal or an automatic payout (a daily schedule or payout on settlement).", "required": [ "id", "object", "livemode", "createdAt", "amountMinor", "currency", "feeMinor", "status", "arrivalDate", "automatic", "reconciliationStatus" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "payout" ] }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "amountMinor": { "type": "integer", "description": "What reached the bank." }, "feeMinor": { "type": "integer", "description": "The processor's fee for an automatic EUR payout, taken from the balance on top of `amountMinor`." }, "currency": { "type": "string" }, "status": { "type": "string" }, "arrivalDate": { "type": "string", "format": "date-time", "nullable": true }, "automatic": { "type": "boolean", "description": "Started automatically, not from the dashboard." }, "reconciliationStatus": { "type": "string", "enum": [ "matched", "unmatched" ], "description": "`matched` once Zahlo found the movements this payout settled (they sum exactly to it). Fixed-amount and partial payouts can stay `unmatched`; reconcile those from the CSV." } } }, "Dispute": { "type": "object", "required": [ "id", "paymentId", "status", "amount" ], "properties": { "id": { "type": "string" }, "paymentId": { "type": "string", "description": "The payment's id, as GET /api/v1/payments/{id} takes it." }, "status": { "type": "string", "enum": [ "needs_response", "under_review", "won", "lost", "closed" ] }, "amount": { "$ref": "#/components/schemas/Money" }, "reason": { "type": "string" }, "evidenceDueAt": { "type": "string", "format": "date-time" } } }, "DisputeEvidenceRequest": { "type": "object", "required": [ "evidence" ], "properties": { "evidence": { "type": "object", "required": [ "defenseReasonCode" ], "properties": { "defenseReasonCode": { "type": "string", "description": "Reason code from the dispute's accepted defense reasons." }, "documents": { "type": "array", "maxItems": 10, "items": { "type": "object", "required": [ "defenseDocumentTypeCode", "fileName", "contentType", "contentBase64" ], "properties": { "defenseDocumentTypeCode": { "type": "string" }, "fileName": { "type": "string" }, "contentType": { "type": "string", "enum": [ "application/pdf", "image/jpeg", "image/jpg", "image/tiff" ] }, "contentBase64": { "type": "string", "description": "Base64 file bytes. PDF up to 2 MB, images up to 10 MB." } } } } } } } }, "FraudRule": { "type": "object", "required": [ "id", "object", "livemode", "createdAt", "kind", "value", "enabled" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "fraud_rule" ] }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": [ "block_email", "block_email_domain", "max_amount", "min_amount", "velocity_email_hour" ] }, "value": { "type": "string", "description": "An email (`block_email`), a domain (`block_email_domain`), an amount in minor units (`max_amount`/`min_amount`, with `currency`), or sessions per customer email per hour (`velocity_email_hour`)." }, "currency": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" } } }, "FraudRuleCreateRequest": { "type": "object", "required": [ "kind", "value" ], "properties": { "kind": { "type": "string", "enum": [ "block_email", "block_email_domain", "max_amount", "min_amount", "velocity_email_hour" ] }, "value": { "type": "string", "description": "An email (`block_email`), a domain (`block_email_domain`), an amount in minor units (`max_amount`/`min_amount`, with `currency`), or sessions per customer email per hour (`velocity_email_hour`)." }, "currency": { "type": "string", "description": "Required for amount rules." }, "enabled": { "type": "boolean", "default": true } } }, "FraudRuleUpdateRequest": { "type": "object", "properties": { "value": { "type": "string", "description": "An email (`block_email`), a domain (`block_email_domain`), an amount in minor units (`max_amount`/`min_amount`, with `currency`), or sessions per customer email per hour (`velocity_email_hour`)." }, "currency": { "type": "string", "nullable": true }, "enabled": { "type": "boolean" } } }, "Refund": { "type": "object", "required": [ "id", "object", "livemode", "createdAt", "paymentId", "amountMinor", "currency", "status", "reason", "metadata" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "refund" ] }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "paymentId": { "type": "string", "description": "The payment's id, as GET /api/v1/payments/{id} takes it." }, "amountMinor": { "type": "integer" }, "currency": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed" ] }, "reason": { "type": "string", "nullable": true }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "RefundCreateRequest": { "type": "object", "required": [ "paymentId" ], "properties": { "paymentId": { "type": "string" }, "amountMinor": { "type": "integer", "minimum": 1 }, "reason": { "type": "string" }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "Customer": { "type": "object", "required": [ "id", "object", "livemode", "createdAt", "email", "metadata" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "customer" ] }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "email": { "type": "string", "format": "email" }, "name": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "type": "object", "nullable": true, "properties": { "line1": { "type": "string", "nullable": true }, "line2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2" } } }, "preferredLocale": { "type": "string", "nullable": true, "description": "For example `en` or `de-DE`; customer emails use it." }, "taxIds": { "type": "array", "maxItems": 5, "description": "Printed on the customer's receipts and invoices. Spaces, dots and dashes are stripped.", "items": { "type": "object", "required": [ "type", "value", "verification" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "eu_vat", "gb_vat", "ch_vat" ] }, "value": { "type": "string", "example": "DE123456789" }, "verification": { "type": "object", "nullable": true, "readOnly": true, "description": "VIES check of an `eu_vat` ID, run shortly after it is set: `pending` until VIES answers (retried hourly while VIES is down), then `verified` or `unverified`. Other types are `unavailable`. Reverse charge never applies to an `unverified` ID.", "required": [ "status", "verifiedName" ], "additionalProperties": false, "properties": { "status": { "type": "string", "enum": [ "pending", "verified", "unverified", "unavailable" ] }, "verifiedName": { "type": "string", "nullable": true, "description": "The registered name VIES returned, if it shares it." } } } } } }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } }, "defaultPaymentMethodId": { "type": "string", "nullable": true } } }, "CustomerCreateRequest": { "type": "object", "required": [ "email" ], "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "type": "object", "nullable": true, "properties": { "line1": { "type": "string", "nullable": true }, "line2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2" } } }, "preferredLocale": { "type": "string", "nullable": true, "description": "For example `en` or `de-DE`; customer emails use it." }, "taxIds": { "type": "array", "maxItems": 5, "description": "Printed on the customer's receipts and invoices. Spaces, dots and dashes are stripped.", "items": { "type": "object", "required": [ "type", "value" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "eu_vat", "gb_vat", "ch_vat" ] }, "value": { "type": "string", "example": "DE123456789" } } } }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "CustomerUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "address": { "type": "object", "nullable": true, "properties": { "line1": { "type": "string", "nullable": true }, "line2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "country": { "type": "string", "nullable": true, "description": "ISO 3166-1 alpha-2" } } }, "preferredLocale": { "type": "string", "nullable": true, "description": "For example `en` or `de-DE`; customer emails use it." }, "taxIds": { "type": "array", "maxItems": 5, "description": "Printed on the customer's receipts and invoices. Spaces, dots and dashes are stripped.", "items": { "type": "object", "required": [ "type", "value" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "eu_vat", "gb_vat", "ch_vat" ] }, "value": { "type": "string", "example": "DE123456789" } } } }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "DeletedCustomer": { "type": "object", "required": [ "id", "object", "deleted" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "customer" ] }, "deleted": { "type": "boolean", "enum": [ true ] } } }, "CustomerPaymentMethod": { "type": "object", "description": "A card saved at checkout. The provider token is never returned; `card` appears once the card details are read.", "required": [ "id", "object", "livemode", "createdAt", "customerId", "checkoutSessionId", "type" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "payment_method" ] }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "customerId": { "type": "string" }, "checkoutSessionId": { "type": "string", "nullable": true, "description": "The checkout session that saved the card." }, "type": { "type": "string", "enum": [ "card" ] }, "card": { "type": "object", "required": [ "brand", "last4", "expMonth", "expYear" ], "properties": { "brand": { "type": "string" }, "last4": { "type": "string" }, "expMonth": { "type": "integer" }, "expYear": { "type": "integer" } } } } }, "Product": { "type": "object", "required": [ "id", "name" ], "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "active": { "type": "boolean" }, "unitLabel": { "type": "string", "maxLength": 12, "nullable": true, "description": "Shown after amounts on the pay page, receipts and invoices (\"€4.00 / kg\"); null = per item." }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "ProductCreateRequest": { "type": "object", "required": [ "name" ], "properties": { "name": { "type": "string" }, "description": { "type": "string" }, "active": { "type": "boolean", "default": true }, "unitLabel": { "type": "string", "maxLength": 12, "nullable": true, "description": "Shown after amounts on the pay page, receipts and invoices (\"€4.00 / kg\"); null = per item." }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "Price": { "type": "object", "required": [ "id", "object", "productId", "currency", "type", "active" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "price" ] }, "productId": { "type": "string" }, "nickname": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "currency": { "type": "string" }, "unitAmountMinor": { "type": "integer", "nullable": true, "description": "Null for a pay-what-you-want price." }, "customUnitAmount": { "type": "object", "nullable": true, "description": "Pay what you want: the payer enters the amount on the payment link page (minor units). Set instead of unitAmountMinor; one-time prices only; payment links only (API checkout sessions reject it).", "properties": { "minimum": { "type": "integer", "nullable": true }, "maximum": { "type": "integer", "nullable": true }, "preset": { "type": "integer", "nullable": true, "description": "The amount the page suggests." } } }, "type": { "type": "string", "enum": [ "one_time", "recurring" ] }, "recurring": { "type": "object", "nullable": true, "properties": { "intervalMonths": { "type": "integer" }, "trialDays": { "type": "integer", "nullable": true }, "usageType": { "type": "string", "enum": [ "licensed", "metered" ] } } }, "lookupKey": { "type": "string", "nullable": true }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "PriceCreateRequest": { "type": "object", "required": [ "productId", "currency" ], "description": "Send unitAmountMinor or customUnitAmount, not both.", "properties": { "productId": { "type": "string" }, "unitAmountMinor": { "type": "integer", "minimum": 0 }, "customUnitAmount": { "type": "object", "description": "Pay what you want, instead of unitAmountMinor: the payer enters the amount on a payment link (one-time prices only; the link holds only this price, quantity 1, no coupon or promotion codes). Each bound must be a checkout amount (EUR 1.00–15,000.00) and minimum ≤ preset ≤ maximum.", "properties": { "minimum": { "type": "integer", "minimum": 1 }, "maximum": { "type": "integer", "minimum": 1 }, "preset": { "type": "integer", "minimum": 1 } } }, "currency": { "type": "string" }, "type": { "type": "string", "enum": [ "one_time", "recurring" ], "default": "one_time" }, "recurring": { "type": "object", "description": "Required with type recurring. Whole months only; one charge is 50–500000 minor units.", "properties": { "interval": { "type": "string", "enum": [ "month", "quarter", "year" ] }, "intervalMonths": { "type": "integer", "minimum": 1, "maximum": 36 }, "trialDays": { "type": "integer", "minimum": 0, "maximum": 730 }, "usageType": { "type": "string", "enum": [ "licensed", "metered" ], "default": "licensed", "description": "metered: unitAmountMinor is per usage unit (at least 1), reported with usage records and billed with the charge after each period." } } }, "nickname": { "type": "string" }, "lookupKey": { "type": "string" }, "active": { "type": "boolean" }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "PriceUpdateRequest": { "type": "object", "properties": { "active": { "type": "boolean" }, "nickname": { "type": "string", "nullable": true }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "Coupon": { "type": "object", "required": [ "id", "object", "livemode", "createdAt", "duration", "timesRedeemed", "active", "metadata" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "coupon" ] }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "name": { "type": "string", "nullable": true }, "percentOff": { "type": "number", "nullable": true, "minimum": 0, "exclusiveMinimum": true, "maximum": 100, "description": "Set exactly one of percentOff and amountOffMinor." }, "amountOffMinor": { "type": "integer", "nullable": true, "minimum": 1 }, "currency": { "type": "string", "nullable": true, "description": "Required with amountOffMinor." }, "duration": { "type": "string", "enum": [ "once", "repeating", "forever" ] }, "durationInMonths": { "type": "integer", "nullable": true, "minimum": 1, "description": "Required for, and only for, duration repeating." }, "code": { "type": "string", "nullable": true, "description": "Promotion code customers type; unique per merchant, case-insensitive." }, "maxRedemptions": { "type": "integer", "nullable": true, "minimum": 1 }, "redeemBy": { "type": "string", "nullable": true, "format": "date-time" }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } }, "timesRedeemed": { "type": "integer" }, "active": { "type": "boolean" } } }, "CouponCreateRequest": { "type": "object", "required": [ "duration" ], "additionalProperties": false, "properties": { "name": { "type": "string", "nullable": true }, "percentOff": { "type": "number", "nullable": true, "minimum": 0, "exclusiveMinimum": true, "maximum": 100, "description": "Set exactly one of percentOff and amountOffMinor." }, "amountOffMinor": { "type": "integer", "nullable": true, "minimum": 1 }, "currency": { "type": "string", "nullable": true, "description": "Required with amountOffMinor." }, "duration": { "type": "string", "enum": [ "once", "repeating", "forever" ] }, "durationInMonths": { "type": "integer", "nullable": true, "minimum": 1, "description": "Required for, and only for, duration repeating." }, "code": { "type": "string", "nullable": true, "description": "Promotion code customers type; unique per merchant, case-insensitive." }, "maxRedemptions": { "type": "integer", "nullable": true, "minimum": 1 }, "redeemBy": { "type": "string", "nullable": true, "format": "date-time" }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "CouponUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "nullable": true }, "active": { "type": "boolean" }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "ShippingRate": { "type": "object", "required": [ "id", "object", "livemode", "createdAt", "active", "displayName", "type", "fixedAmount", "deliveryEstimate", "metadata" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "shipping_rate" ] }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "active": { "type": "boolean" }, "displayName": { "type": "string", "maxLength": 100 }, "type": { "type": "string", "enum": [ "fixed_amount" ] }, "fixedAmount": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": false, "properties": { "amount": { "type": "integer", "minimum": 0, "maximum": 1500000, "description": "Minor units, VAT included." }, "currency": { "type": "string" } } }, "deliveryEstimate": { "type": "object", "nullable": true, "additionalProperties": false, "description": "Either bound may be omitted; the minimum may not exceed the maximum.", "properties": { "minimum": { "type": "object", "nullable": true, "required": [ "unit", "value" ], "additionalProperties": false, "properties": { "unit": { "type": "string", "enum": [ "business_day", "day", "hour", "week", "month" ] }, "value": { "type": "integer", "minimum": 1, "maximum": 1000 } } }, "maximum": { "type": "object", "nullable": true, "required": [ "unit", "value" ], "additionalProperties": false, "properties": { "unit": { "type": "string", "enum": [ "business_day", "day", "hour", "week", "month" ] }, "value": { "type": "integer", "minimum": 1, "maximum": 1000 } } } } }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "ShippingRateCreateRequest": { "type": "object", "required": [ "displayName", "fixedAmount" ], "additionalProperties": false, "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 100 }, "type": { "type": "string", "enum": [ "fixed_amount" ], "default": "fixed_amount" }, "fixedAmount": { "type": "object", "required": [ "amount", "currency" ], "additionalProperties": false, "properties": { "amount": { "type": "integer", "minimum": 0, "maximum": 1500000, "description": "Minor units, VAT included." }, "currency": { "type": "string" } } }, "deliveryEstimate": { "type": "object", "nullable": true, "additionalProperties": false, "description": "Either bound may be omitted; the minimum may not exceed the maximum.", "properties": { "minimum": { "type": "object", "nullable": true, "required": [ "unit", "value" ], "additionalProperties": false, "properties": { "unit": { "type": "string", "enum": [ "business_day", "day", "hour", "week", "month" ] }, "value": { "type": "integer", "minimum": 1, "maximum": 1000 } } }, "maximum": { "type": "object", "nullable": true, "required": [ "unit", "value" ], "additionalProperties": false, "properties": { "unit": { "type": "string", "enum": [ "business_day", "day", "hour", "week", "month" ] }, "value": { "type": "integer", "minimum": 1, "maximum": 1000 } } } } }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "ShippingRateUpdateRequest": { "type": "object", "additionalProperties": false, "properties": { "active": { "type": "boolean" }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "PaymentLink": { "type": "object", "required": [ "id", "object", "url", "active", "lineItems", "collectCustomerEmail" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "payment_link" ] }, "url": { "type": "string", "format": "uri" }, "active": { "type": "boolean" }, "lineItems": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "required": [ "priceId", "quantity" ], "properties": { "priceId": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 } } } }, "couponId": { "type": "string", "nullable": true }, "allowPromotionCodes": { "type": "boolean" }, "paymentMethodTypes": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Per-link override; null uses the merchant default." }, "collectCustomerEmail": { "type": "boolean", "enum": [ true ] }, "shippingAddressCollection": { "type": "object", "nullable": true, "required": [ "allowedCountries" ], "properties": { "allowedCountries": { "type": "array", "minItems": 1, "maxItems": 250, "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "ISO 3166-1 alpha-2 codes the payer may ship to." } }, "description": "Ask the payer for a shipping address on the link page. Null turns it off." }, "shippingOptions": { "type": "array", "maxItems": 5, "items": { "type": "object", "required": [ "shippingRate" ], "additionalProperties": false, "properties": { "shippingRate": { "type": "string", "description": "An active shipping rate in the link's currency." } } }, "description": "Shipping rates the payer picks from on the link page, the first preselected. Needs shippingAddressCollection; one-time links only. An empty list removes them." }, "restrictions": { "type": "object", "nullable": true, "required": [ "completedSessions" ], "additionalProperties": false, "properties": { "completedSessions": { "type": "object", "required": [ "limit", "count" ], "additionalProperties": false, "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 1000000 }, "count": { "type": "integer", "description": "Completed checkouts so far; late payments are not counted." } } } }, "description": "Sales limit: the checkout that reaches `limit` turns the link off, and the page shows `inactiveMessage`. Payers checking out at the same moment can go slightly over. Raising the limit does not turn the link back on. Null removes the limit." }, "inactiveMessage": { "type": "string", "nullable": true, "maxLength": 500, "description": "Shown on the link page once the link is off or sold out; null shows the default text." }, "customFields": { "type": "array", "items": { "$ref": "#/components/schemas/CustomField" }, "description": "Asked on the link page; `value` is always null here." }, "submitType": { "type": "string", "enum": [ "auto", "pay", "book", "donate" ], "description": "The payment page's button label: `auto` keeps the default, the others say Pay, Book or Donate." }, "afterCompletion": { "type": "object", "properties": { "redirectUrl": { "type": "string", "format": "uri", "nullable": true }, "customMessage": { "type": "string", "nullable": true, "maxLength": 500, "description": "Shown on the confirmation page after payment; null shows the default text. Not shown when `redirectUrl` is set." } } }, "phoneNumberCollection": { "type": "object", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } }, "nullable": false, "description": "The link page asks for a phone number (6 to 20 digits, optional +); the session's `customerDetails.phone`." }, "nameCollection": { "type": "object", "nullable": false, "additionalProperties": false, "properties": { "individual": { "type": "object", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } }, "business": { "type": "object", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } } }, "description": "The link page asks for a full name and/or a business name (optional next to the full name); the session's `customerDetails`." }, "consentCollection": { "type": "object", "nullable": false, "additionalProperties": false, "properties": { "promotions": { "type": "string", "enum": [ "auto", "none" ], "description": "`auto`: an optional marketing checkbox; the session's `consent.promotions`." }, "termsOfService": { "type": "string", "enum": [ "required", "none" ], "description": "`required`: a checkbox the payer must tick, linking the terms of service in Checkout → Store policies (400 when none is set)." } } }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "PaymentLinkCreateRequest": { "type": "object", "required": [ "lineItems" ], "properties": { "lineItems": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "required": [ "priceId", "quantity" ], "properties": { "priceId": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 } } } }, "couponId": { "type": "string", "description": "A coupon applied to every checkout from the link. Not with allowPromotionCodes." }, "allowPromotionCodes": { "type": "boolean", "description": "The payment page asks for an optional promotion code (a coupon's code). Not with couponId." }, "paymentMethodTypes": { "type": "array", "nullable": true, "items": { "type": "string" }, "description": "Per-link override; null uses the merchant default." }, "shippingAddressCollection": { "type": "object", "nullable": true, "required": [ "allowedCountries" ], "properties": { "allowedCountries": { "type": "array", "minItems": 1, "maxItems": 250, "items": { "type": "string", "pattern": "^[A-Z]{2}$" }, "description": "ISO 3166-1 alpha-2 codes the payer may ship to." } }, "description": "Ask the payer for a shipping address on the link page. Null turns it off." }, "shippingOptions": { "type": "array", "maxItems": 5, "items": { "type": "object", "required": [ "shippingRate" ], "additionalProperties": false, "properties": { "shippingRate": { "type": "string", "description": "An active shipping rate in the link's currency." } } }, "description": "Shipping rates the payer picks from on the link page, the first preselected. Needs shippingAddressCollection; one-time links only. An empty list removes them." }, "restrictions": { "type": "object", "nullable": true, "required": [ "completedSessions" ], "additionalProperties": false, "properties": { "completedSessions": { "type": "object", "required": [ "limit" ], "additionalProperties": false, "properties": { "limit": { "type": "integer", "minimum": 1, "maximum": 1000000 } } } }, "description": "Sales limit: the checkout that reaches `limit` turns the link off, and the page shows `inactiveMessage`. Payers checking out at the same moment can go slightly over. Raising the limit does not turn the link back on. Null removes the limit." }, "inactiveMessage": { "type": "string", "nullable": true, "maxLength": 500, "description": "Shown on the link page once the link is off or sold out; null shows the default text." }, "customFields": { "type": "array", "maxItems": 3, "items": { "$ref": "#/components/schemas/CustomFieldDefinition" }, "nullable": true, "description": "Up to 3 questions the link page asks; null or [] removes them." }, "submitType": { "type": "string", "enum": [ "auto", "pay", "book", "donate" ], "description": "The payment page's button label: `auto` keeps the default, the others say Pay, Book or Donate.", "nullable": true }, "afterCompletion": { "type": "object", "properties": { "redirectUrl": { "type": "string", "format": "uri", "nullable": true }, "customMessage": { "type": "string", "nullable": true, "maxLength": 500, "description": "Shown on the confirmation page after payment; null shows the default text. Not shown when `redirectUrl` is set." } } }, "phoneNumberCollection": { "type": "object", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } }, "nullable": true, "description": "The link page asks for a phone number (6 to 20 digits, optional +); the session's `customerDetails.phone`." }, "nameCollection": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "individual": { "type": "object", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } }, "business": { "type": "object", "additionalProperties": false, "required": [ "enabled" ], "properties": { "enabled": { "type": "boolean" } } } }, "description": "The link page asks for a full name and/or a business name (optional next to the full name); the session's `customerDetails`." }, "consentCollection": { "type": "object", "nullable": true, "additionalProperties": false, "properties": { "promotions": { "type": "string", "enum": [ "auto", "none" ], "description": "`auto`: an optional marketing checkbox; the session's `consent.promotions`." }, "termsOfService": { "type": "string", "enum": [ "required", "none" ], "description": "`required`: a checkbox the payer must tick, linking the terms of service in Checkout → Store policies (400 when none is set)." } } }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "Subscription": { "type": "object", "required": [ "id", "object", "customerId", "priceId", "status", "currency", "amountMinor", "cancelAtPeriodEnd" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "subscription" ] }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "customerId": { "type": "string" }, "priceId": { "type": "string" }, "quantity": { "type": "integer" }, "status": { "type": "string", "enum": [ "incomplete", "trialing", "active", "past_due", "paused", "cancelled" ] }, "currency": { "type": "string" }, "amountMinor": { "type": "integer", "description": "The current or next period's charge, after discount." }, "couponId": { "type": "string", "nullable": true }, "discountEndsAt": { "type": "string", "format": "date-time", "nullable": true }, "paymentMethodId": { "type": "string", "nullable": true }, "rail": { "type": "string", "enum": [ "card", "sepa_debit" ] }, "trialEnd": { "type": "string", "format": "date-time", "nullable": true }, "currentPeriodStart": { "type": "string", "format": "date-time", "nullable": true }, "currentPeriodEnd": { "type": "string", "format": "date-time", "nullable": true }, "cancelAtPeriodEnd": { "type": "boolean" }, "cancelledAt": { "type": "string", "format": "date-time", "nullable": true }, "cancellationReason": { "type": "string", "enum": [ "requested", "payment_failed" ], "nullable": true }, "pastDueSince": { "type": "string", "format": "date-time", "nullable": true }, "latestPaymentId": { "type": "string", "nullable": true }, "pendingUpdate": { "type": "object", "nullable": true, "properties": { "priceId": { "type": "string" }, "quantity": { "type": "integer" }, "effectiveAt": { "type": "string", "format": "date-time" } } }, "prorationMinor": { "type": "integer", "description": "Proration for an upgrade or seat increase, added to the next period's charge." }, "addOns": { "type": "array", "description": "More recurring prices billed with the main price every period, discounted with it. `pendingQuantity` takes effect at the period end (0 removes the add-on).", "items": { "type": "object", "required": [ "priceId", "quantity", "pendingQuantity" ], "properties": { "priceId": { "type": "string" }, "quantity": { "type": "integer" }, "pendingQuantity": { "type": "integer", "nullable": true } } } }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "SubscriptionCreateRequest": { "type": "object", "required": [ "customerId", "priceId" ], "properties": { "customerId": { "type": "string" }, "priceId": { "type": "string", "description": "An active recurring price." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999, "default": 1 }, "couponId": { "type": "string" }, "paymentMethodId": { "type": "string", "description": "Defaults to the customer's default, then the newest saved card. With a trial the customer may have none: the subscription starts with paymentMethodId null and the first charge after the trial goes to failed-payment recovery unless a card is added." }, "trialDays": { "type": "integer", "minimum": 0, "maximum": 730, "description": "Defaults to the price's trial." }, "addOns": { "type": "array", "maxItems": 10, "items": { "type": "object", "required": [ "priceId", "quantity" ], "additionalProperties": false, "properties": { "priceId": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 } } }, "description": "More active recurring prices at the main price's interval and currency, billed with it every period. A metered price bills its usage records in arrears (its quantity is 1). Card only." }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "SubscriptionUpdateRequest": { "type": "object", "properties": { "priceId": { "type": "string", "description": "Same currency. An upgrade or seat increase applies now and prorates; a downgrade or interval switch applies at the period end." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 }, "addOns": { "type": "array", "maxItems": 10, "items": { "type": "object", "required": [ "priceId", "quantity" ], "additionalProperties": false, "properties": { "priceId": { "type": "string" }, "quantity": { "type": "integer", "minimum": 1, "maximum": 999 } } }, "description": "Replaces the add-ons. A new add-on or a higher quantity applies now and prorates on the next charge; a lower quantity or a removal applies at the period end. Card only." }, "paymentMethodId": { "type": "string" }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "SubscriptionAdvanceRequest": { "type": "object", "required": [ "to" ], "properties": { "to": { "type": "string", "enum": [ "trial_will_end", "renewal_succeeded", "renewal_failed", "renewal_requires_action", "sepa_returned", "period_end" ] } } }, "SubscriptionCancelRequest": { "type": "object", "properties": { "atPeriodEnd": { "type": "boolean", "default": true } } }, "UsageRecord": { "type": "object", "required": [ "id", "object", "subscriptionId", "priceId", "quantity", "occurredAt" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "usage_record" ] }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "subscriptionId": { "type": "string" }, "priceId": { "type": "string" }, "quantity": { "type": "integer" }, "occurredAt": { "type": "string", "format": "date-time" }, "billed": { "type": "boolean" } } }, "UsageRecordCreateRequest": { "type": "object", "required": [ "quantity" ], "properties": { "priceId": { "type": "string", "description": "A metered add-on of the subscription; required when it has several." }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000000 } } }, "Invoice": { "type": "object", "required": [ "id", "object", "livemode", "createdAt", "kind", "status", "number", "paymentId", "currency", "amountSubtotalMinor", "amountDiscountMinor", "amountPaidMinor", "tax", "customerTaxIds", "lines", "paidAt", "hostedInvoiceUrl", "invoicePdfUrl" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "invoice" ] }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "kind": { "type": "string", "enum": [ "invoice", "receipt" ], "description": "`receipt` until you set an invoice VAT rate." }, "status": { "type": "string", "enum": [ "paid" ] }, "number": { "type": "string", "description": "Sequential per merchant." }, "customerId": { "type": "string", "nullable": true }, "subscriptionId": { "type": "string", "nullable": true }, "paymentId": { "type": "string" }, "currency": { "type": "string" }, "amountSubtotalMinor": { "type": "integer" }, "amountDiscountMinor": { "type": "integer" }, "amountPaidMinor": { "type": "integer", "description": "Tax-inclusive total." }, "tax": { "type": "object", "nullable": true, "description": "The VAT contained in the tax-inclusive total at your rate (Zahlo calculates no tax; it splits what you charged).", "required": [ "rateBps", "netMinor", "taxMinor" ], "properties": { "rateBps": { "type": "integer", "description": "1900 = 19 %." }, "netMinor": { "type": "integer" }, "taxMinor": { "type": "integer" } } }, "customerTaxIds": { "type": "array", "items": { "type": "string" } }, "lines": { "type": "array", "items": { "type": "object", "required": [ "name", "quantity", "unitAmountMinor", "amountMinor" ], "properties": { "name": { "type": "string" }, "quantity": { "type": "integer" }, "unitAmountMinor": { "type": "integer" }, "amountMinor": { "type": "integer" } } } }, "periodStart": { "type": "string", "nullable": true, "format": "date-time", "description": "Service period of a subscription invoice." }, "periodEnd": { "type": "string", "nullable": true, "format": "date-time" }, "paidAt": { "type": "string", "format": "date-time" }, "hostedInvoiceUrl": { "type": "string", "format": "uri" }, "invoicePdfUrl": { "type": "string", "format": "uri" } } }, "CustomerPortalConfiguration": { "type": "object", "required": [ "object", "noCodePortalUrl" ], "properties": { "object": { "type": "string", "enum": [ "customer_portal_configuration" ] }, "noCodePortalUrl": { "type": "string", "format": "uri", "description": "Your permanent no-code portal link (`/billing-portal/m/`)." } } }, "CustomerPortalSessionRequest": { "type": "object", "required": [ "customerId", "returnUrl" ], "properties": { "customerId": { "type": "string" }, "returnUrl": { "type": "string", "format": "uri", "description": "Absolute https URL the portal's back link goes to." }, "locale": { "type": "string", "enum": [ "en", "de" ] } } }, "CustomerPortalSession": { "type": "object", "required": [ "id", "object", "customerId", "url", "returnUrl", "expiresAt" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "billing_portal_session" ] }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "customerId": { "type": "string" }, "url": { "type": "string", "format": "uri" }, "returnUrl": { "type": "string", "format": "uri" }, "expiresAt": { "type": "string", "format": "date-time" } } }, "WebhookEndpoint": { "type": "object", "required": [ "id", "object", "livemode", "createdAt", "url", "enabledEvents", "status" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "webhook_endpoint" ] }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "url": { "type": "string", "format": "uri" }, "enabledEvents": { "type": "array", "minItems": 1, "items": { "type": "string", "description": "A catalog event type or `*` for every event." } }, "status": { "type": "string", "enum": [ "enabled", "disabled" ] }, "description": { "type": "string", "nullable": true }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } }, "failingSince": { "type": "string", "nullable": true, "format": "date-time", "description": "Start of the current run of failed deliveries; null while healthy. After 3 days the endpoint is disabled." }, "disabledReason": { "type": "string", "nullable": true, "enum": [ "failing", null ], "description": "`failing` when Zahlo disabled the endpoint after 3 days of failures." }, "secret": { "type": "string", "description": "Only in the create and rotate-secret responses." } } }, "WebhookEndpointCreateRequest": { "type": "object", "required": [ "url", "enabledEvents" ], "properties": { "url": { "type": "string", "format": "uri" }, "enabledEvents": { "type": "array", "minItems": 1, "items": { "type": "string", "description": "A catalog event type or `*` for every event." } }, "description": { "type": "string", "maxLength": 200 }, "metadata": { "type": "object", "description": "Up to 50 key-value pairs; keys up to 40 characters, values strings up to 500 characters.", "maxProperties": 50, "additionalProperties": { "type": "string", "maxLength": 500 } }, "enabled": { "type": "boolean", "default": true } } }, "WebhookDelivery": { "type": "object", "required": [ "id", "object", "endpointId", "eventId", "eventType", "status", "attempts" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "webhook_delivery" ] }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "endpointId": { "type": "string" }, "eventId": { "type": "string" }, "eventType": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "sending", "succeeded", "failed" ] }, "attempts": { "type": "integer" }, "lastAttemptAt": { "type": "string", "nullable": true, "format": "date-time" }, "lastResponseStatus": { "type": "integer", "nullable": true }, "lastResponseBody": { "type": "string", "nullable": true }, "lastError": { "type": "string", "nullable": true }, "nextAttemptAt": { "type": "string", "nullable": true, "format": "date-time" } } }, "WebhookDeliveryAttempt": { "type": "object", "required": [ "id", "object", "createdAt", "deliveryId", "durationMs" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "webhook_delivery_attempt" ] }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "deliveryId": { "type": "string" }, "responseStatus": { "type": "integer", "nullable": true }, "error": { "type": "string", "nullable": true, "description": "`timeout`, `network_error`, `http_`, … ; null on success." }, "durationMs": { "type": "integer" } } }, "WebhookTestRequest": { "type": "object", "required": [ "type" ], "properties": { "type": { "type": "string", "description": "A catalog event type." } } }, "WebhookTestResult": { "type": "object", "properties": { "eventId": { "type": "string" }, "ok": { "type": "boolean" }, "responseStatus": { "type": "integer", "nullable": true }, "error": { "type": "string", "nullable": true } } }, "EventResendRequest": { "type": "object", "required": [ "endpointId" ], "properties": { "endpointId": { "type": "string", "description": "Any enabled endpoint of the merchant, whether or not it had a delivery of this event." } } }, "Event": { "type": "object", "required": [ "id", "object", "type", "livemode", "createdAt", "data" ], "properties": { "id": { "type": "string" }, "object": { "type": "string", "enum": [ "event" ] }, "type": { "type": "string" }, "livemode": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "data": { "type": "object", "required": [ "object" ], "properties": { "object": { "type": "object", "additionalProperties": true } } } } }, "TestDisputeRequest": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "needs_response", "under_review", "won", "lost" ] } } }, "TestOutcomeRequest": { "type": "object", "required": [ "outcome" ], "properties": { "outcome": { "type": "string", "enum": [ "succeeded", "failed" ] } } } } } }