{ "openapi": "3.1.0", "info": { "title": "ecomPay API", "version": "1", "description": "Card payments for any website. Create a checkout session on your server, show the ecomPay card form in the browser, confirm payment by webhook or by fetching the session. Full guide: https://api.ecompay.co.uk/llms-full.txt", "contact": { "email": "support@ecompay.co.uk" } }, "servers": [ { "url": "https://api.ecompay.co.uk" } ], "security": [ { "secretKey": [] } ], "tags": [ { "name": "Checkout sessions" }, { "name": "Payment links" }, { "name": "Refunds" }, { "name": "Webhooks" }, { "name": "Sandbox" } ], "paths": { "/v1/checkout/sessions": { "post": { "tags": [ "Checkout sessions" ], "summary": "Create a checkout session", "operationId": "createCheckoutSession", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Same key and body returns the stored reply for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "integer", "minimum": 1, "maximum": 99999999, "description": "Minor units: 4999 is £49.99." }, "currency": { "type": "string", "minLength": 3, "maxLength": 3, "example": "GBP" }, "reference": { "type": "string", "maxLength": 255, "description": "Your order id." }, "description": { "type": "string", "maxLength": 255, "description": "Shown to the customer." }, "customer": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string", "maxLength": 90 }, "phone": { "type": "string", "maxLength": 32 } } }, "billing_address": { "type": "object", "properties": { "line1": { "type": "string", "maxLength": 255 }, "line2": { "type": "string", "maxLength": 255 }, "city": { "type": "string", "maxLength": 255 }, "postal_code": { "type": "string", "maxLength": 32 }, "state": { "type": "string", "maxLength": 3 }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "2 letter ISO code, for example GB." } } }, "shipping_address": { "type": "object", "properties": { "line1": { "type": "string", "maxLength": 255 }, "line2": { "type": "string", "maxLength": 255 }, "city": { "type": "string", "maxLength": 255 }, "postal_code": { "type": "string", "maxLength": 32 }, "state": { "type": "string", "maxLength": 3 }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "2 letter ISO code, for example GB." } } }, "success_url": { "type": "string", "format": "uri", "description": "https only. Thank-you page the customer is sent to after paying (embedded form and hosted page), with session_id and reference added. Falls back to the dashboard setting." }, "cancel_url": { "type": "string", "format": "uri" }, "expires_in": { "type": "integer", "minimum": 300, "maximum": 86400, "default": 1800 }, "metadata": { "type": "object", "maxProperties": 20, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "example": { "amount": 4999, "currency": "GBP", "reference": "order_1001", "customer": { "email": "sam@example.com" } } } } }, "responses": { "200": { "description": "The new session, with client_secret and url.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "400": { "description": "parameter_missing, parameter_invalid, amount_too_large, currency_not_enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "live_mode_not_enabled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Checkout sessions" ], "summary": "List checkout sessions", "operationId": "listCheckoutSessions", "parameters": [ { "name": "reference", "in": "query", "schema": { "type": "string" }, "description": "Only sessions with this reference." }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CheckoutSession" } } } } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "webhooks_not_available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/checkout/sessions/{id}": { "get": { "tags": [ "Checkout sessions" ], "summary": "Retrieve a checkout session", "description": "If the session is processing, ecomPay checks with the bank first. Safe to call from a thank-you page.", "operationId": "getCheckoutSession", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The session.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutSession" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "session_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/checkout/sessions/{id}/refunds": { "post": { "tags": [ "Refunds" ], "summary": "Refund a paid session", "operationId": "createRefund", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Same key and body returns the stored reply for 24 hours." } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "integer", "minimum": 1, "description": "Leave out to refund everything left." }, "reason": { "type": "string", "maxLength": 255 } } } } } }, "responses": { "200": { "description": "The refund.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "400": { "description": "refund_exceeds_amount, parameter_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "session_not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "session_not_refundable, idempotency_conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "processor_unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/payment_links": { "post": { "tags": [ "Payment links" ], "summary": "Create a payment link", "operationId": "createPaymentLink", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 255 }, "description": "Same key and body returns the stored reply for 24 hours." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "amount", "currency", "description" ], "properties": { "amount": { "type": "integer", "minimum": 1, "maximum": 99999999 }, "currency": { "type": "string", "minLength": 3, "maxLength": 3 }, "description": { "type": "string", "maxLength": 255 }, "kind": { "type": "string", "enum": [ "single", "reusable" ], "default": "single" }, "reference": { "type": "string", "maxLength": 255 }, "customer": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string", "maxLength": 90 } }, "description": "One-off links only." }, "success_url": { "type": "string", "format": "uri" }, "expires_at": { "type": "string", "format": "date-time", "description": "10 minutes to 1 year ahead." }, "metadata": { "type": "object", "maxProperties": 19, "additionalProperties": { "type": "string", "maxLength": 500 } } } }, "example": { "amount": 12500, "currency": "GBP", "description": "Invoice 1042", "reference": "INV-1042", "customer": { "email": "client@example.com" } } } } }, "responses": { "200": { "description": "The new link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "400": { "description": "parameter_missing, parameter_invalid, amount_too_large", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "webhooks_not_available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Payment links" ], "summary": "List payment links", "operationId": "listPaymentLinks", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "active", "paid", "expired", "deactivated" ] } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } } ], "responses": { "200": { "description": "Newest first.", "content": { "application/json": { "schema": { "type": "object", "properties": { "object": { "const": "list" }, "has_more": { "type": "boolean" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PaymentLink" } } } } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/payment_links/{id}": { "get": { "tags": [ "Payment links" ], "summary": "Retrieve a payment link", "operationId": "getPaymentLink", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The link with totals.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/payment_links/{id}/deactivate": { "post": { "tags": [ "Payment links" ], "summary": "Close a payment link", "operationId": "deactivatePaymentLink", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "The closed link.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentLink" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/webhook_endpoints": { "post": { "tags": [ "Webhooks" ], "summary": "Set the webhook address for this mode", "description": "One address per mode. Setting a new one replaces the old and makes a new secret, shown once.", "operationId": "setWebhookEndpoint", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "url" ], "properties": { "url": { "type": "string", "format": "uri", "description": "https only." } } } } } }, "responses": { "200": { "description": "The endpoint with its secret.", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "object": { "const": "webhook_endpoint" }, "url": { "type": "string" }, "secret": { "type": "string", "example": "whsec_..." }, "livemode": { "type": "boolean" } } } } } }, "400": { "description": "parameter_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "webhooks_not_available", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/events/{id}/resend": { "post": { "tags": [ "Webhooks" ], "summary": "Send an event to your webhook again", "operationId": "resendEvent", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "How many deliveries were queued.", "content": { "application/json": { "schema": { "type": "object", "properties": { "resent": { "type": "integer" } } } } } }, "401": { "description": "invalid_api_key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/sandbox/signup": { "post": { "tags": [ "Sandbox" ], "summary": "Get an instant test key (no account)", "security": [], "operationId": "sandboxSignup", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string", "format": "email" }, "business_name": { "type": "string", "maxLength": 90 } } } } } }, "responses": { "200": { "description": "A test secret key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "merchant_id": { "type": "string" }, "secret_key": { "type": "string", "example": "sk_test_..." }, "livemode": { "const": false }, "note": { "type": "string" } } } } } }, "400": { "description": "parameter_invalid", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": { "session.completed": { "post": { "summary": "Sent to your webhook address when a session is paid (and other session.* events with the same shape)", "parameters": [ { "name": "Ecompay-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "t=,v1=" }, { "name": "Ecompay-Event-Id", "in": "header", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Event" } } } }, "responses": { "200": { "description": "Any 2xx within 15 seconds counts as received." } } } } }, "components": { "securitySchemes": { "secretKey": { "type": "http", "scheme": "bearer", "description": "Your sk_test_ or sk_live_ secret key. Server side only." } }, "schemas": { "CheckoutSession": { "type": "object", "properties": { "id": { "type": "string", "example": "cs_test_8HAbtgvZuqCktLdzMouJJ2EE" }, "object": { "type": "string", "const": "checkout.session" }, "status": { "type": "string", "enum": [ "open", "processing", "paid", "failed", "expired", "refunded", "disputed" ] }, "livemode": { "type": "boolean" }, "amount": { "type": "integer", "description": "Minor units." }, "amount_refunded": { "type": "integer" }, "currency": { "type": "string" }, "reference": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "customer": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } } }, "billing_address": { "oneOf": [ { "type": "object", "properties": { "line1": { "type": "string", "maxLength": 255 }, "line2": { "type": "string", "maxLength": 255 }, "city": { "type": "string", "maxLength": 255 }, "postal_code": { "type": "string", "maxLength": 32 }, "state": { "type": "string", "maxLength": 3 }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "2 letter ISO code, for example GB." } } }, { "type": "null" } ] }, "shipping_address": { "oneOf": [ { "type": "object", "properties": { "line1": { "type": "string", "maxLength": 255 }, "line2": { "type": "string", "maxLength": 255 }, "city": { "type": "string", "maxLength": 255 }, "postal_code": { "type": "string", "maxLength": 32 }, "state": { "type": "string", "maxLength": 3 }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "2 letter ISO code, for example GB." } } }, { "type": "null" } ] }, "success_url": { "type": [ "string", "null" ] }, "cancel_url": { "type": [ "string", "null" ] }, "expires_at": { "type": "string", "format": "date-time" }, "attempts": { "type": "integer", "description": "Card attempts so far." }, "failure_code": { "type": [ "string", "null" ], "enum": [ "card_declined", "invalid_card", "expired_card", "risk_declined", "authentication_failed", "processing_error", "processor_unavailable", "account_configuration", null ] }, "failure_message": { "type": [ "string", "null" ], "description": "Written for the customer." }, "payment": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "card_brand": { "type": [ "string", "null" ] }, "card_last4": { "type": [ "string", "null" ] }, "three_d_secure": { "type": [ "string", "null" ], "enum": [ "frictionless", "challenge", null ] }, "authorization_code": { "type": [ "string", "null" ] }, "paid_at": { "type": "string", "format": "date-time" } } } ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "payment_link": { "type": [ "string", "null" ], "description": "The payment link this checkout came from, if any." }, "client_secret": { "type": "string", "description": "Returned to your server only. Pass it to EcomPay.checkout() in the browser." }, "url": { "type": "string", "format": "uri", "description": "Hosted checkout page for this session." } } }, "Refund": { "type": "object", "properties": { "id": { "type": "string", "example": "re_..." }, "object": { "type": "string", "const": "refund" }, "session": { "type": "string" }, "amount": { "type": "integer" }, "status": { "type": "string", "enum": [ "succeeded", "pending", "failed" ] }, "reason": { "type": [ "string", "null" ] }, "failure_message": { "type": [ "string", "null" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "PaymentLink": { "type": "object", "properties": { "id": { "type": "string", "example": "pl_..." }, "object": { "type": "string", "const": "payment_link" }, "url": { "type": "string", "format": "uri", "description": "Send this to the customer." }, "code": { "type": "string" }, "kind": { "type": "string", "enum": [ "single", "reusable" ] }, "status": { "type": "string", "enum": [ "active", "paid", "expired", "deactivated" ] }, "livemode": { "type": "boolean" }, "amount": { "type": "integer" }, "currency": { "type": "string" }, "description": { "type": "string" }, "reference": { "type": [ "string", "null" ] }, "customer": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" } } }, "success_url": { "type": [ "string", "null" ] }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "paid_session": { "type": [ "string", "null" ], "description": "One-off links: the checkout that paid it." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "created_at": { "type": "string", "format": "date-time" }, "payments_count": { "type": "integer" }, "amount_collected": { "type": "integer", "description": "Paid minus refunded, minor units." } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message", "fix", "request_id" ], "properties": { "code": { "type": "string", "enum": [ "invalid_api_key", "live_mode_not_enabled", "parameter_missing", "parameter_invalid", "amount_too_large", "currency_not_enabled", "session_not_found", "idempotency_conflict", "request_in_progress", "session_not_refundable", "refund_exceeds_amount", "webhooks_not_available", "rate_limited", "processor_unavailable", "account_configuration", "invalid_client_secret", "session_not_payable", "payment_in_progress", "card_not_encrypted", "not_found", "unauthorized", "internal_error" ] }, "param": { "type": "string", "description": "The field at fault, when there is one." }, "message": { "type": "string", "description": "What is wrong." }, "fix": { "type": "string", "description": "What to change." }, "doc_url": { "type": "string", "format": "uri" }, "request_id": { "type": "string" } } } } }, "Event": { "type": "object", "properties": { "id": { "type": "string", "example": "evt_..." }, "type": { "type": "string", "enum": [ "session.completed", "session.failed", "session.expired", "session.refunded", "session.disputed", "session.dispute_closed", "session.duplicate_refunded", "payment_link.paid", "payment_link.duplicate_payment", "test.ping" ] }, "created": { "type": "string", "format": "date-time" }, "livemode": { "type": "boolean" }, "data": { "description": "The session (without client_secret or url). session.refunded adds data.refund.", "allOf": [ { "type": "object", "properties": { "id": { "type": "string", "example": "cs_test_8HAbtgvZuqCktLdzMouJJ2EE" }, "object": { "type": "string", "const": "checkout.session" }, "status": { "type": "string", "enum": [ "open", "processing", "paid", "failed", "expired", "refunded", "disputed" ] }, "livemode": { "type": "boolean" }, "amount": { "type": "integer", "description": "Minor units." }, "amount_refunded": { "type": "integer" }, "currency": { "type": "string" }, "reference": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "customer": { "type": "object", "properties": { "email": { "type": "string" }, "name": { "type": "string" }, "phone": { "type": "string" } } }, "billing_address": { "oneOf": [ { "type": "object", "properties": { "line1": { "type": "string", "maxLength": 255 }, "line2": { "type": "string", "maxLength": 255 }, "city": { "type": "string", "maxLength": 255 }, "postal_code": { "type": "string", "maxLength": 32 }, "state": { "type": "string", "maxLength": 3 }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "2 letter ISO code, for example GB." } } }, { "type": "null" } ] }, "shipping_address": { "oneOf": [ { "type": "object", "properties": { "line1": { "type": "string", "maxLength": 255 }, "line2": { "type": "string", "maxLength": 255 }, "city": { "type": "string", "maxLength": 255 }, "postal_code": { "type": "string", "maxLength": 32 }, "state": { "type": "string", "maxLength": 3 }, "country": { "type": "string", "minLength": 2, "maxLength": 2, "description": "2 letter ISO code, for example GB." } } }, { "type": "null" } ] }, "success_url": { "type": [ "string", "null" ] }, "cancel_url": { "type": [ "string", "null" ] }, "expires_at": { "type": "string", "format": "date-time" }, "attempts": { "type": "integer", "description": "Card attempts so far." }, "failure_code": { "type": [ "string", "null" ], "enum": [ "card_declined", "invalid_card", "expired_card", "risk_declined", "authentication_failed", "processing_error", "processor_unavailable", "account_configuration", null ] }, "failure_message": { "type": [ "string", "null" ], "description": "Written for the customer." }, "payment": { "oneOf": [ { "type": "null" }, { "type": "object", "properties": { "card_brand": { "type": [ "string", "null" ] }, "card_last4": { "type": [ "string", "null" ] }, "three_d_secure": { "type": [ "string", "null" ], "enum": [ "frictionless", "challenge", null ] }, "authorization_code": { "type": [ "string", "null" ] }, "paid_at": { "type": "string", "format": "date-time" } } } ] }, "paid_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "metadata": { "type": "object", "additionalProperties": { "type": "string" } }, "payment_link": { "type": [ "string", "null" ], "description": "The payment link this checkout came from, if any." }, "client_secret": { "type": "string", "description": "Returned to your server only. Pass it to EcomPay.checkout() in the browser." }, "url": { "type": "string", "format": "uri", "description": "Hosted checkout page for this session." } } } ] } } } } } }