{ "components": { "schemas": { "AmountRial": { "$id": "#/components/schemas/AmountRial", "description": "Integer amount in IRR rial (never toman).", "examples": [ 1250000 ], "maximum": 1000000000000, "minimum": 1, "type": "integer" }, "ApiKey": { "$id": "#/components/schemas/ApiKey", "properties": { "createdAt": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, "id": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "lastUsedAt": { "anyOf": [ { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, { "type": "null" } ] }, "livemode": { "description": "false for sandbox (test) objects.", "type": "boolean" }, "name": { "type": "string" }, "prefix": { "type": "string" }, "revokedAt": { "anyOf": [ { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, { "type": "null" } ] }, "scopes": { "items": { "enum": [ "invoices:write", "invoices:read" ], "type": "string" }, "type": "array" } }, "required": [ "id", "name", "prefix", "livemode", "scopes", "createdAt", "lastUsedAt", "revokedAt" ], "type": "object" }, "ApproveBrowserChallengeRequest": { "$id": "#/components/schemas/ApproveBrowserChallengeRequest", "properties": { "challengeId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "decision": { "enum": [ "approve", "deny" ], "type": "string" }, "displayCode": { "description": "Code the user typed from their own browser; required to approve. A mismatch denies the challenge.", "pattern": "^[0-9]{6}$", "type": "string" }, "displayName": { "maxLength": 200, "minLength": 1, "type": "string" }, "telegramUserId": { "pattern": "^[0-9]{1,20}$", "type": "string" }, "telegramUsername": { "maxLength": 64, "type": "string" } }, "required": [ "challengeId", "telegramUserId", "displayName", "decision" ], "type": "object" }, "BrowserChallenge": { "$id": "#/components/schemas/BrowserChallenge", "properties": { "botDeepLink": { "type": "string" }, "browserSecret": { "description": "Keep in memory; required to redeem the approved challenge.", "type": "string" }, "challengeId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "displayCode": { "type": "string" }, "expiresAt": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" } }, "required": [ "challengeId", "browserSecret", "displayCode", "botDeepLink", "expiresAt" ], "type": "object" }, "BrowserChallengeStatus": { "$id": "#/components/schemas/BrowserChallengeStatus", "properties": { "grant": { "$ref": "#/components/schemas/SessionGrant" }, "status": { "enum": [ "pending", "approved", "denied", "expired", "consumed" ], "type": "string" } }, "required": [ "status" ], "type": "object" }, "CreateApiKeyRequest": { "$id": "#/components/schemas/CreateApiKeyRequest", "properties": { "livemode": { "type": "boolean" }, "name": { "maxLength": 80, "minLength": 1, "type": "string" }, "scopes": { "items": { "enum": [ "invoices:write", "invoices:read" ], "type": "string" }, "minItems": 1, "type": "array" } }, "required": [ "name", "livemode", "scopes" ], "type": "object" }, "CreateDestinationRequest": { "$id": "#/components/schemas/CreateDestinationRequest", "properties": { "accountNumber": { "pattern": "^[0-9]{6,26}$", "type": "string" }, "bankCode": { "description": "Derived from the card BIN when omitted.", "type": "string" }, "cardNumber": { "description": "16-digit card number; Persian digits, spaces and dashes are accepted.", "maxLength": 24, "minLength": 16, "type": "string" }, "dailyLimitRial": { "$ref": "#/components/schemas/AmountRial" }, "holderName": { "maxLength": 120, "minLength": 1, "type": "string" }, "iban": { "maxLength": 40, "type": "string" }, "label": { "maxLength": 80, "minLength": 1, "type": "string" }, "smsAccountHints": { "description": "Account/card fragments as they appear in bank SMS (e.g. \"5678\"), used to resolve the destination.", "items": { "pattern": "^[0-9*]{2,26}$", "type": "string" }, "maxItems": 10, "type": "array" }, "weight": { "maximum": 100, "minimum": 1, "type": "integer" } }, "required": [ "label", "cardNumber", "holderName" ], "type": "object" }, "CreateDevicePairingRequest": { "$id": "#/components/schemas/CreateDevicePairingRequest", "properties": { "destinationIds": { "default": [], "items": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "maxItems": 20, "type": "array" }, "deviceName": { "maxLength": 80, "minLength": 1, "type": "string" } }, "required": [ "deviceName" ], "type": "object" }, "CreateInvoiceRequest": { "$id": "#/components/schemas/CreateInvoiceRequest", "properties": { "baseAmountRial": { "$ref": "#/components/schemas/AmountRial" }, "customerRef": { "maxLength": 128, "minLength": 1, "type": "string" }, "description": { "maxLength": 500, "type": "string" }, "destinationId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "livemode": { "description": "Dashboard sessions only (default true). API keys always use their own mode; a mismatch is rejected.", "type": "boolean" }, "metadata": { "additionalProperties": { "maxLength": 500, "type": "string" }, "propertyNames": { "maxLength": 40, "type": "string" }, "type": "object" }, "orderRef": { "maxLength": 128, "minLength": 1, "type": "string" }, "returnUrl": { "format": "uri", "maxLength": 2048, "type": "string" }, "ttlSeconds": { "maximum": 86400, "minimum": 300, "type": "integer" } }, "required": [ "baseAmountRial" ], "type": "object" }, "CreateMerchantRequest": { "$id": "#/components/schemas/CreateMerchantRequest", "properties": { "name": { "maxLength": 120, "minLength": 1, "type": "string" } }, "required": [ "name" ], "type": "object" }, "CreateWebhookEndpointRequest": { "$id": "#/components/schemas/CreateWebhookEndpointRequest", "properties": { "description": { "maxLength": 200, "type": "string" }, "eventTypes": { "items": { "$ref": "#/components/schemas/WebhookEventType" }, "minItems": 1, "type": "array" }, "livemode": { "type": "boolean" }, "url": { "format": "uri", "maxLength": 2048, "type": "string" } }, "required": [ "url", "livemode", "eventTypes" ], "type": "object" }, "CreatedApiKey": { "$id": "#/components/schemas/CreatedApiKey", "properties": { "apiKey": { "$ref": "#/components/schemas/ApiKey" }, "secret": { "description": "Full key, shown once. Server-side use only.", "type": "string" } }, "required": [ "apiKey", "secret" ], "type": "object" }, "CreatedWebhookEndpoint": { "$id": "#/components/schemas/CreatedWebhookEndpoint", "properties": { "endpoint": { "$ref": "#/components/schemas/WebhookEndpoint" }, "secret": { "description": "Signing secret (whsec_…), shown once.", "type": "string" } }, "required": [ "endpoint", "secret" ], "type": "object" }, "CreditBalance": { "$id": "#/components/schemas/CreditBalance", "properties": { "availableRial": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "reservedRial": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "subscription": { "anyOf": [ { "properties": { "includedConfirmations": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "periodEnd": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, "planCode": { "type": "string" }, "usedConfirmations": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" } }, "required": [ "planCode", "periodEnd", "usedConfirmations", "includedConfirmations" ], "type": "object" }, { "type": "null" } ] }, "zeroFee": { "type": "boolean" } }, "required": [ "availableRial", "reservedRial", "zeroFee", "subscription" ], "type": "object" }, "Deposit": { "$id": "#/components/schemas/Deposit", "properties": { "accountMask": { "type": [ "string", "null" ] }, "amountRial": { "$ref": "#/components/schemas/AmountRial" }, "assurance": { "enum": [ "relay_https", "relay_sms", "forwarder", "manual", "sandbox", "none" ], "type": "string" }, "bankCode": { "type": [ "string", "null" ] }, "bankTime": { "anyOf": [ { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, { "type": "null" } ] }, "cardMask": { "type": [ "string", "null" ] }, "createdAt": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, "destinationId": { "anyOf": [ { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, { "type": "null" } ] }, "direction": { "enum": [ "deposit", "withdrawal" ], "type": "string" }, "id": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "invoiceId": { "anyOf": [ { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, { "type": "null" } ] }, "livemode": { "description": "false for sandbox (test) objects.", "type": "boolean" }, "observedAt": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, "possibleDuplicateOf": { "anyOf": [ { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, { "type": "null" } ] }, "reference": { "type": [ "string", "null" ] }, "reviewReason": { "type": [ "string", "null" ] }, "status": { "enum": [ "unmatched", "matched", "review", "ignored", "duplicate" ], "type": "string" } }, "required": [ "id", "livemode", "status", "reviewReason", "direction", "amountRial", "bankCode", "accountMask", "cardMask", "bankTime", "observedAt", "reference", "assurance", "destinationId", "invoiceId", "possibleDuplicateOf", "createdAt" ], "type": "object" }, "DepositPage": { "$id": "#/components/schemas/DepositPage", "properties": { "data": { "items": { "$ref": "#/components/schemas/Deposit" }, "type": "array" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "type": "object" }, "Destination": { "$id": "#/components/schemas/Destination", "properties": { "accountNumber": { "type": [ "string", "null" ] }, "bankCode": { "type": "string" }, "cardNumber": { "type": "string" }, "createdAt": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, "dailyLimitRial": { "anyOf": [ { "$ref": "#/components/schemas/AmountRial" }, { "type": "null" } ] }, "holderName": { "type": "string" }, "iban": { "type": [ "string", "null" ] }, "id": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "label": { "type": "string" }, "smsAccountHints": { "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "active", "paused", "suspended", "archived" ], "type": "string" }, "weight": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" } }, "required": [ "id", "label", "cardNumber", "iban", "accountNumber", "holderName", "bankCode", "smsAccountHints", "status", "dailyLimitRial", "weight", "createdAt" ], "type": "object" }, "Device": { "$id": "#/components/schemas/Device", "properties": { "appVersion": { "type": [ "string", "null" ] }, "createdAt": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, "destinationIds": { "items": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "type": "array" }, "health": { "enum": [ "healthy", "degraded", "offline", "never_seen", "revoked" ], "type": "string" }, "id": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "lastSeenAt": { "anyOf": [ { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, { "type": "null" } ] }, "name": { "type": "string" }, "osVersion": { "type": [ "string", "null" ] }, "queueDepth": { "anyOf": [ { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, { "type": "null" } ] }, "revokedAt": { "anyOf": [ { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, { "type": "null" } ] }, "shortId": { "type": "string" }, "smsFallbackEnabled": { "type": "boolean" }, "status": { "enum": [ "active", "revoked" ], "type": "string" } }, "required": [ "id", "shortId", "name", "status", "health", "appVersion", "osVersion", "smsFallbackEnabled", "lastSeenAt", "queueDepth", "destinationIds", "createdAt", "revokedAt" ], "type": "object" }, "DeviceConfig": { "$id": "#/components/schemas/DeviceConfig", "properties": { "bankSenders": { "items": { "properties": { "bank": { "type": "string" }, "senders": { "items": { "type": "string" }, "type": "array" } }, "required": [ "bank", "senders" ], "type": "object" }, "type": "array" }, "extraSenders": { "items": { "type": "string" }, "type": "array" }, "fallback": { "properties": { "enabled": { "type": "boolean" }, "lineNumber": { "type": [ "string", "null" ] } }, "required": [ "enabled", "lineNumber" ], "type": "object" }, "heartbeatIntervalSeconds": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "maxBatchSize": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "merchantName": { "type": "string" } }, "required": [ "merchantName", "bankSenders", "extraSenders", "fallback", "heartbeatIntervalSeconds", "maxBatchSize" ], "type": "object" }, "DeviceEvent": { "$id": "#/components/schemas/DeviceEvent", "properties": { "body": { "maxLength": 2000, "minLength": 1, "type": "string" }, "eventId": { "description": "UUIDv7 generated on the device; stable across retries and channels.", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "receivedAt": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, "sender": { "maxLength": 64, "minLength": 1, "type": "string" }, "simSlot": { "maximum": 7, "minimum": 0, "type": "integer" }, "subscriptionId": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" } }, "required": [ "eventId", "sender", "body", "receivedAt" ], "type": "object" }, "DeviceEventResult": { "$id": "#/components/schemas/DeviceEventResult", "properties": { "eventId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "reason": { "enum": [ "otp_detected", "invalid_event" ], "type": "string" }, "status": { "enum": [ "accepted", "duplicate", "rejected" ], "type": "string" } }, "required": [ "eventId", "status" ], "type": "object" }, "DeviceEventsRequest": { "$id": "#/components/schemas/DeviceEventsRequest", "properties": { "events": { "items": { "$ref": "#/components/schemas/DeviceEvent" }, "maxItems": 50, "minItems": 1, "type": "array" } }, "required": [ "events" ], "type": "object" }, "DeviceEventsResponse": { "$id": "#/components/schemas/DeviceEventsResponse", "properties": { "results": { "items": { "$ref": "#/components/schemas/DeviceEventResult" }, "type": "array" }, "serverTime": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" } }, "required": [ "results", "serverTime" ], "type": "object" }, "DeviceHeartbeatRequest": { "$id": "#/components/schemas/DeviceHeartbeatRequest", "properties": { "appVersion": { "maxLength": 40, "type": "string" }, "batteryOptimizationIgnored": { "type": "boolean" }, "lastDeliveryAt": { "anyOf": [ { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, { "type": "null" } ] }, "oldestQueuedAt": { "anyOf": [ { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, { "type": "null" } ] }, "osVersion": { "maxLength": 60, "type": "string" }, "permissions": { "properties": { "postNotifications": { "type": "boolean" }, "receiveSms": { "type": "boolean" }, "sendSms": { "type": "boolean" } }, "required": [ "receiveSms", "sendSms", "postNotifications" ], "type": "object" }, "queueDepth": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "sims": { "items": { "$ref": "#/components/schemas/DeviceSimInfo" }, "maxItems": 4, "type": "array" }, "smsFallbackEnabled": { "type": "boolean" } }, "required": [ "appVersion", "osVersion", "queueDepth", "oldestQueuedAt", "lastDeliveryAt", "permissions", "batteryOptimizationIgnored", "smsFallbackEnabled", "sims" ], "type": "object" }, "DeviceHeartbeatResponse": { "$id": "#/components/schemas/DeviceHeartbeatResponse", "properties": { "config": { "$ref": "#/components/schemas/DeviceConfig" }, "serverTime": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" } }, "required": [ "serverTime", "config" ], "type": "object" }, "DevicePairRequest": { "$id": "#/components/schemas/DevicePairRequest", "properties": { "appVersion": { "maxLength": 40, "type": "string" }, "deviceName": { "maxLength": 80, "minLength": 1, "type": "string" }, "locator": { "pattern": "^[0-9]{6}$", "type": "string" }, "osVersion": { "maxLength": 60, "type": "string" }, "secret": { "pattern": "^[A-HJ-NP-Z2-9]{8}$", "type": "string" }, "sims": { "default": [], "items": { "$ref": "#/components/schemas/DeviceSimInfo" }, "maxItems": 4, "type": "array" } }, "required": [ "locator", "secret", "deviceName", "appVersion", "osVersion" ], "type": "object" }, "DevicePairResponse": { "$id": "#/components/schemas/DevicePairResponse", "properties": { "config": { "$ref": "#/components/schemas/DeviceConfig" }, "deviceId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "deviceSecret": { "description": "Shown once. Store in Android Keystore-protected storage.", "type": "string" }, "merchantName": { "type": "string" }, "shortId": { "type": "string" } }, "required": [ "deviceId", "shortId", "deviceSecret", "merchantName", "config" ], "type": "object" }, "DevicePairing": { "$id": "#/components/schemas/DevicePairing", "properties": { "expiresAt": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, "id": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "locator": { "type": "string" }, "pairingUri": { "description": "paynyx://pair?u=…&l=…&s=… for the QR code.", "type": "string" }, "secret": { "description": "Shown once; expires with the pairing.", "type": "string" } }, "required": [ "id", "locator", "secret", "pairingUri", "expiresAt" ], "type": "object" }, "DeviceSimInfo": { "$id": "#/components/schemas/DeviceSimInfo", "properties": { "carrier": { "maxLength": 64, "type": "string" }, "slot": { "maximum": 7, "minimum": 0, "type": "integer" }, "subscriptionId": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" } }, "required": [ "slot" ], "type": "object" }, "Invoice": { "$id": "#/components/schemas/Invoice", "properties": { "baseAmountRial": { "$ref": "#/components/schemas/AmountRial" }, "cancelledAt": { "anyOf": [ { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, { "type": "null" } ] }, "checkoutUrl": { "format": "uri", "type": "string" }, "confirmation": { "anyOf": [ { "$ref": "#/components/schemas/InvoiceConfirmation" }, { "type": "null" } ] }, "createdAt": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, "currency": { "const": "IRR", "type": "string" }, "customerFeeRial": { "maximum": 100000000, "minimum": 0, "type": "integer" }, "customerRef": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "destination": { "$ref": "#/components/schemas/PaymentDestination" }, "expiresAt": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, "id": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "livemode": { "description": "false for sandbox (test) objects.", "type": "boolean" }, "merchantFeeRial": { "description": "PAYNYX service charge debited from service credit on confirmation.", "maximum": 100000000, "minimum": 0, "type": "integer" }, "metadata": { "additionalProperties": { "type": "string" }, "propertyNames": { "type": "string" }, "type": "object" }, "object": { "const": "invoice", "type": "string" }, "offsetRial": { "maximum": 9007199254740991, "minimum": 0, "type": "integer" }, "orderRef": { "type": [ "string", "null" ] }, "paidAt": { "anyOf": [ { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, { "type": "null" } ] }, "payableAmountRial": { "$ref": "#/components/schemas/AmountRial", "description": "The EXACT amount the buyer must transfer, in rial." }, "publicId": { "type": "string" }, "returnUrl": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/InvoiceStatus" } }, "required": [ "id", "object", "publicId", "livemode", "status", "baseAmountRial", "customerFeeRial", "offsetRial", "payableAmountRial", "merchantFeeRial", "currency", "destination", "orderRef", "customerRef", "description", "metadata", "checkoutUrl", "returnUrl", "expiresAt", "paidAt", "cancelledAt", "confirmation", "createdAt" ], "type": "object" }, "InvoiceConfirmation": { "$id": "#/components/schemas/InvoiceConfirmation", "properties": { "bankTime": { "anyOf": [ { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, { "type": "null" } ] }, "depositId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "evidenceAssurance": { "enum": [ "relay_https", "relay_sms", "forwarder", "manual", "sandbox" ], "type": "string" }, "kind": { "enum": [ "auto", "manual" ], "type": "string" }, "reference": { "type": [ "string", "null" ] } }, "required": [ "kind", "depositId", "bankTime", "reference", "evidenceAssurance" ], "type": "object" }, "InvoicePage": { "$id": "#/components/schemas/InvoicePage", "properties": { "data": { "items": { "$ref": "#/components/schemas/Invoice" }, "type": "array" }, "nextCursor": { "type": [ "string", "null" ] } }, "required": [ "data", "nextCursor" ], "type": "object" }, "InvoiceStatus": { "$id": "#/components/schemas/InvoiceStatus", "description": "open: awaiting transfer · paid: confirmed by matched bank evidence (terminal) · review: evidence needs a human decision · expired / cancelled: no longer payable (late transfers go to review).", "enum": [ "open", "paid", "review", "expired", "cancelled" ], "type": "string" }, "Me": { "$id": "#/components/schemas/Me", "properties": { "session": { "properties": { "expiresAt": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, "id": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "kind": { "enum": [ "web", "miniapp" ], "type": "string" } }, "required": [ "id", "kind", "expiresAt" ], "type": "object" }, "user": { "properties": { "displayName": { "type": "string" }, "id": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "telegramUsername": { "type": [ "string", "null" ] } }, "required": [ "id", "displayName", "telegramUsername" ], "type": "object" } }, "required": [ "user", "session" ], "type": "object" }, "Merchant": { "$id": "#/components/schemas/Merchant", "properties": { "branding": { "properties": { "accentColor": { "type": "string" }, "displayName": { "type": "string" }, "logoUrl": { "type": "string" }, "supportTelegram": { "type": "string" }, "supportUrl": { "type": "string" } }, "type": "object" }, "createdAt": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, "forwarderAutoConfirm": { "type": "boolean" }, "id": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "name": { "type": "string" }, "role": { "$ref": "#/components/schemas/Role", "description": "The caller's role in this merchant." }, "routingStrategy": { "enum": [ "manual", "random", "round_robin", "least_success", "health" ], "type": "string" }, "smsSenderAllowlist": { "description": "Bank SMS sender IDs the relay forwards (as shown on the phone).", "items": { "type": "string" }, "type": "array" }, "status": { "enum": [ "active", "suspended", "closed" ], "type": "string" } }, "required": [ "id", "name", "status", "role", "routingStrategy", "smsSenderAllowlist", "forwarderAutoConfirm", "branding", "createdAt" ], "type": "object" }, "MiniAppLoginRequest": { "$id": "#/components/schemas/MiniAppLoginRequest", "properties": { "initData": { "description": "Raw Telegram.WebApp.initData string.", "maxLength": 8192, "minLength": 1, "type": "string" } }, "required": [ "initData" ], "type": "object" }, "PaymentDestination": { "$id": "#/components/schemas/PaymentDestination", "properties": { "bankCode": { "type": "string" }, "cardNumber": { "pattern": "^[0-9]{16}$", "type": "string" }, "holderName": { "type": "string" }, "iban": { "type": [ "string", "null" ] } }, "required": [ "cardNumber", "holderName", "bankCode", "iban" ], "type": "object" }, "Problem": { "$id": "#/components/schemas/Problem", "properties": { "code": { "description": "Stable machine-readable error code.", "type": "string" }, "detail": { "type": "string" }, "errors": { "description": "Validation errors, when code = validation_failed.", "items": { "properties": { "message": { "type": "string" }, "path": { "type": "string" } }, "required": [ "path", "message" ], "type": "object" }, "type": "array" }, "requestId": { "type": "string" }, "status": { "maximum": 9007199254740991, "minimum": -9007199254740991, "type": "integer" }, "title": { "type": "string" }, "type": { "type": "string" } }, "required": [ "type", "title", "status", "code", "requestId" ], "type": "object" }, "PublicInvoice": { "$id": "#/components/schemas/PublicInvoice", "properties": { "description": { "type": [ "string", "null" ] }, "destination": { "$ref": "#/components/schemas/PaymentDestination" }, "expiresAt": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, "livemode": { "description": "false for sandbox (test) objects.", "type": "boolean" }, "merchant": { "properties": { "accentColor": { "type": [ "string", "null" ] }, "displayName": { "type": "string" }, "logoUrl": { "type": [ "string", "null" ] }, "supportUrl": { "type": [ "string", "null" ] } }, "required": [ "displayName", "logoUrl", "accentColor", "supportUrl" ], "type": "object" }, "paidAt": { "anyOf": [ { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, { "type": "null" } ] }, "payableAmountRial": { "$ref": "#/components/schemas/AmountRial" }, "publicId": { "type": "string" }, "returnUrl": { "description": "Only present once the invoice is paid.", "type": [ "string", "null" ] }, "serverTime": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, "status": { "$ref": "#/components/schemas/InvoiceStatus" } }, "required": [ "publicId", "status", "payableAmountRial", "destination", "description", "expiresAt", "paidAt", "returnUrl", "livemode", "merchant", "serverTime" ], "type": "object" }, "RedeemBrowserChallengeRequest": { "$id": "#/components/schemas/RedeemBrowserChallengeRequest", "properties": { "browserSecret": { "maxLength": 100, "minLength": 20, "type": "string" } }, "required": [ "browserSecret" ], "type": "object" }, "ResolveDepositRequest": { "$id": "#/components/schemas/ResolveDepositRequest", "oneOf": [ { "properties": { "action": { "const": "confirm", "type": "string" }, "invoiceId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "reason": { "maxLength": 500, "minLength": 3, "type": "string" } }, "required": [ "action", "invoiceId", "reason" ], "type": "object" }, { "properties": { "action": { "const": "reject", "type": "string" }, "reason": { "maxLength": 500, "minLength": 3, "type": "string" } }, "required": [ "action", "reason" ], "type": "object" } ] }, "Role": { "$id": "#/components/schemas/Role", "enum": [ "owner", "admin", "finance", "developer", "support", "readonly", "restricted" ], "type": "string" }, "SandboxDepositRequest": { "$id": "#/components/schemas/SandboxDepositRequest", "properties": { "amountRial": { "$ref": "#/components/schemas/AmountRial" }, "invoiceId": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, "required": [ "invoiceId" ], "type": "object" }, "SessionGrant": { "$id": "#/components/schemas/SessionGrant", "properties": { "csrfToken": { "type": "string" }, "expiresAt": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, "me": { "$ref": "#/components/schemas/Me" }, "token": { "description": "Bearer token for the Mini App. Browser sessions receive an HttpOnly cookie instead (token omitted).", "type": "string" } }, "required": [ "expiresAt", "me" ], "type": "object" }, "UpdateDestinationRequest": { "$id": "#/components/schemas/UpdateDestinationRequest", "properties": { "dailyLimitRial": { "anyOf": [ { "$ref": "#/components/schemas/AmountRial" }, { "type": "null" } ] }, "label": { "maxLength": 80, "minLength": 1, "type": "string" }, "smsAccountHints": { "items": { "pattern": "^[0-9*]{2,26}$", "type": "string" }, "maxItems": 10, "type": "array" }, "status": { "enum": [ "active", "paused", "archived" ], "type": "string" }, "weight": { "maximum": 100, "minimum": 1, "type": "integer" } }, "type": "object" }, "UpdateMerchantRequest": { "$id": "#/components/schemas/UpdateMerchantRequest", "properties": { "branding": { "properties": { "accentColor": { "pattern": "^#[0-9a-fA-F]{6}$", "type": "string" }, "displayName": { "maxLength": 80, "minLength": 1, "type": "string" }, "supportTelegram": { "pattern": "^@?[A-Za-z0-9_]{5,32}$", "type": "string" }, "supportUrl": { "format": "uri", "maxLength": 500, "type": "string" } }, "type": "object" }, "forwarderAutoConfirm": { "type": "boolean" }, "name": { "maxLength": 120, "minLength": 1, "type": "string" }, "routingStrategy": { "enum": [ "manual", "random", "round_robin", "least_success", "health" ], "type": "string" }, "smsSenderAllowlist": { "items": { "maxLength": 32, "minLength": 2, "pattern": "^[\\p{L}\\p{N}+ ._-]+$", "type": "string" }, "maxItems": 50, "type": "array" } }, "type": "object" }, "WebhookEndpoint": { "$id": "#/components/schemas/WebhookEndpoint", "properties": { "createdAt": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, "description": { "type": [ "string", "null" ] }, "eventTypes": { "items": { "$ref": "#/components/schemas/WebhookEventType" }, "type": "array" }, "id": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "livemode": { "description": "false for sandbox (test) objects.", "type": "boolean" }, "status": { "enum": [ "active", "disabled" ], "type": "string" }, "url": { "type": "string" } }, "required": [ "id", "url", "livemode", "eventTypes", "status", "description", "createdAt" ], "type": "object" }, "WebhookEvent": { "$id": "#/components/schemas/WebhookEvent", "properties": { "apiVersion": { "const": "2026-10-08", "type": "string" }, "createdAt": { "description": "ISO-8601 UTC timestamp.", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" }, "data": { "properties": { "deposit": { "additionalProperties": {}, "propertyNames": { "type": "string" }, "type": "object" }, "invoice": { "$ref": "#/components/schemas/Invoice" } }, "type": "object" }, "id": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" }, "livemode": { "description": "false for sandbox (test) objects.", "type": "boolean" }, "type": { "$ref": "#/components/schemas/WebhookEventType" } }, "required": [ "id", "type", "apiVersion", "createdAt", "livemode", "data" ], "type": "object" }, "WebhookEventType": { "$id": "#/components/schemas/WebhookEventType", "enum": [ "invoice.paid", "invoice.review_required", "invoice.expired", "invoice.cancelled", "deposit.unmatched", "device.degraded", "credit.low" ], "type": "string" } }, "securitySchemes": { "apiKey": { "description": "Merchant API key (pk_live_… / pk_test_…). Server-side only — never expose it in browser or mobile code.", "scheme": "bearer", "type": "http" }, "device": { "description": "HMAC-signed device request; see docs/integrations/device-api.md.", "in": "header", "name": "X-Paynyx-Signature", "type": "apiKey" }, "service": { "description": "Internal service credential (bot → API).", "scheme": "bearer", "type": "http" }, "session": { "description": "Dashboard session. Browsers use an HttpOnly cookie plus the X-CSRF-Token header; the Telegram Mini App uses a bearer token.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "PAYNYX (a NYXON.TECH product) reconciles merchant bank deposits with invoices. Money is always integer rial (fields end in `Rial`). PAYNYX never holds funds.", "title": "PAYNYX API", "version": "1.0.0" }, "openapi": "3.1.0", "paths": { "/v1/auth/logout": { "post": { "operationId": "logout", "parameters": [], "responses": { "204": { "description": "Success (no content)" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "session": [] } ], "summary": "Revoke the current session", "tags": [ "auth" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] } }, "/v1/auth/telegram/browser-challenges": { "post": { "operationId": "createBrowserLoginChallenge", "parameters": [], "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserChallenge" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: rate_limited." } }, "security": [], "summary": "Start a browser login approved through the PAYNYX Telegram bot", "tags": [ "auth" ], "x-error-codes": [ "rate_limited" ] } }, "/v1/auth/telegram/browser-challenges/{challengeId}/redeem": { "post": { "operationId": "redeemBrowserLoginChallenge", "parameters": [ { "in": "path", "name": "challengeId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemBrowserChallengeRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BrowserChallengeStatus" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, not_found, rate_limited." } }, "security": [], "summary": "Poll a challenge; returns a session exactly once after approval", "tags": [ "auth" ], "x-error-codes": [ "validation_failed", "not_found", "rate_limited" ] } }, "/v1/auth/telegram/miniapp": { "post": { "operationId": "loginWithTelegramMiniApp", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MiniAppLoginRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SessionGrant" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, telegram_init_invalid, telegram_init_expired, telegram_init_replayed, rate_limited." } }, "security": [], "summary": "Exchange validated Telegram Mini App initData for a session", "tags": [ "auth" ], "x-error-codes": [ "validation_failed", "telegram_init_invalid", "telegram_init_expired", "telegram_init_replayed", "rate_limited" ] } }, "/v1/device/config": { "get": { "operationId": "getDeviceConfig", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceConfig" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: device_signature_invalid, device_clock_skew, device_nonce_reused, device_revoked." } }, "security": [ { "device": [] } ], "summary": "Fetch relay configuration", "tags": [ "device" ], "x-error-codes": [ "device_signature_invalid", "device_clock_skew", "device_nonce_reused", "device_revoked" ] } }, "/v1/device/events": { "post": { "operationId": "submitDeviceEvents", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceEventsRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceEventsResponse" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, device_signature_invalid, device_clock_skew, device_nonce_reused, device_revoked." } }, "security": [ { "device": [] } ], "summary": "Submit classified bank SMS events", "tags": [ "device" ], "x-error-codes": [ "validation_failed", "device_signature_invalid", "device_clock_skew", "device_nonce_reused", "device_revoked" ] } }, "/v1/device/heartbeat": { "post": { "operationId": "sendDeviceHeartbeat", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceHeartbeatRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeviceHeartbeatResponse" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, device_signature_invalid, device_clock_skew, device_nonce_reused, device_revoked." } }, "security": [ { "device": [] } ], "summary": "Report relay health", "tags": [ "device" ], "x-error-codes": [ "validation_failed", "device_signature_invalid", "device_clock_skew", "device_nonce_reused", "device_revoked" ] } }, "/v1/device/pair": { "post": { "operationId": "pairDevice", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevicePairRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevicePairResponse" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, pairing_invalid, pairing_locked, rate_limited." } }, "security": [], "summary": "Exchange a pairing code for a device credential", "tags": [ "device" ], "x-error-codes": [ "validation_failed", "pairing_invalid", "pairing_locked", "rate_limited" ] } }, "/v1/device/test": { "post": { "operationId": "testDeviceConnection", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": {}, "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "ok": { "const": true, "type": "boolean" }, "serverTime": { "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$", "type": "string" } }, "required": [ "ok", "serverTime" ], "type": "object" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: device_signature_invalid, device_clock_skew, device_nonce_reused, device_revoked." } }, "security": [ { "device": [] } ], "summary": "Connectivity and signature self-test (creates no evidence)", "tags": [ "device" ], "x-error-codes": [ "device_signature_invalid", "device_clock_skew", "device_nonce_reused", "device_revoked" ] } }, "/v1/me": { "get": { "operationId": "getMe", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Me" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "session": [] } ], "summary": "Current user and session", "tags": [ "auth" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] } }, "/v1/merchants": { "get": { "operationId": "listMerchants", "parameters": [], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Merchant" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "session": [] } ], "summary": "List the caller's merchants", "tags": [ "merchants" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] }, "post": { "operationId": "createMerchant", "parameters": [], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateMerchantRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Merchant" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "session": [] } ], "summary": "Create a merchant (caller becomes owner)", "tags": [ "merchants" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] } }, "/v1/merchants/{merchantId}": { "get": { "operationId": "getMerchant", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Merchant" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "session": [] } ], "summary": "Get a merchant", "tags": [ "merchants" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] }, "patch": { "operationId": "updateMerchant", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMerchantRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Merchant" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "session": [] } ], "summary": "Update merchant settings (owner/admin)", "tags": [ "merchants" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] } }, "/v1/merchants/{merchantId}/api-keys": { "get": { "operationId": "listApiKeys", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/ApiKey" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "session": [] } ], "summary": "List API keys", "tags": [ "developers" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] }, "post": { "operationId": "createApiKey", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedApiKey" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "session": [] } ], "summary": "Create a server-side API key (secret shown once)", "tags": [ "developers" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] } }, "/v1/merchants/{merchantId}/api-keys/{apiKeyId}/revoke": { "post": { "operationId": "revokeApiKey", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "in": "path", "name": "apiKeyId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "session": [] } ], "summary": "Revoke an API key", "tags": [ "developers" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] } }, "/v1/merchants/{merchantId}/credit": { "get": { "operationId": "getCreditBalance", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreditBalance" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "session": [] } ], "summary": "Service-credit balance and plan usage", "tags": [ "billing" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] } }, "/v1/merchants/{merchantId}/deposits": { "get": { "operationId": "listDeposits", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 200, "type": "string" } }, { "in": "query", "name": "status", "required": false, "schema": { "enum": [ "unmatched", "matched", "review", "ignored", "duplicate" ], "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositPage" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "session": [] } ], "summary": "List parsed deposits (review queue, unmatched, matched)", "tags": [ "deposits" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] } }, "/v1/merchants/{merchantId}/deposits/{depositId}/resolve": { "post": { "operationId": "resolveDeposit", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "in": "path", "name": "depositId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveDepositRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deposit" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited, invalid_state, amount_mismatch, insufficient_credit." } }, "security": [ { "session": [] } ], "summary": "Manually confirm a deposit against an invoice or reject it (audited)", "tags": [ "deposits" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited", "invalid_state", "amount_mismatch", "insufficient_credit" ] } }, "/v1/merchants/{merchantId}/destinations": { "get": { "operationId": "listDestinations", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Destination" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "session": [] } ], "summary": "List destinations", "tags": [ "destinations" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] }, "post": { "operationId": "createDestination", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDestinationRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Destination" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited, invalid_card_number, invalid_iban, destination_exists." } }, "security": [ { "session": [] } ], "summary": "Register a merchant-owned card destination", "tags": [ "destinations" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited", "invalid_card_number", "invalid_iban", "destination_exists" ] } }, "/v1/merchants/{merchantId}/destinations/{destinationId}": { "patch": { "operationId": "updateDestination", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "in": "path", "name": "destinationId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDestinationRequest" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Destination" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "session": [] } ], "summary": "Update a destination (open invoices keep their assigned destination)", "tags": [ "destinations" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] } }, "/v1/merchants/{merchantId}/device-pairings": { "post": { "operationId": "createDevicePairing", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDevicePairingRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DevicePairing" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "session": [] } ], "summary": "Create a single-use pairing code for the Android relay", "tags": [ "devices" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] } }, "/v1/merchants/{merchantId}/devices": { "get": { "operationId": "listDevices", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/Device" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "session": [] } ], "summary": "List relay devices", "tags": [ "devices" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] } }, "/v1/merchants/{merchantId}/devices/{deviceId}/revoke": { "post": { "operationId": "revokeDevice", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "in": "path", "name": "deviceId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Device" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "session": [] } ], "summary": "Revoke a device credential immediately", "tags": [ "devices" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] } }, "/v1/merchants/{merchantId}/invoices": { "get": { "operationId": "listInvoices", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "in": "query", "name": "limit", "required": false, "schema": { "default": 20, "maximum": 100, "minimum": 1, "type": "integer" } }, { "in": "query", "name": "cursor", "required": false, "schema": { "maxLength": 200, "type": "string" } }, { "in": "query", "name": "status", "required": false, "schema": { "$ref": "#/components/schemas/InvoiceStatus" } }, { "in": "query", "name": "orderRef", "required": false, "schema": { "maxLength": 128, "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoicePage" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "List invoices (newest first)", "tags": [ "invoices" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] }, "post": { "operationId": "createInvoice", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "description": "Unique per logical request (≤255 chars). Replays return the original response for 24 h.", "in": "header", "name": "Idempotency-Key", "required": true, "schema": { "maxLength": 255, "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoiceRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited, idempotency_conflict, no_destination_available, amount_capacity_exhausted, insufficient_credit, merchant_inactive." } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "Create an invoice with an exact payable amount and destination", "tags": [ "invoices" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited", "idempotency_conflict", "no_destination_available", "amount_capacity_exhausted", "insufficient_credit", "merchant_inactive" ] } }, "/v1/merchants/{merchantId}/invoices/{invoiceId}": { "get": { "operationId": "getInvoice", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "in": "path", "name": "invoiceId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "Get an invoice", "tags": [ "invoices" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] } }, "/v1/merchants/{merchantId}/invoices/{invoiceId}/cancel": { "post": { "operationId": "cancelInvoice", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "in": "path", "name": "invoiceId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited, invalid_state." } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "Cancel an open invoice", "tags": [ "invoices" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited", "invalid_state" ] } }, "/v1/merchants/{merchantId}/invoices/{invoiceId}/verify": { "post": { "operationId": "verifyInvoice", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "in": "path", "name": "invoiceId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "Authoritatively re-read invoice status before fulfillment (never charges)", "tags": [ "invoices" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] } }, "/v1/merchants/{merchantId}/sandbox/deposits": { "post": { "operationId": "createSandboxDeposit", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxDepositRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Deposit" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited, livemode_not_allowed." } }, "security": [ { "apiKey": [] }, { "session": [] } ], "summary": "Simulate a bank deposit for a test-mode invoice", "tags": [ "sandbox" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited", "livemode_not_allowed" ] } }, "/v1/merchants/{merchantId}/webhook-endpoints": { "get": { "operationId": "listWebhookEndpoints", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "data": { "items": { "$ref": "#/components/schemas/WebhookEndpoint" }, "type": "array" } }, "required": [ "data" ], "type": "object" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "session": [] } ], "summary": "List webhook endpoints", "tags": [ "developers" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] }, "post": { "operationId": "createWebhookEndpoint", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateWebhookEndpointRequest" } } }, "required": true }, "responses": { "201": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreatedWebhookEndpoint" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited, unsafe_url." } }, "security": [ { "session": [] } ], "summary": "Register an HTTPS webhook endpoint (secret shown once)", "tags": [ "developers" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited", "unsafe_url" ] } }, "/v1/merchants/{merchantId}/webhook-endpoints/{endpointId}/disable": { "post": { "operationId": "disableWebhookEndpoint", "parameters": [ { "in": "path", "name": "merchantId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } }, { "in": "path", "name": "endpointId", "required": true, "schema": { "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEndpoint" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: validation_failed, unauthenticated, forbidden, not_found, rate_limited." } }, "security": [ { "session": [] } ], "summary": "Disable a webhook endpoint (pending deliveries stop)", "tags": [ "developers" ], "x-error-codes": [ "validation_failed", "unauthenticated", "forbidden", "not_found", "rate_limited" ] } }, "/v1/public/invoices/{publicId}": { "get": { "operationId": "getPublicInvoice", "parameters": [ { "in": "path", "name": "publicId", "required": true, "schema": { "pattern": "^[A-Za-z0-9_-]{22}$", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicInvoice" } } }, "description": "Success" }, "default": { "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "description": "Error. Possible codes: not_found, rate_limited." } }, "security": [], "summary": "Buyer-facing invoice view for hosted checkout", "tags": [ "checkout" ], "x-error-codes": [ "not_found", "rate_limited" ] } } }, "servers": [ { "description": "Replace with your deployment URL", "url": "https://api.paynyx.example" } ], "tags": [ { "name": "auth" }, { "name": "billing" }, { "name": "checkout" }, { "name": "deposits" }, { "name": "destinations" }, { "name": "developers" }, { "name": "device" }, { "name": "devices" }, { "name": "invoices" }, { "name": "merchants" }, { "name": "sandbox" } ], "webhooks": { "paynyxEvent": { "post": { "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } }, "responses": { "2XX": { "description": "Acknowledged; any non-2xx is retried with backoff." } }, "summary": "Event delivered to your webhook endpoint" } } } }