{"openapi":"3.1.0","info":{"title":"HandyPay Ecommerce API","version":"2025-01-01","description":"Create payments, subscriptions, refunds, and webhooks for a HandyPay merchant. Monetary amounts use the smallest currency unit. Never expose an hp_live_ or hp_test_ API key in browser or mobile code.","contact":{"name":"HandyPay Support","email":"support@tryhandypay.com","url":"https://tryhandypay.com/contact"}},"jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","servers":[{"url":"https://api.handypay.me/api","description":"Production"}],"tags":[{"name":"Products","description":"One-time sale products and prices."},{"name":"Customers","description":"Customer records scoped to the merchant."},{"name":"Payments","description":"Hosted and embedded payment flows."},{"name":"Refunds","description":"Full and partial merchant-owned refunds."},{"name":"Disputes","description":"Chargeback retrieval and evidence submission."},{"name":"Subscriptions","description":"Recurring products, checkout, and lifecycle management."},{"name":"Webhooks","description":"Independent, signed event deliveries."},{"name":"Account","description":"Connected payout account details."}],"paths":{"/v1/products":{"post":{"tags":["Products"],"operationId":"createProduct","summary":"Create a product","security":[{"ApiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateProductRequest"}}}},"responses":{"200":{"description":"Product created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"get":{"tags":["Products"],"operationId":"listProducts","summary":"List products","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"limit","in":"query","description":"Items per page. Defaults to 10.","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},{"name":"starting_after","in":"query","description":"ID of the last object from the previous page.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Products returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ProductList"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/products/{id}":{"get":{"tags":["Products"],"operationId":"getProduct","summary":"Get a product","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Product returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"put":{"tags":["Products"],"operationId":"updateProduct","summary":"Update a product","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateProductRequest"}}}},"responses":{"200":{"description":"Product updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Product"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"tags":["Products"],"operationId":"archiveProduct","summary":"Archive a product","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Product ID","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Product archived","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Deleted"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/customers":{"post":{"tags":["Customers"],"operationId":"createCustomer","summary":"Create a customer","security":[{"ApiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCustomerRequest"}}}},"responses":{"200":{"description":"Customer created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Customer"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"get":{"tags":["Customers"],"operationId":"listCustomers","summary":"List customers","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"limit","in":"query","description":"Items per page. Defaults to 10.","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},{"name":"starting_after","in":"query","description":"ID of the last object from the previous page.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Customers returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/CustomerList"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/customers/{id}":{"get":{"tags":["Customers"],"operationId":"getCustomer","summary":"Get a customer","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Customer ID","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Customer returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Customer"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"put":{"tags":["Customers"],"operationId":"updateCustomer","summary":"Update a customer","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Customer ID","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCustomerRequest"}}}},"responses":{"200":{"description":"Customer updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Customer"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"delete":{"tags":["Customers"],"operationId":"deleteCustomer","summary":"Delete a customer","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Customer ID","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Customer deleted","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Deleted"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/payment-sessions":{"post":{"tags":["Payments"],"operationId":"createPaymentSession","summary":"Create a hosted payment session","security":[{"ApiKeyBearer":[]}],"description":"Redirect the customer to the returned URL. Confirm the final outcome with a signed webhook; a browser return is not proof of payment.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentSessionRequest"}}}},"responses":{"200":{"description":"Payment session created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentSession"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/payment-sessions/{id}":{"get":{"tags":["Payments"],"operationId":"getPaymentSession","summary":"Get a payment session","security":[{"ApiKeyBearer":[]}],"description":"A completed session remains queryable when it belongs to the authenticated merchant and API mode.","parameters":[{"name":"id","in":"path","required":true,"description":"Checkout Session ID (cs_...)","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Payment session returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentSession"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/test-payments":{"get":{"tags":["Payments"],"operationId":"listTestPayments","summary":"List sandbox payments","security":[{"ApiKeyBearer":[]}],"description":"Requires an hp_test_ API key.","parameters":[{"name":"limit","in":"query","description":"Items per page. Defaults to 10.","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},{"name":"starting_after","in":"query","description":"ID of the last object from the previous page.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Test payments returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentList"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/payment-intents":{"post":{"tags":["Payments"],"operationId":"createPaymentIntent","summary":"Create an embedded PaymentIntent","security":[{"ApiKeyBearer":[]}],"description":"Returns a short-lived client_secret for Stripe.js/Elements. Use the publishable key and stripe_account in the client; keep the HandyPay API key on your server.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentIntentRequest"}}}},"responses":{"200":{"description":"PaymentIntent created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentIntentClient"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/refunds":{"post":{"tags":["Refunds"],"operationId":"createRefund","summary":"Create a full or partial refund","security":[{"ApiKeyBearer":[]}],"description":"Provide exactly one merchant-owned Checkout Session or PaymentIntent. Full refunds omit amount. Refunds fail closed when ownership or available balance cannot be verified.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateRefundRequest"}}}},"responses":{"200":{"description":"Refund created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Refund"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/disputes":{"get":{"tags":["Disputes"],"operationId":"listDisputes","summary":"List disputes","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":50}}],"responses":{"200":{"description":"Disputes returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/DisputeList"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/disputes/{id}":{"get":{"tags":["Disputes"],"operationId":"getDispute","summary":"Get a dispute","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Dispute ID (dp_...)","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Dispute returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Dispute"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/disputes/{id}/evidence":{"post":{"tags":["Disputes"],"operationId":"submitDisputeEvidence","summary":"Update or submit dispute evidence","security":[{"ApiKeyBearer":[]}],"description":"Set submit only after the evidence is complete. Stripe may prevent further changes after submission.","parameters":[{"name":"id","in":"path","required":true,"description":"Dispute ID (dp_...)","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DisputeEvidenceRequest"}}}},"responses":{"200":{"description":"Dispute updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Dispute"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/subscription-products":{"post":{"tags":["Subscriptions"],"operationId":"createSubscriptionProduct","summary":"Create a recurring product","security":[{"ApiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubscriptionProductRequest"}}}},"responses":{"200":{"description":"Recurring product created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SubscriptionProduct"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"get":{"tags":["Subscriptions"],"operationId":"listSubscriptionProducts","summary":"List recurring products","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"limit","in":"query","description":"Items per page. Defaults to 10.","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},{"name":"starting_after","in":"query","description":"ID of the last object from the previous page.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Recurring products returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SubscriptionProductList"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/subscription-sessions":{"post":{"tags":["Subscriptions"],"operationId":"createSubscriptionSession","summary":"Create a subscription checkout","security":[{"ApiKeyBearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubscriptionSessionRequest"}}}},"responses":{"200":{"description":"Subscription checkout created","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/PaymentSession"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/subscriptions":{"get":{"tags":["Subscriptions"],"operationId":"listSubscriptions","summary":"List subscriptions","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"limit","in":"query","description":"Items per page. Defaults to 10.","schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},{"name":"starting_after","in":"query","description":"ID of the last object from the previous page.","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Subscriptions returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/SubscriptionList"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/subscriptions/{id}/cancel":{"post":{"tags":["Subscriptions"],"operationId":"cancelSubscription","summary":"Cancel a subscription at period end","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Subscription ID (sub_...)","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Subscription cancellation scheduled","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Subscription"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/subscriptions/{id}/quantity":{"patch":{"tags":["Subscriptions"],"operationId":"updateSubscriptionQuantity","summary":"Update subscription quantity","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Subscription ID (sub_...)","schema":{"type":"string","minLength":1}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateSubscriptionQuantityRequest"}}}},"responses":{"200":{"description":"Subscription quantity updated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Subscription"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/webhook-endpoints":{"post":{"tags":["Webhooks"],"operationId":"createWebhookEndpoint","summary":"Register a webhook endpoint","security":[{"ApiKeyBearer":[]}],"description":"The response includes the signing secret once. Each active endpoint receives its own independently signed delivery.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateWebhookEndpointRequest"}}}},"responses":{"200":{"description":"Webhook endpoint registered","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/WebhookEndpoint"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"get":{"tags":["Webhooks"],"operationId":"listWebhookEndpoints","summary":"List webhook endpoints","security":[{"ApiKeyBearer":[]}],"responses":{"200":{"description":"Webhook endpoints returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/webhook-endpoints/{id}":{"delete":{"tags":["Webhooks"],"operationId":"deleteWebhookEndpoint","summary":"Deactivate a webhook endpoint","security":[{"ApiKeyBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"description":"Webhook endpoint ID","schema":{"type":"string","minLength":1}}],"responses":{"200":{"description":"Webhook endpoint deactivated","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Deleted"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}},"/v1/account":{"get":{"tags":["Account"],"operationId":"getAccount","summary":"Get the connected payout account","security":[{"ApiKeyBearer":[]}],"description":"Returns payout readiness and masked bank details. Full bank and routing numbers are never exposed.","responses":{"200":{"description":"Account returned","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/SuccessEnvelope"},{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Account"}}}]}}}},"400":{"description":"Invalid request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing, invalid, expired, or revoked API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"413":{"description":"Request body exceeds 1 MiB","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"500":{"description":"Unexpected server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"502":{"description":"Upstream payment provider error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}},"components":{"securitySchemes":{"ApiKeyBearer":{"type":"http","scheme":"bearer","bearerFormat":"hp_live_... or hp_test_...","description":"Server-side API key. Live and test keys are isolated and must never be embedded in public client code."}},"schemas":{"SuccessEnvelope":{"type":"object","required":["success","data","request_id"],"properties":{"success":{"type":"boolean","const":true},"data":{},"request_id":{"type":"string","format":"uuid"}}},"ErrorEnvelope":{"type":"object","required":["success","error","request_id"],"properties":{"success":{"type":"boolean","const":false},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}},"request_id":{"type":"string","format":"uuid"}}},"Metadata":{"type":"object","additionalProperties":{"type":"string"},"maxProperties":50},"Deleted":{"type":"object","required":["deleted"],"properties":{"deleted":{"type":"boolean","const":true}}},"PriceInput":{"type":"object","required":["amount","currency"],"additionalProperties":false,"properties":{"amount":{"type":"integer","minimum":1,"maximum":99999999,"description":"Smallest currency unit."},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$"},"tax_behavior":{"type":"string","enum":["inclusive","exclusive","unspecified"]}}},"CreateProductRequest":{"type":"object","required":["name"],"properties":{"name":{"type":"string","minLength":1},"description":{"type":"string"},"images":{"type":"array","maxItems":8,"items":{"type":"string","format":"uri","pattern":"^https://"}},"metadata":{"$ref":"#/components/schemas/Metadata"},"active":{"type":"boolean","default":true},"url":{"type":"string","format":"uri","pattern":"^https://"},"shippable":{"type":"boolean"},"unit_label":{"type":"string"},"statement_descriptor":{"type":"string","maxLength":22},"tax_code":{"type":"string"},"price":{"$ref":"#/components/schemas/PriceInput"}}},"UpdateProductRequest":{"type":"object","properties":{"name":{"type":"string","minLength":1},"description":{"type":"string"},"images":{"type":"array","maxItems":8,"items":{"type":"string","format":"uri","pattern":"^https://"}},"metadata":{"$ref":"#/components/schemas/Metadata"},"active":{"type":"boolean"},"url":{"type":"string","format":"uri","pattern":"^https://"},"shippable":{"type":"boolean"},"unit_label":{"type":"string"},"statement_descriptor":{"type":"string","maxLength":22},"tax_code":{"type":"string"},"price":{"$ref":"#/components/schemas/PriceInput"}}},"Product":{"type":"object","required":["id","name","active","images","metadata","created"],"properties":{"id":{"type":"string","pattern":"^prod_"},"name":{"type":"string"},"description":{"type":["string","null"]},"active":{"type":"boolean"},"images":{"type":"array","items":{"type":"string","format":"uri"}},"url":{"type":["string","null"],"format":"uri"},"metadata":{"$ref":"#/components/schemas/Metadata"},"default_price":{"type":"object","properties":{"id":{"type":"string","pattern":"^price_"},"amount":{"type":"integer"},"currency":{"type":"string"},"tax_behavior":{"type":["string","null"]}}},"created":{"type":"integer","description":"Unix timestamp."}}},"ProductList":{"type":"object","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"has_more":{"type":"boolean"}}},"CreateCustomerRequest":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"},"phone":{"type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"UpdateCustomerRequest":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string"},"phone":{"type":"string"},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"Customer":{"type":"object","required":["id","email","name","phone","metadata","created"],"properties":{"id":{"type":"string","pattern":"^cus_"},"email":{"type":["string","null"],"format":"email"},"name":{"type":["string","null"]},"phone":{"type":["string","null"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"created":{"type":"integer"}}},"CustomerList":{"type":"object","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Customer"}},"has_more":{"type":"boolean"}}},"LineItem":{"type":"object","required":["quantity"],"properties":{"price_id":{"type":"string","pattern":"^price_"},"amount":{"type":"integer","minimum":1,"maximum":99999999},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$"},"name":{"type":"string"},"quantity":{"type":"integer","minimum":1,"maximum":1000}},"description":"Use price_id, or use amount + currency + name."},"CreatePaymentSessionRequest":{"type":"object","required":["line_items","success_url","cancel_url"],"properties":{"line_items":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/LineItem"}},"success_url":{"type":"string","format":"uri","pattern":"^https://"},"cancel_url":{"type":"string","format":"uri","pattern":"^https://"},"customer_id":{"type":"string"},"customer_email":{"type":"string","format":"email"},"pass_fees_to_customer":{"type":"boolean","default":false},"metadata":{"$ref":"#/components/schemas/Metadata"},"collect_shipping_address":{"type":"boolean"},"billing_address_collection":{"type":"string","enum":["auto","required"]},"shipping_countries":{"type":"array","items":{"type":"string","pattern":"^[A-Za-z]{2}$"}},"shipping_options":{"type":"array","items":{"type":"object","required":["label","amount"],"properties":{"label":{"type":"string"},"amount":{"type":"integer","minimum":0}}}}}},"PaymentSession":{"type":"object","required":["id","url","status","payment_status","created"],"properties":{"id":{"type":"string","pattern":"^cs_"},"url":{"type":["string","null"],"format":"uri"},"status":{"type":["string","null"]},"payment_status":{"type":"string"},"amount_total":{"type":["integer","null"]},"currency":{"type":["string","null"]},"customer":{"type":["string","null"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"created":{"type":"integer"}}},"Payment":{"type":"object","properties":{"id":{"type":"string","pattern":"^pi_"},"amount":{"type":"integer"},"amount_received":{"type":"integer"},"currency":{"type":"string"},"status":{"type":"string"},"customer":{"type":["string","null"]},"customer_email":{"type":["string","null"],"format":"email"},"description":{"type":["string","null"]},"metadata":{"$ref":"#/components/schemas/Metadata"},"created":{"type":"integer"},"livemode":{"type":"boolean"}}},"PaymentList":{"type":"object","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"has_more":{"type":"boolean"}}},"CreatePaymentIntentRequest":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"integer","minimum":1,"maximum":99999999},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$"},"description":{"type":"string"},"customer_email":{"type":"string","format":"email"},"pass_fees_to_customer":{"type":"boolean","default":false},"metadata":{"$ref":"#/components/schemas/Metadata"},"source":{"type":"string"},"device":{"type":"string"}}},"PaymentIntentClient":{"type":"object","required":["client_secret","payment_intent_id","publishable_key","stripe_account","amount","currency"],"properties":{"client_secret":{"type":"string","description":"Use only to complete this payment in Stripe.js/Elements."},"payment_intent_id":{"type":"string","pattern":"^pi_"},"publishable_key":{"type":"string","pattern":"^pk_"},"stripe_account":{"type":"string","pattern":"^acct_"},"amount":{"type":"integer"},"currency":{"type":"string"}}},"CreateRefundRequest":{"type":"object","oneOf":[{"required":["session_id"]},{"required":["payment_intent"]}],"properties":{"session_id":{"type":"string","pattern":"^cs_"},"payment_intent":{"type":"string","pattern":"^pi_"},"amount":{"type":"integer","minimum":1,"description":"Omit for a full refund."},"reason":{"type":"string","enum":["duplicate","fraudulent","requested_by_customer"]}}},"Refund":{"type":"object","required":["id","status","amount_cents","currency"],"properties":{"id":{"type":"string","pattern":"^re_"},"status":{"type":"string"},"amount_cents":{"type":"integer"},"currency":{"type":"string"}}},"Dispute":{"type":"object","required":["id","status","reason","amount_cents","currency","created"],"properties":{"id":{"type":"string","pattern":"^dp_"},"status":{"type":"string"},"reason":{"type":"string"},"amount_cents":{"type":"integer"},"currency":{"type":"string"},"evidence_due_by":{"type":["integer","null"]},"has_evidence":{"type":"boolean"},"submission_count":{"type":"integer"},"payment_intent":{"type":["string","null"]},"charge":{"type":["string","null"]},"evidence":{"type":"object","additionalProperties":true},"created":{"type":"integer"}}},"DisputeList":{"type":"object","required":["data","has_more"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Dispute"}},"has_more":{"type":"boolean"}}},"DisputeEvidenceRequest":{"type":"object","properties":{"evidence":{"type":"object","additionalProperties":{"type":"string"}},"submit":{"type":"boolean","default":false}}},"CreateSubscriptionProductRequest":{"type":"object","required":["name","amount","currency","interval"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"amount":{"type":"integer","minimum":1,"maximum":99999999},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$"},"interval":{"type":"string","enum":["weekly","bi-weekly","monthly","bi-monthly","quarterly","semi-annual","annual"]},"trial_period_days":{"type":"integer","minimum":0},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"SubscriptionProduct":{"type":"object","properties":{"id":{"type":"string","pattern":"^prod_"},"name":{"type":"string"},"description":{"type":["string","null"]},"active":{"type":"boolean"},"price":{"type":"object","properties":{"id":{"type":"string","pattern":"^price_"},"amount":{"type":"integer"},"currency":{"type":"string"},"interval":{"type":"string"},"interval_count":{"type":"integer"},"trial_period_days":{"type":["integer","null"]}}},"metadata":{"$ref":"#/components/schemas/Metadata"},"created":{"type":"integer"}}},"SubscriptionProductList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SubscriptionProduct"}},"has_more":{"type":"boolean"}}},"CreateSubscriptionSessionRequest":{"type":"object","required":["success_url","cancel_url"],"properties":{"price_id":{"type":"string","pattern":"^price_"},"amount_cents":{"type":"integer","minimum":1},"currency":{"type":"string","pattern":"^[A-Za-z]{3}$"},"interval":{"type":"string"},"interval_count":{"type":"integer","minimum":1},"name":{"type":"string"},"quantity":{"type":"integer","minimum":1,"maximum":1000,"default":1},"success_url":{"type":"string","format":"uri","pattern":"^https://"},"cancel_url":{"type":"string","format":"uri","pattern":"^https://"},"customer_id":{"type":"string"},"customer_email":{"type":"string","format":"email"},"trial_period_days":{"type":"integer","minimum":0},"pass_fees_to_customer":{"type":"boolean","default":false},"metadata":{"$ref":"#/components/schemas/Metadata"}}},"UpdateSubscriptionQuantityRequest":{"type":"object","required":["quantity"],"properties":{"quantity":{"type":"integer","minimum":1,"maximum":1000},"proration_behavior":{"type":"string","enum":["create_prorations","always_invoice","none"]},"item_id":{"type":"string"}}},"Subscription":{"type":"object","properties":{"id":{"type":"string","pattern":"^sub_"},"status":{"type":"string"},"customer":{"type":"string"},"current_period_start":{"type":"integer"},"current_period_end":{"type":"integer"},"cancel_at_period_end":{"type":"boolean"},"items":{"type":"array","items":{"type":"object","properties":{"price_id":{"type":"string"},"product_id":{"type":"string"},"quantity":{"type":"integer"}}}},"metadata":{"$ref":"#/components/schemas/Metadata"},"created":{"type":"integer"}}},"SubscriptionList":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}},"has_more":{"type":"boolean"}}},"WebhookEventType":{"type":"string","enum":["payment_intent.succeeded","payment_intent.payment_failed","checkout.session.completed","checkout.session.expired","checkout.session.async_payment_succeeded","checkout.session.async_payment_failed","customer.subscription.created","customer.subscription.updated","customer.subscription.deleted","charge.refunded","charge.dispute.created","charge.dispute.closed"]},"CreateWebhookEndpointRequest":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string","format":"uri","pattern":"^https://"},"events":{"type":"array","minItems":1,"uniqueItems":true,"items":{"$ref":"#/components/schemas/WebhookEventType"}}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"url":{"type":"string","format":"uri"},"events":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEventType"}},"isActive":{"type":"boolean"},"secret":{"type":"string","writeOnly":true,"description":"Returned only when the endpoint is created."},"consecutiveFailures":{"type":"integer"}}},"Account":{"type":"object","properties":{"id":{"type":"string","pattern":"^acct_"},"type":{"type":["string","null"]},"country":{"type":["string","null"]},"email":{"type":["string","null"],"format":"email"},"payoutsEnabled":{"type":"boolean"},"chargesEnabled":{"type":"boolean"},"detailsSubmitted":{"type":"boolean"},"bankAccount":{"anyOf":[{"type":"null"},{"type":"object","description":"Masked bank account details only.","properties":{"id":{"type":"string"},"last4":{"type":["string","null"]},"bankName":{"type":["string","null"]},"routingLast4":{"type":["string","null"]},"currency":{"type":["string","null"]},"country":{"type":["string","null"]},"status":{"type":["string","null"]}}}]},"dashboardUrl":{"type":"string","format":"uri"}}}}}}