{"openapi":"3.1.0","info":{"title":"Teyra Pay API","version":"0.1.0","description":"Teyra Pay payment gateway API.\n\n- `/v1` — public API for merchant servers and plugins. Authenticate with a secret key: `Authorization: Bearer sk_test_…`.\n\nMoney is always an integer in minor units with an ISO currency (KWD/BHD/OMR/JOD: 3 decimals; SAR/AED/QAR/EGP: 2).\nLists return `{data, has_more, next_cursor}`; pass `cursor` to get the next page.\nErrors return `{\"error\":{\"code\",\"message\",\"details\"?}}`.\nPOST requests to `/v1` accept an `Idempotency-Key` header.\nWebhooks are signed: `Teyra-Signature: t=<unix>,v1=<hex HMAC-SHA256(secret, \"<t>.<raw body>\")>`."},"components":{"securitySchemes":{"secretKey":{"type":"http","scheme":"bearer","bearerFormat":"sk_test_… / sk_live_…","description":"Secret API key"}},"schemas":{"Payment":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["payment"]},"livemode":{"type":"boolean"},"amount":{"type":"integer"},"currency":{"type":"string"},"amount_refunded":{"type":"integer"},"status":{"type":"string","description":"requires_payment | processing | succeeded | failed | canceled | expired"},"description":{"type":["string","null"]},"reference":{"type":["string","null"]},"customer":{"type":"object","properties":{"name":{"type":["string","null"]},"email":{"type":["string","null"]},"phone":{"type":["string","null"]}},"required":["name","email","phone"],"additionalProperties":false},"payment_method":{"type":["string","null"]},"card":{"anyOf":[{"type":"object","properties":{"brand":{"type":"string"},"last4":{"type":"string"}},"required":["brand","last4"],"additionalProperties":false},{"type":"null"}]},"channel":{"type":"string"},"checkout_url":{"type":"string"},"return_url":{"type":["string","null"]},"failure_code":{"type":["string","null"]},"failure_message":{"type":["string","null"]},"commission":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"Teyra Pay fee for this payment (your rate: percentage + fixed amount), minor units; set once succeeded. The only fee deducted from the payment."},"net":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"What you receive: amount − commission, minor units; set once succeeded. Refunds are deducted from your balance separately."},"metadata":{"type":"object","additionalProperties":{"type":"string"}},"payment_link_id":{"type":["string","null"]},"created_at":{"type":"string","description":"ISO 8601 UTC timestamp"},"paid_at":{"type":["string","null"],"description":"ISO 8601 UTC timestamp"},"expires_at":{"type":"string","description":"ISO 8601 UTC timestamp"}},"required":["id","object","livemode","amount","currency","amount_refunded","status","description","reference","customer","payment_method","card","channel","checkout_url","return_url","failure_code","failure_message","commission","net","metadata","payment_link_id","created_at","paid_at","expires_at"],"additionalProperties":false,"description":"Payment"},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable error code, e.g. `payment_not_found`."},"message":{"type":"string"},"details":{"type":"object","additionalProperties":{}}},"required":["code","message"],"additionalProperties":false}},"required":["error"],"additionalProperties":false,"description":"Error"},"Refund":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["refund"]},"livemode":{"type":"boolean"},"payment_id":{"type":"string"},"amount":{"type":"integer"},"currency":{"type":"string"},"status":{"type":"string","description":"pending | succeeded | failed | canceled"},"reason":{"type":"string"},"created_at":{"type":"string","description":"ISO 8601 UTC timestamp"},"succeeded_at":{"type":["string","null"],"description":"ISO 8601 UTC timestamp"},"failure_message":{"type":["string","null"]}},"required":["id","object","livemode","payment_id","amount","currency","status","reason","created_at","succeeded_at","failure_message"],"additionalProperties":false,"description":"Refund"},"PaymentLink":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["payment_link"]},"livemode":{"type":"boolean"},"url":{"type":"string"},"amount":{"type":"integer"},"currency":{"type":"string"},"description":{"type":"string"},"single_use":{"type":"boolean"},"active":{"type":"boolean"},"expires_at":{"type":["string","null"],"description":"ISO 8601 UTC timestamp"},"payments_count":{"type":"integer"},"paid_count":{"type":"integer"},"created_at":{"type":"string","description":"ISO 8601 UTC timestamp"}},"required":["id","object","livemode","url","amount","currency","description","single_use","active","expires_at","payments_count","paid_count","created_at"],"additionalProperties":false,"description":"PaymentLink"},"Deposit":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["deposit"]},"amount":{"type":"integer"},"currency":{"type":"string"},"bank_name":{"type":["string","null"]},"iban_last4":{"type":["string","null"]},"reference":{"type":["string","null"]},"status":{"type":"string","description":"paid | pending | in_transit | failed | canceled"},"deposited_at":{"type":"string","description":"ISO 8601 UTC timestamp"}},"required":["id","object","amount","currency","bank_name","iban_last4","reference","status","deposited_at"],"additionalProperties":false,"description":"Deposit"},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string"},"object":{"type":"string","enum":["webhook_endpoint"]},"livemode":{"type":"boolean"},"url":{"type":"string"},"events":{"type":"array","items":{"type":"string"}},"active":{"type":"boolean"},"created_at":{"type":"string","description":"ISO 8601 UTC timestamp"},"secret":{"type":"string","description":"Only in the create and roll-secret responses"}},"required":["id","object","livemode","url","events","active","created_at"],"additionalProperties":false,"description":"WebhookEndpoint"}}},"paths":{"/checkout/{payment_id}":{"get":{"summary":"Hosted checkout","tags":["Hosted pages"],"description":"Embedded checkout (default): the Teyra Pay checkout page with the secure card form. Redirect checkout (`CHECKOUT_MODE=redirect`): 302 to the payment page. An HTML error page when the payment is paid, expired or unknown.","parameters":[{"schema":{"type":"string"},"in":"query","name":"lang","required":false},{"schema":{"type":"string","maxLength":64},"in":"path","name":"payment_id","required":true}],"responses":{"200":{"description":"Checkout page (HTML)","content":{"text/html":{"schema":{"type":"string","description":"Checkout page (HTML)"}}}},"302":{"description":"Redirect to the payment page"}}}},"/return":{"get":{"summary":"Customer return from the payment page","tags":["Hosted pages"],"description":"Syncs the payment status, then 302s to the merchant `return_url` with `payment_id` and `status` (`succeeded` | `failed` | `processing`). Payments without a `return_url` get a Teyra Pay result page.","parameters":[{"schema":{"type":"string","maxLength":64},"in":"query","name":"payment","required":true},{"schema":{"type":"string","maxLength":100},"in":"query","name":"paymentId","required":false},{"schema":{"type":"string"},"in":"query","name":"lang","required":false}],"responses":{"302":{"description":"Redirect to the merchant"}}}},"/l/{slug}":{"get":{"summary":"Payment link page","tags":["Hosted pages"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"lang","required":false},{"schema":{"type":"string","maxLength":40},"in":"path","name":"slug","required":true}],"responses":{"200":{"description":"HTML page","content":{"text/html":{"schema":{"type":"string","description":"HTML page"}}}}}},"post":{"summary":"Pay a payment link (form post)","tags":["Hosted pages"],"description":"Creates a payment with `channel=payment_link` and 303s to its checkout. A single-use link can be paid once: only one payment at a time may reach the payment page, and everyone else gets the branded \"link already used\" page (409).","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"email":{"anyOf":[{"type":"string","format":"email","maxLength":254},{"type":"string","enum":[""]}]},"phone":{"type":"string","maxLength":32},"lang":{"type":"string"}},"additionalProperties":false,"default":{}}}}},"parameters":[{"schema":{"type":"string","maxLength":40},"in":"path","name":"slug","required":true}],"responses":{"303":{"description":"Default Response"}}}},"/v1/payments":{"post":{"summary":"Create a payment","tags":["Payments"],"description":"Creates a payment and returns its hosted `checkout_url`. Send the customer there, or set `send_email: true` to have Teyra Pay email it to `customer.email` as an invoice.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"maximum":9000000000000,"description":"Integer amount in minor units"},"currency":{"type":"string","enum":["KWD","BHD","OMR","JOD","SAR","AED","QAR","EGP"]},"return_url":{"type":"string","format":"uri","maxLength":2000,"description":"Where the customer is sent after paying (we append payment_id and status). Live mode: must be https:// (422 on `return_url`); test mode may use http."},"description":{"type":"string","maxLength":500},"reference":{"type":"string","maxLength":100,"description":"Your order number"},"customer":{"type":"object","properties":{"name":{"type":"string","maxLength":200},"email":{"type":"string","format":"email","maxLength":254},"phone":{"type":"string","maxLength":32}},"additionalProperties":false},"payment_method":{"type":"string","enum":["card","mada","knet","apple_pay","google_pay","benefit","stc_pay"],"description":"Pre-select a method on the payment page"},"language":{"type":"string","enum":["en","ar"]},"metadata":{"type":"object","additionalProperties":{"type":"string","maxLength":500}},"expires_in_minutes":{"type":"integer","minimum":5,"maximum":43200,"description":"Default 60"},"channel":{"type":"string","enum":["api","shopify","woocommerce"],"description":"Set by the official plugins; default `api`"},"send_email":{"type":"boolean","description":"Email the payment to `customer.email` as an invoice with a \"Pay now\" button (merchant-branded, in `language`). Default false: API payments are not emailed. Requires `customer.email` (422 on `customer.email`)."}},"required":["amount","currency","return_url"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"header","name":"idempotency-key","required":false,"description":"Same key + same body replays the first response"}],"security":[{"secretKey":[]}],"responses":{"201":{"description":"Payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List payments","tags":["Payments"],"parameters":[{"schema":{"type":"string","enum":["requires_payment","processing","succeeded","failed","canceled","expired"]},"in":"query","name":"status","required":false},{"schema":{"type":"string","maxLength":100},"in":"query","name":"reference","required":false},{"schema":{"type":"string"},"in":"query","name":"created_gte","required":false},{"schema":{"type":"string"},"in":"query","name":"created_lte","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false,"description":"1–100, default 20"},{"schema":{"type":"string","maxLength":500},"in":"query","name":"cursor","required":false,"description":"Opaque cursor from `next_cursor`"}],"security":[{"secretKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Payment"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["data","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payments/{id}":{"get":{"summary":"Retrieve a payment","tags":["Payments"],"parameters":[{"schema":{"type":"string","minLength":3,"maxLength":64},"in":"path","name":"id","required":true}],"security":[{"secretKey":[]}],"responses":{"200":{"description":"Payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Payment"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payments/{id}/refunds":{"post":{"summary":"Refund a payment","tags":["Refunds"],"description":"Full refund by default; pass `amount` for a partial refund.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"maximum":9000000000000,"description":"Default: the amount left to refund"},"reason":{"type":"string","enum":["requested_by_customer","duplicate","fraudulent","other"]}},"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","minLength":3,"maxLength":64},"in":"path","name":"id","required":true},{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"header","name":"idempotency-key","required":false,"description":"Same key + same body replays the first response"}],"security":[{"secretKey":[]}],"responses":{"201":{"description":"Refund","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/refunds/{id}":{"get":{"summary":"Retrieve a refund","tags":["Refunds"],"parameters":[{"schema":{"type":"string","minLength":3,"maxLength":64},"in":"path","name":"id","required":true}],"security":[{"secretKey":[]}],"responses":{"200":{"description":"Refund","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Refund"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/refunds":{"get":{"summary":"List refunds","tags":["Refunds"],"parameters":[{"schema":{"type":"string"},"in":"query","name":"payment_id","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false,"description":"1–100, default 20"},{"schema":{"type":"string","maxLength":500},"in":"query","name":"cursor","required":false,"description":"Opaque cursor from `next_cursor`"}],"security":[{"secretKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Refund"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["data","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payment-links":{"post":{"summary":"Create a payment link","tags":["Payment links"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"integer","exclusiveMinimum":0,"maximum":9000000000000,"description":"Integer amount in minor units"},"currency":{"type":"string","enum":["KWD","BHD","OMR","JOD","SAR","AED","QAR","EGP"]},"description":{"type":"string","minLength":1,"maxLength":500},"single_use":{"type":"boolean"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]}},"required":["amount","currency","description"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"header","name":"idempotency-key","required":false,"description":"Same key + same body replays the first response"}],"security":[{"secretKey":[]}],"responses":{"201":{"description":"PaymentLink","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List payment links","tags":["Payment links"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false,"description":"1–100, default 20"},{"schema":{"type":"string","maxLength":500},"in":"query","name":"cursor","required":false,"description":"Opaque cursor from `next_cursor`"}],"security":[{"secretKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/PaymentLink"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["data","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payment-links/{id}":{"get":{"summary":"Retrieve a payment link","tags":["Payment links"],"parameters":[{"schema":{"type":"string","minLength":3,"maxLength":64},"in":"path","name":"id","required":true}],"security":[{"secretKey":[]}],"responses":{"200":{"description":"PaymentLink","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/payment-links/{id}/deactivate":{"post":{"summary":"Deactivate a payment link","tags":["Payment links"],"parameters":[{"schema":{"type":"string","minLength":3,"maxLength":64},"in":"path","name":"id","required":true},{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"header","name":"idempotency-key","required":false,"description":"Same key + same body replays the first response"}],"security":[{"secretKey":[]}],"responses":{"200":{"description":"PaymentLink","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentLink"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/deposits":{"get":{"summary":"List deposits","tags":["Deposits"],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false,"description":"1–100, default 20"},{"schema":{"type":"string","maxLength":500},"in":"query","name":"cursor","required":false,"description":"Opaque cursor from `next_cursor`"}],"security":[{"secretKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Deposit"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["data","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook-endpoints":{"post":{"summary":"Create a webhook endpoint","tags":["Webhooks"],"description":"The response includes the signing `secret` — it is shown only once.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri","maxLength":2000,"description":"Live endpoints must use https:// (422 on `url`); test endpoints may use http."},"events":{"type":"array","items":{"anyOf":[{"type":"string","enum":["payment.succeeded","payment.failed","payment.canceled","payment.expired","refund.succeeded","refund.failed","deposit.paid"]},{"type":"string","enum":["*"]}]},"minItems":1,"maxItems":20}},"required":["url","events"],"additionalProperties":false}}}},"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":255},"in":"header","name":"idempotency-key","required":false,"description":"Same key + same body replays the first response"}],"security":[{"secretKey":[]}],"responses":{"201":{"description":"WebhookEndpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"get":{"summary":"List webhook endpoints","tags":["Webhooks"],"security":[{"secretKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"has_more":{"type":"boolean"},"next_cursor":{"type":["string","null"]}},"required":["data","has_more","next_cursor"],"additionalProperties":false}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/v1/webhook-endpoints/{id}":{"delete":{"summary":"Delete a webhook endpoint","tags":["Webhooks"],"parameters":[{"schema":{"type":"string","minLength":3,"maxLength":64},"in":"path","name":"id","required":true}],"security":[{"secretKey":[]}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"deleted":{"type":"boolean","enum":[true]}},"required":["id","deleted"],"additionalProperties":false}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"502":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"servers":[{"url":"https://api.teyra.co","description":"Production"},{"url":"http://localhost:4000","description":"Local development"}],"tags":[{"name":"Payments","description":"Create and read payments (secret key)"},{"name":"Refunds"},{"name":"Payment links"},{"name":"Deposits"},{"name":"Webhooks"},{"name":"Hosted pages","description":"Customer-facing pages served by Teyra Pay"},{"name":"System"}]}