{ "openapi": "3.0.0", "info": { "title": "NapoleonPay API Docs", "description": "NapoleonPay payment gateway API for creating payments and withdrawals", "version": "1.6.0", "license": { "name": "Proprietary — © NapoleonPay", "url": "https://napoleonpay.com" } }, "servers": [ { "url": "https://api.napoleonpay.com" } ], "tags": [ { "name": "Authentication", "description": "Every request to the NapoleonPay API carries **two headers**:\n\n| Header | Value |\n| --- | --- |\n| `Authorization` | `Bearer ` |\n| `Signature` | HMAC SHA-256 of the request body, hex-encoded, keyed with your sign key |\n\n## Two different secrets\n\nYou are issued **two** credentials, and they are not interchangeable:\n\n- the **API key** identifies you and goes in the `Authorization: Bearer` header;\n- the **sign key** is used only to compute the `Signature` and is never transmitted.\n\nSigning with the API key by mistake is a common cause of `401`.\n\n## Signing a request\n\nBuild the JSON body **once**, compute an HMAC-SHA256 of that exact string using your sign key, then send the **same** string as the request body. The signed bytes and the transmitted bytes must be **byte-for-byte identical**.\n\n**JSON formatting is up to you.** The signature is verified against the raw request body exactly as received, so indentation, line breaks, key order, and escaped or unescaped slashes make no difference — minified JSON works fine. You may see `JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT` in existing integrations; those flags only make the payload easier to read while debugging and are **not** required.\n\n### Reference\n\n| Property | Value |\n| --- | --- |\n| Algorithm | HMAC-SHA256 |\n| Signed content | The exact request body bytes you transmit |\n| Key | Your **sign key** |\n| Output | Lowercase hexadecimal, 64 characters |\n| Comparison | Byte-exact (`hash_equals`) — an uppercase signature is rejected |\n| Encoding | UTF-8 |\n| Request header | `Signature: ` |\n| Content-Type | `application/json` (a `;charset=utf-8` suffix is fine) — not part of the signature |\n\n### PHP\n\n```php\n$payload = json_encode($requestData);\n$signature = hash_hmac('sha256', $payload, $signKey);\n\n$headers = [\n 'Content-Type: application/json',\n 'Authorization: Bearer ' . $apiKey,\n 'Signature: ' . $signature,\n];\n\n// Send the SAME $payload you signed:\ncurl_setopt($ch, CURLOPT_POSTFIELDS, $payload);\n```\n\n### Node.js\n\n```js\nimport crypto from 'node:crypto';\n\n// 1. Build the body ONCE (a string, not an object)\nconst payload = JSON.stringify(requestData);\n\n// 2. Sign that exact string -> lowercase hex\nconst signature = crypto\n .createHmac('sha256', signKey)\n .update(payload, 'utf8')\n .digest('hex');\n\n// 3. Send the SAME string you signed\nconst response = await fetch('https://api.napoleonpay.com/api/v1/payments', {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n Authorization: `Bearer ${apiKey}`,\n Signature: signature,\n },\n body: payload,\n});\n```\n\n### Python\n\n```python\nimport hashlib\nimport hmac\nimport json\n\nimport requests\n\n# 1. Build the body ONCE\npayload = json.dumps(request_data)\n\n# 2. Sign that exact string -> lowercase hex\nsignature = hmac.new(\n sign_key.encode(\"utf-8\"),\n payload.encode(\"utf-8\"),\n hashlib.sha256,\n).hexdigest()\n\n# 3. Send the SAME string you signed.\n# Use data=..., NOT json=... — json= re-serializes and breaks the signature.\nresponse = requests.post(\n \"https://api.napoleonpay.com/api/v1/payments\",\n data=payload.encode(\"utf-8\"),\n headers={\n \"Content-Type\": \"application/json\",\n \"Authorization\": f\"Bearer {api_key}\",\n \"Signature\": signature,\n },\n)\n```\n\n### C#\n\n```csharp\nusing System.Security.Cryptography;\nusing System.Text;\nusing System.Text.Json;\n\n// 1. Build the body ONCE\nvar payload = JsonSerializer.Serialize(requestData);\n\n// 2. Sign that exact string. ToHexString() returns UPPERCASE — lowercase it.\nusing var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(signKey));\nvar hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));\nvar signature = Convert.ToHexString(hash).ToLowerInvariant();\n\n// 3. Send the SAME string you signed\nusing var client = new HttpClient();\nvar content = new StringContent(payload, Encoding.UTF8, \"application/json\");\nclient.DefaultRequestHeaders.Add(\"Authorization\", $\"Bearer {apiKey}\");\nclient.DefaultRequestHeaders.Add(\"Signature\", signature);\n\nvar response = await client.PostAsync(\n \"https://api.napoleonpay.com/api/v1/payments\", content);\n```\n\n### Why a signature is rejected\n\nNearly every failure is the body changing between signing and sending:\n\n- **Letting your HTTP client serialize for you.** Helpers that accept an object rather than a string re-encode it, producing different bytes than the ones you signed — for example Python's `requests.post(url, json=data)`. Build the string yourself and pass it as the raw body (`data=payload`).\n- **Rebuilding, re-indenting or re-ordering the JSON after computing the signature.**\n- **Wrong signature format** — it must be lowercase hex, not uppercase and not Base64.\n- **Wrong key** — see [Two different secrets](#two-different-secrets).\n\n**Non-ASCII values:** PHP escapes non-ASCII characters to `\\uXXXX` by default, while some stacks (for example JavaScript's `JSON.stringify`) emit raw UTF-8. These produce different bytes and therefore different signatures, so make sure the string you sign is the same string you transmit.\n\n## Verifying a callback signature\n\nEvery callback we send carries a `Signature` header — HMAC-SHA256 of the payload, lowercase hex, keyed with your sign key.\n\n> **This works the opposite way to the requests you send us.** When you call the API we hash the **raw body exactly as received**. For callbacks you must **not** hash the bytes you receive: the signature is computed over a *canonical rendering* of the payload, while the HTTP body is serialized separately with different options. The two are never byte-identical, so hashing the received body always fails.\n\n### The canonical form\n\nParse the JSON body, then re-serialize it with these exact rules — this is what PHP's `json_encode($payload, JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT)` produces:\n\n| Rule | Detail |\n| --- | --- |\n| Indentation | 4 spaces per level, `\\n` line endings |\n| Key separator | `\": \"` (colon + single space) |\n| Key order | Exactly as received — never sorted |\n| Forward slashes | **Not** escaped — `https://example.com/x` |\n| Non-ASCII | Escaped as lowercase `\\uXXXX` (per UTF-16 code unit) |\n| Whole numbers | No fractional part — `100.0` is rendered as `100` |\n| Empty object | Rendered as `[]`, not `{}` |\n\nThen HMAC-SHA256 that string with your sign key and compare it to the header, using a constant-time comparison.\n\n### PHP\n\n```php\n$raw = file_get_contents('php://input');\n$data = json_decode($raw, true);\n\n// Rebuild the canonical form — do NOT hash $raw\n$canonical = json_encode($data, JSON_UNESCAPED_SLASHES | JSON_PRETTY_PRINT);\n$expected = hash_hmac('sha256', $canonical, $signKey);\n\nif (!hash_equals($expected, $_SERVER['HTTP_SIGNATURE'] ?? '')) {\n http_response_code(401);\n exit;\n}\n\nhttp_response_code(200); // acknowledge\n```\n\n### Node.js\n\n`JSON.stringify` already drops the `.0` from whole numbers, but it emits raw UTF-8 where PHP escapes it, and keeps `{}` for empty objects — both are corrected below.\n\n```js\nimport crypto from 'node:crypto';\n\nconst canonicalise = (v) =>\n Array.isArray(v)\n ? v.map(canonicalise)\n : v && typeof v === 'object'\n ? (Object.keys(v).length\n ? Object.fromEntries(Object.entries(v).map(([k, x]) => [k, canonicalise(x)]))\n : []) // empty object -> []\n : v;\n\nconst escapeNonAscii = (s) =>\n s.replace(/[€-￿]/g, (c) =>\n '\\\\u' + c.charCodeAt(0).toString(16).padStart(4, '0'));\n\n// rawBody must be the untouched request body string, not a re-serialized object\nexport function verifyCallback(rawBody, signatureHeader, signKey) {\n const canonical = escapeNonAscii(\n JSON.stringify(canonicalise(JSON.parse(rawBody)), null, 4)\n );\n const expected = crypto\n .createHmac('sha256', signKey)\n .update(canonical, 'utf8')\n .digest('hex');\n\n const a = Buffer.from(expected);\n const b = Buffer.from(signatureHeader || '');\n return a.length === b.length && crypto.timingSafeEqual(a, b);\n}\n```\n\n> In Express, register the route with `express.raw({ type: 'application/json' })` so you receive the original bytes — `express.json()` parses and discards them.\n\n### Python\n\n`json.dumps(..., indent=4)` matches on indentation and `\\uXXXX` escaping, but renders `100.0` instead of `100` and keeps `{}` — both are corrected below.\n\n```python\nimport hashlib\nimport hmac\nimport json\n\n\ndef _canonicalise(value):\n if isinstance(value, bool):\n return value\n if isinstance(value, float) and value.is_integer():\n return int(value) # 100.0 -> 100\n if isinstance(value, dict):\n return {k: _canonicalise(v) for k, v in value.items()} if value else []\n if isinstance(value, list):\n return [_canonicalise(v) for v in value]\n return value\n\n\ndef verify_callback(raw_body: str, signature_header: str, sign_key: str) -> bool:\n canonical = json.dumps(_canonicalise(json.loads(raw_body)), indent=4)\n expected = hmac.new(\n sign_key.encode(\"utf-8\"),\n canonical.encode(\"utf-8\"),\n hashlib.sha256,\n ).hexdigest()\n return hmac.compare_digest(expected, signature_header or \"\")\n```\n\n### Other languages\n\nImplement the canonical form exactly as specified above. The defaults of most JSON libraries differ in at least one respect — indentation width, uppercase hex in `\\u` escapes, key re-ordering, or how whole-number floats are rendered — so verify your output byte-for-byte against a known-good payload before going live.\n\nBodies are UTF-8 in both directions, and callbacks are sent with `Content-Type: application/json`.\n\n### Test vector\n\nCheck your implementation against this known-good result before going live. The signature is the HMAC-SHA256 of the **canonical form**, not of the bytes you receive.\n\n**Sign key**\n\n```\ntest_sign_key_0123456789abcdef\n```\n\n**Payload as received**\n\n```json\n{\n \"id\": \"01a10000-0000-7000-8000-000000000001\",\n \"reference\": \"PAYOUT-2026-000123\",\n \"paymentStatus\": \"COMPLETED\",\n \"paymentType\": \"WITHDRAWAL\",\n \"paymentMethod\": \"CARD\",\n \"amount\": 50,\n \"currency\": \"EUR\",\n \"created\": {\n \"date\": \"2026-10-06 12:34:56.000000\",\n \"timezone_type\": 3,\n \"timezone\": \"Europe/Vilnius\"\n },\n \"customer\": {\n \"firstName\": \"JOHN\",\n \"lastName\": \"DOE\",\n \"email\": null,\n \"phone\": null,\n \"ipaddress\": null,\n \"dateOfBirth\": null,\n \"referenceId\": \"PLAYER-10045\",\n \"accountNumber\": null,\n \"bankCode\": null\n },\n \"providerId\": \"01a10000-0000-7000-8000-000000000001\",\n \"fallbackPaymentStatus\": \"default\"\n}\n```\n\n**Canonical form — this exact string is what gets hashed**\n\n```\n{\n \"id\": \"01a10000-0000-7000-8000-000000000001\",\n \"reference\": \"PAYOUT-2026-000123\",\n \"paymentStatus\": \"COMPLETED\",\n \"paymentType\": \"WITHDRAWAL\",\n \"paymentMethod\": \"CARD\",\n \"amount\": 50,\n \"currency\": \"EUR\",\n \"created\": {\n \"date\": \"2026-10-06 12:34:56.000000\",\n \"timezone_type\": 3,\n \"timezone\": \"Europe/Vilnius\"\n },\n \"customer\": {\n \"firstName\": \"JOHN\",\n \"lastName\": \"DOE\",\n \"email\": null,\n \"phone\": null,\n \"ipaddress\": null,\n \"dateOfBirth\": null,\n \"referenceId\": \"PLAYER-10045\",\n \"accountNumber\": null,\n \"bankCode\": null\n },\n \"providerId\": \"01a10000-0000-7000-8000-000000000001\",\n \"fallbackPaymentStatus\": \"default\"\n}\n```\n\n**Expected `Signature` header**\n\n```\n4bc50699f81c526281d40c14a9d64a72ef3575960cc24c20ab7059243f048b6a\n```\n\nIf your canonical string matches byte for byte but the signature differs, the problem is the key or the HMAC call. If the signature differs and the canonical string does too, compare them line by line — indentation, escaping and whole-number formatting are the usual culprits.\n" }, { "name": "Payments", "description": "Operations related to creating and managing deposits and withdrawals" } ], "paths": { "/api/v1/payments": { "post": { "tags": [ "Payments" ], "summary": "Create a deposit or a withdrawal", "description": "Create a deposit or a withdrawal by using a single endpoint. The `paymentType` field determines the operation:\n- `DEPOSIT` — fund an account via Apple Pay, Google Pay, BLIK, CARD, ONRAMP, PAYID, or a European bank-redirect APM (iDEAL, Bancontact, Multibanco, EPS, Przelewy24).\n- `WITHDRAWAL` — send funds out via PAYID, SEPA, FPS or CARD.\n\n### Payment types & methods\n\nChoose a `paymentType`, then a `paymentMethod` valid for that type:\n\n| paymentType | paymentMethod |\n| --- | --- |\n| `DEPOSIT` (pay-in) | APPLEPAY, GOOGLEPAY, BLIK, CARD, ONRAMP, PAYID, IDEAL, BANCONTACT, MULTIBANCO, EPS, P24 |\n| `WITHDRAWAL` (payout) | PAYID, SEPA, FPS, CARD |\n| `DEPOSIT` — onramp terminals only | USER_CHOICE, ONRAMP_PAYID, ONRAMP_PIX, ONRAMP_ZAR, ONRAMP_PSE, ONRAMP_KHIPU, ONRAMP_QRTHWALLET, ONRAMP_CARD, ONRAMP_INTERAC, ONRAMP_OPENBANKING, ONRAMP_GBPBANKTRANSFER, ONRAMP_SPEI, ONRAMP_APPLEPAY, ONRAMP_GOOGLEPAY |\n\nThe last row applies only when your terminal is configured for onramp. `USER_CHOICE` lets the customer pick in the widget; an `ONRAMP_*` value pins the widget to that one method. See **Onramp — deposit** in the request selector.\n\nWhen making an NFT purchase only the methods APPLEPAY, GOOGLEPAY, OPENBANKING, CARD are available.\nThe request schema depends on `paymentMethod`.\n\n## Authentication\n\nEvery request needs an `Authorization: Bearer ` header and a `Signature` header — HMAC-SHA256 of the request body, keyed with your sign key. Ready-to-run samples in PHP, Node.js, Python and C# are in the request samples panel.\n\nSee **[Authentication](#tag/Authentication)** for the full details, including why signatures get rejected and how to verify the ones we send you.\n", "operationId": "createPayment", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentRequest" }, "examples": { "ApplePay": { "summary": "Create Apple Pay payment", "value": { "paymentType": "DEPOSIT", "paymentMethod": "APPLEPAY", "amount": 20, "currency": "EUR", "reference": "YOUR-SYSTEM-TRX-ID", "billingAddress": { "countryCode": "LT" }, "returnUrl": "https://example.com/return", "webhookUrl": "https://example.com/webhook" } }, "PAYID": { "summary": "Create PAYID payment", "value": { "paymentType": "DEPOSIT", "paymentMethod": "PAYID", "amount": 20, "currency": "AUD", "reference": "YOUR-SYSTEM-TRX-ID", "billingAddress": { "countryCode": "LT" }, "returnUrl": "https://example.com/return", "webhookUrl": "https://example.com/webhook" } }, "GooglePay": { "summary": "Create Google Pay payment", "value": { "paymentType": "DEPOSIT", "paymentMethod": "GOOGLEPAY", "amount": 20, "currency": "EUR", "reference": "YOUR-SYSTEM-TRX-ID", "billingAddress": { "countryCode": "LT" }, "returnUrl": "https://example.com/return", "webhookUrl": "https://example.com/webhook" } }, "BLIK": { "summary": "Create BLIK payment", "value": { "paymentType": "DEPOSIT", "paymentMethod": "BLIK", "amount": 10, "currency": "PLN", "customer": { "email": "john.doe@example.com", "firstName": "John", "lastName": "Doe", "phone": "+370 60000000", "ipaddress": "203.0.113.10" }, "billingAddress": { "address1": "211 Victory Street", "city": "Vilnius", "countryCode": "LT", "postalCode": "01001", "state": "Vilnius" }, "returnUrl": "https://example.com/return", "webhookUrl": "https://example.com/webhook" } }, "CARD": { "summary": "Create Card payment", "value": { "paymentType": "DEPOSIT", "paymentMethod": "CARD", "amount": 21.2, "currency": "EUR", "merchantUrl": "https://sample.casino", "customer": { "referenceId": "MERCHANT-REF-001", "email": "john.doe@example.com", "firstName": "John", "lastName": "Doe", "phone": "+370 60000000", "dateOfBirth": "1990-01-01" }, "billingAddress": { "address1": "211 Victory Street", "city": "Vilnius", "state": "Vilnius", "countryCode": "LT", "postalCode": "01001" }, "card": { "pan": "4111111111111111", "cvv": "123", "exp_month": 3, "exp_year": 2028, "holder": "Ben John" }, "callbackUrl": "https://napoleonpay.com/payment_callback.php", "additionalParameters": { "purpose": "purpose" } } }, "CardNFT": { "summary": "Create Card payment for NFT purchase", "description": "Use CARD method with walletAddress, blockchain, and cryptoCurrency in additionalParameters for NFT purchases.", "value": { "paymentType": "DEPOSIT", "paymentMethod": "CARD", "amount": 21.2, "currency": "EUR", "merchantUrl": "https://sample.casino", "customer": { "referenceId": "MERCHANT-REF-001", "email": "john.doe@example.com", "firstName": "John", "lastName": "Doe", "phone": "+370 60000000", "dateOfBirth": "1990-01-01" }, "billingAddress": { "address1": "211 Victory Street", "city": "Vilnius", "state": "Vilnius", "countryCode": "LT", "postalCode": "01001" }, "card": { "pan": "4111111111111111", "cvv": "123", "exp_month": 3, "exp_year": 2028, "holder": "Ben John" }, "callbackUrl": "https://napoleonpay.com/payment_callback.php", "additionalParameters": { "walletAddress": "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359", "blockchain": "MATIC", "cryptoCurrency": "USDC" } } }, "ONRAMP": { "summary": "Create Onramp payment", "value": { "paymentType": "DEPOSIT", "paymentMethod": "ONRAMP", "amount": 21.2, "currency": "EUR", "merchantUrl": "https://sample.casino", "customer": { "referenceId": "MERCHANT-REF-001", "email": "john.doe@example.com", "firstName": "John", "lastName": "Doe", "phone": "+370 60000000", "dateOfBirth": "1990-01-01" }, "billingAddress": { "address1": "211 Victory Street", "city": "Vilnius", "state": "Vilnius", "countryCode": "LT", "postalCode": "01001" }, "callbackUrl": "https://napoleonpay.com/payment_callback.php", "additionalParameters": { "walletAddress": "3c499c542cEF5E3811e1192ce70d8cC03d5c3359", "blockchain": "MATIC", "cryptoCurrency": "USDC" } } }, "PAYIDWithdrawal": { "summary": "Create PAYID withdrawal", "value": { "paymentType": "WITHDRAWAL", "paymentMethod": "PAYID", "amount": 20, "currency": "AUD", "reference": "YOUR-SYSTEM-TRX-ID", "customer": { "email": "john.doe@example.com" }, "webhookUrl": "https://example.com/webhook" } }, "SEPAWithdrawal": { "summary": "Create SEPA withdrawal", "value": { "paymentType": "WITHDRAWAL", "paymentMethod": "SEPA", "amount": 2, "currency": "EUR", "description": "Payout order x112", "reference": "x112", "customer": { "referenceId": "MERCHANT-REF-001", "email": "john.doe@example.com", "firstName": "John", "lastName": "Doe", "phone": "+370 60000000", "accountNumber": "LT63550037167864539" }, "billingAddress": { "address1": "211 Victory Street", "city": "Vilnius", "state": "Vilnius", "postalCode": "01001", "countryCode": "LT" }, "callbackUrl": "https://example.com/webhook", "additionalParameters": { "purpose": "Payout" } } }, "FPSWithdrawal": { "summary": "Create FPS (Faster Payments) withdrawal", "value": { "paymentType": "WITHDRAWAL", "paymentMethod": "FPS", "amount": 2, "currency": "GBP", "description": "Payout order x11555", "reference": "x11555", "customer": { "referenceId": "MERCHANT-REF-001", "email": "john.doe@example.com", "firstName": "John", "lastName": "Doe", "phone": "+370 60000000", "accountNumber": "12345678", "bankCode": "040004", "ipaddress": "203.0.113.10" }, "billingAddress": { "address1": "211 Victory Street", "city": "Vilnius", "state": "Vilnius", "postalCode": "01001", "countryCode": "LT" }, "callbackUrl": "https://example.com/webhook", "additionalParameters": { "purpose": "Payout" } } }, "Ideal": { "summary": "Create iDEAL payment", "value": { "paymentType": "DEPOSIT", "paymentMethod": "IDEAL", "amount": 10, "currency": "EUR", "description": "3a8e40a2-64e5-439d-99a5-09acbe8d5b7f order", "externalApiId": "3a8e40a2-64e5-439d-99a5-09acbe8d5b7f", "webhookUrl": "https://api.sample.com/api/v1/webhook/all/ext/3a8e40a2-64e5-439d-99a5-09acbe8d5b7f", "customer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+370 60000000" } } }, "Bancontact": { "summary": "Create Bancontact payment", "value": { "paymentType": "DEPOSIT", "paymentMethod": "BANCONTACT", "amount": 10, "currency": "EUR", "description": "3a8e40a2-64e5-439d-99a5-09acbe8d5b7f order", "externalApiId": "3a8e40a2-64e5-439d-99a5-09acbe8d5b7f", "webhookUrl": "https://api.sample.com/api/v1/webhook/all/ext/3a8e40a2-64e5-439d-99a5-09acbe8d5b7f", "customer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+370 60000000" } } }, "Multibanco": { "summary": "Create Multibanco payment", "value": { "paymentType": "DEPOSIT", "paymentMethod": "MULTIBANCO", "amount": 10, "currency": "EUR", "description": "3a8e40a2-64e5-439d-99a5-09acbe8d5b7f order", "externalApiId": "3a8e40a2-64e5-439d-99a5-09acbe8d5b7f", "webhookUrl": "https://api.sample.com/api/v1/webhook/all/ext/3a8e40a2-64e5-439d-99a5-09acbe8d5b7f", "customer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+370 60000000" } } }, "Eps": { "summary": "Create EPS payment", "value": { "paymentType": "DEPOSIT", "paymentMethod": "EPS", "amount": 10, "currency": "EUR", "description": "3a8e40a2-64e5-439d-99a5-09acbe8d5b7f order", "externalApiId": "3a8e40a2-64e5-439d-99a5-09acbe8d5b7f", "webhookUrl": "https://api.sample.com/api/v1/webhook/all/ext/3a8e40a2-64e5-439d-99a5-09acbe8d5b7f", "customer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+370 60000000" } } }, "Przelewy24": { "summary": "Create Przelewy24 (P24) payment", "value": { "paymentType": "DEPOSIT", "paymentMethod": "P24", "amount": 10, "currency": "PLN", "description": "3a8e40a2-64e5-439d-99a5-09acbe8d5b7f order", "externalApiId": "3a8e40a2-64e5-439d-99a5-09acbe8d5b7f", "webhookUrl": "https://api.sample.com/api/v1/webhook/all/ext/3a8e40a2-64e5-439d-99a5-09acbe8d5b7f", "customer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+370 60000000" } } }, "CardWithdrawal": { "summary": "Create CARD withdrawal", "value": { "paymentType": "WITHDRAWAL", "paymentMethod": "CARD", "amount": 50, "currency": "EUR", "reference": "PAYOUT-2026-000123", "customer": { "firstName": "JOHN", "lastName": "DOE", "referenceId": "PLAYER-10045" }, "card": { "pan": "4111111111111111" }, "webhookUrl": "https://merchant.example.com/napoleonpay/webhook" } } } } } }, "responses": { "200": { "$ref": "#/components/responses/PaymentCreated" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "422": { "$ref": "#/components/responses/ValidationError" } }, "callbacks": { "paymentStatusUpdate": { "{$request.body#/webhookUrl}": { "post": { "summary": "Payment status update", "description": "NapoleonPay sends a **POST** to your `webhookUrl` (or `callbackUrl`) whenever the payment status changes. Acknowledge with any `2xx`; non-`2xx` responses are retried. The examples below show the final status per payment method.\n\n## Delivering and acknowledging\n\n- **Respond with exactly `200`.** Any other code — including `201` and `204` — counts as a failure.\n- **Answer within a few seconds.** Delivery is abandoned after about 25 seconds.\n- **Retries:** up to 10 attempts — after roughly 10 s, 50 s, 4 min, 21 min, then hourly, about 6.5 hours in total.\n- **The same event can arrive more than once.** Process idempotently, keyed on `id` plus `paymentStatus`.\n- `providerId` and `fallbackPaymentStatus` are internal — ignore them.\n\nFor **CARD withdrawals** only final statuses are sent: `COMPLETED` or `FAILED`, never `PENDING`.\n\n## Verifying the callback signature\n\nEach callback carries a `Signature` header. **Do not hash the raw body you receive** — the signature is computed over a canonical rendering of the payload, so hashing the received bytes always fails.\n\nSee **[Authentication](#tag/Authentication)** for the canonical form and verification code in PHP, Node.js and Python.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" }, "examples": { "CARD": { "summary": "CARD — final status", "value": { "id": "019ab727-1378-795a-bec3-1fa75dd18f48", "paymentStatus": "COMPLETED", "created": { "date": "2025-11-24 20:36:23.000000", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "Test payin", "paymentMethod": "CARD", "reference": null, "amount": 10, "currency": "EUR", "customer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+370 60000000", "ipaddress": null, "referenceId": null }, "billingAddress": { "address1": "211 Victory Street", "city": "Vilnius", "countryCode": "LT", "postalCode": "01001", "state": "Vilnius" } } }, "GOOGLEPAY": { "summary": "GOOGLEPAY — final status", "value": { "id": "019bebd8-75ce-7ebb-8049-e4e9bda33320", "paymentStatus": "COMPLETED", "created": { "date": "2026-01-23 19:13:11.000000", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "Test payment", "paymentMethod": "GOOGLEPAY", "reference": "97f405f850a94f5cba5a7aeef1398dc6", "amount": 20, "currency": "EUR", "customer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+370 60000000", "ipaddress": "203.0.113.10", "dateOfBirth": null, "referenceId": "MERCHANT-REF-001" }, "billingAddress": { "address1": "211 Victory Street", "city": "Vilnius", "countryCode": "LT", "postalCode": "01001", "state": "Vilnius" }, "fallbackPaymentStatus": 1 } }, "APPLEPAY": { "summary": "APPLEPAY — final status", "value": { "id": "019bebd4-5b04-7016-8a50-b918fca777c5", "paymentStatus": "COMPLETED", "created": { "date": "2026-01-23 19:08:41.000000", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "Test payment", "paymentMethod": "APPLEPAY", "reference": "ce43f23650994ae7896ad31433992a53", "amount": 100, "currency": "EUR", "customer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+370 60000000", "ipaddress": "203.0.113.10", "dateOfBirth": null, "referenceId": "MERCHANT-REF-001" }, "billingAddress": { "address1": "211 Victory Street", "city": "Vilnius", "countryCode": "LT", "postalCode": "01001", "state": "Vilnius" } } }, "BLIK": { "summary": "BLIK — final status", "value": { "id": "019bebb4-5d6b-7c89-ae10-05b06d2b89d9", "paymentStatus": "COMPLETED", "created": { "date": "2026-01-23 18:33:50.000000", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "Test payment", "paymentMethod": "BLIK", "reference": "0f6632f4f62d4c42a1a08eed53ddfa77", "amount": 50, "currency": "PLN", "billingAddress": { "address1": "211 Victory Street", "city": "Vilnius", "countryCode": "LT", "postalCode": "01001", "state": "Vilnius" }, "customer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+370 60000000", "ipaddress": "203.0.113.10" } } }, "PAYID": { "summary": "PAYID — final status (same payload for Redirect and H2H flows)", "value": { "id": "019f6ea2-7413-70b3-a7d4-2441633ca869", "paymentStatus": "COMPLETED", "created": { "date": "2026-07-17 08:52:48.000000", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "Test payment", "paymentMethod": "PAYID", "reference": "txn_f8fcaef9c2192809", "amount": 100, "currency": "AUD", "customer": { "firstName": "John", "lastName": "Doe", "email": null, "phone": "+370 60000000", "ipaddress": null, "dateOfBirth": null, "referenceId": null, "accountNumber": null, "bankCode": null } } }, "PAYIDDeclined": { "summary": "PAYID — declined payment (FAILED)", "value": { "id": "019f6c7f-81c7-78b1-8f32-5321acd2384a", "paymentStatus": "FAILED", "created": { "date": "2026-07-16 22:55:24.000000", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "Test payment", "paymentMethod": "PAYID", "reference": "txn_98177752201fa52d", "amount": 80, "currency": "AUD", "customer": { "firstName": "John", "lastName": "Doe", "email": null, "phone": "+370 60000000", "ipaddress": null, "dateOfBirth": null, "referenceId": null, "accountNumber": null, "bankCode": null } } }, "CardPayoutCompleted": { "summary": "CARD withdrawal — COMPLETED", "value": { "id": "01a10000-0000-7000-8000-000000000001", "reference": "PAYOUT-2026-000123", "paymentStatus": "COMPLETED", "paymentType": "WITHDRAWAL", "paymentMethod": "CARD", "amount": 50, "currency": "EUR", "created": { "date": "2026-10-06 12:34:56.000000", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "customer": { "firstName": "JOHN", "lastName": "DOE", "email": null, "phone": null, "ipaddress": null, "dateOfBirth": null, "referenceId": "PLAYER-10045", "accountNumber": null, "bankCode": null }, "providerId": "01a10000-0000-7000-8000-000000000001", "fallbackPaymentStatus": "default" } }, "CardPayoutFailed": { "summary": "CARD withdrawal — FAILED", "value": { "id": "01a10000-0000-7000-8000-000000000001", "reference": "PAYOUT-2026-000123", "paymentStatus": "FAILED", "paymentType": "WITHDRAWAL", "paymentMethod": "CARD", "amount": 50, "currency": "EUR", "created": { "date": "2026-10-06 12:34:56.000000", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "customer": { "firstName": "JOHN", "lastName": "DOE", "email": null, "phone": null, "ipaddress": null, "dateOfBirth": null, "referenceId": "PLAYER-10045", "accountNumber": null, "bankCode": null }, "providerId": "01a10000-0000-7000-8000-000000000001", "fallbackPaymentStatus": "default" } } } } } }, "responses": { "200": { "description": "Acknowledged. Return any 2xx to confirm receipt." }, "4XX": { "description": "Any non-2xx response tells NapoleonPay the event was not accepted; delivery is retried." } }, "security": [] } } } }, "security": [ { "Bearer": [], "Signature": [] } ], "x-codeSamples": [ { "lang": "PHP", "label": "PHP", "source": " 'DEPOSIT',\n 'paymentMethod' => 'APPLEPAY',\n 'amount' => 20.00,\n 'currency' => 'EUR',\n 'reference' => 'YOUR-SYSTEM-TRX-ID',\n 'billingAddress' => ['countryCode' => 'LT'],\n 'returnUrl' => 'https://example.com/return',\n 'webhookUrl' => 'https://example.com/webhook',\n];\n\n// 1. Build the body ONCE\n$payload = json_encode($requestData);\n\n// 2. Sign that exact string\n$signature = hash_hmac('sha256', $payload, $signKey);\n\n// 3. Send the SAME string you signed\n$ch = curl_init('https://api.napoleonpay.com/api/v1/payments');\ncurl_setopt($ch, CURLOPT_RETURNTRANSFER, true);\ncurl_setopt($ch, CURLOPT_POSTFIELDS, $payload);\ncurl_setopt($ch, CURLOPT_HTTPHEADER, [\n 'Content-Type: application/json',\n 'Authorization: Bearer ' . $apiKey,\n 'Signature: ' . $signature,\n]);\n\n$response = curl_exec($ch);\ncurl_close($ch);" }, { "lang": "JavaScript", "label": "Node.js", "source": "import crypto from 'node:crypto';\n\nconst apiKey = 'YOUR_API_KEY';\nconst signKey = 'YOUR_SIGN_KEY';\n\nconst requestData = {\n paymentType: 'DEPOSIT',\n paymentMethod: 'APPLEPAY',\n amount: 20.0,\n currency: 'EUR',\n reference: 'YOUR-SYSTEM-TRX-ID',\n billingAddress: { countryCode: 'LT' },\n returnUrl: 'https://example.com/return',\n webhookUrl: 'https://example.com/webhook',\n};\n\n// 1. Build the body ONCE (a string, not an object)\nconst payload = JSON.stringify(requestData);\n\n// 2. Sign that exact string -> lowercase hex\nconst signature = crypto\n .createHmac('sha256', signKey)\n .update(payload, 'utf8')\n .digest('hex');\n\n// 3. Send the SAME string you signed\nconst response = await fetch('https://api.napoleonpay.com/api/v1/payments', {\n method: 'POST',\n headers: {\n 'Content-Type': 'application/json',\n Authorization: `Bearer ${apiKey}`,\n Signature: signature,\n },\n body: payload,\n});\n\nconst result = await response.json();" }, { "lang": "Python", "label": "Python", "source": "import hashlib\nimport hmac\nimport json\n\nimport requests\n\napi_key = \"YOUR_API_KEY\"\nsign_key = \"YOUR_SIGN_KEY\"\n\nrequest_data = {\n \"paymentType\": \"DEPOSIT\",\n \"paymentMethod\": \"APPLEPAY\",\n \"amount\": 20.00,\n \"currency\": \"EUR\",\n \"reference\": \"YOUR-SYSTEM-TRX-ID\",\n \"billingAddress\": {\"countryCode\": \"LT\"},\n \"returnUrl\": \"https://example.com/return\",\n \"webhookUrl\": \"https://example.com/webhook\",\n}\n\n# 1. Build the body ONCE\npayload = json.dumps(request_data)\n\n# 2. Sign that exact string -> lowercase hex\nsignature = hmac.new(\n sign_key.encode(\"utf-8\"),\n payload.encode(\"utf-8\"),\n hashlib.sha256,\n).hexdigest()\n\n# 3. Send the SAME string you signed.\n# Use data=..., NOT json=... — json= re-serializes and breaks the signature.\nresponse = requests.post(\n \"https://api.napoleonpay.com/api/v1/payments\",\n data=payload.encode(\"utf-8\"),\n headers={\n \"Content-Type\": \"application/json\",\n \"Authorization\": f\"Bearer {api_key}\",\n \"Signature\": signature,\n },\n)\n\nresult = response.json()" }, { "lang": "C#", "label": "C#", "source": "using System.Security.Cryptography;\nusing System.Text;\nusing System.Text.Json;\n\nvar apiKey = \"YOUR_API_KEY\";\nvar signKey = \"YOUR_SIGN_KEY\";\n\nvar requestData = new\n{\n paymentType = \"DEPOSIT\",\n paymentMethod = \"APPLEPAY\",\n amount = 20.00,\n currency = \"EUR\",\n reference = \"YOUR-SYSTEM-TRX-ID\",\n billingAddress = new { countryCode = \"LT\" },\n returnUrl = \"https://example.com/return\",\n webhookUrl = \"https://example.com/webhook\",\n};\n\n// 1. Build the body ONCE\nvar payload = JsonSerializer.Serialize(requestData);\n\n// 2. Sign that exact string. ToHexString() returns UPPERCASE — lowercase it.\nusing var hmac = new HMACSHA256(Encoding.UTF8.GetBytes(signKey));\nvar hash = hmac.ComputeHash(Encoding.UTF8.GetBytes(payload));\nvar signature = Convert.ToHexString(hash).ToLowerInvariant();\n\n// 3. Send the SAME string you signed\nusing var client = new HttpClient();\nvar content = new StringContent(payload, Encoding.UTF8, \"application/json\");\nclient.DefaultRequestHeaders.Add(\"Authorization\", $\"Bearer {apiKey}\");\nclient.DefaultRequestHeaders.Add(\"Signature\", signature);\n\nvar response = await client.PostAsync(\n \"https://api.napoleonpay.com/api/v1/payments\", content);\nvar result = await response.Content.ReadAsStringAsync();" } ] } }, "/api/v1/payments/{id}": { "get": { "tags": [ "Payments" ], "summary": "Get payment by ID", "description": "Retrieve a single payment by its unique ID. Only **Bearer token** authentication is required — this endpoint is not signed.\n\n> **Read the status from the body, not the HTTP code.** A payment that exists always returns **`200`**, whether it succeeded or failed. The outcome is in `result.paymentStatus`; treating `200` as success will mark declined payments as paid. (`404` means no payment with that id.)\n\nThe payment is wrapped in a `result` object.\n\n### Which id to use\n\n| Field | Meaning |\n| --- | --- |\n| `{id}` / `result.id` | The payment's internal UID — the value this endpoint is keyed on |\n| `result.reference` | Your own merchant-side id, e.g. `TXN-…` |\n\n### Fields that depend on status\n\n| Field | Present when |\n| --- | --- |\n| `errorMessage` | `FAILED` (not guaranteed — see below) |\n| `settled_crypto_amount` | `COMPLETED` |\n| `crypto_tx_hash` | `COMPLETED` |\n| `destination_wallet` | `COMPLETED` |\n\n### Reading a decline\n\nOn `FAILED`, `errorMessage` carries the reason relayed from the payment processor. Numeric processor codes are translated to human-readable text before storage — for example `4004` becomes an insufficient-balance message, `4001` a CVV error, and `4018` \"Payment was canceled by the user\". Reasons that arrive without a code pass through verbatim, such as `\"Payment not funded\"`, which means the order was created but never funded.\n\n`errorMessage` is **not guaranteed on every failure**. Do not branch on its presence: the reliable \"funds were not delivered\" signal is **`paymentStatus: FAILED` together with no `crypto_tx_hash`**. Treat `errorMessage` as a human-readable explanation, not as a machine-readable status.\n\n### Field names and types\n\nTwo things here are deliberate, not typos — match them exactly:\n\n- **Casing is mixed.** camelCase for `paymentStatus`, `paymentType`, `paymentMethod`, `cryptoAmount`, `cryptoCurrency`, `errorMessage` and `billingAddress`; snake_case for `crypto_fx`, `settled_crypto_amount`, `crypto_tx_hash` and `destination_wallet` (and `timezone_type` inside `created`).\n- **The two crypto amounts have different types.** `cryptoAmount` is a **string** (`\"53.36000000\"`) while `settled_crypto_amount` is a **number** (`53.35`). Parse each accordingly rather than assuming one shape.\n", "operationId": "getPaymentById", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Unique payment identifier (UUID)", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Payment retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPaymentResponse" }, "examples": { "Failed": { "summary": "FAILED — declined, with a decline reason", "value": { "result": { "id": "0199aaaa-bbbb-7ccc-dddd-eeeeffff0001", "paymentStatus": "FAILED", "created": { "date": "2026-09-21 14:00:02.000000", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "Deposit TXN-SAMPLE0000000000000001", "paymentMethod": "USER_CHOICE", "reference": "TXN-SAMPLE0000000000000001", "amount": 57.3, "cryptoAmount": "53.36000000", "cryptoCurrency": "USDC", "currency": "USD", "customer": { "firstName": "JOHN", "lastName": "DOE", "email": "john.doe@example.com", "phone": "+447700900001", "ipaddress": "2001:db8:750:4101::6e8c", "dateOfBirth": "1985-06-15", "referenceId": "10001", "accountNumber": null, "bankCode": null }, "billingAddress": { "address1": null, "city": null, "countryCode": "GB", "postalCode": null, "state": null }, "errorMessage": "Payment not funded", "crypto_fx": 1.07383808 } } }, "Completed": { "summary": "COMPLETED — settled on chain", "value": { "result": { "id": "0199aaaa-bbbb-7ccc-dddd-eeeeffff0002", "paymentStatus": "COMPLETED", "created": { "date": "2026-09-21 16:20:44.000000", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "Deposit TXN-SAMPLE0000000000000002", "paymentMethod": "USER_CHOICE", "reference": "TXN-SAMPLE0000000000000002", "amount": 57.3, "cryptoAmount": "53.36000000", "cryptoCurrency": "USDC", "currency": "USD", "customer": { "firstName": "JANE", "lastName": "ROE", "email": "jane.roe@example.com", "phone": "+447700900002", "ipaddress": "2001:db8:13e7:3a01::bb2", "dateOfBirth": "1990-03-22", "referenceId": "10002", "accountNumber": null, "bankCode": null }, "billingAddress": { "address1": null, "city": null, "countryCode": "GB", "postalCode": null, "state": null }, "settled_crypto_amount": 53.35, "crypto_fx": 1.07403936, "crypto_tx_hash": "0x1111111111111111111111111111111111111111111111111111111111111111", "destination_wallet": "0x1234567890abcdef1234567890abcdef12345678" } } } } } } }, "401": { "$ref": "#/components/responses/UnauthorizedError" }, "404": { "$ref": "#/components/responses/NotFoundError" } }, "security": [ { "Bearer": [] } ] } } }, "components": { "securitySchemes": { "Bearer": { "type": "http", "scheme": "bearer", "description": "API Key used as a Bearer token" }, "Signature": { "type": "apiKey", "in": "header", "name": "Signature", "description": "HMAC SHA-256 signature of the request payload, sent in the `Signature` header. Compute it as `hash_hmac('sha256', body, signKey)` over the **exact JSON body** you send — see the **Authentication** section of the *Create a deposit or a withdrawal* operation for a full PHP example." } }, "responses": { "PaymentCreated": { "description": "Payment created successfully.\n\nThe payment is returned **wrapped in a `result` object**:\n\n```json\n{ \"result\": { \"id\": \"...\", \"paymentStatus\": \"PENDING\", ... } }\n```\n\nFor **deposits (pay-ins)** `result` includes a `redirectUrl` — redirect your customer there to complete the payment. For **withdrawals (payouts)** there is no `redirectUrl`.\n\nThe payment starts as `PENDING`; the **final status (completed or failed) is delivered to your `webhookUrl` as a callback** (see **Callbacks** below), not in this response. Note that webhook payloads are **not** wrapped in `result` — their fields are at the top level.\n\n**PAYID H2H deposits** additionally return the PayID transfer details as top-level fields alongside `result` — `number` (the PayID address), `full_holder_name`, `payment_description`, `amount`, `currency`, `uuid`, `order_id`. Display these to your customer so they can complete the bank transfer; there is no redirect in this flow.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentCreatedBody" }, "examples": { "ApplePay": { "summary": "Apple Pay response", "value": { "result": { "id": "01990efa-5437-70c6-8244-85546f382bb3", "paymentStatus": "PENDING", "created": { "date": "2025-09-03 12:48:31.020712", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "Test ApplePay payment for order order-45c721ca", "paymentMethod": "APPLEPAY", "reference": "order-45c721ca", "amount": 10.23, "currency": "EUR", "customer": null, "billingAddress": { "address1": null, "city": null, "countryCode": "LT", "postalCode": null, "state": null }, "redirectUrl": "https://gate.napoleonpay.io/payment/form/init/BB38447031435167306949777573304A3062422B4D486E55532F436B733679673758437038776C6A634243343D" } } }, "PAYID": { "summary": "PAYID deposit response — Redirect flow", "value": { "result": { "id": "01990efa-5437-70c6-8244-85546f382bb3", "paymentStatus": "PENDING", "created": { "date": "2025-09-03 12:48:31.020712", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "Test PAYID payment for order order-45c721ca", "paymentMethod": "PAYID", "reference": "order-45c721ca", "amount": 10.23, "currency": "AUD", "customer": null, "billingAddress": { "address1": null, "city": null, "countryCode": "LT", "postalCode": null, "state": null }, "redirectUrl": "https://gate.napoleonpay.io/payment/form/init/BB38447031435167306949777573304A3062422B4D486E55532F436B733679673758437038776C6A634243343D" } } }, "PAYIDH2H": { "summary": "PAYID deposit response — H2H flow", "value": { "result": { "id": "019f6ea2-7413-70b3-a7d4-2441633ca869", "paymentStatus": "PENDING", "created": { "date": "2026-07-17 08:52:48.886873", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "Test payment", "paymentMethod": "PAYID", "reference": "txn_f8fcaef9c2192809", "amount": "100", "currency": "AUD", "customer": { "firstName": "John", "lastName": "Doe", "email": null, "phone": "+370 60000000", "ipaddress": null, "dateOfBirth": null, "referenceId": null, "accountNumber": null, "bankCode": null } }, "number": "PAYID@EXAMPLE.COM", "full_holder_name": "EXAMPLE ACCOUNT HOLDER", "payment_description": "839646", "amount": "100.00", "currency": "AUD", "uuid": "636d3b0a-c7c9-456e-b73d-1f8f305dece1", "order_id": "019f6ea2-7413-70b3-a7d4-2441633ca869" } }, "GooglePay": { "summary": "Google Pay response", "value": { "result": { "id": "01990ef9-cef3-7041-8b78-7b60cea8f49b", "paymentStatus": "PENDING", "created": { "date": "2025-09-03 12:47:57.293162", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "Test GooglePay payment for order order-9842d960", "paymentMethod": "GOOGLEPAY", "reference": "order-9842d960", "amount": 10.23, "currency": "EUR", "customer": null, "billingAddress": { "address1": null, "city": null, "countryCode": "LT", "postalCode": null, "state": null }, "redirectUrl": "https://gate.napoleonpay.io/payment/form/init/BB38447031435167306949777573304A3062422B4D486E55532F436B733679673758437038776C6A634243343D", "fallbackPaymentStatus": 1 } } }, "Blik": { "summary": "BLIK response", "value": { "result": { "id": "01990efb-a655-74cb-a0bf-da9fcce56282", "paymentStatus": "PENDING", "created": { "date": "2025-09-03 12:49:57.972605", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "Test payment for BLIK order order-f59d99d0", "paymentMethod": "BLIK", "reference": "24614a49f36d4712b6de0496c1e5bdb8", "amount": 20.23, "currency": "PLN", "customer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+370 60000000", "ipaddress": "203.0.113.10" }, "billingAddress": { "address1": "211 Victory Street", "city": "Vilnius", "countryCode": "LT", "postalCode": "01001", "state": "Vilnius" }, "redirectUrl": "https://gate.napoleonpay.io/payment/form/init/BB38447031435167306949777573304A3062422B4D486E55532F436B733679673758437038776C6A634243343D" } } }, "CARD": { "summary": "CARD response", "value": { "result": { "id": "01990eff-2aa1-7031-bc33-cbec6a97c4c2", "paymentStatus": "PENDING", "created": { "date": "2025-09-03 12:53:49.305205", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "Test payment", "paymentMethod": "CARD", "amount": 21.2, "currency": "EUR", "customer": { "firstName": null, "lastName": null, "email": "john.doe@example.com", "phone": null, "ipaddress": null, "referenceId": "MERCHANT-REF-001" }, "billingAddress": { "address1": null, "city": "Vilnius", "countryCode": "LT", "postalCode": "01001", "state": "Vilnius" }, "authorizationCode": null, "cardType": null, "redirectUrl": "https://gate.napoleonpay.io/payment/form/init/BB38447031435167306949777573304A3062422B4D486E55532F436B733679673758437038776C6A634243343D" } } }, "ONRAMP": { "summary": "ONRAMP response", "value": { "result": { "id": "01990eff-2aa1-7031-bc33-cbec6a97c4c2", "paymentStatus": "PENDING", "created": { "date": "2025-09-03 12:53:49.305205", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "Test payment", "paymentMethod": "ONRAMP", "amount": 21.2, "currency": "EUR", "customer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+370 60000000", "ipaddress": null, "referenceId": "MERCHANT-REF-001", "dateOfBirth": "1990-01-01" }, "billingAddress": { "address1": "211 Victory Street", "city": "Vilnius", "countryCode": "LT", "postalCode": "01001", "state": "Vilnius" }, "redirectUrl": "https://gate.napoleonpay.io/payment/form/init/BB38447031435167306949777573304A3062422B4D486E55532F436B733679673758437038776C6A634243343D" } } }, "Ideal": { "summary": "iDEAL response", "value": { "result": { "id": "019bf0a1-3c44-7a01-9b22-77ad9f0e1231", "paymentStatus": "PENDING", "created": { "date": "2026-01-24 10:15:00.000000", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "3a8e40a2-64e5-439d-99a5-09acbe8d5b7f order", "paymentMethod": "IDEAL", "reference": null, "amount": 10, "currency": "EUR", "customer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+370 60000000" }, "redirectUrl": "https://gate.napoleonpay.io/payment/form/init/BB38447031435167306949777573304A3062422B4D486E55532F436B733679673758437038776C6A634243343D" } } }, "Bancontact": { "summary": "Bancontact response", "value": { "result": { "id": "019bf0a1-3c44-7a01-9b22-77ad9f0e1232", "paymentStatus": "PENDING", "created": { "date": "2026-01-24 10:15:00.000000", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "3a8e40a2-64e5-439d-99a5-09acbe8d5b7f order", "paymentMethod": "BANCONTACT", "reference": null, "amount": 10, "currency": "EUR", "customer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+370 60000000" }, "redirectUrl": "https://gate.napoleonpay.io/payment/form/init/BB38447031435167306949777573304A3062422B4D486E55532F436B733679673758437038776C6A634243343D" } } }, "Multibanco": { "summary": "Multibanco response", "value": { "result": { "id": "019bf0a1-3c44-7a01-9b22-77ad9f0e1234", "paymentStatus": "PENDING", "created": { "date": "2026-01-24 10:15:00.000000", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "3a8e40a2-64e5-439d-99a5-09acbe8d5b7f order", "paymentMethod": "MULTIBANCO", "reference": null, "amount": 10, "currency": "EUR", "customer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+370 60000000" }, "redirectUrl": "https://gate.napoleonpay.io/payment/form/init/BB38447031435167306949777573304A3062422B4D486E55532F436B733679673758437038776C6A634243343D" } } }, "Eps": { "summary": "EPS response", "value": { "result": { "id": "019bf0a1-3c44-7a01-9b22-77ad9f0e1235", "paymentStatus": "PENDING", "created": { "date": "2026-01-24 10:15:00.000000", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "3a8e40a2-64e5-439d-99a5-09acbe8d5b7f order", "paymentMethod": "EPS", "reference": null, "amount": 10, "currency": "EUR", "customer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+370 60000000" }, "redirectUrl": "https://gate.napoleonpay.io/payment/form/init/BB38447031435167306949777573304A3062422B4D486E55532F436B733679673758437038776C6A634243343D" } } }, "Przelewy24": { "summary": "Przelewy24 (P24) response", "value": { "result": { "id": "019bf0a1-3c44-7a01-9b22-77ad9f0e1236", "paymentStatus": "PENDING", "created": { "date": "2026-01-24 10:15:00.000000", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "DEPOSIT", "description": "3a8e40a2-64e5-439d-99a5-09acbe8d5b7f order", "paymentMethod": "P24", "reference": null, "amount": 10, "currency": "PLN", "customer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+370 60000000" }, "redirectUrl": "https://gate.napoleonpay.io/payment/form/init/BB38447031435167306949777573304A3062422B4D486E55532F436B733679673758437038776C6A634243343D" } } }, "PAYIDWithdrawal": { "summary": "PAYID withdrawal response", "value": { "result": { "id": "019e6dca-cf46-77d7-8765-c1d5cfa15983", "paymentStatus": "PENDING", "created": { "date": "2026-05-28 08:54:29.276107", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "WITHDRAWAL", "description": "Payout order YOUR-SYSTEM-TRX-ID", "paymentMethod": "PAYID", "reference": "YOUR-SYSTEM-TRX-ID", "amount": "20", "currency": "AUD", "customer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+370 60000000", "ipaddress": "203.0.113.10", "dateOfBirth": null, "referenceId": "MERCHANT-REF-001" }, "billingAddress": { "address1": "211 Victory Street", "city": "Vilnius", "countryCode": "LT", "postalCode": "01001", "state": "Vilnius" } } } }, "SEPAWithdrawal": { "summary": "SEPA withdrawal response", "value": { "result": { "id": "019e7a01-3c44-7a01-9b22-77ad9f0e9abc", "paymentStatus": "PENDING", "created": { "date": "2026-05-28 09:10:00.000000", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "WITHDRAWAL", "description": "Payout order x112", "paymentMethod": "SEPA", "reference": "x112", "amount": "2", "currency": "EUR", "customer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+370 60000000", "ipaddress": "203.0.113.10", "dateOfBirth": null, "referenceId": "MERCHANT-REF-001", "accountNumber": "LT63550037167864539" }, "billingAddress": { "address1": "211 Victory Street", "city": "Vilnius", "countryCode": "LT", "postalCode": "01001", "state": "Vilnius" } } } }, "FPSWithdrawal": { "summary": "FPS withdrawal response", "value": { "result": { "id": "019f41de-2099-7efb-bc32-79ff81f37585", "paymentStatus": "PENDING", "created": { "date": "2026-07-08 16:15:04.745285", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "paymentType": "WITHDRAWAL", "description": "Payout order x11555", "paymentMethod": "FPS", "reference": "x11555", "amount": "1", "currency": "GBP", "customer": { "firstName": "John", "lastName": "Doe", "email": "john.doe@example.com", "phone": "+370 60000000", "ipaddress": "203.0.113.10", "dateOfBirth": null, "referenceId": "MERCHANT-REF-001", "accountNumber": "12345678", "bankCode": "040004" }, "billingAddress": { "address1": "211 Victory Street", "city": "Vilnius", "countryCode": "LT", "postalCode": "01001", "state": "Vilnius" } } } }, "CardWithdrawal": { "summary": "CARD withdrawal response", "value": { "result": { "id": "01a10000-0000-7000-8000-000000000001", "reference": "PAYOUT-2026-000123", "paymentStatus": "PENDING", "paymentType": "WITHDRAWAL", "paymentMethod": "CARD", "amount": 50, "currency": "EUR", "created": { "date": "2026-10-06 12:34:56.123456", "timezone_type": 3, "timezone": "Europe/Vilnius" }, "customer": { "firstName": "JOHN", "lastName": "DOE", "email": null, "phone": null, "ipaddress": null, "dateOfBirth": null, "referenceId": "PLAYER-10045", "accountNumber": null, "bankCode": null } } } }, "Refused": { "summary": "Refused — no payment created (HTTP 200, success false)", "value": { "success": false, "message": "Response validation failed", "info": [] } } } } } }, "BadRequestError": { "description": "The payment type or method is not enabled for this project.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotAllowedError" }, "examples": { "TypeNotAllowed": { "summary": "Payout not enabled for this project", "value": { "success": false, "message": "Payments of the chosen type are not allowed for this terminal" } }, "NoTerminal": { "summary": "No terminal for that method and currency", "value": { "success": false, "message": "No terminal configured for payment method: CARD (EUR)" } } } } } }, "UnauthorizedError": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthError" }, "examples": { "InvalidKey": { "summary": "Invalid API key", "value": { "message": "Invalid API Key" } } } } } }, "NotFoundError": { "description": "No payment exists with the supplied `id`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ValidationError": { "description": "Input validation failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationProblem" }, "examples": { "MissingField": { "summary": "Required field missing", "value": { "type": "https://symfony.com/errors/validation", "title": "Validation Failed", "status": 422, "detail": "customer.referenceId: This value should not be null.", "violations": [ { "propertyPath": "customer.referenceId", "title": "This value should not be null.", "template": "This value should not be null.", "parameters": { "{{ value }}": "null" }, "type": "urn:uuid:ad32d13f-c3d4-423b-909a-857b961eb720" } ] } }, "DuplicateReference": { "summary": "reference already used", "value": { "type": "https://symfony.com/errors/validation", "title": "Validation Failed", "status": 422, "detail": "reference: Transaction with same reference already exists for this project", "violations": [ { "propertyPath": "reference", "title": "Transaction with same reference already exists for this project", "template": "Transaction with same reference already exists for this project", "parameters": {}, "type": "urn:uuid:23bd9dbf-6b9b-41cd-a99e-4844bcf3077f" } ] } }, "BadPan": { "summary": "Card number rejected", "value": { "type": "https://symfony.com/errors/validation", "title": "Validation Failed", "status": 422, "detail": "card.pan: PAN must be 12-19 digits", "violations": [ { "propertyPath": "card.pan", "title": "PAN must be 12-19 digits", "template": "PAN must be 12-19 digits", "parameters": {}, "type": "urn:uuid:9ff3fdc4-b214-49db-8718-39c315e33d45" } ] } } } } } } }, "schemas": { "Error": { "type": "object", "description": "Standard error envelope returned on 4xx responses. NOTE: this shape is illustrative — replace it with NapoleonPay's actual error body once confirmed.", "properties": { "message": { "type": "string", "description": "Human-readable description of what went wrong" }, "code": { "type": "string", "nullable": true, "description": "Machine-readable error code, when available" } } }, "PaymentRequest": { "oneOf": [ { "$ref": "#/components/schemas/PaymentRequestApplePay" }, { "$ref": "#/components/schemas/PaymentRequestGooglePay" }, { "$ref": "#/components/schemas/PaymentRequestBlik" }, { "$ref": "#/components/schemas/PaymentRequestCARD" }, { "$ref": "#/components/schemas/PaymentRequestONRAMP" }, { "$ref": "#/components/schemas/PaymentRequestPAYID" }, { "$ref": "#/components/schemas/PaymentRequestAPM" }, { "$ref": "#/components/schemas/WithdrawalRequestPAYID" }, { "$ref": "#/components/schemas/WithdrawalRequestSEPA" }, { "$ref": "#/components/schemas/WithdrawalRequestFPS" }, { "$ref": "#/components/schemas/WithdrawalRequestCARD" } ], "description": "Pick the flow you need. Deposits (pay-ins) and withdrawals (payouts) are listed separately, because they require different fields even when they share a `paymentMethod`." }, "PaymentType": { "type": "string", "enum": [ "DEPOSIT", "WITHDRAWAL" ] }, "CustomerInfo": { "type": "object", "nullable": true, "description": "Customer details.", "properties": { "firstName": { "type": "string", "nullable": true }, "lastName": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "phone": { "type": "string", "nullable": true }, "ipaddress": { "type": "string", "nullable": true }, "referenceId": { "type": "string", "nullable": true }, "dateOfBirth": { "type": "string", "nullable": true, "description": "Required only when making card FTD" }, "accountNumber": { "type": "string", "nullable": true, "description": "Recipient IBAN. Required for SEPA withdrawals." }, "bankCode": { "type": "string", "nullable": true, "description": "Bank / sort code. Required for FPS withdrawals." } } }, "BillingAddress": { "type": "object", "description": "Billing address.", "properties": { "address1": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true }, "state": { "type": "string", "nullable": true } } }, "CardInfo": { "type": "object", "description": "Card details required for CARD payment method.", "properties": { "pan": { "type": "string", "description": "Primary account number (card number)" }, "cvv": { "type": "string", "description": "Card verification value" }, "exp_month": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Expiry month (1–12). Accepted as a number or a string (\"11\")." }, "exp_year": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Expiry year, 4-digit. Accepted as a number or a string (\"2030\")." }, "holder": { "type": "string", "description": "Cardholder name as it appears on the card" } }, "required": [ "pan", "cvv", "exp_month", "exp_year", "holder" ] }, "AdditionalParameters": { "type": "object", "description": "Method-specific parameters.", "properties": { "purpose": { "type": "string", "description": "Payment purpose." } } }, "Browser": { "type": "object", "description": "Browser information (commonly required for wallet-based methods).", "properties": { "acceptHeader": { "type": "string", "nullable": true }, "colorDepth": { "type": "integer", "nullable": true }, "ip": { "type": "string", "nullable": true }, "language": { "type": "string", "nullable": true }, "screenHeight": { "type": "integer", "nullable": true }, "screenWidth": { "type": "integer", "nullable": true }, "timeZone": { "type": "integer", "nullable": true }, "userAgent": { "type": "string", "nullable": true }, "javaEnabled": { "type": "boolean", "nullable": true }, "windowWidth": { "type": "integer", "nullable": true }, "windowHeight": { "type": "integer", "nullable": true } } }, "BaseRequest": { "type": "object", "properties": { "paymentType": { "$ref": "#/components/schemas/PaymentType" }, "paymentMethod": { "type": "string", "enum": [ "APPLEPAY", "GOOGLEPAY", "BLIK", "CARD", "ONRAMP", "ONRAMP_PAYID", "ONRAMP_PIX", "ONRAMP_ZAR", "ONRAMP_PSE", "ONRAMP_KHIPU", "ONRAMP_QRTHWALLET", "ONRAMP_CARD", "ONRAMP_INTERAC", "ONRAMP_OPENBANKING", "ONRAMP_GBPBANKTRANSFER", "ONRAMP_SPEI", "ONRAMP_APPLEPAY", "ONRAMP_GOOGLEPAY", "PAYID", "IDEAL", "BANCONTACT", "MULTIBANCO", "EPS", "P24", "SEPA", "FPS", "USER_CHOICE" ] }, "amount": { "type": "number", "format": "float", "minimum": 0, "exclusiveMinimum": true }, "currency": { "type": "string" } }, "required": [ "paymentType", "paymentMethod", "amount", "currency" ] }, "GetPaymentResponse": { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/PaymentStatusResult" } } }, "PaymentRequestApplePay": { "allOf": [ { "$ref": "#/components/schemas/BaseRequest" }, { "type": "object", "properties": { "paymentMethod": { "type": "string", "enum": [ "APPLEPAY" ] }, "additionalParameters": { "$ref": "#/components/schemas/AdditionalParametersOnramp" }, "reference": { "type": "string", "nullable": true }, "billingAddress": { "allOf": [ { "$ref": "#/components/schemas/BillingAddress" }, { "type": "object", "required": [ "countryCode" ] } ] }, "returnUrl": { "type": "string", "nullable": true }, "webhookUrl": { "type": "string", "nullable": true, "description": "URL to receive payment status updates. Interchangeable with `callbackUrl` — both perform the same function. At least one of `webhookUrl` or `callbackUrl` must be provided.\n" }, "browser": { "$ref": "#/components/schemas/Browser" }, "paymentType": { "type": "string", "enum": [ "DEPOSIT" ] } }, "required": [ "paymentMethod", "reference", "billingAddress", "returnUrl", "webhookUrl" ], "description": "**Apple Pay deposit.** The response returns a `redirectUrl` — send the customer there to complete the payment.\n\n**Required:** `paymentType`, `paymentMethod`, `amount`, `currency`, `reference`, `billingAddress`, `returnUrl`, `webhookUrl`. To let the customer pick the method instead of fixing it here, send `USER_CHOICE` — see the Onramp entry.\n" } ], "title": "Apple Pay — deposit" }, "PaymentRequestPAYID": { "allOf": [ { "$ref": "#/components/schemas/BaseRequest" }, { "type": "object", "description": "**PayID deposit** (AUD).\n\n**Required:** `paymentType`, `paymentMethod`, `amount`, `currency`, `reference`, `billingAddress.countryCode`, `returnUrl`, `webhookUrl`.\n\nTwo deposit flows exist. *Redirect* returns a `redirectUrl` to send the customer to. *H2H* instead returns the PayID transfer details as top-level fields on the response (`number`, `full_holder_name`, `payment_description`) for you to display — there is no redirect. Which applies depends on your account configuration; webhooks are identical either way.\n", "properties": { "paymentMethod": { "type": "string", "enum": [ "PAYID" ] }, "reference": { "type": "string", "nullable": true }, "webhookUrl": { "type": "string", "nullable": true, "description": "URL to receive payment status updates. Interchangeable with `callbackUrl` — both perform the same function. At least one of `webhookUrl` or `callbackUrl` must be provided.\n" }, "billingAddress": { "allOf": [ { "$ref": "#/components/schemas/BillingAddress" }, { "type": "object", "required": [ "countryCode" ] } ] }, "returnUrl": { "type": "string", "nullable": true }, "paymentType": { "type": "string", "enum": [ "DEPOSIT" ] } }, "required": [ "paymentMethod", "reference", "billingAddress", "returnUrl", "webhookUrl" ] } ], "title": "PayID — deposit" }, "PaymentRequestGooglePay": { "allOf": [ { "$ref": "#/components/schemas/BaseRequest" }, { "type": "object", "properties": { "paymentMethod": { "type": "string", "enum": [ "GOOGLEPAY" ] }, "additionalParameters": { "$ref": "#/components/schemas/AdditionalParametersOnramp" }, "reference": { "type": "string", "nullable": true }, "billingAddress": { "allOf": [ { "$ref": "#/components/schemas/BillingAddress" }, { "type": "object", "required": [ "countryCode" ] } ] }, "returnUrl": { "type": "string", "nullable": true }, "webhookUrl": { "type": "string", "nullable": true, "description": "URL to receive payment status updates. Interchangeable with `callbackUrl` — both perform the same function. At least one of `webhookUrl` or `callbackUrl` must be provided.\n" }, "browser": { "$ref": "#/components/schemas/Browser" }, "paymentType": { "type": "string", "enum": [ "DEPOSIT" ] } }, "required": [ "paymentMethod", "reference", "billingAddress", "returnUrl", "webhookUrl" ], "description": "**Google Pay deposit.** The response returns a `redirectUrl` — send the customer there to complete the payment.\n\n**Required:** `paymentType`, `paymentMethod`, `amount`, `currency`, `reference`, `billingAddress`, `returnUrl`, `webhookUrl`. To let the customer pick the method instead of fixing it here, send `USER_CHOICE` — see the Onramp entry.\n" } ], "title": "Google Pay — deposit" }, "PaymentRequestBlik": { "allOf": [ { "$ref": "#/components/schemas/BaseRequest" }, { "type": "object", "properties": { "paymentMethod": { "type": "string", "enum": [ "BLIK" ] }, "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerInfo" }, { "type": "object", "required": [ "email", "firstName", "lastName", "phone", "ipaddress" ] } ] }, "billingAddress": { "allOf": [ { "$ref": "#/components/schemas/BillingAddress" }, { "type": "object", "required": [ "address1", "city", "state", "countryCode", "postalCode" ] } ] }, "returnUrl": { "type": "string", "nullable": true }, "webhookUrl": { "type": "string", "nullable": true, "description": "URL to receive payment status updates. Interchangeable with `callbackUrl` — both perform the same function. At least one of `webhookUrl` or `callbackUrl` must be provided.\n" }, "paymentType": { "type": "string", "enum": [ "DEPOSIT" ] } }, "required": [ "paymentMethod", "customer", "billingAddress", "returnUrl", "webhookUrl" ], "description": "**BLIK deposit** (PLN). The response returns a `redirectUrl` — send the customer there to enter their BLIK code.\n\n**Required:** `paymentType`, `paymentMethod`, `amount`, `currency`, `customer` (`email`, `firstName`, `lastName`, `phone`, `ipaddress`), `billingAddress`, `returnUrl`, `webhookUrl`.\n" } ], "title": "BLIK — deposit" }, "PaymentRequestCARD": { "allOf": [ { "$ref": "#/components/schemas/BaseRequest" }, { "type": "object", "properties": { "paymentMethod": { "type": "string", "enum": [ "CARD" ] }, "additionalParameters": { "$ref": "#/components/schemas/AdditionalParametersOnramp" }, "card": { "$ref": "#/components/schemas/CardInfo" }, "merchantUrl": { "type": "string", "nullable": true, "description": "URL of the merchant site or storefront initiating the payment." }, "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerInfo" }, { "type": "object", "required": [ "referenceId", "email", "firstName", "lastName", "phone", "dateOfBirth" ] } ] }, "billingAddress": { "allOf": [ { "$ref": "#/components/schemas/BillingAddress" }, { "type": "object", "required": [ "address1", "city", "state", "countryCode", "postalCode" ] } ] }, "callbackUrl": { "type": "string", "nullable": true, "description": "URL to receive payment status updates. Interchangeable with `webhookUrl` — both perform the same function. At least one of `callbackUrl` or `webhookUrl` must be provided.\n" }, "browser": { "$ref": "#/components/schemas/Browser" }, "paymentType": { "type": "string", "enum": [ "DEPOSIT" ] } }, "required": [ "paymentMethod", "merchantUrl", "customer", "billingAddress", "card", "callbackUrl", "additionalParameters" ], "description": "**Card deposit.** Send the card details in `card`. The response returns a `redirectUrl`, which carries the customer through 3-D Secure where required.\n\n**Required:** `paymentType`, `paymentMethod`, `amount`, `currency`, `card` (`pan`, `cvv`, `exp_month`, `exp_year`, `holder`), `customer` — including `dateOfBirth` for a first-time deposit — `billingAddress`, `merchantUrl`, `callbackUrl`, `additionalParameters`. To let the customer pick the method instead of fixing it here, send `USER_CHOICE` — see the Onramp entry.\n" } ], "title": "Card — deposit" }, "PaymentRequestONRAMP": { "allOf": [ { "$ref": "#/components/schemas/BaseRequest" }, { "type": "object", "properties": { "paymentMethod": { "type": "string", "enum": [ "USER_CHOICE", "ONRAMP", "ONRAMP_PAYID", "ONRAMP_PIX", "ONRAMP_ZAR", "ONRAMP_PSE", "ONRAMP_KHIPU", "ONRAMP_QRTHWALLET", "ONRAMP_CARD", "ONRAMP_INTERAC", "ONRAMP_OPENBANKING", "ONRAMP_GBPBANKTRANSFER", "ONRAMP_SPEI", "ONRAMP_APPLEPAY", "ONRAMP_GOOGLEPAY" ] }, "additionalParameters": { "$ref": "#/components/schemas/AdditionalParametersOnramp" }, "merchantUrl": { "type": "string", "nullable": true, "description": "URL of the merchant site or storefront initiating the payment." }, "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerInfo" }, { "type": "object", "required": [ "referenceId", "email", "firstName", "lastName", "phone", "dateOfBirth" ] } ] }, "billingAddress": { "allOf": [ { "$ref": "#/components/schemas/BillingAddress" }, { "type": "object", "required": [ "address1", "city", "state", "countryCode", "postalCode" ] } ] }, "callbackUrl": { "type": "string", "nullable": true, "description": "URL to receive payment status updates. Interchangeable with `webhookUrl` — both perform the same function. At least one of `callbackUrl` or `webhookUrl` must be provided.\n" }, "paymentType": { "type": "string", "enum": [ "DEPOSIT" ] } }, "required": [ "paymentMethod", "merchantUrl", "customer", "billingAddress", "callbackUrl", "additionalParameters" ], "description": "**Onramp deposit.** Fiat is converted and delivered to the customer's wallet, so the crypto destination goes in `additionalParameters`. The response returns a `redirectUrl`.\n\n**Required:** `paymentType`, `paymentMethod`, `amount`, `currency`, `customer`, `billingAddress`, `merchantUrl`, `callbackUrl`, `additionalParameters`.\n\n### Who picks the payment method\n\nOn an onramp payment you decide whether the customer chooses how to pay, or you fix it up front:\n\n- **Let the customer choose** — send `paymentMethod: USER_CHOICE`. The widget offers **Apple Pay, Google Pay and card**, and the customer picks one.\n- **Choose for them** — send `CARD`, `APPLEPAY` or `GOOGLEPAY` instead, as their own payment methods (see the Card, Apple Pay and Google Pay entries in the selector). The widget is then pinned to that one method.\n\n> This choice exists **only for onramp**. `USER_CHOICE` has no meaning for the other payment methods, and outside an onramp terminal the crypto fields in `additionalParameters` do not apply.\n" } ], "title": "Onramp — deposit" }, "PaymentRequestAPM": { "allOf": [ { "$ref": "#/components/schemas/BaseRequest" }, { "type": "object", "description": "**European bank-redirect APMs** — iDEAL, Bancontact, Multibanco, EPS and Przelewy24 (P24). The response returns a `redirectUrl` that sends the customer to their bank; the final status arrives on your `webhookUrl`.\n\n**Required:** `paymentType`, `paymentMethod`, `amount`, `currency`, `description`, `externalApiId`, `webhookUrl`, `customer` (`firstName`, `lastName`, `email`, `phone`).\n\nPrzelewy24 settles in PLN; the others in EUR.\n", "properties": { "paymentMethod": { "type": "string", "enum": [ "IDEAL", "BANCONTACT", "MULTIBANCO", "EPS", "P24" ] }, "description": { "type": "string", "nullable": true }, "externalApiId": { "type": "string", "nullable": true }, "webhookUrl": { "type": "string", "nullable": true, "description": "URL to receive payment status updates. Interchangeable with `callbackUrl` — both perform the same function. At least one of `webhookUrl` or `callbackUrl` must be provided.\n" }, "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerInfo" }, { "type": "object", "required": [ "firstName", "lastName", "email", "phone" ] } ] }, "paymentType": { "type": "string", "enum": [ "DEPOSIT" ] } }, "required": [ "paymentMethod", "description", "externalApiId", "webhookUrl", "customer" ] } ], "title": "Bank redirect: iDEAL, Bancontact, Multibanco, EPS, P24 — deposit" }, "WithdrawalRequestSEPA": { "allOf": [ { "$ref": "#/components/schemas/BaseRequest" }, { "type": "object", "description": "**SEPA payout** (EUR). Funds are sent to the recipient's IBAN — there is no redirect and no `redirectUrl` on the response.\n\n**Required:** `paymentType`, `paymentMethod`, `amount`, `currency`, `description`, `reference`, `billingAddress`, `callbackUrl`, `additionalParameters`, and `customer` — which must carry the recipient IBAN in `customer.accountNumber`, alongside `email`, `firstName`, `lastName`, `phone` and `referenceId`.\n", "properties": { "paymentMethod": { "type": "string", "enum": [ "SEPA" ] }, "additionalParameters": { "$ref": "#/components/schemas/AdditionalParameters" }, "description": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerInfo" }, { "type": "object", "required": [ "referenceId", "email", "firstName", "lastName", "phone", "accountNumber" ] } ] }, "billingAddress": { "allOf": [ { "$ref": "#/components/schemas/BillingAddress" }, { "type": "object", "required": [ "address1", "city", "state", "countryCode", "postalCode" ] } ] }, "callbackUrl": { "type": "string", "nullable": true, "description": "URL to receive payment status updates. Interchangeable with `webhookUrl` — both perform the same function. At least one of `callbackUrl` or `webhookUrl` must be provided.\n" }, "paymentType": { "type": "string", "enum": [ "WITHDRAWAL" ] } }, "required": [ "paymentMethod", "description", "reference", "customer", "billingAddress", "callbackUrl", "additionalParameters" ] } ], "title": "SEPA — withdrawal" }, "WithdrawalRequestFPS": { "allOf": [ { "$ref": "#/components/schemas/BaseRequest" }, { "type": "object", "description": "**FPS payout** — UK Faster Payments (GBP). Funds are sent to a UK account; there is no redirect and no `redirectUrl` on the response.\n\n**Required:** `paymentType`, `paymentMethod`, `amount`, `currency`, `description`, `reference`, `billingAddress`, `callbackUrl`, `additionalParameters`, and `customer` — which must carry `accountNumber` (8-digit UK account number) and `bankCode` (6-digit sort code), alongside `email`, `firstName`, `lastName`, `phone`, `referenceId` and `ipaddress`.\n", "properties": { "paymentMethod": { "type": "string", "enum": [ "FPS" ] }, "additionalParameters": { "$ref": "#/components/schemas/AdditionalParameters" }, "description": { "type": "string", "nullable": true }, "reference": { "type": "string", "nullable": true }, "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerInfo" }, { "type": "object", "required": [ "referenceId", "email", "firstName", "lastName", "phone", "accountNumber", "bankCode", "ipaddress" ] } ] }, "billingAddress": { "allOf": [ { "$ref": "#/components/schemas/BillingAddress" }, { "type": "object", "required": [ "address1", "city", "state", "countryCode", "postalCode" ] } ] }, "callbackUrl": { "type": "string", "nullable": true, "description": "URL to receive payment status updates. Interchangeable with `webhookUrl` — both perform the same function. At least one of `callbackUrl` or `webhookUrl` must be provided.\n" }, "paymentType": { "type": "string", "enum": [ "WITHDRAWAL" ] } }, "required": [ "paymentMethod", "description", "reference", "customer", "billingAddress", "callbackUrl", "additionalParameters" ] } ], "title": "FPS — withdrawal" }, "PaymentResponse": { "title": "Payment response", "type": "object", "required": [ "result" ], "description": "The created payment, wrapped in a `result` object. Deposits include a `redirectUrl` inside `result` (Redirect flow); withdrawals do not. For **PAYID H2H** deposits the response additionally carries the PayID transfer details as top-level fields next to `result` (`number`, `full_holder_name`, `payment_description`, …) — display these to your customer instead of redirecting.", "properties": { "result": { "$ref": "#/components/schemas/BasePaymentResponse" }, "number": { "type": "string", "nullable": true, "description": "PAYID H2H flow only. The PayID address (e.g. an email) your customer must send the transfer to. Display it together with `payment_description` and `amount`." }, "full_holder_name": { "type": "string", "nullable": true, "description": "PAYID H2H flow only. Account holder name of the receiving PayID — show it to the customer so they can verify the recipient." }, "payment_description": { "type": "string", "nullable": true, "description": "PAYID H2H flow only. Payment reference code the customer must attach to the transfer." }, "amount": { "type": "string", "nullable": true, "description": "PAYID H2H flow only. Amount to transfer, formatted with two decimals." }, "currency": { "type": "string", "nullable": true, "description": "PAYID H2H flow only. Currency of the transfer." }, "uuid": { "type": "string", "nullable": true, "description": "PAYID H2H flow only. Unique identifier of this H2H payment instruction." }, "order_id": { "type": "string", "nullable": true, "description": "PAYID H2H flow only. Equals `result.id` — the NapoleonPay payment id." } } }, "BasePaymentResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique payment identifier (UUID)" }, "paymentStatus": { "type": "string", "enum": [ "PENDING", "AUTHORIZED", "COMPLETED", "FAILED", "CANCELED" ] }, "created": { "type": "object", "properties": { "date": { "type": "string" }, "timezone_type": { "type": "integer" }, "timezone": { "type": "string" } } }, "paymentType": { "type": "string", "enum": [ "DEPOSIT", "WITHDRAWAL" ] }, "description": { "type": "string", "nullable": true }, "paymentMethod": { "type": "string", "enum": [ "APPLEPAY", "GOOGLEPAY", "BLIK", "CARD", "ONRAMP", "ONRAMP_PAYID", "ONRAMP_PIX", "ONRAMP_ZAR", "ONRAMP_PSE", "ONRAMP_KHIPU", "ONRAMP_QRTHWALLET", "ONRAMP_CARD", "ONRAMP_INTERAC", "ONRAMP_OPENBANKING", "ONRAMP_GBPBANKTRANSFER", "ONRAMP_SPEI", "ONRAMP_APPLEPAY", "ONRAMP_GOOGLEPAY", "PAYID", "IDEAL", "BANCONTACT", "MULTIBANCO", "EPS", "P24", "SEPA", "FPS", "USER_CHOICE" ] }, "reference": { "type": "string", "nullable": true }, "amount": { "oneOf": [ { "type": "number", "format": "float" }, { "type": "string" } ], "description": "Payment amount. Returned as a number or a string depending on the method and flow (withdrawals and PAYID H2H deposits return it as a string)." }, "currency": { "type": "string" }, "customer": { "$ref": "#/components/schemas/CustomerInfo" }, "billingAddress": { "$ref": "#/components/schemas/BillingAddress" }, "redirectUrl": { "type": "string", "nullable": true, "description": "URL to redirect the customer to complete the payment" }, "fallbackPaymentStatus": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Internal value echoed back on some payments. Ignore it." }, "authorizationCode": { "type": "string", "nullable": true, "description": "Authorization code returned by the card network (CARD only)." }, "cardType": { "type": "string", "nullable": true, "description": "Card brand, e.g. VISA / MASTERCARD (CARD only)." } } }, "WebhookEvent": { "title": "Webhook event (not result-wrapped)", "description": "Payment status-update event delivered to your webhook / callback URL. Unlike the API responses, webhook payloads are **not** wrapped in `result` — the payment fields are at the top level.", "allOf": [ { "$ref": "#/components/schemas/BasePaymentResponse" }, { "type": "object", "properties": { "providerId": { "type": "string", "description": "Internal. Ignore it — currently equal to `id`." } } } ] }, "AdditionalParametersOnramp": { "type": "object", "description": "Method-specific parameters, plus the crypto destination for onramp terminals.", "properties": { "purpose": { "type": "string", "description": "Payment purpose." }, "walletAddress": { "type": "string", "nullable": true, "description": "Destination wallet address. Only applies when your terminal is configured for onramp — the `paymentMethod` itself does not change. These values can be preset on your API key, in which case they do not need to be sent with each request.", "example": "0x0e1B211f6AE916887Da14F17CF9636B64044C868" }, "blockchain": { "type": "string", "nullable": true, "description": "Destination blockchain. Only applies when your terminal is configured for onramp — the `paymentMethod` itself does not change. These values can be preset on your API key, in which case they do not need to be sent with each request.", "example": "polygon" }, "cryptoCurrency": { "type": "string", "nullable": true, "description": "Cryptocurrency to deliver. Only applies when your terminal is configured for onramp — the `paymentMethod` itself does not change. These values can be preset on your API key, in which case they do not need to be sent with each request.", "example": "USDT" } } }, "WithdrawalRequestPAYID": { "title": "PayID — withdrawal", "allOf": [ { "$ref": "#/components/schemas/BaseRequest" }, { "type": "object", "description": "**PayID payout** (AUD). `customer.email` identifies the destination PayID. There is no redirect and no `redirectUrl` on the response — the final status arrives on your `webhookUrl`.\n\n**Required:** `paymentType`, `paymentMethod`, `amount`, `currency`, `reference`, `customer.email`, `webhookUrl`.\n", "properties": { "paymentType": { "type": "string", "enum": [ "WITHDRAWAL" ] }, "paymentMethod": { "type": "string", "enum": [ "PAYID" ] }, "reference": { "type": "string", "nullable": true }, "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerInfo" }, { "type": "object", "required": [ "email" ] } ] }, "webhookUrl": { "type": "string", "nullable": true, "description": "URL to receive payment status updates. Interchangeable with `callbackUrl` — both perform the same function. At least one of `webhookUrl` or `callbackUrl` must be provided.\n" } }, "required": [ "paymentMethod", "reference", "customer", "webhookUrl" ] } ] }, "PaymentStatusResult": { "title": "Payment status", "allOf": [ { "$ref": "#/components/schemas/BasePaymentResponse" }, { "type": "object", "properties": { "cryptoAmount": { "type": "string", "description": "Crypto amount ordered, as a string.", "example": "53.36000000" }, "cryptoCurrency": { "type": "string", "description": "Cryptocurrency ordered.", "example": "USDC" }, "crypto_fx": { "type": "number", "description": "FX rate used to convert the fiat amount to crypto.", "example": 1.07383808 }, "errorMessage": { "type": "string", "description": "Decline reason, relayed from the payment processor. **Present only when `paymentStatus` is `FAILED`, and not guaranteed even then** — see *Reading a decline* below.", "example": "Payment not funded" }, "settled_crypto_amount": { "type": "number", "description": "Crypto actually delivered, which may differ slightly from `cryptoAmount`. Present only when `paymentStatus` is `COMPLETED`.", "example": 53.35 }, "crypto_tx_hash": { "type": "string", "description": "On-chain settlement transaction hash. Present only when `paymentStatus` is `COMPLETED`." }, "destination_wallet": { "type": "string", "description": "Wallet the funds were delivered to. Present only when `paymentStatus` is `COMPLETED`." } } } ] }, "CardPayoutDetails": { "type": "object", "description": "Card to credit. Only the number is used for a payout.", "properties": { "pan": { "type": "string", "pattern": "^[0-9]{12,19}$", "description": "Card number, digits only, 12–19 digits. Must pass the Luhn check.", "example": "4111111111111111" } }, "required": [ "pan" ] }, "WithdrawalRequestCARD": { "title": "Card — withdrawal", "allOf": [ { "$ref": "#/components/schemas/BaseRequest" }, { "type": "object", "description": "**Card payout.** Credits a card directly — there is no redirect, and the final status arrives by webhook.\n\n**Required:** `paymentType`, `paymentMethod`, `amount`, `currency`, `card.pan`, and `customer` carrying `firstName`, `lastName` and `referenceId`.\n\n**Recommended:** `reference` (your own id for the payout — it comes back on every response and webhook, and duplicates are rejected with `422`) and `webhookUrl` (without it you must poll the status endpoint).\n\n> **The receiver's name comes from `customer.firstName` and `customer.lastName`** — set them to the cardholder's name. `card.holder` is not used.\n\n**Do not send** `card.cvv`, `card.exp_month`, `card.exp_year` or `card.holder` — they are not used for payouts, and the CVV in particular should never be sent. `billingAddress` is not used either and can be omitted. `customer.email`, `customer.phone` and `customer.ipaddress` are accepted but unused.\n", "properties": { "paymentType": { "type": "string", "enum": [ "WITHDRAWAL" ] }, "paymentMethod": { "type": "string", "enum": [ "CARD" ] }, "reference": { "type": "string", "nullable": true }, "webhookUrl": { "type": "string", "nullable": true, "description": "URL to receive payment status updates. Interchangeable with `callbackUrl` — both perform the same function. At least one of `webhookUrl` or `callbackUrl` must be provided.\n" }, "customer": { "allOf": [ { "$ref": "#/components/schemas/CustomerInfo" }, { "type": "object", "required": [ "firstName", "lastName", "referenceId" ] } ] }, "card": { "$ref": "#/components/schemas/CardPayoutDetails" } }, "required": [ "paymentMethod", "customer", "card" ] } ] }, "RefusedResponse": { "title": "Refused — no payment created", "type": "object", "description": "Returned with HTTP **200**, but `success` is `false`: the request was refused and **no payment was created**. There is no `id`, nothing follows, and no webhook will arrive. Treat it as failed. Retrying creates a new payment attempt.", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Response validation failed" }, "info": { "type": "array", "items": {} } }, "required": [ "success", "message" ] }, "PaymentCreatedBody": { "oneOf": [ { "$ref": "#/components/schemas/PaymentResponse" }, { "$ref": "#/components/schemas/RefusedResponse" } ], "description": "Either the created payment (wrapped in `result`), or a refusal carrying `success: false` with no payment created." }, "ValidationProblem": { "type": "object", "description": "Input validation failed (RFC 7807 problem document).", "properties": { "type": { "type": "string", "example": "https://symfony.com/errors/validation" }, "title": { "type": "string", "example": "Validation Failed" }, "status": { "type": "integer", "example": 422 }, "detail": { "type": "string", "example": "customer.referenceId: This value should not be null." }, "violations": { "type": "array", "items": { "type": "object", "properties": { "propertyPath": { "type": "string" }, "title": { "type": "string" }, "template": { "type": "string" }, "parameters": { "type": "object" }, "type": { "type": "string" } } } } } }, "NotAllowedError": { "type": "object", "description": "The payment type or method is not enabled for this project.", "properties": { "success": { "type": "boolean", "example": false }, "message": { "type": "string", "example": "Payments of the chosen type are not allowed for this terminal" } } }, "AuthError": { "type": "object", "description": "Authentication failed.", "properties": { "message": { "type": "string", "example": "Invalid API Key" } } } } } }