{"openapi":"3.1.0","info":{"title":"QashX Pay — Public Payments API","version":"1.0.0","description":"Provider-agnostic REST API for creating and managing payments. The API selects the settlement infrastructure automatically based on the requested capability (method + currency). Payment methods, banking rails and stablecoins are exposed as capabilities — never as provider names.","contact":{"name":"QashX Pay Support"}},"servers":[{"url":"https://platform.qashx.app/functions/v1/api-v1-payments","description":"Production"}],"tags":[{"name":"Payments","description":"Create and manage payment sessions"}],"security":[{"bearerAuth":[]},{"apiKey":[]}],"paths":{"/":{"post":{"tags":["Payments"],"operationId":"createPayment","summary":"Create a payment","parameters":[{"name":"x-idempotency-key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Prevents duplicate creation on retries. Same key + same body ⇒ replay."},{"name":"x-correlation-id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional client-provided trace id, echoed on the response."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentRequest"}}}},"responses":{"201":{"description":"Payment session created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Idempotency conflict","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"422":{"description":"Capability not available","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"get":{"tags":["Payments"],"operationId":"listPayments","summary":"List payments","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"status","in":"query","schema":{"$ref":"#/components/schemas/PaymentStatus"}},{"name":"x-correlation-id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional client-provided trace id, echoed on the response."}],"responses":{"200":{"description":"Paginated payments","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/{id}":{"get":{"tags":["Payments"],"operationId":"getPayment","summary":"Retrieve a payment","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"x-correlation-id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional client-provided trace id, echoed on the response."}],"responses":{"200":{"description":"Payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/{id}/status":{"get":{"tags":["Payments"],"operationId":"getPaymentStatus","summary":"Retrieve payment status only","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"x-correlation-id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional client-provided trace id, echoed on the response."}],"responses":{"200":{"description":"Status snapshot","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentStatusSnapshot"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/{id}/cancel":{"post":{"tags":["Payments"],"operationId":"cancelPayment","summary":"Cancel a payment before it is paid","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"x-idempotency-key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Prevents duplicate creation on retries. Same key + same body ⇒ replay."},{"name":"x-correlation-id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional client-provided trace id, echoed on the response."}],"responses":{"200":{"description":"Cancelled payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Cannot cancel in current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/{id}/refund":{"post":{"tags":["Payments"],"operationId":"refundPayment","summary":"Refund a completed payment","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"x-idempotency-key","in":"header","required":false,"schema":{"type":"string","maxLength":200},"description":"Prevents duplicate creation on retries. Same key + same body ⇒ replay."},{"name":"x-correlation-id","in":"header","required":false,"schema":{"type":"string"},"description":"Optional client-provided trace id, echoed on the response."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequest"}}}},"responses":{"200":{"description":"Refund processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"409":{"description":"Payment not refundable in current state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"501":{"description":"Refund not supported for this payment method","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"},"apiKey":{"type":"apiKey","in":"header","name":"x-api-key","description":"Reserved for the next iteration; keys are not yet issued."}},"parameters":{},"schemas":{"PaymentStatus":{"type":"string","enum":["created","awaiting_payment","processing","pending_settlement","completed","failed","refunded","cancelled","disputed","expired","paused"]},"PaymentMethod":{"type":"string","enum":["card","apple_pay","google_pay","sepa","sepa_instant","swift","ach","wire","faster_payments","pix","spei","stablecoin"],"description":"Capability requested by the caller. The API routes it to the appropriate infrastructure internally."},"Currency":{"type":"string","minLength":3,"maxLength":3,"description":"ISO-4217 code, or stablecoin ticker (USDC, USDT, EURC, EURE, GBPE)."},"CreatePaymentRequest":{"type":"object","required":["amount_minor","currency"],"properties":{"amount_minor":{"type":"integer","minimum":1,"description":"Amount in minor units (e.g. cents)."},"currency":{"$ref":"#/components/schemas/Currency"},"description":{"type":"string","maxLength":500},"reference":{"type":"string","maxLength":80,"description":"Merchant reference echoed on the receipt."},"methods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"},"description":"Capabilities the payer is allowed to use. Defaults to a reasonable set for the currency."},"payer":{"type":"object","properties":{"email":{"type":"string","format":"email"},"name":{"type":"string","maxLength":200},"country":{"type":"string","minLength":2,"maxLength":2}}},"expires_at":{"type":"string","format":"date-time"},"return_url":{"type":"string","format":"uri"},"metadata":{"type":"object","additionalProperties":true}}},"Payment":{"type":"object","required":["id","status","amount_minor","currency","checkout_url"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["payment"]},"reference":{"type":"string"},"status":{"$ref":"#/components/schemas/PaymentStatus"},"amount_minor":{"type":"integer"},"currency":{"$ref":"#/components/schemas/Currency"},"fee_minor":{"type":"integer"},"net_minor":{"type":"integer"},"description":{"type":"string","nullable":true},"methods":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethod"}},"payer":{"type":"object","properties":{"email":{"type":"string","nullable":true},"name":{"type":"string","nullable":true},"country":{"type":"string","nullable":true}}},"checkout_url":{"type":"string","format":"uri"},"expires_at":{"type":"string","format":"date-time","nullable":true},"metadata":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"},"settled_at":{"type":"string","format":"date-time","nullable":true}}},"PaymentStatusSnapshot":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","enum":["payment.status"]},"status":{"$ref":"#/components/schemas/PaymentStatus"},"settled_at":{"type":"string","format":"date-time","nullable":true},"updated_at":{"type":"string","format":"date-time"}}},"PaymentList":{"type":"object","properties":{"object":{"type":"string","enum":["list"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"has_more":{"type":"boolean"},"next_cursor":{"type":"string","nullable":true}}},"RefundRequest":{"type":"object","properties":{"amount_minor":{"type":"integer","minimum":1,"description":"Omit for full refund."},"reason":{"type":"string","maxLength":200}}},"ApiError":{"type":"object","properties":{"error":{"type":"object","required":["code","message","correlation_id"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"correlation_id":{"type":"string"},"details":{"nullable":true}}}}}}}}