{"openapi":"3.1.0","info":{"title":"LINK4PAY Payment Gateway API","description":"\nLINK4PAY Payment Gateway is a REST API for **card, Apple Pay and Google Pay payments with 3-D Secure 2**, a\n**hosted checkout page**, **saved cards** (recurring and one-click payments) and **signed webhooks**.\nAll requests and responses are JSON (UTF-8) over TLS. Two calls take a payment; everything else is optional.\n\n## Integration at a glance\n\n![Hosted checkout – call sequence](/docs/static/integration-flow.svg)\n\n

Download: hosted checkout sequence (SVG) ·\nserver-to-server card sequence (SVG) ·\npayment lifecycle (SVG)

\n\n| Step | Who | What |\n|---|---|---|\n| 1 | your server | `POST /v2/auth/token` with `apiKey` + `apiSecret` → `access_token` (1 hour) |\n| 2 | your server | `POST /v2/payments` with amount, currency, your `reference` (merchant transaction reference), `returnUrl`, `webhookUrl` → `status: pending` + `checkoutUrl` |\n| 3 | your server | redirect the customer to `checkoutUrl` |\n| 4 | gateway | the customer pays (Card · Apple Pay · Google Pay), 3-D Secure runs, the acquirer authorizes and captures |\n| 5 | gateway | the customer returns to `returnUrl?reference=…&status=…`; your `webhookUrl` receives the signed event |\n| 6 | your server | `GET /v2/payments/{reference}` to confirm `captured` before delivering |\n\n## Environments\n\n| Environment | Base URL | Notes |\n|---|---|---|\n| Stage (sandbox) | `https://pgt.link4pay.com` | sandbox acquirers, 3-D Secure test server, Google Pay TEST environment, this documentation |\n| Production | `https://pg.link4pay.com` | live processing, no documentation endpoints |\n\nThe **Servers** selector below this guide points at the environment serving this page.\n\nYour stage and production credentials are different. Call the API **from your server only** - never put the\n`apiSecret` or an access token in a browser or a mobile application.\n\n## Authentication\n\nYou receive an `apiKey` (identifies your merchant account), an `apiSecret` and a **webhook signing secret**.\nThere is one way to authenticate: exchange the credentials for a short-lived **Bearer access token**.\n\n```http\nPOST /v2/auth/token\nContent-Type: application/json\n\n{\"apiKey\": \"ABC24010112345\", \"apiSecret\": \"your_api_secret\"}\n```\n\n```json\n{\"access_token\": \"eyJhbGciOiJIUzI1NiIs…\", \"token_type\": \"Bearer\", \"expires_in\": 3600, \"expires_at\": 1761600000,\n \"merchant\": {\"apiKey\": \"ABC24010112345\", \"name\": \"Example Shop Ltd\", \"acquirer\": \"Paynetics\"}}\n```\n\nThe same endpoint also accepts OAuth2 client credentials (`grant_type=client_credentials&client_id=&client_secret=`,\nform encoded) and HTTP Basic `apiKey:apiSecret`. Send `Authorization: Bearer ` on every other call and\nrequest a new token before it expires; the `apiSecret` itself is never accepted as a Bearer token.\n\nIn this page press **Authorize**, enter your `apiKey` as *client_id* and your `apiSecret` as *client_secret*:\nSwagger UI fetches the token and sends it with every \"Try it out\" request.\n\n## Payment with the hosted checkout\n\nThe recommended flow: the gateway shows one lightweight page with **Card, Apple Pay and Google Pay**, runs 3-D\nSecure and returns the customer to you. No card data touches your systems (no PCI DSS scope).\n\n**Request** - `POST /v2/payments` without `paymentMethod`:\n\n```json\n{\n \"amount\": \"12.00\",\n \"currency\": \"EUR\",\n \"reference\": \"order-00001\",\n \"description\": \"Order #00001\",\n \"customer\": {\"id\": \"cust-42\", \"email\": \"igo.ria@example.com\", \"firstName\": \"Igo\", \"lastName\": \"Ria\", \"phone\": \"+35722123456\"},\n \"billingAddress\": {\"line1\": \"Lemesos Ave 60\", \"city\": \"Nicosia\", \"postalCode\": \"2014\", \"country\": \"CY\"},\n \"returnUrl\": \"https://www.google.com/search?q=payment+return\",\n \"cancelUrl\": \"https://www.google.com/search?q=payment+cancelled\",\n \"webhookUrl\": \"https://www.google.com/search?q=webhook\",\n \"paymentMethods\": [\"card\", \"applepay\", \"googlepay\"],\n \"capture\": true,\n \"language\": \"en\",\n \"metadata\": {\"orderId\": \"00001\"}\n}\n```\n\nOnly `amount`, `currency` and `returnUrl` are required. `paymentMethods` selects what the page offers (default all\nthree; send `[\"card\"]` to hide the wallets - a wallet the merchant's acquirer cannot process is hidden anyway).\n`capture: true` (default) takes the money at once; `capture: false` only reserves it until you call `/capture`.\nThe page shows the billing address fields on the card form, prefilled with what you sent, because the issuer uses\nthem for 3-D Secure; wallets take the address from the wallet sheet. **Response** `201`:\n\n```json\n{\"reference\": \"order-00001\", \"status\": \"pending\", \"amount\": \"12.00\", \"currency\": \"EUR\", \"capture\": true,\n \"paymentMethods\": [\"card\", \"applepay\", \"googlepay\"],\n \"checkoutUrl\": \"https://pgt.link4pay.com/checkout/O8-aYeGzr56bLYOgsdCAuPEFVzNWTRwP\",\n \"nextAction\": {\"type\": \"redirect\", \"url\": \"https://pgt.link4pay.com/checkout/O8-aYeGzr56bLYOgsdCAuPEFVzNWTRwP\"}, \"…\": \"…\"}\n```\n\nRedirect the customer to `checkoutUrl`. The page is valid for **30 minutes** and allows **one payment attempt**;\nafterwards the customer lands on `returnUrl?reference=order-00001&status=captured` (or `declined`, `failed`;\n`cancelUrl?reference=…&status=cancelled` when they cancel). Treat the query string as a hint only and confirm with\n`GET /v2/payments/order-00001` or the webhook.\n\n## Payment without the hosted checkout (card, server-to-server)\n\nFor PCI DSS merchants that collect the card on their own page. 3-D Secure 2 is **always** performed, so send the\ncustomer's browser data and a `returnUrl`.\n\n![Server-to-server card payment – call sequence](/docs/static/server-to-server-flow.svg)\n\n**Request** - `POST /v2/payments` with `paymentMethod.type = card`:\n\n```json\n{\n \"amount\": \"49.90\", \"currency\": \"EUR\", \"reference\": \"order-00002\", \"capture\": true,\n \"customer\": {\"id\": \"cust-42\", \"email\": \"igo.ria@example.com\", \"ip\": \"203.0.113.10\"},\n \"billingAddress\": {\"line1\": \"Lemesos Ave 60\", \"city\": \"Nicosia\", \"postalCode\": \"2014\", \"country\": \"CY\"},\n \"paymentMethod\": {\"type\": \"card\", \"save\": true,\n \"card\": {\"number\": \"4111101011111003\", \"expMonth\": \"12\", \"expYear\": \"2030\", \"cvv\": \"987\", \"holder\": \"Igo Ria\"}},\n \"browser\": {\"acceptHeader\": \"text/html,application/xhtml+xml,*/*;q=0.8\", \"userAgent\": \"Mozilla/5.0 …\",\n \"language\": \"en-GB\", \"colorDepth\": \"24\", \"screenHeight\": \"1117\", \"screenWidth\": \"1728\",\n \"timeZoneOffset\": \"-120\", \"javaEnabled\": false, \"javascriptEnabled\": true},\n \"returnUrl\": \"https://www.google.com/search?q=payment+return\",\n \"webhookUrl\": \"https://www.google.com/search?q=webhook\"\n}\n```\n\nTwo possible answers:\n\n* **Final** (frictionless 3-D Secure): `status` is `captured`, `authorized` or `declined` right away.\n* **The issuer needs the customer**: `status: pending` and `nextAction = {\"type\": \"redirect\", \"url\": \"https://pgt.link4pay.com/3ds/…\"}`.\n Send the customer's browser to that url (redirect or full-page navigation). The gateway completes the 3-D Secure\n method and challenge with the issuer, authorizes at the acquirer and returns the customer to\n `returnUrl?reference=order-00002&status=captured`.\n\n`paymentMethod.save: true` stores the card and returns `paymentMethod.token` for later payments.\n\n## Capture\n\nFor payments created with `capture: false` (funds reserved, status `authorized`). Omit `amount` for the full\namount; a smaller amount captures partially where the acquirer supports it. Afterwards the status is `captured`.\n\n```http\nPOST /v2/payments/booking-7781/capture\n{\"amount\": \"100.00\"}\n```\n\n## Void\n\nCancels an `authorized` payment that was not captured (hotel no-show, order cancelled before shipping).\nCaptured payments are refunded instead. Afterwards the status is `voided`.\n\n```http\nPOST /v2/payments/booking-7781/void\n```\n\n## Refund\n\nReturns money to the customer for a `captured` payment: full, partial, and repeatable until the captured amount is\nreached. `reference` names the refund in your system and must be unique. The payment becomes `partially_refunded`\nor `refunded`. A delayed refund is simply a refund you send later - there is no separate call.\n\n```http\nPOST /v2/payments/order-00001/refund\n{\"amount\": \"5.00\", \"reference\": \"refund-00001-a\"}\n```\n\n```json\n{\"refund\": {\"reference\": \"refund-00001-a\", \"amount\": \"5.00\", \"currency\": \"EUR\", \"acquirerTransactionId\": \"2105834512\", \"status\": \"refunded\"},\n \"payment\": {\"reference\": \"order-00001\", \"status\": \"partially_refunded\", \"refundedAmount\": \"5.00\", \"…\": \"…\"}}\n```\n\n## Recurring and one-click payments\n\n1. **First payment with the customer present** - hosted checkout or server-to-server card with\n `paymentMethod.save: true`; the response carries `paymentMethod.token` (``). Store it with your customer.\n For a subscription set `paymentMethod.seriesType: \"recurring\"` on this first payment.\n2. **Later payments without the customer** - `paymentMethod = {\"type\": \"token\", \"token\": \"\", \"initiator\": \"merchant\",\n \"seriesType\": \"recurring\"}` (fixed schedule) or `\"unscheduled\"` (top-ups, one-click). No 3-D Secure, no redirect:\n the answer is final.\n\n```json\n{\"amount\": \"9.99\", \"currency\": \"EUR\", \"reference\": \"sub-2026-11-cust-42\",\n \"customer\": {\"id\": \"cust-42\", \"email\": \"igo.ria@example.com\"},\n \"paymentMethod\": {\"type\": \"token\", \"token\": \"7Hq2kPz9mN4vL8sR3wXy6bC1dF5gJq2k\", \"initiator\": \"merchant\", \"seriesType\": \"recurring\"},\n \"webhookUrl\": \"https://www.google.com/search?q=webhook\"}\n```\n\n3. **One-click with the customer present** - the same token with `initiator: \"customer\"` (optionally `cvv`):\n 3-D Secure runs like for a card, so send `browser`, `customer.email`, `billingAddress.country` and `returnUrl`.\n\n## Tokenization (saved cards)\n\n| Need | Call |\n|---|---|\n| Save a card without charging it | `POST /v2/tokens` with `card` and `customer.id` → `token` |\n| Save a card during a payment | `paymentMethod.save: true` → `paymentMethod.token` in the payment |\n| Card details of a token (masked) | `GET /v2/tokens/{token}` |\n| All tokens of a customer | `GET /v2/tokens?customerId=cust-42` |\n| Delete a token | `DELETE /v2/tokens/{token}` |\n\nCards are stored encrypted with AWS KMS wrapped keys; the clear card number is never stored. The same card of the\nsame customer returns the existing token.\n\n```json\n{\"card\": {\"number\": \"4111101011111003\", \"expMonth\": \"12\", \"expYear\": \"2030\", \"cvv\": \"987\", \"holder\": \"Igo Ria\"},\n \"customer\": {\"id\": \"cust-42\", \"email\": \"igo.ria@example.com\"}}\n```\n\n```json\n{\"token\": \"7Hq2kPz9mN4vL8sR3wXy6bC1dF5gJq2k\", \"brand\": \"visa\", \"last4\": \"1003\", \"masked\": \"411110XXXXXX1003\",\n \"expMonth\": \"12\", \"expYear\": \"2030\", \"holder\": \"Igo Ria\", \"customerId\": \"cust-42\", \"createdAt\": \"2026-10-27 20:18:01\"}\n```\n\n## Transaction status\n\n`GET /v2/payments/{reference}` returns the full payment at any time: status, amounts, masked card, 3-D Secure\nresult, acquirer transaction id, decline reason, refunded amount. Poll it after the customer returns, or rely on the\nwebhook. A `pending` hosted checkout that was never completed becomes `expired` after 30 minutes.\n\n![Payment lifecycle](/docs/static/payment-lifecycle.svg)\n\n| Status | Meaning | Final |\n|---|---|---|\n| `pending` | waiting for the customer (hosted checkout, 3-D Secure) | no |\n| `authorized` | funds reserved (`capture: false`) - capture or void it | no |\n| `captured` | paid | yes |\n| `declined` | declined by the issuer / acquirer, or 3-D Secure failed (`decline.code`, `decline.message`) | yes |\n| `failed` | technical failure (acquirer or 3-D Secure server unavailable) | yes |\n| `expired` | hosted checkout not completed within 30 minutes | yes |\n| `voided` | authorization cancelled | yes |\n| `partially_refunded` / `refunded` | money returned to the customer | - / yes |\n\n## Apple Pay and Google Pay server-to-server\n\nUse this only when you render the wallet buttons yourself; the hosted checkout already includes both wallets.\n\n* Apple Pay: `paymentMethod = {\"type\": \"applepay\", \"walletToken\": }`.\n* Google Pay: `paymentMethod = {\"type\": \"googlepay\", \"walletToken\": }`.\n\nApple Pay and Google Pay `CRYPTOGRAM_3DS` tokens complete synchronously; Google Pay `PAN_ONLY` cards go through\n3-D Secure (the `nextAction` redirect of the card flow), so send `browser`, `customer.email`, `billingAddress.country`\nand `returnUrl` for them.\n\n## Payouts (money to a card)\n\nSend money **to** a customer's card - winnings, rewards, returned deposits. Available for Clearhaus merchants (other\nacquirers answer `payouts_not_supported`). A payout is final at once: there is no capture, void or refund of a payout,\nand no 3-D Secure (the customer does not authenticate - the money goes to them).\n\n| `paymentMethod` | What happens | Response |\n|---|---|---|\n| *omitted* | **Hosted payout page**: the customer enters the card that should receive the money | `status: pending`, `checkoutUrl` → redirect the customer there |\n| `{\"type\": \"card\", ...}` | payout to the given card (`card.holder` required, no `cvv`) | final `paid` or `declined` |\n| `{\"type\": \"token\", ...}` | payout to a saved card (saved with `/v2/tokens` or `save: true` on a payment) | final `paid` or `declined` |\n\n**Request** `POST /v2/payouts` (card):\n\n```json\n{\n \"amount\": \"25.00\", \"currency\": \"EUR\", \"reference\": \"payout-00001\", \"description\": \"Winnings #00001\",\n \"paymentMethod\": {\"type\": \"card\", \"card\": {\"number\": \"4111101011111003\", \"expMonth\": \"12\", \"expYear\": \"2030\", \"holder\": \"Igo Ria\"}},\n \"customer\": {\"id\": \"cust-42\", \"email\": \"igo.ria@example.com\", \"firstName\": \"Igo\", \"lastName\": \"Ria\"},\n \"webhookUrl\": \"https://www.google.com/search?q=webhook\"\n}\n```\n\n**Response** `201`:\n\n```json\n{\"reference\": \"payout-00001\", \"status\": \"paid\", \"amount\": \"25.00\", \"currency\": \"EUR\",\n \"paymentMethod\": {\"type\": \"card\", \"brand\": \"visa\", \"last4\": \"1003\", \"masked\": \"411110XXXXXX1003\", \"expMonth\": \"12\", \"expYear\": \"2030\", \"holder\": \"Igo Ria\"},\n \"acquirer\": {\"name\": \"clearhaus\", \"transactionId\": \"1b377999-bafb-42b0-a24f-106b312b0b40\", \"responseCode\": \"20000\"},\n \"createdAt\": \"2026-10-28T09:30:00Z\", \"updatedAt\": \"2026-10-28T09:30:02Z\"}\n```\n\n**Saved card**: `\"paymentMethod\": {\"type\": \"token\", \"token\": \"7Hq2kPz9mN4vL8sR3wXy6bC1dF5gJq2k\"}` - the name on the card\ncomes from the saved card or from `customer.firstName` / `lastName`.\n\n**Hosted payout page**: omit `paymentMethod` and send `returnUrl` (and optionally `cancelUrl`, `language`). The answer\nis `status: pending` with `checkoutUrl`; redirect the customer there. The page asks for the card number, the expiry\nand the name on the card (no CVV, no 3-D Secure) and then sends the customer to `returnUrl?reference=...&status=paid`\n(or `declined`). Read the final state with `GET /v2/payouts/{reference}` or take it from the `payout.*` webhook.\n\n| Status | Meaning |\n|---|---|\n| `pending` | hosted payout page created, the customer has not entered a card yet |\n| `paid` | the acquirer accepted the credit; the money reaches the cardholder within a few business days |\n| `declined` | the acquirer refused it (`decline.code`, `decline.message`) |\n| `failed` | the request could not be processed |\n| `expired` | the hosted page was not used in time |\n\n## Idempotency and duplicates\n\nYour `reference` (merchant transaction reference) is the idempotency key - no extra header is needed:\n\n* sending `POST /v2/payments` again with the **same `reference` and the same request** (for example after a timeout)\n returns the existing payment with `200` and the header `Idempotent-Replayed: true` instead of creating a second one;\n* the **same `reference` with different data** (another amount, currency, customer, …) is rejected with\n `409 duplicate_reference`, so an accidental reuse never charges the customer twice.\n\nCard data, wallet tokens, CVV and browser data are not part of the comparison. Always generate one `reference` per\norder attempt and store it before calling the API.\n\n## Webhooks\n\nGive a `webhookUrl` (https) when creating a payment. The gateway POSTs\n\n```json\n{\"event\": \"payment.captured\", \"createdAt\": \"2026-10-27T20:18:09Z\",\n \"payment\": {\"reference\": \"order-00001\", \"status\": \"captured\", \"amount\": \"12.00\", \"currency\": \"EUR\", \"…\": \"…\"}}\n```\n\nwith the headers `X-L4P-Event: payment.captured` and\n`X-L4P-Signature: t=,v1=.\")>` where `secret` is your webhook\nsigning secret. Verify the signature, reject deliveries older than 300 seconds, answer `2xx` within 10 seconds;\nfailed deliveries are retried 3 times with back-off, so handle duplicates by `reference` + `status`.\n\nEvents: `payment.authorized`, `payment.captured`, `payment.declined`, `payment.failed`, `payment.expired`,\n`payment.voided`, `payment.refunded` (the body then also has `refund`).\n\n```python\nimport hmac, hashlib, time\ndef verify(secret: str, body: bytes, header: str) -> bool:\n parts = dict(p.split(\"=\", 1) for p in header.split(\",\"))\n expected = hmac.new(secret.encode(), f\"{parts['t']}.\".encode() + body, hashlib.sha256).hexdigest()\n return abs(time.time() - int(parts[\"t\"])) < 300 and hmac.compare_digest(expected, parts[\"v1\"])\n```\n\n```javascript\nconst crypto = require(\"crypto\");\nfunction verify(secret, rawBody, header) {\n const p = Object.fromEntries(header.split(\",\").map(x => x.split(\"=\")));\n const expected = crypto.createHmac(\"sha256\", secret).update(`${p.t}.`).update(rawBody).digest(\"hex\");\n return Math.abs(Date.now() / 1000 - Number(p.t)) < 300 && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(p.v1));\n}\n```\n\n## Errors\n\nErrors use HTTP status codes and the body `{\"error\": {\"code\": \"\", \"message\": \"...\", \"details\": [...]}}`.\n\n| HTTP | code | When |\n|---|---|---|\n| 400 | `validation_error` | a field is missing or malformed (`details` lists the fields) |\n| 400 | `invalid_card_number`, `card_expired`, `unsupported_card`, `invalid_cvv` | card checks |\n| 400 | `invalid_wallet_token`, `wallet_not_supported`, `acquirer_not_supported`, `invalid_amount` | request cannot be processed |\n| 401 | `unauthorized`, `invalid_token`, `invalid_credentials`, `invalid_api_key` | authentication |\n| 403 | `merchant_not_configured` | merchant account not ready for payments |\n| 404 | `unknown_payment`, `unknown_token`, `not_found` | nothing with that reference / token |\n| 409 | `duplicate_reference`, `invalid_state` | reference already used / operation not allowed in the current status |\n| 402 | `capture_failed`, `refund_failed`, `void_failed` | the acquirer refused the operation (`message` explains) |\n| 413 | `payload_too_large` | body over 256 KB |\n| 500 | `internal_error` | unexpected - retry or contact support |\n\n```json\n{\"error\": {\"code\": \"validation_error\", \"message\": \"The request is not valid\",\n \"details\": [{\"field\": \"amount\", \"message\": \"String should match pattern '^[0-9]{1,10}(\\\\.[0-9]{1,2})?$'\"}]}}\n```\n\n## Testing on Stage\n\nUse `https://pgt.link4pay.com` with your stage credentials. On the hosted checkout (or in `paymentMethod.card`) enter\nany name, any future expiry date and `987` as the CVV, with one of the 3-D Secure test cards:\n\n| 3-D Secure result | Outcome | Card numbers |\n|---|---|---|\n| Frictionless | **Success** - authenticated, payment `captured` / `authorized` | `4111101011111003` · `4111101011112003` · `5100080000002003` · `5100080000000018` |\n| Frictionless | **Fail** - authentication refused, payment `declined` | `4111101011111071` · `4111101011112013` · `5111100000000011` · `5111100000000029` |\n| Challenge | **Manual** - the issuer page asks the customer to confirm | `4111101011111072` · `4111101011112072` · `5100080000000017` · `5100080000000025` |\n\nOther numbers are answered with `declined` / \"Card number not valid for any payment system\". The stage acquirers\nonly accept their own test cards, so after 3-D Secure the gateway substitutes the card number with the acquirer's\nsandbox card. Google Pay runs in the `TEST` environment; Apple Pay requires an Apple sandbox tester account.\nWebhooks are delivered to any https endpoint you provide (for example a request bin).\n\nQuestions or suggestions: **integrations@link4.tech**.\n","version":"2.0.0","contact":{"name":"LINK4PAY","url":"https://link4pay.com"},"x-logo":{"url":"/docs/static/logo.png","altText":"LINK4PAY"}},"servers":[{"url":"https://pgt.link4pay.com","description":"Stage"}],"paths":{"/v2/auth/token":{"post":{"tags":["Authentication"],"summary":"Get an access token","description":"Exchanges your credentials for a Bearer access token.\n\n#### Three ways to send the credentials\n\n| Format | Body / header |\n|---|---|\n| JSON | `{\"apiKey\": \"…\", \"apiSecret\": \"…\"}` |\n| OAuth2 client credentials (form) | `grant_type=client_credentials&client_id=&client_secret=` |\n| HTTP Basic | `Authorization: Basic base64(apiKey:apiSecret)` |\n\n#### Then\n\n* Send `Authorization: Bearer ` on every other call.\n* The token is valid for `expires_in` seconds (1 hour): request a new one before it expires.\n* Tokens are bound to your merchant account; call this endpoint from your server only.","operationId":"getAccessToken","requestBody":{"content":{"application/json":{"schema":{"properties":{"apiKey":{"type":"string","maxLength":20,"minLength":6,"description":"your merchant apiKey"},"apiSecret":{"type":"string","maxLength":64,"minLength":8,"description":"your apiSecret"}},"type":"object","required":["apiKey","apiSecret"]},"example":{"apiKey":"ABC24010112345","apiSecret":"your_api_secret"}},"application/x-www-form-urlencoded":{"schema":{"properties":{"grant_type":{"type":"string","enum":["client_credentials"],"default":"client_credentials"},"client_id":{"type":"string","description":"your apiKey"},"client_secret":{"type":"string","description":"your apiSecret"}},"type":"object","required":["client_id","client_secret"]},"example":{"grant_type":"client_credentials","client_id":"ABC24010112345","client_secret":"your_api_secret"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccessTokenResponse"},"example":{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJBQkMyNDAxMDExMjM0NSIsImlhdCI6MTc2MTU5NjQwMCwiZXhwIjoxNzYxNjAwMDAwLCJqdGkiOiI3YjM0ZDJlMWY4YzA5YTViIiwibWlkIjoxNDYsInNjb3BlIjoiYXBpIn0.V3h2dGlXMmZ4bFhlZ2RWY2w0TmRkNjhIZ1l2WE1Ia2s","token_type":"Bearer","expires_in":3600,"expires_at":1761600000,"merchant":{"apiKey":"ABC24010112345","name":"Example Shop Ltd","acquirer":"Paynetics"}}}}},"401":{"description":"`invalid_credentials` / `invalid_api_key`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"`validation_error`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[]}},"/v2/payments":{"post":{"tags":["Payments"],"summary":"Create a payment","description":"Creates a payment. The `status` and `nextAction` in the answer tell you what to do next.\n\n#### Choose how the customer pays\n\n| `paymentMethod` | What happens | Answer |\n|---|---|---|\n| *omitted* | **Hosted checkout**: the gateway page offers the `paymentMethods` you allow (Card, Apple Pay, Google Pay) and runs 3-D Secure | `status: pending`, `checkoutUrl` → redirect the customer there |\n| `type: card` | **Server-to-server** card, 3-D Secure always (send `browser`, `customer.email`, `billingAddress.country`, `returnUrl`) | final status, or `pending` + `nextAction.url` (gateway 3-D Secure page) |\n| `type: token`, `initiator: customer` | saved card with the customer present, 3-D Secure like a card | same as card |\n| `type: token`, `initiator: merchant` | subscription / one-click without the customer, no 3-D Secure | final status at once |\n| `type: applepay` / `googlepay` | wallet token from your own wallet integration | final status at once (Google Pay `PAN_ONLY`: like card) |\n\n#### Afterwards\n\n1. The customer lands on `returnUrl?reference=…&status=…` (hosted checkout and 3-D Secure redirects).\n2. Your `webhookUrl` receives the signed event (`payment.captured`, `payment.declined`, …).\n3. Confirm with `GET /v2/payments/{reference}` before delivering.\n\n#### Good to know\n\n* `amount` is a string in major units (`\"12.00\"`); JPY and KRW take no decimals.\n* `reference` is **your** unique id of the payment and the key of every other call; it is generated when omitted.\n* `capture: false` only reserves the money (`authorized`); capture or void it later. Default `true`.\n* `paymentMethods` chooses what the hosted checkout shows (default `[\"card\", \"applepay\", \"googlepay\"]`).\n* Retries are safe: sending the same `reference` with the same request again returns the existing payment\n (`200`, header `Idempotent-Replayed: true`); the same `reference` with different data is rejected with `409`.","operationId":"createPayment","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePaymentRequest"},"examples":{"hosted_checkout":{"summary":"Hosted checkout (card · Apple Pay · Google Pay)","description":"No `paymentMethod`: redirect the customer to `checkoutUrl`.","value":{"amount":"12.00","currency":"EUR","reference":"order-00001","description":"Order #00001","customer":{"id":"cust-42","email":"igo.ria@example.com","firstName":"Igo","lastName":"Ria"},"billingAddress":{"line1":"Lemesos Ave 60","city":"Nicosia","postalCode":"2014","country":"CY"},"returnUrl":"https://www.google.com/search?q=payment+return","cancelUrl":"https://www.google.com/search?q=payment+cancelled","webhookUrl":"https://www.google.com/search?q=webhook","language":"en","metadata":{"orderId":"00001"}}},"card_server_to_server":{"summary":"Card payment (server-to-server, 3-D Secure)","description":"PCI DSS merchants only. `browser`, `customer.email`, `billingAddress.country` and `returnUrl` are required.","value":{"amount":"49.90","currency":"EUR","reference":"order-00002","capture":true,"customer":{"id":"cust-42","email":"igo.ria@example.com","ip":"203.0.113.10"},"billingAddress":{"line1":"Lemesos Ave 60","city":"Nicosia","postalCode":"2014","country":"CY"},"paymentMethod":{"type":"card","save":true,"card":{"number":"4111101011111003","expMonth":"12","expYear":"2030","cvv":"987","holder":"Igo Ria"}},"browser":{"acceptHeader":"text/html,application/xhtml+xml,*/*;q=0.8","userAgent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 14_0) AppleWebKit/605.1.15","language":"en-GB","colorDepth":"24","screenHeight":"1117","screenWidth":"1728","timeZoneOffset":"-120","javaEnabled":false,"javascriptEnabled":true},"threeDSecure":{"challengePreference":"auto"},"returnUrl":"https://www.google.com/search?q=payment+return","webhookUrl":"https://www.google.com/search?q=webhook"}},"only_required":{"summary":"Only required fields (hosted checkout)","description":"The page asks the customer for e-mail, name and address; all three payment methods are offered.","value":{"amount":"10.00","currency":"EUR","returnUrl":"https://www.google.com/search?q=payment+return"}},"card_only_checkout":{"summary":"Hosted checkout with card only","description":"`paymentMethods` limits what the page shows; the wallets are hidden.","value":{"amount":"10.00","currency":"EUR","reference":"order-00009","paymentMethods":["card"],"customer":{"email":"igo.ria@example.com"},"returnUrl":"https://www.google.com/search?q=payment+return"}},"authorize_then_capture":{"summary":"Authorize now, capture later","description":"`capture: false` leaves the payment `authorized`; call /capture or /void afterwards.","value":{"amount":"120.00","currency":"EUR","reference":"booking-7781","capture":false,"paymentMethods":["card","applepay"],"customer":{"email":"igo.ria@example.com"},"returnUrl":"https://www.google.com/search?q=booking+return"}},"token_merchant_initiated":{"summary":"Saved card, merchant initiated (subscription)","description":"No customer present, no 3-D Secure; completes synchronously.","value":{"amount":"9.99","currency":"EUR","reference":"sub-2026-11-cust-42","customer":{"id":"cust-42","email":"igo.ria@example.com"},"paymentMethod":{"type":"token","token":"7Hq2kPz9mN4vL8sR3wXy6bC1dF5gJq2k","initiator":"merchant","seriesType":"recurring"},"webhookUrl":"https://www.google.com/search?q=webhook"}},"card_challenge_test":{"summary":"Card payment that needs a challenge (stage test card)","description":"4111101011111072 makes the issuer ask the customer to confirm: the answer is `pending` with `nextAction.url`.","value":{"amount":"25.00","currency":"EUR","reference":"order-00006","customer":{"id":"cust-42","email":"igo.ria@example.com","ip":"203.0.113.10"},"billingAddress":{"line1":"Lemesos Ave 60","city":"Nicosia","postalCode":"2014","country":"CY"},"paymentMethod":{"type":"card","card":{"number":"4111101011111072","expMonth":"12","expYear":"2030","cvv":"987","holder":"Igo Ria"}},"browser":{"userAgent":"Mozilla/5.0","language":"en","colorDepth":"24","screenHeight":"900","screenWidth":"1440","timeZoneOffset":"0","javaEnabled":false,"javascriptEnabled":true},"returnUrl":"https://www.google.com/search?q=payment+return"}},"card_declined_test":{"summary":"Card payment refused by 3-D Secure (stage test card)","description":"4111101011111071 fails the authentication: the answer is final with `status: declined`.","value":{"amount":"25.00","currency":"EUR","reference":"order-00007","customer":{"id":"cust-42","email":"igo.ria@example.com","ip":"203.0.113.10"},"billingAddress":{"line1":"Lemesos Ave 60","city":"Nicosia","postalCode":"2014","country":"CY"},"paymentMethod":{"type":"card","card":{"number":"4111101011111071","expMonth":"12","expYear":"2030","cvv":"987","holder":"Igo Ria"}},"browser":{"userAgent":"Mozilla/5.0","language":"en","colorDepth":"24","screenHeight":"900","screenWidth":"1440","timeZoneOffset":"0","javaEnabled":false,"javascriptEnabled":true},"returnUrl":"https://www.google.com/search?q=payment+return"}},"subscription_first_payment":{"summary":"Subscription: first payment, card saved (hosted checkout)","description":"`seriesType: recurring` on the first payment; the token for the next charges arrives in the webhook / GET as `paymentMethod.token`.","value":{"amount":"9.99","currency":"EUR","reference":"sub-2026-10-cust-42","description":"Monthly plan","customer":{"id":"cust-42","email":"igo.ria@example.com"},"returnUrl":"https://www.google.com/search?q=payment+return","webhookUrl":"https://www.google.com/search?q=webhook"}},"jpy_no_decimals":{"summary":"Currency without decimals (JPY)","value":{"amount":"1500","currency":"JPY","reference":"order-00008","returnUrl":"https://www.google.com/search?q=payment+return"}},"token_customer_initiated":{"summary":"Saved card, customer present (3-D Secure)","value":{"amount":"25.00","currency":"EUR","reference":"order-00003","customer":{"id":"cust-42","email":"igo.ria@example.com"},"billingAddress":{"country":"CY","city":"Nicosia","postalCode":"2014","line1":"Lemesos Ave 60"},"paymentMethod":{"type":"token","token":"7Hq2kPz9mN4vL8sR3wXy6bC1dF5gJq2k","cvv":"987","initiator":"customer"},"browser":{"userAgent":"Mozilla/5.0","language":"en","colorDepth":"24","screenHeight":"900","screenWidth":"1440","timeZoneOffset":"0","javaEnabled":false,"javascriptEnabled":true},"returnUrl":"https://www.google.com/search?q=payment+return"}},"apple_pay":{"summary":"Apple Pay token (server-to-server)","description":"`walletToken` is `ApplePayPayment.token.paymentData` from your own Apple Pay JS integration.","value":{"amount":"12.00","currency":"EUR","reference":"order-00004","customer":{"email":"igo.ria@example.com"},"paymentMethod":{"type":"applepay","walletToken":{"version":"EC_v1","data":"","signature":"","header":{"ephemeralPublicKey":"","publicKeyHash":"","transactionId":""}}}}},"google_pay":{"summary":"Google Pay token (server-to-server)","description":"`walletToken` is `paymentMethodData.tokenizationData.token` parsed as JSON.","value":{"amount":"12.00","currency":"EUR","reference":"order-00005","customer":{"email":"igo.ria@example.com"},"billingAddress":{"country":"CY","city":"Nicosia","postalCode":"2014","line1":"Lemesos Ave 60"},"paymentMethod":{"type":"googlepay","walletToken":{"protocolVersion":"ECv2","signature":"","intermediateSigningKey":{"signedKey":"","signatures":[""]},"signedMessage":""}},"returnUrl":"https://www.google.com/search?q=payment+return"}}}}},"required":true},"responses":{"201":{"description":"Payment created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"},"examples":{"hosted_checkout":{"summary":"Hosted checkout - redirect the customer","value":{"reference":"order-00001","status":"pending","amount":"12.00","currency":"EUR","capture":true,"paymentMethods":["card","applepay","googlepay"],"description":"Order #00001","customer":{"id":"cust-42","email":"igo.ria@example.com"},"capturedAmount":"0.00","refundedAmount":"0.00","returnUrl":"https://www.google.com/search?q=payment+return","webhookUrl":"https://www.google.com/search?q=webhook","metadata":{"orderId":"00001"},"createdAt":"2026-10-27T20:18:01Z","updatedAt":"2026-10-27T20:18:01Z","checkoutUrl":"https://pgt.link4pay.com/checkout/O8-aYeGzr56bLYOgsdCAuPEFVzNWTRwP","nextAction":{"type":"redirect","url":"https://pgt.link4pay.com/checkout/O8-aYeGzr56bLYOgsdCAuPEFVzNWTRwP"}}},"captured":{"summary":"Final: captured (frictionless 3-D Secure or wallet)","value":{"reference":"order-00001","status":"captured","amount":"12.00","currency":"EUR","capture":true,"paymentMethods":["card","applepay","googlepay"],"description":"Order #00001","customer":{"id":"cust-42","email":"igo.ria@example.com"},"billingAddress":{"line1":"Lemesos Ave 60","city":"Nicosia","postalCode":"2014","country":"CY"},"paymentMethod":{"type":"card","brand":"visa","last4":"1003","masked":"411110XXXXXX1003","expMonth":"12","expYear":"2030","holder":"Igo Ria"},"threeDSecure":{"status":"Y","version":"2.2.0","eci":"05","dsTransId":"f38e6948-5388-41a6-bca4-b49723c19437","challenged":false},"acquirer":{"name":"paynetics","transactionId":"2105834471","responseCode":"00"},"capturedAmount":"12.00","refundedAmount":"0.00","returnUrl":"https://www.google.com/search?q=payment+return","webhookUrl":"https://www.google.com/search?q=webhook","metadata":{"orderId":"00001"},"createdAt":"2026-10-27T20:18:01Z","updatedAt":"2026-10-27T20:18:09Z"}},"threeds_redirect":{"summary":"3-D Secure needs the customer - redirect","value":{"reference":"order-00001","status":"pending","amount":"12.00","currency":"EUR","capture":true,"paymentMethods":["card","applepay","googlepay"],"description":"Order #00001","customer":{"id":"cust-42","email":"igo.ria@example.com"},"paymentMethod":{"type":"card","brand":"visa","last4":"1003","masked":"411110XXXXXX1003","expMonth":"12","expYear":"2030","holder":"Igo Ria"},"capturedAmount":"0.00","refundedAmount":"0.00","returnUrl":"https://www.google.com/search?q=payment+return","webhookUrl":"https://www.google.com/search?q=webhook","metadata":{"orderId":"00001"},"createdAt":"2026-10-27T20:18:01Z","updatedAt":"2026-10-27T20:18:01Z","nextAction":{"type":"redirect","url":"https://pgt.link4pay.com/3ds/9f1c2b7e4a5d4c0e8b6a1d2f3e4c5b6a"}}},"declined":{"summary":"Final: declined","value":{"reference":"order-00001","status":"declined","amount":"12.00","currency":"EUR","capture":true,"paymentMethods":["card","applepay","googlepay"],"description":"Order #00001","customer":{"id":"cust-42","email":"igo.ria@example.com"},"billingAddress":{"line1":"Lemesos Ave 60","city":"Nicosia","postalCode":"2014","country":"CY"},"paymentMethod":{"type":"card","brand":"visa","last4":"1003","masked":"411110XXXXXX1003","expMonth":"12","expYear":"2030","holder":"Igo Ria"},"threeDSecure":{"status":"Y","version":"2.2.0","eci":"05","dsTransId":"f38e6948-5388-41a6-bca4-b49723c19437","challenged":false},"acquirer":{"name":"paynetics","transactionId":"2105834488","responseCode":"05","message":"Do not honour"},"decline":{"code":"05","message":"Do not honour"},"capturedAmount":"0.00","refundedAmount":"0.00","returnUrl":"https://www.google.com/search?q=payment+return","webhookUrl":"https://www.google.com/search?q=webhook","metadata":{"orderId":"00001"},"createdAt":"2026-10-27T20:18:01Z","updatedAt":"2026-10-27T20:18:09Z"}}}}}},"200":{"description":"Idempotent replay: the same `reference` with the same request was already created (header `Idempotent-Replayed: true`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"409":{"description":"`duplicate_reference` - the reference was already used with a different request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Validation error or request that cannot be processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing / invalid credentials or access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v2/payments/{reference}":{"get":{"tags":["Payments"],"summary":"Get a payment","description":"Returns the current state of a payment: status, amounts, masked card, 3-D Secure result, acquirer\ntransaction id, decline reason and refunded amount.\n\n#### When to call it\n\n* after the customer returned to `returnUrl` - never trust the query string alone;\n* when a webhook did not arrive, or to reconcile at the end of the day;\n* a `pending` hosted checkout that was never completed becomes `expired` after 30 minutes.\n\nSee the **Payment lifecycle** diagram in the guide for every status and transition.","operationId":"getPayment","parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","description":"Your payment reference (the `reference` of the payment)","examples":["order-00001"],"title":"Reference"},"description":"Your payment reference (the `reference` of the payment)"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"},"examples":{"captured":{"summary":"Captured","value":{"reference":"order-00001","status":"captured","amount":"12.00","currency":"EUR","capture":true,"paymentMethods":["card","applepay","googlepay"],"description":"Order #00001","customer":{"id":"cust-42","email":"igo.ria@example.com"},"billingAddress":{"line1":"Lemesos Ave 60","city":"Nicosia","postalCode":"2014","country":"CY"},"paymentMethod":{"type":"card","brand":"visa","last4":"1003","masked":"411110XXXXXX1003","expMonth":"12","expYear":"2030","holder":"Igo Ria"},"threeDSecure":{"status":"Y","version":"2.2.0","eci":"05","dsTransId":"f38e6948-5388-41a6-bca4-b49723c19437","challenged":false},"acquirer":{"name":"paynetics","transactionId":"2105834471","responseCode":"00"},"capturedAmount":"12.00","refundedAmount":"0.00","returnUrl":"https://www.google.com/search?q=payment+return","webhookUrl":"https://www.google.com/search?q=webhook","metadata":{"orderId":"00001"},"createdAt":"2026-10-27T20:18:01Z","updatedAt":"2026-10-27T20:18:09Z"}},"pending":{"summary":"Pending (hosted checkout open)","value":{"reference":"order-00001","status":"pending","amount":"12.00","currency":"EUR","capture":true,"paymentMethods":["card","applepay","googlepay"],"description":"Order #00001","customer":{"id":"cust-42","email":"igo.ria@example.com"},"capturedAmount":"0.00","refundedAmount":"0.00","returnUrl":"https://www.google.com/search?q=payment+return","webhookUrl":"https://www.google.com/search?q=webhook","metadata":{"orderId":"00001"},"createdAt":"2026-10-27T20:18:01Z","updatedAt":"2026-10-27T20:18:01Z","checkoutUrl":"https://pgt.link4pay.com/checkout/O8-aYeGzr56bLYOgsdCAuPEFVzNWTRwP","nextAction":{"type":"redirect","url":"https://pgt.link4pay.com/checkout/O8-aYeGzr56bLYOgsdCAuPEFVzNWTRwP"}}},"declined":{"summary":"Declined","value":{"reference":"order-00001","status":"declined","amount":"12.00","currency":"EUR","capture":true,"paymentMethods":["card","applepay","googlepay"],"description":"Order #00001","customer":{"id":"cust-42","email":"igo.ria@example.com"},"billingAddress":{"line1":"Lemesos Ave 60","city":"Nicosia","postalCode":"2014","country":"CY"},"paymentMethod":{"type":"card","brand":"visa","last4":"1003","masked":"411110XXXXXX1003","expMonth":"12","expYear":"2030","holder":"Igo Ria"},"threeDSecure":{"status":"Y","version":"2.2.0","eci":"05","dsTransId":"f38e6948-5388-41a6-bca4-b49723c19437","challenged":false},"acquirer":{"name":"paynetics","transactionId":"2105834488","responseCode":"05","message":"Do not honour"},"decline":{"code":"05","message":"Do not honour"},"capturedAmount":"0.00","refundedAmount":"0.00","returnUrl":"https://www.google.com/search?q=payment+return","webhookUrl":"https://www.google.com/search?q=webhook","metadata":{"orderId":"00001"},"createdAt":"2026-10-27T20:18:01Z","updatedAt":"2026-10-27T20:18:09Z"}}}}}},"400":{"description":"Validation error or request that cannot be processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing / invalid credentials or access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Unknown payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v2/payments/{reference}/capture":{"post":{"tags":["Payments"],"summary":"Capture an authorized payment","description":"Captures a payment created with `capture: false` (status `authorized`, funds reserved).\n\n* Omit `amount` (or send an empty body) to capture the full authorized amount.\n* A smaller `amount` captures partially where the acquirer supports it.\n* Afterwards the status is `captured`; the webhook `payment.captured` is sent.\n\nTypical use: ship first, charge when the parcel leaves; hotel bookings; marketplaces.","operationId":"capturePayment","parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","description":"Your payment reference (the `reference` of the payment)","examples":["order-00001"],"title":"Reference"},"description":"Your payment reference (the `reference` of the payment)"}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AmountRequest"},{"type":"null"}],"title":"Body"},"examples":{"full":{"summary":"Full amount","value":{}},"partial":{"summary":"Partial amount","value":{"amount":"100.00"}}}}}},"responses":{"200":{"description":"Captured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"},"example":{"reference":"order-00001","status":"captured","amount":"12.00","currency":"EUR","capture":true,"paymentMethods":["card","applepay","googlepay"],"description":"Order #00001","customer":{"id":"cust-42","email":"igo.ria@example.com"},"billingAddress":{"line1":"Lemesos Ave 60","city":"Nicosia","postalCode":"2014","country":"CY"},"paymentMethod":{"type":"card","brand":"visa","last4":"1003","masked":"411110XXXXXX1003","expMonth":"12","expYear":"2030","holder":"Igo Ria"},"threeDSecure":{"status":"Y","version":"2.2.0","eci":"05","dsTransId":"f38e6948-5388-41a6-bca4-b49723c19437","challenged":false},"acquirer":{"name":"paynetics","transactionId":"2105834471","responseCode":"00"},"capturedAmount":"12.00","refundedAmount":"0.00","returnUrl":"https://www.google.com/search?q=payment+return","webhookUrl":"https://www.google.com/search?q=webhook","metadata":{"orderId":"00001"},"createdAt":"2026-10-27T20:18:01Z","updatedAt":"2026-10-27T20:18:09Z"}}}},"402":{"description":"`capture_failed` - refused by the acquirer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`invalid_state` - only `authorized` payments can be captured","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Validation error or request that cannot be processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing / invalid credentials or access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Unknown payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v2/payments/{reference}/refund":{"post":{"tags":["Payments"],"summary":"Refund a captured payment","description":"Returns money to the customer for a `captured` (or `partially_refunded`) payment.\n\n* Omit `amount` to refund everything that is left; send a smaller `amount` for a partial refund.\n* Repeat partial refunds until the captured amount is reached.\n* `reference` names the refund in your system and must be unique (generated when omitted).\n* The answer carries the `refund` and the updated `payment` (`partially_refunded` or `refunded`).\n\nA delayed refund is simply a refund sent later - there is no separate call.","operationId":"refundPayment","parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","description":"Your payment reference (the `reference` of the payment)","examples":["order-00001"],"title":"Reference"},"description":"Your payment reference (the `reference` of the payment)"}],"requestBody":{"content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/AmountRequest"},{"type":"null"}],"title":"Body"},"examples":{"full":{"summary":"Refund everything left","value":{}},"partial":{"summary":"Partial refund with your reference","value":{"amount":"5.00","reference":"refund-00001-a"}}}}}},"responses":{"200":{"description":"Refund accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundResponse"},"example":{"refund":{"reference":"R-5f4a1d4e-8f0e-4e3b-9d12-9d2c0a9a1b22","amount":"5.00","currency":"EUR","acquirerTransactionId":"2105834512","status":"refunded"},"payment":{"reference":"order-00001","status":"partially_refunded","amount":"12.00","currency":"EUR","capture":true,"paymentMethods":["card","applepay","googlepay"],"description":"Order #00001","customer":{"id":"cust-42","email":"igo.ria@example.com"},"billingAddress":{"line1":"Lemesos Ave 60","city":"Nicosia","postalCode":"2014","country":"CY"},"paymentMethod":{"type":"card","brand":"visa","last4":"1003","masked":"411110XXXXXX1003","expMonth":"12","expYear":"2030","holder":"Igo Ria"},"threeDSecure":{"status":"Y","version":"2.2.0","eci":"05","dsTransId":"f38e6948-5388-41a6-bca4-b49723c19437","challenged":false},"acquirer":{"name":"paynetics","transactionId":"2105834471","responseCode":"00"},"capturedAmount":"12.00","refundedAmount":"5.00","returnUrl":"https://www.google.com/search?q=payment+return","webhookUrl":"https://www.google.com/search?q=webhook","metadata":{"orderId":"00001"},"createdAt":"2026-10-27T20:18:01Z","updatedAt":"2026-10-27T20:18:09Z"}}}}},"402":{"description":"`refund_failed` - refused by the acquirer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`invalid_state` / `duplicate_reference`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Validation error or request that cannot be processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing / invalid credentials or access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Unknown payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v2/payments/{reference}/void":{"post":{"tags":["Payments"],"summary":"Void an authorized payment","description":"Cancels an `authorized` payment that was not captured (created with `capture: false`).\n\n* Nothing to send: the full authorization is released; the status becomes `voided`.\n* Captured payments cannot be voided - refund them instead.","operationId":"voidPayment","parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","description":"Your payment reference (the `reference` of the payment)","examples":["order-00001"],"title":"Reference"},"description":"Your payment reference (the `reference` of the payment)"}],"responses":{"200":{"description":"Voided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"},"example":{"reference":"order-00001","status":"voided","amount":"12.00","currency":"EUR","capture":true,"paymentMethods":["card","applepay","googlepay"],"description":"Order #00001","customer":{"id":"cust-42","email":"igo.ria@example.com"},"billingAddress":{"line1":"Lemesos Ave 60","city":"Nicosia","postalCode":"2014","country":"CY"},"paymentMethod":{"type":"card","brand":"visa","last4":"1003","masked":"411110XXXXXX1003","expMonth":"12","expYear":"2030","holder":"Igo Ria"},"threeDSecure":{"status":"Y","version":"2.2.0","eci":"05","dsTransId":"f38e6948-5388-41a6-bca4-b49723c19437","challenged":false},"acquirer":{"name":"paynetics","transactionId":"2105834471","responseCode":"00"},"capturedAmount":"0.00","refundedAmount":"0.00","returnUrl":"https://www.google.com/search?q=payment+return","webhookUrl":"https://www.google.com/search?q=webhook","metadata":{"orderId":"00001"},"createdAt":"2026-10-27T20:18:01Z","updatedAt":"2026-10-27T20:18:09Z"}}}},"402":{"description":"`void_failed` - refused by the acquirer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"`invalid_state` - only `authorized` payments can be voided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Validation error or request that cannot be processed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing / invalid credentials or access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Unknown payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v2/payouts":{"post":{"tags":["Payouts"],"summary":"Create a payout","description":"Sends money **to** a card (winnings, rewards, returned deposits). Available for Clearhaus merchants; other\nacquirers answer `payouts_not_supported`. A payout is final at once - there is no capture, void or refund of a payout.\n\n| `paymentMethod` | What happens | Response |\n|---|---|---|\n| *omitted* | **Hosted payout page**: the customer enters the card that should receive the money (`returnUrl` required) | `status: pending`, `checkoutUrl` → redirect the customer there |\n| `{\"type\": \"card\", \"card\": {...}}` | payout to the given card; `card.holder` (name on card) is required, `cvv` is not used | final `paid` or `declined` |\n| `{\"type\": \"token\", \"token\": \"...\"}` | payout to a saved card (see /v2/tokens) | final `paid` or `declined` |\n\n* `reference` is your payout reference and the idempotency key: the same reference with the same request replays the\n stored answer (`200`, header `Idempotent-Replayed: true`); with different data it is rejected with `409`. Payments and\n payouts share the reference space of a merchant.\n* The money usually reaches the cardholder's account within a few business days (depends on the issuer).\n* Webhooks: `payout.paid`, `payout.declined`, `payout.failed`, `payout.expired` (hosted page not used in time), the payout under `payout`.","operationId":"createPayout","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePayoutRequest"},"examples":{"card_payout":{"summary":"Payout to a card","description":"The name on the card is required: the card schemes check it for payouts.","value":{"amount":"25.00","currency":"EUR","reference":"payout-00001","description":"Winnings #00001","paymentMethod":{"type":"card","card":{"number":"4111101011111003","expMonth":"12","expYear":"2030","holder":"Igo Ria"}},"customer":{"id":"cust-42","email":"igo.ria@example.com","firstName":"Igo","lastName":"Ria"},"billingAddress":{"line1":"Lemesos Ave 60","city":"Nicosia","postalCode":"2014","country":"CY"},"webhookUrl":"https://www.google.com/search?q=webhook","metadata":{"payoutBatch":"2026-10"}}},"token_payout":{"summary":"Payout to a saved card (token)","description":"The card was saved with /v2/tokens or with `save: true` on a payment; the name on the card comes from the saved card or from `customer.firstName` / `lastName`.","value":{"amount":"25.00","currency":"EUR","reference":"payout-00002","description":"Winnings #00002","paymentMethod":{"type":"token","token":"7Hq2kPz9mN4vL8sR3wXy6bC1dF5gJq2k"},"customer":{"id":"cust-42","email":"igo.ria@example.com","firstName":"Igo","lastName":"Ria"},"webhookUrl":"https://www.google.com/search?q=webhook"}},"hosted_payout":{"summary":"Hosted payout page","description":"No `paymentMethod`: redirect the customer to `checkoutUrl`, they enter the card that should receive the money.","value":{"amount":"25.00","currency":"EUR","reference":"payout-00003","description":"Winnings #00003","customer":{"id":"cust-42","email":"igo.ria@example.com"},"returnUrl":"https://www.google.com/search?q=payout+return","cancelUrl":"https://www.google.com/search?q=payout+cancelled","webhookUrl":"https://www.google.com/search?q=webhook","language":"en"}},"mastercard_test_card":{"summary":"Payout to a Mastercard test card","value":{"amount":"10.00","currency":"EUR","reference":"payout-00005","paymentMethod":{"type":"card","card":{"number":"5100080000002003","expMonth":"12","expYear":"2030","holder":"Igo Ria"}},"customer":{"id":"cust-42","email":"igo.ria@example.com","firstName":"Igo","lastName":"Ria"}}},"only_required":{"summary":"Only required fields (card)","value":{"amount":"5.00","currency":"EUR","paymentMethod":{"type":"card","card":{"number":"4111101011111003","expMonth":"12","expYear":"2030","holder":"Igo Ria"}}}}}}},"required":true},"responses":{"201":{"description":"Payout created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutResponse"},"examples":{"paid":{"summary":"Final: paid (card)","value":{"reference":"payout-00001","status":"paid","amount":"25.00","currency":"EUR","description":"Winnings #00001","customer":{"id":"cust-42","email":"igo.ria@example.com","firstName":"Igo","lastName":"Ria"},"billingAddress":{"line1":"Lemesos Ave 60","city":"Nicosia","postalCode":"2014","country":"CY"},"paymentMethod":{"type":"card","brand":"visa","last4":"1003","masked":"411110XXXXXX1003","expMonth":"12","expYear":"2030","holder":"Igo Ria"},"acquirer":{"name":"clearhaus","transactionId":"1b377999-bafb-42b0-a24f-106b312b0b40","responseCode":"20000"},"webhookUrl":"https://www.google.com/search?q=webhook","metadata":{"payoutBatch":"2026-10"},"createdAt":"2026-10-28T09:30:00Z","updatedAt":"2026-10-28T09:30:02Z"}},"paid_token":{"summary":"Final: paid (saved card)","value":{"reference":"payout-00002","status":"paid","amount":"25.00","currency":"EUR","description":"Winnings #00001","customer":{"id":"cust-42","email":"igo.ria@example.com","firstName":"Igo","lastName":"Ria"},"billingAddress":{"line1":"Lemesos Ave 60","city":"Nicosia","postalCode":"2014","country":"CY"},"paymentMethod":{"type":"token","brand":"visa","last4":"1003","masked":"411110XXXXXX1003","expMonth":"12","expYear":"2030","holder":"Igo Ria","token":"7Hq2kPz9mN4vL8sR3wXy6bC1dF5gJq2k"},"acquirer":{"name":"clearhaus","transactionId":"1b377999-bafb-42b0-a24f-106b312b0b40","responseCode":"20000"},"webhookUrl":"https://www.google.com/search?q=webhook","metadata":{"payoutBatch":"2026-10"},"createdAt":"2026-10-28T09:30:00Z","updatedAt":"2026-10-28T09:30:02Z"}},"hosted":{"summary":"Hosted payout page - redirect the customer","value":{"reference":"payout-00003","status":"pending","amount":"25.00","currency":"EUR","description":"Winnings #00003","customer":{"id":"cust-42","email":"igo.ria@example.com"},"returnUrl":"https://www.google.com/search?q=payout+return","webhookUrl":"https://www.google.com/search?q=webhook","createdAt":"2026-10-28T09:30:00Z","updatedAt":"2026-10-28T09:30:00Z","checkoutUrl":"https://pgt.link4pay.com/checkout/O8-aYeGzr56bLYOgsdCAuPEFVzNWTRwP","nextAction":{"type":"redirect","url":"https://pgt.link4pay.com/checkout/O8-aYeGzr56bLYOgsdCAuPEFVzNWTRwP"}}},"declined":{"summary":"Final: declined","value":{"reference":"payout-00004","status":"declined","amount":"25.00","currency":"EUR","description":"Winnings #00001","customer":{"id":"cust-42","email":"igo.ria@example.com","firstName":"Igo","lastName":"Ria"},"billingAddress":{"line1":"Lemesos Ave 60","city":"Nicosia","postalCode":"2014","country":"CY"},"paymentMethod":{"type":"card","brand":"visa","last4":"1003","masked":"411110XXXXXX1003","expMonth":"12","expYear":"2030","holder":"Igo Ria"},"acquirer":{"name":"clearhaus","responseCode":"40110"},"decline":{"code":"40110","message":"Invalid card number"},"webhookUrl":"https://www.google.com/search?q=webhook","metadata":{"payoutBatch":"2026-10"},"createdAt":"2026-10-28T09:30:00Z","updatedAt":"2026-10-28T09:30:02Z"}}}}}},"200":{"description":"Idempotent replay: the same `reference` with the same request was already created (header `Idempotent-Replayed: true`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutResponse"}}}},"409":{"description":"`duplicate_reference` - the reference was already used with a different request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"400":{"description":"Validation error, `payouts_not_supported` (acquirer without payouts) or `holder_required`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing / invalid credentials or access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Unknown payout (`unknown_payout`) or unknown saved card (`unknown_token`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v2/payouts/{reference}":{"get":{"tags":["Payouts"],"summary":"Get a payout","description":"Current state of a payout by your `reference`. Poll it after the hosted payout page sent the customer back,\nor rely on the webhooks. A payment reference is not found here (payments live under `/v2/payments`).","operationId":"getPayout","parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","description":"Your payout reference (the `reference` of the payout)","examples":["payout-00001"],"title":"Reference"},"description":"Your payout reference (the `reference` of the payout)"}],"responses":{"200":{"description":"Current state of the payout","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayoutResponse"},"examples":{"paid":{"summary":"Paid","value":{"reference":"payout-00001","status":"paid","amount":"25.00","currency":"EUR","description":"Winnings #00001","customer":{"id":"cust-42","email":"igo.ria@example.com","firstName":"Igo","lastName":"Ria"},"billingAddress":{"line1":"Lemesos Ave 60","city":"Nicosia","postalCode":"2014","country":"CY"},"paymentMethod":{"type":"card","brand":"visa","last4":"1003","masked":"411110XXXXXX1003","expMonth":"12","expYear":"2030","holder":"Igo Ria"},"acquirer":{"name":"clearhaus","transactionId":"1b377999-bafb-42b0-a24f-106b312b0b40","responseCode":"20000"},"webhookUrl":"https://www.google.com/search?q=webhook","metadata":{"payoutBatch":"2026-10"},"createdAt":"2026-10-28T09:30:00Z","updatedAt":"2026-10-28T09:30:02Z"}},"pending":{"summary":"Hosted page not used yet","value":{"reference":"payout-00003","status":"pending","amount":"25.00","currency":"EUR","description":"Winnings #00003","customer":{"id":"cust-42","email":"igo.ria@example.com"},"returnUrl":"https://www.google.com/search?q=payout+return","webhookUrl":"https://www.google.com/search?q=webhook","createdAt":"2026-10-28T09:30:00Z","updatedAt":"2026-10-28T09:30:00Z","checkoutUrl":"https://pgt.link4pay.com/checkout/O8-aYeGzr56bLYOgsdCAuPEFVzNWTRwP","nextAction":{"type":"redirect","url":"https://pgt.link4pay.com/checkout/O8-aYeGzr56bLYOgsdCAuPEFVzNWTRwP"}}},"declined":{"summary":"Declined","value":{"reference":"payout-00004","status":"declined","amount":"25.00","currency":"EUR","description":"Winnings #00001","customer":{"id":"cust-42","email":"igo.ria@example.com","firstName":"Igo","lastName":"Ria"},"billingAddress":{"line1":"Lemesos Ave 60","city":"Nicosia","postalCode":"2014","country":"CY"},"paymentMethod":{"type":"card","brand":"visa","last4":"1003","masked":"411110XXXXXX1003","expMonth":"12","expYear":"2030","holder":"Igo Ria"},"acquirer":{"name":"clearhaus","responseCode":"40110"},"decline":{"code":"40110","message":"Invalid card number"},"webhookUrl":"https://www.google.com/search?q=webhook","metadata":{"payoutBatch":"2026-10"},"createdAt":"2026-10-28T09:30:00Z","updatedAt":"2026-10-28T09:30:02Z"}}}}}},"400":{"description":"Validation error, `payouts_not_supported` (acquirer without payouts) or `holder_required`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing / invalid credentials or access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Unknown payout (`unknown_payout`) or unknown saved card (`unknown_token`)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v2/tokens":{"post":{"tags":["Tokens"],"summary":"Save a card","description":"Stores a card without charging it and returns a `token` for later payments\n(`paymentMethod: {\"type\": \"token\", \"token\": \"\"}`).\n\n* Cards are encrypted with AWS KMS wrapped keys; the clear card number is never stored.\n* The same card of the same `customer.id` returns the existing token.\n* To save a card **during** a payment use `paymentMethod.save: true` instead; the token then appears in\n `paymentMethod.token` of the payment.","operationId":"createToken","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRequest"},"examples":{"save":{"summary":"Save a card for a customer","value":{"card":{"number":"4111101011111003","expMonth":"12","expYear":"2030","cvv":"987","holder":"Igo Ria"},"customer":{"id":"cust-42","email":"igo.ria@example.com"}}}}}}},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"},"example":{"token":"7Hq2kPz9mN4vL8sR3wXy6bC1dF5gJq2k","brand":"visa","last4":"1003","masked":"411110XXXXXX1003","expMonth":"12","expYear":"2030","holder":"Igo Ria","customerId":"cust-42","createdAt":"2026-10-27 20:18:01"}}}},"400":{"description":"Card checks failed (`invalid_card_number`, `card_expired`, ...)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing / invalid credentials or access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"get":{"tags":["Tokens"],"summary":"List the saved cards of a customer","description":"Lists the saved cards of one customer (your `customer.id`), newest first, up to 50 - for a\n\"pay with a saved card\" selection on your checkout.","operationId":"listTokens","parameters":[{"name":"customerId","in":"query","required":true,"schema":{"type":"string","maxLength":50,"description":"Your customer identifier","examples":["cust-42"],"title":"Customerid"},"description":"Your customer identifier"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenListResponse"},"example":{"items":[{"token":"7Hq2kPz9mN4vL8sR3wXy6bC1dF5gJq2k","brand":"visa","last4":"1003","masked":"411110XXXXXX1003","expMonth":"12","expYear":"2030","holder":"Igo Ria","customerId":"cust-42","createdAt":"2026-10-27 20:18:01"}]}}}},"401":{"description":"Missing / invalid credentials or access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/v2/tokens/{token}":{"get":{"tags":["Tokens"],"summary":"Get a saved card","description":"Masked details of a saved card: brand, last 4 digits, expiry, holder and the customer it belongs to.\nUse it to show the card to the customer or to check the expiry before a merchant initiated payment.","operationId":"getToken","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","description":"Card token","examples":["7Hq2kPz9mN4vL8sR3wXy6bC1dF5gJq2k"],"title":"Token"},"description":"Card token"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenResponse"},"example":{"token":"7Hq2kPz9mN4vL8sR3wXy6bC1dF5gJq2k","brand":"visa","last4":"1003","masked":"411110XXXXXX1003","expMonth":"12","expYear":"2030","holder":"Igo Ria","customerId":"cust-42","createdAt":"2026-10-27 20:18:01"}}}},"401":{"description":"Missing / invalid credentials or access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`unknown_token`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}},"delete":{"tags":["Tokens"],"summary":"Delete a saved card","description":"Deletes a saved card. The token cannot be used for payments afterwards (existing payments are not affected).","operationId":"deleteToken","parameters":[{"name":"token","in":"path","required":true,"schema":{"type":"string","description":"Card token","examples":["7Hq2kPz9mN4vL8sR3wXy6bC1dF5gJq2k"],"title":"Token"},"description":"Card token"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenDeletedResponse"}}}},"401":{"description":"Missing / invalid credentials or access token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"`unknown_token`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}},"components":{"schemas":{"AccessTokenResponse":{"properties":{"access_token":{"type":"string","title":"Access Token","description":"Bearer token for `Authorization: Bearer `","examples":["eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJBQkMyNDAxMDExMjM0NSIsIm1pZCI6MTQ2fQ.4f0c…"]},"token_type":{"type":"string","const":"Bearer","title":"Token Type","default":"Bearer"},"expires_in":{"type":"integer","title":"Expires In","description":"Seconds until the token expires","examples":[3600]},"expires_at":{"type":"integer","title":"Expires At","description":"Expiry as unix timestamp","examples":[1761600000]},"merchant":{"$ref":"#/components/schemas/MerchantInfo"}},"type":"object","required":["access_token","expires_in","expires_at","merchant"],"title":"AccessTokenResponse"},"AcquirerOut":{"properties":{"name":{"type":"string","title":"Name","examples":["paynetics"]},"transactionId":{"type":"string","title":"Transactionid","description":"Acquirer transaction / order id","examples":["2105834471"]},"responseCode":{"type":"string","title":"Responsecode","description":"Acquirer response code","examples":["00"]},"message":{"type":"string","title":"Message","examples":[null]},"authorizedAmount":{"type":"string","title":"Authorizedamount","description":"Set on partial approvals","examples":[null]}},"type":"object","title":"AcquirerOut"},"Address":{"properties":{"line1":{"type":"string","maxLength":100,"minLength":1,"pattern":"^[^\\x00-\\x1f<>]*$","title":"Line1","description":"Street and number, 1-100 printable characters (no `<` `>`).","examples":["Lemesos Ave 60"]},"city":{"type":"string","maxLength":50,"minLength":1,"pattern":"^[^\\x00-\\x1f<>]*$","title":"City","description":"1-50 printable characters.","examples":["Nicosia"]},"state":{"type":"string","maxLength":4,"minLength":1,"pattern":"^[A-Za-z0-9]{1,4}$","title":"State","description":"Region / state code, 1-4 letters or digits (e.g. `CA`, `NY`, `01`).","examples":["01"]},"postalCode":{"type":"string","maxLength":20,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9 -]{0,19}$","title":"Postalcode","description":"1-20 characters: letters, digits, spaces, `-`.","examples":["2014"]},"country":{"type":"string","maxLength":2,"minLength":2,"pattern":"^[A-Za-z]{2}$","title":"Country","description":"ISO 3166-1 alpha-2 country code, 2 letters.","examples":["CY"]}},"additionalProperties":false,"type":"object","title":"Address"},"AddressOut":{"properties":{"line1":{"type":"string","title":"Line1","examples":["Lemesos Ave 60"]},"city":{"type":"string","title":"City","examples":["Nicosia"]},"state":{"type":"string","title":"State","examples":[null]},"postalCode":{"type":"string","title":"Postalcode","examples":["2014"]},"country":{"type":"string","title":"Country","description":"ISO 3166-1 alpha-2","examples":["CY"]}},"type":"object","title":"AddressOut"},"AmountRequest":{"properties":{"amount":{"type":"string","maxLength":13,"minLength":1,"pattern":"^[0-9]{1,10}(\\.[0-9]{1,2})?$","title":"Amount","description":"Partial amount in major units (digits, at most 2 decimals). Omit for the full remaining amount.","examples":["5.00"]},"reference":{"type":"string","maxLength":40,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$","title":"Reference","description":"Your reference of this operation: 1-40 characters, letters, digits, `. _ -`. Generated when omitted.","examples":["refund-00001-a"]}},"additionalProperties":false,"type":"object","title":"AmountRequest"},"Browser":{"properties":{"acceptHeader":{"type":"string","maxLength":2048,"title":"Acceptheader","description":"The `Accept` header the customer's browser sent you (up to 2048 characters).","examples":["text/html,application/xhtml+xml,*/*;q=0.8"]},"userAgent":{"type":"string","maxLength":2048,"title":"Useragent","description":"The customer's `User-Agent` (up to 2048 characters).","examples":["Mozilla/5.0 (Macintosh; Intel Mac OS X 14_0) AppleWebKit/605.1.15"]},"language":{"type":"string","maxLength":8,"minLength":2,"pattern":"^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,4})?$","title":"Language","description":"`navigator.language`, e.g. `en` or `en-GB`.","examples":["en-GB"]},"colorDepth":{"type":"string","maxLength":2,"pattern":"^(1|4|8|15|16|24|30|32|48)$","title":"Colordepth","description":"`screen.colorDepth`: 1, 4, 8, 15, 16, 24, 30, 32 or 48.","examples":["24"]},"screenHeight":{"type":"string","maxLength":6,"pattern":"^[0-9]{1,6}$","title":"Screenheight","description":"`screen.height` in pixels.","examples":["1117"]},"screenWidth":{"type":"string","maxLength":6,"pattern":"^[0-9]{1,6}$","title":"Screenwidth","description":"`screen.width` in pixels.","examples":["1728"]},"timeZoneOffset":{"type":"string","maxLength":5,"pattern":"^-?[0-9]{1,4}$","title":"Timezoneoffset","description":"`new Date().getTimezoneOffset()` in minutes, -840..840.","examples":["-120"]},"javaEnabled":{"type":"boolean","title":"Javaenabled","description":"`navigator.javaEnabled()`","examples":[false]},"javascriptEnabled":{"type":"boolean","title":"Javascriptenabled","description":"`true` when the page ran JavaScript","examples":[true]}},"additionalProperties":false,"type":"object","title":"Browser","description":"Browser data of the cardholder, needed for 3-D Secure on server-to-server card payments."},"CardInput":{"properties":{"number":{"type":"string","maxLength":23,"minLength":12,"pattern":"^[0-9 -]{12,23}$","title":"Number","description":"Card number (PAN), 12-19 digits; spaces or dashes between groups are ignored.","examples":["4111101011111003"]},"expMonth":{"type":"string","maxLength":2,"minLength":1,"pattern":"^(0?[1-9]|1[0-2])$","title":"Expmonth","description":"Expiry month `01`-`12`.","examples":["12"]},"expYear":{"type":"string","maxLength":4,"minLength":2,"pattern":"^([0-9]{2}|20[0-9]{2})$","title":"Expyear","description":"Expiry year, 4 digits (`2030`) or 2 digits (`30`).","examples":["2030"]},"cvv":{"type":"string","maxLength":4,"minLength":3,"pattern":"^[0-9]{3,4}$","title":"Cvv","description":"Card security code, 3 digits (4 for American Express).","examples":["987"]},"holder":{"type":"string","maxLength":50,"minLength":2,"pattern":"^[^\\x00-\\x1f<>0-9]{1,50}$","title":"Holder","description":"Name on the card, 2-50 characters: letters, spaces, `. ' -`.","examples":["Igo Ria"]}},"additionalProperties":false,"type":"object","required":["number","expMonth","expYear"],"title":"CardInput"},"CreatePaymentRequest":{"properties":{"amount":{"type":"string","maxLength":13,"minLength":1,"pattern":"^[0-9]{1,10}(\\.[0-9]{1,2})?$","title":"Amount","description":"Amount in major units as a string: digits with at most 2 decimals (`\"12.00\"`, `\"5\"`). JPY and KRW take no decimals. 0.01 - 999999999.99.","examples":["12.00"]},"currency":{"type":"string","maxLength":3,"minLength":3,"pattern":"^[A-Za-z]{3}$","title":"Currency","description":"ISO 4217 alpha-3 currency code, 3 letters (`EUR`, `USD`, `GBP`, ...).","examples":["EUR"]},"reference":{"type":"string","maxLength":40,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$","title":"Reference","description":"Your merchant transaction reference: 1-40 characters, letters, digits, `. _ -`, starting with a letter or digit; unique per merchant. It identifies the payment in every other call and makes retries safe (same reference + same request = the existing payment). Generated (`L4P-...`) when omitted.","examples":["order-00001"]},"description":{"type":"string","maxLength":100,"minLength":1,"pattern":"^[^\\x00-\\x1f<>]*$","title":"Description","description":"Shown on the hosted checkout: 1-100 printable characters (no `<` `>`).","examples":["Order #00001"]},"capture":{"type":"boolean","title":"Capture","description":"`true` (default): the gateway captures right after the authorization. `false`: the money is only reserved (status `authorized`) and you call /capture (or /void) yourself later.","default":true,"examples":[true]},"paymentMethods":{"items":{"type":"string","enum":["card","applepay","googlepay"]},"type":"array","maxItems":3,"minItems":1,"title":"Paymentmethods","description":"Payment methods offered on the hosted checkout, in display order. Default: all three. Send only the ones you want to show; a method the merchant's acquirer does not support is hidden anyway.","examples":[["card","applepay","googlepay"]]},"customer":{"$ref":"#/components/schemas/Customer"},"billingAddress":{"$ref":"#/components/schemas/Address","description":"Billing address. `country` is required for card payments (3-D Secure); the hosted checkout asks the customer for the missing fields."},"returnUrl":{"type":"string","maxLength":2048,"minLength":12,"pattern":"^https://[^\\s/$.?#].[^\\s]*$","title":"Returnurl","description":"https URL (up to 2048 characters) the customer is sent to after the hosted checkout / 3-D Secure, with `?reference=&status=` appended. Required for the hosted checkout and for card payments.","examples":["https://www.google.com/search?q=payment+return"]},"cancelUrl":{"type":"string","maxLength":2048,"minLength":12,"pattern":"^https://[^\\s/$.?#].[^\\s]*$","title":"Cancelurl","description":"https URL the customer is sent to when cancelling the hosted checkout (`?reference&status=cancelled`).","examples":["https://www.google.com/search?q=payment+cancelled"]},"webhookUrl":{"type":"string","maxLength":2048,"minLength":12,"pattern":"^https://[^\\s/$.?#].[^\\s]*$","title":"Webhookurl","description":"https URL that receives the signed payment events (see Webhooks).","examples":["https://www.google.com/search?q=webhook"]},"paymentMethod":{"$ref":"#/components/schemas/PaymentMethod","description":"Omit to use the hosted checkout (card · Apple Pay · Google Pay)."},"browser":{"$ref":"#/components/schemas/Browser","description":"Customer browser data for 3-D Secure (server-to-server card payments)."},"threeDSecure":{"$ref":"#/components/schemas/ThreeDSOptions"},"language":{"type":"string","maxLength":5,"minLength":2,"pattern":"^(en|ru|de|es|fr|el)$","title":"Language","description":"Language of the hosted checkout: `en`, `ru`, `de`, `es`, `fr` or `el`.","default":"en","examples":["en"]},"metadata":{"additionalProperties":{"type":"string"},"type":"object","title":"Metadata","description":"Up to 20 string pairs (keys up to 40 characters, values up to 200) returned in responses and webhooks.","examples":[{"orderId":"00001"}]}},"additionalProperties":false,"type":"object","required":["amount","currency"],"title":"CreatePaymentRequest"},"CreatePayoutRequest":{"properties":{"amount":{"type":"string","maxLength":14,"minLength":1,"pattern":"^[0-9]{1,10}(\\.[0-9]{1,2})?$","title":"Amount","description":"Amount in major units as a decimal string, 1-14 characters, digits with an optional `.` and at most 2 decimals (`\"25.00\"`). Zero-decimal currencies (JPY, KRW) take whole numbers.","examples":["25.00"]},"currency":{"type":"string","maxLength":3,"minLength":3,"pattern":"^[A-Za-z]{3}$","title":"Currency","description":"ISO 4217 currency code, 3 letters.","examples":["EUR"]},"reference":{"type":"string","maxLength":40,"minLength":1,"pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,39}$","title":"Reference","description":"Your payout reference, unique per merchant: 1-40 letters, digits, `.`, `_` or `-`. It is also the idempotency key. Generated when omitted.","examples":["payout-00001"]},"description":{"type":"string","maxLength":100,"title":"Description","description":"Free text shown on the hosted page, 1-100 characters.","examples":["Winnings #00001"]},"paymentMethod":{"$ref":"#/components/schemas/PayoutMethod","description":"Omit it for the hosted payout page (the customer enters the card to be paid). `card`: pay out to the given card. `token`: pay out to a saved card."},"customer":{"$ref":"#/components/schemas/Customer","description":"The payee. `customer.id` links the payout to your customer."},"billingAddress":{"$ref":"#/components/schemas/Address","description":"Address of the payee (optional, kept with the payout)."},"returnUrl":{"type":"string","maxLength":2048,"minLength":12,"pattern":"^https://[^\\s/$.?#].[^\\s]*$","title":"Returnurl","description":"Where the hosted payout page sends the customer afterwards (https, `reference` and `status` are appended). Required for the hosted page.","examples":["https://www.google.com/search?q=payout+return"]},"cancelUrl":{"type":"string","maxLength":2048,"minLength":12,"pattern":"^https://[^\\s/$.?#].[^\\s]*$","title":"Cancelurl","description":"Where the hosted payout page sends the customer when they cancel (https).","examples":["https://www.google.com/search?q=payout+cancelled"]},"webhookUrl":{"type":"string","maxLength":2048,"minLength":12,"pattern":"^https://[^\\s/$.?#].[^\\s]*$","title":"Webhookurl","description":"https URL that receives the signed `payout.*` webhooks.","examples":["https://www.google.com/search?q=webhook"]},"language":{"type":"string","maxLength":5,"minLength":2,"pattern":"^(en|ru|de|es|fr|el)$","title":"Language","description":"Language of the hosted page: `en`, `ru`, `de`, `es`, `fr`, `el`.","examples":["en"]},"metadata":{"additionalProperties":{"type":"string"},"type":"object","title":"Metadata","description":"Up to 20 key/value strings returned unchanged (keys up to 40, values up to 200 characters).","examples":[{"payoutBatch":"2026-10"}]}},"additionalProperties":false,"type":"object","required":["amount","currency"],"title":"CreatePayoutRequest","description":"POST /v2/payouts - money to a card: hosted payout page (no paymentMethod), card or saved token."},"Customer":{"properties":{"id":{"type":"string","maxLength":50,"minLength":1,"pattern":"^[A-Za-z0-9._@:-]{1,50}$","title":"Id","description":"Your identifier of the customer. 1-50 characters: letters, digits, `. _ @ : -`. Needed to list saved cards per customer.","examples":["cust-42"]},"email":{"type":"string","maxLength":100,"minLength":6,"pattern":"^[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\\.[A-Za-z]{2,}$","title":"Email","description":"Customer e-mail, 6-100 characters, valid address. Required for card payments (3-D Secure).","examples":["igo.ria@example.com"]},"firstName":{"type":"string","maxLength":50,"minLength":1,"pattern":"^[^\\x00-\\x1f<>0-9]{1,50}$","title":"Firstname","description":"1-50 characters: letters (any alphabet), spaces, `. ' -`. No digits.","examples":["Igo"]},"lastName":{"type":"string","maxLength":50,"minLength":1,"pattern":"^[^\\x00-\\x1f<>0-9]{1,50}$","title":"Lastname","description":"1-50 characters: letters (any alphabet), spaces, `. ' -`. No digits.","examples":["Ria"]},"phone":{"type":"string","maxLength":30,"minLength":5,"pattern":"^\\+?[0-9][0-9 ()./-]{4,29}$","title":"Phone","description":"5-30 characters: optional leading `+`, digits, spaces, `( ) . / -`.","examples":["+35722123456"]},"ip":{"type":"string","maxLength":45,"minLength":7,"pattern":"^[0-9A-Fa-f.:]{7,45}$","title":"Ip","description":"Customer IPv4 / IPv6 address for server-to-server payments (used by 3-D Secure and fraud rules).","examples":["203.0.113.10"]}},"additionalProperties":false,"type":"object","title":"Customer"},"CustomerOut":{"properties":{"id":{"type":"string","title":"Id","examples":["cust-42"]},"email":{"type":"string","title":"Email","examples":["igo.ria@example.com"]},"firstName":{"type":"string","title":"Firstname","examples":["Igo"]},"lastName":{"type":"string","title":"Lastname","examples":["Ria"]},"phone":{"type":"string","title":"Phone","examples":["+35799123456"]}},"type":"object","title":"CustomerOut"},"DeclineOut":{"properties":{"code":{"type":"string","title":"Code","examples":["05"]},"message":{"type":"string","title":"Message","examples":["Do not honour"]}},"type":"object","required":["code","message"],"title":"DeclineOut"},"ErrorBody":{"properties":{"code":{"type":"string","title":"Code","description":"Machine readable error code (snake_case)","examples":["validation_error"]},"message":{"type":"string","title":"Message","description":"Human readable explanation","examples":["The request is not valid"]},"details":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Details","description":"Field level problems (validation errors)","examples":[[{"field":"amount","message":"amount must be positive"}]]}},"type":"object","required":["code","message"],"title":"ErrorBody"},"ErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ErrorBody"}},"type":"object","required":["error"],"title":"ErrorResponse"},"MerchantInfo":{"properties":{"apiKey":{"type":"string","title":"Apikey","examples":["ABC24010112345"]},"name":{"type":"string","title":"Name","examples":["Example Shop Ltd"]},"acquirer":{"type":"string","title":"Acquirer","description":"Acquirer the merchant is connected to","examples":["Paynetics"]}},"type":"object","required":["apiKey"],"title":"MerchantInfo"},"NextAction":{"properties":{"type":{"type":"string","const":"redirect","title":"Type","description":"Only `redirect` exists today"},"url":{"type":"string","title":"Url","description":"Send the customer's browser here (hosted checkout or 3-D Secure page)","examples":["https://pgt.link4pay.com/checkout/O8-aYeGzr56bLYOgsdCAuPEFVzNWTRwP"]}},"type":"object","required":["type","url"],"title":"NextAction"},"PaymentMethod":{"properties":{"type":{"type":"string","enum":["card","token","applepay","googlepay"],"title":"Type","description":"`card` full card data · `token` saved card · `applepay` / `googlepay` wallet token","examples":["card"]},"card":{"$ref":"#/components/schemas/CardInput","description":"Required for `type=card`."},"token":{"type":"string","maxLength":100,"minLength":8,"pattern":"^[A-Za-z0-9_-]{8,100}$","title":"Token","description":"Saved card token (`type=token`), as returned by /v2/tokens or `paymentMethod.token`: 8-100 letters, digits, `_ -`.","examples":["7Hq2kPz9mN4vL8sR3wXy6bC1dF5gJq2k"]},"cvv":{"type":"string","maxLength":4,"minLength":3,"pattern":"^[0-9]{3,4}$","title":"Cvv","description":"Optional security code for a saved card payment, 3-4 digits.","examples":["987"]},"walletToken":{"additionalProperties":true,"type":"object","title":"Wallettoken","description":"Apple Pay: `ApplePayPayment.token.paymentData` · Google Pay: `paymentMethodData.tokenizationData.token` parsed as JSON (object)."},"save":{"type":"boolean","title":"Save","description":"`type=card` only: store the card and return `paymentMethod.token` in the response.","default":false,"examples":[false]},"initiator":{"type":"string","enum":["customer","merchant"],"title":"Initiator","description":"`customer` (default): the customer is present, 3-D Secure runs. `merchant`: merchant initiated payment with a saved token, no 3-D Secure.","default":"customer","examples":["customer"]},"seriesType":{"type":"string","enum":["recurring","unscheduled"],"title":"Seriestype","description":"Credentials-on-file series: `recurring` (fixed schedule) or `unscheduled` (one-click / top-up).","examples":["recurring"]}},"additionalProperties":false,"type":"object","required":["type"],"title":"PaymentMethod"},"PaymentMethodOut":{"properties":{"type":{"type":"string","enum":["card","token","applepay","googlepay"],"title":"Type","examples":["card"]},"brand":{"type":"string","title":"Brand","examples":["visa"]},"last4":{"type":"string","title":"Last4","examples":["1111"]},"masked":{"type":"string","title":"Masked","examples":["411110XXXXXX1003"]},"expMonth":{"type":"string","title":"Expmonth","examples":["12"]},"expYear":{"type":"string","title":"Expyear","examples":["2030"]},"holder":{"type":"string","title":"Holder","examples":["Igo Ria"]},"token":{"type":"string","title":"Token","description":"Saved card token (when the card was saved or a token was used)","examples":["7Hq2kPz9mN4vL8sR3wXy6bC1dF5gJq2k"]}},"type":"object","required":["type"],"title":"PaymentMethodOut"},"PaymentResponse":{"properties":{"reference":{"type":"string","title":"Reference","description":"Your payment reference - the identifier of the payment","examples":["order-00001"]},"status":{"type":"string","enum":["pending","authorized","captured","declined","failed","expired","voided","refunded","partially_refunded"],"title":"Status","examples":["captured"]},"amount":{"type":"string","title":"Amount","examples":["12.00"]},"currency":{"type":"string","title":"Currency","examples":["EUR"]},"capture":{"type":"boolean","title":"Capture","description":"true = captured right after the authorization; false = authorize only","examples":[true]},"paymentMethods":{"items":{"type":"string"},"type":"array","title":"Paymentmethods","description":"Methods offered on the hosted checkout","examples":[["card","applepay","googlepay"]]},"description":{"type":"string","title":"Description","examples":["Order #00001"]},"customer":{"$ref":"#/components/schemas/CustomerOut"},"billingAddress":{"$ref":"#/components/schemas/AddressOut"},"paymentMethod":{"$ref":"#/components/schemas/PaymentMethodOut"},"threeDSecure":{"$ref":"#/components/schemas/ThreeDSOut"},"acquirer":{"$ref":"#/components/schemas/AcquirerOut"},"decline":{"$ref":"#/components/schemas/DeclineOut","description":"Present when status is declined / failed"},"capturedAmount":{"type":"string","title":"Capturedamount","examples":["12.00"]},"refundedAmount":{"type":"string","title":"Refundedamount","examples":["0.00"]},"returnUrl":{"type":"string","title":"Returnurl","examples":["https://www.google.com/search?q=payment+return"]},"webhookUrl":{"type":"string","title":"Webhookurl","examples":["https://www.google.com/search?q=webhook"]},"metadata":{"additionalProperties":{"type":"string"},"type":"object","title":"Metadata","examples":[{"orderId":"00001"}]},"createdAt":{"type":"string","title":"Createdat","examples":["2026-10-27T20:18:01Z"]},"updatedAt":{"type":"string","title":"Updatedat","examples":["2026-10-27T20:18:09Z"]},"checkoutUrl":{"type":"string","title":"Checkouturl","description":"Hosted checkout url while the payment is pending","examples":["https://pgt.link4pay.com/checkout/O8-aYeGzr56bLYOgsdCAuPEFVzNWTRwP"]},"nextAction":{"$ref":"#/components/schemas/NextAction","description":"What to do next; `null` when the payment is final"}},"type":"object","required":["reference","status","amount","currency","capture","capturedAmount","refundedAmount","createdAt","updatedAt"],"title":"PaymentResponse"},"PayoutMethod":{"properties":{"type":{"type":"string","enum":["card","token"],"title":"Type","description":"`card`: full card data · `token`: a saved card (see /v2/tokens).","examples":["card"]},"card":{"$ref":"#/components/schemas/CardInput","description":"Required for `type=card`. `holder` (name on card) is required - the card schemes need it for payouts; `cvv` is not used."},"token":{"type":"string","maxLength":100,"minLength":8,"pattern":"^[A-Za-z0-9_-]{8,100}$","title":"Token","description":"Saved card token (`type=token`), as returned by /v2/tokens or `paymentMethod.token` of a payment.","examples":["7Hq2kPz9mN4vL8sR3wXy6bC1dF5gJq2k"]}},"additionalProperties":false,"type":"object","required":["type"],"title":"PayoutMethod"},"PayoutMethodOut":{"properties":{"type":{"type":"string","enum":["card","token"],"title":"Type","examples":["card"]},"brand":{"type":"string","title":"Brand","examples":["visa"]},"last4":{"type":"string","title":"Last4","examples":["1003"]},"masked":{"type":"string","title":"Masked","examples":["411110XXXXXX1003"]},"expMonth":{"type":"string","title":"Expmonth","examples":["12"]},"expYear":{"type":"string","title":"Expyear","examples":["2030"]},"holder":{"type":"string","title":"Holder","examples":["Igo Ria"]},"token":{"type":"string","title":"Token","description":"The saved card used (`type=token`)","examples":["7Hq2kPz9mN4vL8sR3wXy6bC1dF5gJq2k"]}},"type":"object","required":["type"],"title":"PayoutMethodOut"},"PayoutResponse":{"properties":{"reference":{"type":"string","title":"Reference","examples":["payout-00001"]},"status":{"type":"string","enum":["pending","paid","declined","failed","expired"],"title":"Status","description":"`pending` (hosted page not used yet) · `paid` · `declined` · `failed` · `expired`","examples":["paid"]},"amount":{"type":"string","title":"Amount","examples":["25.00"]},"currency":{"type":"string","title":"Currency","examples":["EUR"]},"description":{"type":"string","title":"Description","examples":["Winnings #00001"]},"customer":{"$ref":"#/components/schemas/CustomerOut"},"billingAddress":{"$ref":"#/components/schemas/AddressOut"},"paymentMethod":{"$ref":"#/components/schemas/PayoutMethodOut"},"acquirer":{"$ref":"#/components/schemas/AcquirerOut"},"decline":{"$ref":"#/components/schemas/DeclineOut","description":"Why the payout was not made"},"returnUrl":{"type":"string","title":"Returnurl","examples":["https://www.google.com/search?q=payout+return"]},"webhookUrl":{"type":"string","title":"Webhookurl","examples":["https://www.google.com/search?q=webhook"]},"metadata":{"additionalProperties":{"type":"string"},"type":"object","title":"Metadata","examples":[{"payoutBatch":"2026-10"}]},"createdAt":{"type":"string","title":"Createdat","examples":["2026-10-28T09:30:00Z"]},"updatedAt":{"type":"string","title":"Updatedat","examples":["2026-10-28T09:30:02Z"]},"checkoutUrl":{"type":"string","title":"Checkouturl","description":"Hosted payout page (status `pending` only) - send the customer there","examples":["https://pgt.link4pay.com/checkout/O8-aYeGzr56bLYOgsdCAuPEFVzNWTRwP"]},"nextAction":{"$ref":"#/components/schemas/NextAction","description":"`redirect` to `checkoutUrl` for the hosted page; absent when final"}},"type":"object","required":["reference","status","amount","currency","createdAt","updatedAt"],"title":"PayoutResponse"},"RefundInfo":{"properties":{"reference":{"type":"string","title":"Reference","description":"Reference of the refund row","examples":["R-5f4a1d4e-8f0e-4e3b-9d12-9d2c0a9a1b22"]},"amount":{"type":"string","title":"Amount","examples":["5.00"]},"currency":{"type":"string","title":"Currency","examples":["EUR"]},"acquirerTransactionId":{"type":"string","title":"Acquirertransactionid","examples":["2105834512"]},"status":{"type":"string","const":"refunded","title":"Status","default":"refunded"}},"type":"object","required":["reference","amount","currency"],"title":"RefundInfo"},"RefundResponse":{"properties":{"refund":{"$ref":"#/components/schemas/RefundInfo"},"payment":{"$ref":"#/components/schemas/PaymentResponse"}},"type":"object","required":["refund","payment"],"title":"RefundResponse"},"ThreeDSOptions":{"properties":{"challengePreference":{"type":"string","enum":["auto","required"],"title":"Challengepreference","description":"`auto` (default): the issuer decides. `required`: always ask for a challenge.","default":"auto","examples":["auto"]}},"additionalProperties":false,"type":"object","title":"ThreeDSOptions"},"ThreeDSOut":{"properties":{"status":{"type":"string","title":"Status","description":"`Y` authenticated, `A` attempted, `wallet` = wallet cryptogram","examples":["Y"]},"version":{"type":"string","title":"Version","examples":["2.2.0"]},"eci":{"type":"string","title":"Eci","examples":["05"]},"dsTransId":{"type":"string","title":"Dstransid","examples":["f38e6948-5388-41a6-bca4-b49723c19437"]},"challenged":{"type":"boolean","title":"Challenged","description":"True when the customer passed a challenge","examples":[false]}},"type":"object","title":"ThreeDSOut"},"TokenDeletedResponse":{"properties":{"token":{"type":"string","title":"Token","examples":["7Hq2kPz9mN4vL8sR3wXy6bC1dF5gJq2k"]},"deleted":{"type":"boolean","const":true,"title":"Deleted","default":true}},"type":"object","required":["token"],"title":"TokenDeletedResponse"},"TokenListResponse":{"properties":{"items":{"items":{"$ref":"#/components/schemas/TokenResponse"},"type":"array","title":"Items"}},"type":"object","required":["items"],"title":"TokenListResponse"},"TokenRequest":{"properties":{"card":{"$ref":"#/components/schemas/CardInput"},"customer":{"$ref":"#/components/schemas/Customer","description":"`customer.id` links the token to your customer (listing per customer)."}},"additionalProperties":false,"type":"object","required":["card"],"title":"TokenRequest"},"TokenResponse":{"properties":{"token":{"type":"string","title":"Token","examples":["7Hq2kPz9mN4vL8sR3wXy6bC1dF5gJq2k"]},"brand":{"type":"string","title":"Brand","examples":["visa"]},"last4":{"type":"string","title":"Last4","examples":["1111"]},"masked":{"type":"string","title":"Masked","examples":["411110XXXXXX1003"]},"expMonth":{"type":"string","title":"Expmonth","examples":["12"]},"expYear":{"type":"string","title":"Expyear","examples":["2030"]},"holder":{"type":"string","title":"Holder","examples":["Igo Ria"]},"customerId":{"type":"string","title":"Customerid","examples":["cust-42"]},"createdAt":{"type":"string","title":"Createdat","examples":["2026-10-27 20:18:01"]}},"type":"object","required":["token","last4","masked","expMonth","expYear"],"title":"TokenResponse"}},"securitySchemes":{"merchant":{"type":"oauth2","description":"Enter your apiKey as client_id and your apiSecret as client_secret: the token endpoint returns the Bearer access token used for every call.","flows":{"clientCredentials":{"tokenUrl":"/v2/auth/token","scopes":{}}}}}},"tags":[{"name":"Authentication","description":"Exchange your `apiKey` / `apiSecret` for a Bearer access token."},{"name":"Payments","description":"Create payments (hosted checkout, card, saved card, Apple Pay, Google Pay), read them, capture, refund and void."},{"name":"Payouts","description":"Money to a card (winnings, rewards): hosted payout page, card or saved token. Clearhaus merchants."},{"name":"Tokens","description":"Saved cards: store a card once, pay with the token later (customer or merchant initiated)."}],"security":[{"merchant":[]}]}