{ "openapi": "3.0.0", "info": { "title": "Paymentic Payment API", "description": "Paymentic REST API for accepting online payments — BLIK, fast bank transfers and cards. Create transactions, check statuses, issue refunds and receive webhook notifications.", "version": "1.2" }, "servers": [ { "url": "https://api.paymentic.com/v1_2" }, { "url": "https://api.sandbox.paymentic.com/v1_2" } ], "paths": { "/payment/points/{pointId}/transactions": { "get": { "tags": [ "Transactions" ], "summary": "List transactions", "operationId": "get-transactions", "parameters": [ { "$ref": "#/components/parameters/pointId" }, { "name": "filter[status]", "in": "query", "required": false, "schema": { "type": "string", "example": "PAID" } }, { "name": "filter[amount]", "in": "query", "required": false, "schema": { "type": "string", "example": "100.50" } }, { "name": "filter[externalReferenceId]", "in": "query", "required": false, "schema": { "type": "string", "example": "EXT-REF-123" } }, { "name": "filter[orderId]", "in": "query", "required": false, "schema": { "type": "string", "example": "ORD-12345" } }, { "name": "filter[customerName]", "in": "query", "required": false, "schema": { "type": "string", "example": "John Doe" } }, { "name": "filter[customerEmail]", "in": "query", "required": false, "schema": { "type": "string", "format": "email", "example": "john@example.com" } }, { "name": "filter[blikId]", "in": "query", "required": false, "schema": { "type": "string", "example": "BLIK123" } }, { "name": "filter[cardBin]", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 6, "minLength": 6, "example": "411111" } }, { "name": "filter[providerId]", "in": "query", "required": false, "schema": { "type": "string", "example": "blik" } }, { "name": "filter[createdAt]", "in": "query", "description": "Date range in format: YYYY-MM-DDTHH:MM:SSZ,YYYY-MM-DDTHH:MM:SSZ", "required": false, "schema": { "type": "string", "example": "2024-01-01T00:00:00Z,2024-12-31T23:59:59Z" } }, { "name": "filter[paidAt]", "in": "query", "description": "Date range in format: YYYY-MM-DDTHH:MM:SSZ,YYYY-MM-DDTHH:MM:SSZ", "required": false, "schema": { "type": "string", "example": "2024-01-01T00:00:00Z,2024-12-31T23:59:59Z" } }, { "name": "query[full]", "in": "query", "description": "Full-text search across all searchable fields", "required": false, "schema": { "type": "string", "example": "John" } }, { "name": "query[customerName]", "in": "query", "description": "Search by customer name", "required": false, "schema": { "type": "string", "example": "John Doe" } }, { "name": "query[customerEmail]", "in": "query", "description": "Search by customer email", "required": false, "schema": { "type": "string", "format": "email", "example": "john@example.com" } }, { "name": "query[title]", "in": "query", "description": "Search by transaction title", "required": false, "schema": { "type": "string", "example": "Order #12345" } }, { "name": "page[number]", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "example": 1 } }, { "name": "page[size]", "in": "query", "required": false, "schema": { "type": "integer", "maximum": 100, "minimum": 1, "example": 25 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GetTransactionsResource" } }, "pagination": { "properties": { "page": { "type": "integer", "example": 1 }, "pageSize": { "type": "integer", "example": 25 }, "total": { "type": "integer", "example": 320 }, "totalPages": { "type": "integer", "example": 13 }, "from": { "type": "integer", "example": 1, "nullable": true }, "to": { "type": "integer", "example": 25, "nullable": true }, "links": { "properties": { "first": { "type": "string", "format": "url", "nullable": true }, "prev": { "type": "string", "format": "url", "nullable": true }, "next": { "type": "string", "format": "url", "nullable": true }, "last": { "type": "string", "format": "url", "nullable": true } }, "type": "object" } }, "type": "object" } }, "type": "object" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PointNotFoundExceptionSchema" }, { "$ref": "#/components/schemas/NotFoundHttpExceptionSchema" } ] } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MethodNotAllowedHttpExceptionSchema" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationExceptionSchema" } } } } }, "x-priority": 11 }, "post": { "tags": [ "Transactions" ], "summary": "Create payment transaction", "description": "Creates a payment transaction and returns a redirect URL for the payer. Supports BLIK, cards and fast bank transfers.", "operationId": "create-payment-transaction", "parameters": [ { "$ref": "#/components/parameters/pointId" } ], "requestBody": { "description": "Create payment transaction", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransactionRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CreateTransactionResource" } }, "type": "object" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PointNotActiveExceptionSchema" } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PointNotFoundExceptionSchema" }, { "$ref": "#/components/schemas/NotFoundHttpExceptionSchema" } ] } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MethodNotAllowedHttpExceptionSchema" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationExceptionSchema" } } } } }, "x-priority": 10 } }, "/payment/points/{pointId}/transactions/{transactionId}": { "get": { "tags": [ "Transactions" ], "summary": "Get transaction details", "operationId": "get-transaction-details", "parameters": [ { "$ref": "#/components/parameters/pointId" }, { "$ref": "#/components/parameters/transactionId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/GetTransactionDetailsResource" } }, "type": "object" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PointNotFoundExceptionSchema" }, { "$ref": "#/components/schemas/TransactionNotFoundExceptionSchema" }, { "$ref": "#/components/schemas/NotFoundHttpExceptionSchema" } ] } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MethodNotAllowedHttpExceptionSchema" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationExceptionSchema" } } } } }, "x-priority": 20 } }, "/payment/points/{pointId}/transactions/{transactionId}/capture": { "patch": { "tags": [ "Transactions" ], "summary": "Capture a paid transaction", "operationId": "capture-transaction", "parameters": [ { "$ref": "#/components/parameters/pointId" }, { "$ref": "#/components/parameters/transactionId" } ], "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "properties": { "data": { "properties": {} } }, "type": "object" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PointNotActiveExceptionSchema" }, { "$ref": "#/components/schemas/TransactionInvalidStatusExceptionSchema" }, { "$ref": "#/components/schemas/TransactionAlreadyCapturedExceptionSchema" } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PointNotFoundExceptionSchema" }, { "$ref": "#/components/schemas/NotFoundHttpExceptionSchema" } ] } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MethodNotAllowedHttpExceptionSchema" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationExceptionSchema" } } } } }, "x-priority": 30 } }, "/payment/points/{pointId}/channels": { "get": { "tags": [ "Points" ], "summary": "List payment channels for a point", "operationId": "get-point-channels", "parameters": [ { "$ref": "#/components/parameters/pointId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/GetPointChannelsResource" } } }, "type": "object" } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PointNotFoundExceptionSchema" }, { "$ref": "#/components/schemas/NotFoundHttpExceptionSchema" } ] } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MethodNotAllowedHttpExceptionSchema" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationExceptionSchema" } } } } }, "x-priority": 40 } }, "/payment/points/{pointId}/transactions/{transactionId}/refunds": { "post": { "tags": [ "Refunds" ], "summary": "Create transaction refund", "operationId": "create-transaction-refund", "parameters": [ { "$ref": "#/components/parameters/pointId" }, { "$ref": "#/components/parameters/transactionId" } ], "requestBody": { "description": "Create transaction refund", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTransactionRefundRequest" } } } }, "responses": { "201": { "description": "Created", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/CreateTransactionRefundResource" } }, "type": "object" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PointNotActiveExceptionSchema" }, { "$ref": "#/components/schemas/PointRefundsDisabledExceptionSchema" } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PointNotFoundExceptionSchema" }, { "$ref": "#/components/schemas/NotFoundHttpExceptionSchema" } ] } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MethodNotAllowedHttpExceptionSchema" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationExceptionSchema" } } } } }, "x-priority": 50 } }, "/payment/points/{pointId}/transactions/{transactionId}/refunds/{refundId}": { "get": { "tags": [ "Refunds" ], "summary": "Get refund details", "operationId": "get-refund-details", "parameters": [ { "$ref": "#/components/parameters/pointId" }, { "$ref": "#/components/parameters/transactionId" }, { "$ref": "#/components/parameters/refundId" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/GetRefundDetailsResource" } }, "type": "object" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PointNotActiveExceptionSchema" }, { "$ref": "#/components/schemas/PointRefundsDisabledExceptionSchema" } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PointNotFoundExceptionSchema" }, { "$ref": "#/components/schemas/NotFoundHttpExceptionSchema" } ] } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MethodNotAllowedHttpExceptionSchema" } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationExceptionSchema" } } } } }, "x-priority": 51 } }, "/payment/points/{pointId}/transactions/{transactionId}/blik": { "post": { "tags": [ "BLIK" ], "summary": "Process BLIK transaction", "description": "Process a BLIK payment transaction using a 6-digit code", "operationId": "process-blik-transaction", "parameters": [ { "$ref": "#/components/parameters/pointId" }, { "$ref": "#/components/parameters/transactionId" } ], "requestBody": { "description": "BLIK transaction processing data", "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProcessBlikTransactionRequest" } } } }, "responses": { "202": { "description": "Accepted", "content": { "application/json": { "schema": { "properties": { "data": { "$ref": "#/components/schemas/ProcessBlikTransactionResource" } }, "type": "object" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/TransactionInvalidStatusExceptionSchema" }, { "$ref": "#/components/schemas/TransactionMissingDataExceptionSchema" }, { "$ref": "#/components/schemas/ProviderNotSupportedExceptionSchema" }, { "$ref": "#/components/schemas/TransactionBlikProcessingErrorExceptionSchema" } ] } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PointNotFoundExceptionSchema" }, { "$ref": "#/components/schemas/TransactionNotFoundExceptionSchema" }, { "$ref": "#/components/schemas/NotFoundHttpExceptionSchema" } ] } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationExceptionSchema" } } } } }, "x-priority": 60 } }, "/payment/ping": { "get": { "tags": [ "System" ], "summary": "Ping the API", "operationId": "ping", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "properties": { "data": { "properties": { "message": { "type": "string", "example": "pong" }, "environment": { "type": "string", "enum": [ "production", "sandbox" ], "example": "sandbox" }, "tokenId": { "type": "string", "example": "2a77157f-7a73-413d-90a1-cd1263533d61" }, "clientId": { "type": "string", "example": "72b631fe" }, "version": { "type": "string", "example": "1.2" }, "scopes": { "type": "array", "items": { "type": "string" }, "example": [ "*" ] } }, "type": "object" } }, "type": "object" } } } }, "405": { "description": "Method Not Allowed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MethodNotAllowedHttpExceptionSchema" } } } } }, "x-priority": 100 } } }, "components": { "schemas": { "CreateTransactionRequest": { "required": [ "amount", "title" ], "properties": { "amount": { "description": "Amount in minor precision with up to 2 decimals", "type": "string", "format": "decimal", "example": "123.45" }, "currency": { "description": "ISO 4217 3-letter currency code. Defaults to PLN when omitted.", "type": "string", "default": "PLN", "maxLength": 3, "minLength": 3, "enum": [ "PLN", "EUR" ], "example": "PLN", "nullable": true }, "title": { "type": "string", "maxLength": 64, "minLength": 5, "example": "Order #12345" }, "description": { "type": "string", "maxLength": 128, "nullable": true }, "externalReferenceId": { "type": "string", "maxLength": 64, "nullable": true }, "redirect": { "properties": { "success": { "type": "string", "format": "uri", "maxLength": 255, "nullable": true }, "failure": { "type": "string", "format": "uri", "maxLength": 255, "nullable": true } }, "type": "object", "nullable": true }, "customer": { "oneOf": [ { "$ref": "#/components/schemas/CustomerDataSchema" } ], "nullable": true, "type": "object" }, "order": { "oneOf": [ { "$ref": "#/components/schemas/OrderDataSchema" } ], "nullable": true, "type": "object" }, "billingAddress": { "oneOf": [ { "$ref": "#/components/schemas/CustomerFullDataSchema" } ], "nullable": true }, "shippingAddress": { "oneOf": [ { "$ref": "#/components/schemas/CustomerFullDataSchema" } ], "nullable": true }, "cart": { "type": "array", "items": { "properties": { "name": { "type": "string", "maxLength": 64, "nullable": true }, "quantity": { "type": "integer", "minimum": 1, "nullable": true }, "unitPrice": { "type": "string", "format": "decimal", "nullable": true }, "type": { "type": "string", "default": "PRODUCT", "enum": [ "PRODUCT", "SHIPPING", "DISCOUNT", "SURCHARGE", "GIFT_CARD" ], "nullable": true }, "productType": { "type": "string", "enum": [ "PHYSICAL", "DIGITAL", "SERVICE", "VIRTUAL" ], "nullable": true }, "sku": { "type": "string", "maximum": 64, "nullable": true } }, "type": "object" }, "nullable": true }, "paymentMethod": { "type": "string", "enum": [ "BLIK", "PBL", "BNPL", "CARD", "MOBILE_WALLET" ], "example": "CARD", "nullable": true }, "paymentChannel": { "type": "string", "example": null, "nullable": true }, "allowedPaymentMethods": { "description": "Whitelist of payment methods (optionally narrowed to a specific channel) that the gateway will present to the customer. Cannot be combined with hiddenPaymentMethods, paymentMethod or paymentChannel. When paymentChannel is null, all channels of that method are allowed.", "type": "array", "items": { "required": [ "paymentMethod" ], "properties": { "paymentMethod": { "type": "string", "enum": [ "BLIK", "PBL", "BNPL", "CARD", "MW", "PAYSAFE" ], "example": "BLIK" }, "paymentChannel": { "type": "string", "example": "blik-level0", "nullable": true } }, "type": "object" }, "nullable": true }, "hiddenPaymentMethods": { "description": "List of payment methods (optionally narrowed to a specific channel) that the gateway will hide from the customer. Cannot be combined with allowedPaymentMethods, paymentMethod or paymentChannel. When paymentChannel is null, all channels of that method are hidden.", "type": "array", "items": { "required": [ "paymentMethod" ], "properties": { "paymentMethod": { "type": "string", "enum": [ "BLIK", "PBL", "BNPL", "CARD", "MW", "PAYSAFE" ], "example": "BNPL" }, "paymentChannel": { "type": "string", "example": null, "nullable": true } }, "type": "object" }, "nullable": true }, "createRegistration": { "description": "If true, store customer payment instrument for recurring transactions.", "type": "boolean", "nullable": true }, "whitelabel": { "type": "boolean", "nullable": true }, "autoCapture": { "type": "boolean", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "ProcessBlikTransactionRequest": { "required": [ "type", "code" ], "properties": { "type": { "description": "BLIK transaction type", "type": "string", "enum": [ "CODE", "ALIAS" ], "example": "CODE" }, "code": { "description": "6-digit BLIK code (required when type is CODE)", "type": "string", "maxLength": 6, "minLength": 6, "pattern": "^\\d{6}$", "example": "777123" }, "alias": { "description": "Alias data", "required": [ "value" ], "properties": { "value": { "description": "Alias value", "type": "string", "maxLength": 64, "example": "new-alias-123" }, "label": { "description": "Alias label", "type": "string", "maxLength": 35, "example": "joh...eo@ex...le.com" }, "appId": { "description": "Alias app ID", "type": "string", "maxLength": 64, "example": "my-app-id" } }, "type": "object" } }, "type": "object" }, "CreateTransactionRefundRequest": { "required": [ "amount", "title" ], "properties": { "amount": { "description": "Amount in minor precision with up to 2 decimals", "type": "string", "format": "decimal", "example": "123.45" }, "reason": { "description": "Reason for refund", "type": "string", "maxLength": 64, "nullable": true }, "externalReferenceId": { "description": "External reference ID", "type": "string", "maxLength": 64 } }, "type": "object" }, "GetPointChannelsResource": { "properties": { "id": { "description": "Channel ID", "type": "string", "example": "mbank", "nullable": false }, "available": { "description": "Whether the channel is available for use", "type": "boolean", "example": true, "nullable": false }, "method": { "description": "Payment method", "type": "string", "example": "PBL", "nullable": false }, "name": { "description": "Channel name", "type": "string", "example": "mBank", "nullable": false }, "image": { "description": "Channel image", "properties": { "default": { "description": "Default channel image", "type": "string", "format": "url", "example": "https://example.com/image.png", "nullable": true } }, "type": "object" }, "amount": { "description": "Minimum and maximum transaction amount", "properties": { "minimum": { "description": "Minimum transaction amount", "type": "string", "format": "decimal", "example": "10.00", "nullable": false }, "maximum": { "description": "Maximum transaction amount", "type": "string", "format": "decimal", "example": "10000.00", "nullable": false } }, "type": "object" }, "aliases": { "description": "Channel aliases", "type": "array", "items": { "type": "string" }, "nullable": true }, "currencies": { "description": "Supported currencies", "type": "array", "items": { "type": "string" }, "nullable": false }, "commission": { "description": "Commission settings", "properties": { "value": { "description": "Commission value", "type": "string", "format": "decimal", "example": "1.65", "nullable": true }, "minimum": { "description": "Minimum commission amount", "type": "string", "format": "decimal", "example": "0.30", "nullable": true }, "fixed": { "description": "Whether commission is fixed", "type": "string", "format": "decimal", "example": "2.50", "nullable": true } }, "type": "object" }, "authorization": { "description": "Authorization settings", "properties": { "type": { "description": "Authorization type", "type": "array", "items": { "type": "string", "enum": [ "REDIRECT", "MULTI_FACTOR", "SCAN_CODE", "APP_NOTIFICATION" ] } } }, "type": "object" }, "paymentType": { "description": "Payment type", "type": "string", "enum": [ "INSTANT", "PRE_AUTHORIZATION", "OFFLINE" ], "example": "INSTANT", "nullable": false }, "compliance": { "description": "Compliance items for the channel", "type": "array", "items": { "properties": { "id": { "description": "Compliance item identifier", "type": "string", "example": "info_gdpr" }, "type": { "description": "Compliance type", "type": "string", "enum": [ "DISPLAYABLE", "ACCEPTABLE" ], "example": "DISPLAYABLE" }, "required": { "type": "boolean", "example": false }, "checked": { "type": "boolean", "example": false, "nullable": true }, "content": { "properties": { "text": { "type": "string", "example": "Administratorem Twoich danych jest Paymentic..." }, "html": { "type": "string", "example": "Administratorem Twoich danych jest Paymentic..." }, "markdown": { "type": "string", "example": "Administratorem Twoich danych jest **Paymentic**..." } }, "type": "object" }, "links": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "privacy_policy" }, "label": { "type": "string", "example": "Polityka prywatności" }, "url": { "type": "string", "format": "url", "example": "https://example.com/pp.pdf" } }, "type": "object" } } }, "type": "object" }, "nullable": true }, "enablingAt": { "description": "Channel enabling date", "type": "string", "format": "date-time", "nullable": true }, "disablingAt": { "description": "Channel disabling date", "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "CreateTransactionRefundResource": { "properties": { "id": { "$ref": "#/components/parameters/refundId" }, "status": { "$ref": "#/components/schemas/RefundStatusSchema" } }, "type": "object" }, "GetRefundDetailsResource": { "properties": { "id": { "$ref": "#/components/parameters/refundId" }, "status": { "$ref": "#/components/schemas/RefundStatusSchema" }, "amount": { "description": "Refund amount as a string-encoded decimal", "type": "string", "example": "123.45" }, "reason": { "description": "Reason for refund", "type": "string", "maxLength": 64, "nullable": true }, "externalReferenceId": { "description": "External reference ID", "type": "string", "maxLength": 64, "nullable": true }, "createdAt": { "description": "Refund creation timestamp", "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "description": "Refund update timestamp", "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "CreateTransactionResource": { "properties": { "id": { "description": "Transaction ID", "type": "string", "example": "ABCD-123-XYZ-9876", "nullable": false }, "redirectUrl": { "description": "Transaction URL", "type": "string", "format": "url", "example": "https://pay.paymentic.com/ABCD-123-XYZ-9876?token=...", "nullable": false }, "whitelabel": { "type": "object", "example": null, "nullable": true } }, "type": "object" }, "GetTransactionDetailsResource": { "properties": { "id": { "$ref": "#/components/parameters/transactionId" }, "status": { "$ref": "#/components/schemas/TransactionStatusSchema" }, "amount": { "description": "Transaction amount as a string-encoded decimal", "type": "string", "example": "123.45", "nullable": false }, "currency": { "description": "ISO 4217 currency code", "type": "string", "example": "PLN", "nullable": false }, "title": { "type": "string", "example": "Order #12345", "nullable": false }, "commission": { "type": "string", "example": "1.23", "nullable": true }, "description": { "type": "string", "example": "Payment for order #12345", "nullable": true }, "customer": { "$ref": "#/components/schemas/CustomerDataSchema" }, "order": { "$ref": "#/components/schemas/OrderDataSchema" }, "billingAddress": { "oneOf": [ { "$ref": "#/components/schemas/CustomerFullDataSchema" } ], "nullable": true }, "shippingAddress": { "oneOf": [ { "$ref": "#/components/schemas/CustomerFullDataSchema" } ], "nullable": true }, "externalReferenceId": { "type": "string", "example": "EXT-REF-123", "nullable": true }, "redirect": { "properties": { "success": { "type": "string", "format": "url", "example": "https://merchant.example/success", "nullable": true }, "failure": { "type": "string", "format": "url", "example": "https://merchant.example/failure", "nullable": true } }, "type": "object", "nullable": false }, "paymentMethod": { "type": "string", "example": "VISA", "nullable": true }, "paymentChannel": { "type": "string", "example": null, "nullable": true }, "whitelabel": { "type": "boolean", "example": false, "nullable": false }, "cart": { "type": "array", "items": { "$ref": "#/components/schemas/CartItemSchema" }, "nullable": true }, "autoCapture": { "type": "boolean", "example": true, "nullable": false }, "isCaptured": { "type": "boolean", "example": false, "nullable": false }, "capturedAt": { "type": "string", "format": "date-time", "nullable": true }, "paidAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "nullable": true }, "expiresAt": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "GetTransactionsResource": { "properties": { "id": { "$ref": "#/components/schemas/TransactionIdSchema" }, "status": { "$ref": "#/components/schemas/TransactionStatusSchema" }, "amount": { "description": "Transaction amount as a string-encoded decimal", "type": "string", "example": "123.45", "nullable": false }, "title": { "type": "string", "example": "Order #12345", "nullable": false }, "commission": { "type": "string", "example": "1.23", "nullable": true }, "customerName": { "type": "string", "example": "John Doe", "nullable": true }, "customerEmail": { "type": "string", "format": "email", "example": "john@example.com", "nullable": true }, "externalReferenceId": { "type": "string", "example": "EXT-REF-123", "nullable": true }, "paymentMethod": { "type": "string", "example": "BLIK", "nullable": true }, "paymentChannel": { "type": "string", "example": "blik-psp", "nullable": true }, "orderId": { "type": "string", "example": "ORD-12345", "nullable": true }, "blikId": { "type": "string", "example": "BLIK123", "nullable": true }, "cardBin": { "type": "string", "example": "411111", "nullable": true }, "paidAt": { "type": "string", "format": "date-time", "nullable": true }, "createdAt": { "type": "string", "format": "date-time", "nullable": true } }, "type": "object" }, "ProcessBlikTransactionResource": { "properties": { "actionId": { "description": "Unique identifier for the BLIK action", "type": "string", "format": "ulid", "example": "01kaqf5trc82bk6cqqanjcjwnq" }, "alias": { "description": "BLIK alias information", "type": "object", "example": null, "nullable": true } }, "type": "object" }, "MethodNotAllowedHttpExceptionSchema": { "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "METHOD_NOT_ALLOWED" }, "message": { "type": "string", "example": "Method not allowed for " }, "docsUrl": { "type": "string", "example": "https://docs.paymentic.com/errors#METHOD_NOT_ALLOWED" }, "details": { "properties": { "allowedMethods": { "type": "array", "items": { "type": "string", "example": "GET" } } }, "type": "object" } }, "type": "object" } } }, "type": "object" }, "NotFoundHttpExceptionSchema": { "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "PATH_NOT_FOUND" }, "message": { "type": "string", "example": "The path / could not be found" }, "docsUrl": { "type": "string", "example": "https://docs.paymentic.com/errors#PATH_NOT_FOUND" }, "details": { "type": "object", "example": null, "nullable": true } }, "type": "object" } } }, "type": "object" }, "PointNotActiveExceptionSchema": { "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "POINT_NOT_ACTIVE" }, "message": { "type": "string", "example": "Point not active." }, "docsUrl": { "type": "string", "example": "https://docs.paymentic.com/errors#POINT_NOT_ACTIVE" }, "details": { "type": "object", "example": null } }, "type": "object" } } }, "type": "object" }, "PointNotFoundExceptionSchema": { "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "POINT_NOT_FOUND" }, "message": { "type": "string", "example": "Point not found." }, "docsUrl": { "type": "string", "example": "https://docs.paymentic.com/errors#POINT_NOT_FOUND" }, "details": { "type": "object", "example": null } }, "type": "object" } } }, "type": "object" }, "PointRefundsDisabledExceptionSchema": { "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "POINT_REFUNDS_DISABLED" }, "message": { "type": "string", "example": "Point refunds disabled." }, "docsUrl": { "type": "string", "example": "https://docs.paymentic.com/errors#POINT_REFUNDS_DISABLED" }, "details": { "type": "object", "example": null } }, "type": "object" } } }, "type": "object" }, "ProviderNotSupportedExceptionSchema": { "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "PROVIDER_NOT_SUPPORTED" }, "message": { "type": "string", "example": "Provider not supported" }, "docsUrl": { "type": "string", "example": "https://docs.paymentic.com/errors#PROVIDER_NOT_SUPPORTED" }, "details": { "type": "object", "example": null } }, "type": "object" } } }, "type": "object" }, "TransactionAlreadyCapturedExceptionSchema": { "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "TRANSACTION_ALREADY_CAPTURED" }, "message": { "type": "string", "example": "Transaction already captured." }, "docsUrl": { "type": "string", "example": "https://docs.paymentic.com/errors#TRANSACTION_ALREADY_CAPTURED" }, "details": { "type": "object", "example": null } }, "type": "object" } } }, "type": "object" }, "TransactionBlikProcessingErrorExceptionSchema": { "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "TRANSACTION_BLIK_PROCESSING_ERROR" }, "message": { "type": "string", "example": "Transaction BLIK processing error." }, "docsUrl": { "type": "string", "example": "https://docs.paymentic.com/errors#TRANSACTION_BLIK_PROCESSING_ERROR" }, "details": { "properties": { "blikErrorCode": { "type": "string", "example": "DECLINED" } }, "type": "object" } }, "type": "object" } } }, "type": "object" }, "TransactionInvalidStatusExceptionSchema": { "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "TRANSACTION_INVALID_STATUS" }, "message": { "type": "string", "example": "Transaction invalid status." }, "docsUrl": { "type": "string", "example": "https://docs.paymentic.com/errors#TRANSACTION_INVALID_STATUS" }, "details": { "type": "object", "example": null } }, "type": "object" } } }, "type": "object" }, "TransactionMissingDataExceptionSchema": { "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "TRANSACTION_MISSING_DATA" }, "message": { "type": "string", "example": "Transaction missing data." }, "docsUrl": { "type": "string", "example": "https://docs.paymentic.com/errors#TRANSACTION_MISSING_DATA" }, "details": { "properties": { "field": { "type": "string", "example": "customer.email" } }, "type": "object" } }, "type": "object" } } }, "type": "object" }, "TransactionNotFoundExceptionSchema": { "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "TRANSACTION_NOT_FOUND" }, "message": { "type": "string", "example": "Transaction not found." }, "docsUrl": { "type": "string", "example": "https://docs.paymentic.com/errors#TRANSACTION_NOT_FOUND" }, "details": { "type": "object", "example": null } }, "type": "object" } } }, "type": "object" }, "ValidationExceptionSchema": { "properties": { "errors": { "type": "array", "items": { "properties": { "code": { "type": "string", "example": "VALIDATION_ERROR" }, "message": { "type": "string", "example": "The selected pointId is invalid." }, "docsUrl": { "type": "string", "example": "https://docs.paymentic.com/errors#VALIDATION_ERROR" }, "details": { "properties": { "field": { "type": "string", "example": "pointId" }, "messages": { "type": "array", "items": { "type": "string", "example": "The selected pointId is invalid." } } }, "type": "object" } }, "type": "object" } } }, "type": "object" }, "CartItemSchema": { "properties": { "name": { "type": "string", "maxLength": 64, "example": "Harry Potter", "nullable": true }, "quantity": { "type": "integer", "minimum": 1, "example": 1, "nullable": true }, "unitPrice": { "type": "string", "format": "decimal", "example": "19.99", "nullable": true } }, "type": "object" }, "CustomerDataSchema": { "properties": { "name": { "type": "string", "maxLength": 64, "pattern": "^[\\p{L}' -]+$", "example": "John Doe", "nullable": true }, "email": { "type": "string", "maxLength": 64, "example": "john.doe@example.com", "nullable": true }, "emailVerified": { "type": "boolean", "nullable": true }, "phone": { "type": "string", "maxLength": 64, "example": "+48123456789", "nullable": true }, "phoneVerified": { "type": "boolean", "nullable": true }, "country": { "description": "ISO 3166-1 alpha-2", "type": "string", "maxLength": 2, "minLength": 2, "example": "PL", "nullable": true }, "locale": { "description": "ISO 639-1 alpha-2", "type": "string", "maxLength": 2, "minLength": 2, "nullable": true }, "ip": { "type": "string", "maxLength": 64, "nullable": true }, "userAgent": { "type": "string", "maxLength": 128, "nullable": true }, "fingerprint": { "type": "string", "maxLength": 64, "nullable": true } }, "type": "object" }, "CustomerFullDataSchema": { "properties": { "firstName": { "type": "string", "maxLength": 64, "minLength": 2, "pattern": "/^[\\p{L}'-]+$/u", "example": "John", "nullable": true }, "lastName": { "type": "string", "maxLength": 64, "minLength": 2, "pattern": "/^[\\p{L}'-]+$/u", "example": "Doe", "nullable": true }, "street": { "type": "string", "maxLength": 64, "example": "ul. Kowalska", "nullable": true }, "buildingNumber": { "type": "string", "maxLength": 16, "example": "26", "nullable": true }, "flat": { "type": "string", "maxLength": 16, "nullable": true }, "city": { "type": "string", "maxLength": 64, "example": "Bielsko-Biała", "nullable": true }, "region": { "type": "string", "maxLength": 64, "nullable": true }, "postalCode": { "type": "string", "maxLength": 16, "example": "43-316", "nullable": true }, "state": { "type": "string", "maxLength": 64, "nullable": true }, "country": { "type": "string", "format": "ISO-3166-1 alpha-2", "maxLength": 2, "minLength": 2, "example": "PL", "nullable": true }, "company": { "type": "string", "maxLength": 64, "nullable": true } }, "type": "object" }, "OrderDataSchema": { "properties": { "id": { "type": "string", "maxLength": 64, "nullable": true }, "shippingMethod": { "type": "string", "enum": [ "VIRTUAL", "TRACKED_DELIVERY", "UNTRACKED_DELIVERY", "IN_STORE_PICKUP", "PARCEL_PICKUP", "LOCKER_PICKUP", "HYBRID", "OTHER" ], "nullable": true }, "trackingNumber": { "type": "string", "nullable": true }, "customerType": { "type": "string", "enum": [ "B2B", "B2C" ], "nullable": true } }, "type": "object" }, "PointIdSchema": { "type": "string", "pattern": "^[0-9a-f]{8}$", "example": "b8e6e2fc" }, "RefundIdSchema": { "type": "string", "maxLength": 11, "minLength": 11, "pattern": "^[A-Z0-9]{3}-[A-Z0-9]{3}-[A-Z0-9]{3}$", "example": "AB1-AB2-AB3" }, "RefundStatusSchema": { "type": "string", "enum": [ "CREATED", "ACCEPTED", "PENDING", "DONE", "REJECTED", "CANCELLED" ] }, "TransactionIdSchema": { "type": "string", "maxLength": 14, "minLength": 14, "pattern": "^[A-Z0-9]{4}-[A-Z0-9]{3}-[A-Z0-9]{3}-[A-Z0-9]{4}$", "example": "ABC1-AB2-AB3-ABC4" }, "TransactionStatusSchema": { "type": "string", "enum": [ "CREATED", "PENDING", "PAID", "FAILED", "EXPIRED" ] } }, "parameters": { "pointId": { "name": "pointId", "in": "path", "description": "Point ID", "required": true, "schema": { "$ref": "#/components/schemas/PointIdSchema" } }, "refundId": { "name": "refundId", "in": "path", "description": "Refund ID", "required": true, "schema": { "type": "string", "pattern": "^[A-Z0-9]{3}-[A-Z0-9]{3}-[A-Z0-9]{3}$" }, "example": "AB1-AB2-AB3" }, "transactionId": { "name": "transactionId", "in": "path", "description": "Transaction ID", "required": true, "schema": { "$ref": "#/components/schemas/TransactionIdSchema" } }, "Content-Type": { "name": "Content-Type", "in": "header", "required": true, "schema": { "type": "string", "example": "application/json" } }, "X-Paymentic-Event": { "name": "X-Paymentic-Event", "in": "header", "required": true, "schema": { "type": "string", "enum": [ "PAYMENT.TRANSACTION_STATUS_CHANGED", "PAYMENT.REFUND_STATUS_CHANGED", "PAYMENT.BLIK_ALIAS_STATUS_CHANGED" ] } }, "X-Paymentic-Notification-Id": { "name": "X-Paymentic-Notification-Id", "in": "header", "required": true, "schema": { "type": "string", "format": "ulid", "example": "01j96yn02bhbv8j1jjtk36zn2t" } }, "X-Paymentic-Signature": { "name": "X-Paymentic-Signature", "in": "header", "required": true, "schema": { "type": "string", "example": "5Fil+PpabLxsKwo3rWj9+o6gAi4ub93fismBewbYz46mHt7pjPHcHELUVw8McZ5nUb3feMVVBl+dPzXq2XgLQ==" } }, "X-Paymentic-Time": { "name": "X-Paymentic-Time", "in": "header", "required": true, "schema": { "type": "string", "format": "date-time", "example": "2025-01-01T12:00:00+00:00" } }, "User-Agent": { "name": "User-Agent", "in": "header", "required": true, "schema": { "type": "string", "example": "Paymentic/1.2" } } }, "securitySchemes": { "bearerToken": { "type": "apiKey", "name": "Authorization", "in": "header" } } }, "tags": [ { "name": "Transactions", "description": "Create payment transactions, check their status and capture authorized payments." }, { "name": "Points", "description": "List payment channels available for a point." }, { "name": "Refunds", "description": "Create refunds for paid transactions and check their status." }, { "name": "BLIK", "description": "Process BLIK payments for existing transactions." }, { "name": "System", "description": "Health check and diagnostics." } ] }