{ "openapi": "3.1.0", "info": { "title": "Paydex API", "version": "1.0.0", "summary": "Приём платежей по СБП и банковским картам: счета, возвраты, вебхуки", "description": "REST API платёжного шлюза Paydex. Суммы — строки с двумя знаками, даты — ISO 8601 UTC, ошибки — { error: { code, message } }. Документация: https://paydex.pro/docs", "termsOfService": "https://paydex.pro/legal/offer", "contact": { "name": "Paydex Support", "url": "https://paydex.pro/contacts" } }, "servers": [ { "url": "https://paydex.pro/api/v1", "description": "Production (и песочница по ключу sk_test_)" } ], "externalDocs": { "url": "https://paydex.pro/docs", "description": "Документация" }, "tags": [ { "name": "Invoices", "description": "Счета" }, { "name": "Refunds", "description": "Возвраты" }, { "name": "Reference", "description": "Справочники и баланс" }, { "name": "Webhooks", "description": "Исходящие уведомления (описание, не эндпоинт)" } ], "security": [ { "bearerAuth": [] }, { "hmacSignature": [], "publicId": [] } ], "paths": { "/invoices": { "post": { "tags": [ "Invoices" ], "operationId": "createInvoice", "summary": "Создать счёт", "description": "Создаёт счёт и возвращает ссылку на страницу оплаты. orderId идемпотентен в рамках проекта: повтор с тем же orderId возвращает существующий счёт (200), с другими параметрами — 409 order_id_conflict.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateInvoiceRequest" } } } }, "responses": { "200": { "description": "Счёт с таким orderId уже существует (идемпотентный повтор)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceCreated" } } } }, "201": { "description": "Счёт создан", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceCreated" } } } }, "400": { "description": "Некорректный запрос", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation", "message": "Некорректный запрос" } } } } }, "401": { "description": "Неверный ключ или подпись", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Неверный ключ или подпись" } } } } }, "403": { "description": "Проект не активен", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "project_not_active", "message": "Проект не активен" } } } } }, "409": { "description": "orderId занят счётом с другими параметрами", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "order_id_conflict", "message": "orderId занят счётом с другими параметрами" } } } } }, "422": { "description": "Сумма вне лимитов или метод недоступен", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "amount_out_of_range", "message": "Сумма вне лимитов или метод недоступен" } } } } }, "429": { "description": "Превышен лимит запросов", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Через сколько секунд повторить" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Превышен лимит запросов" } } } } }, "503": { "description": "Способ оплаты временно недоступен", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "provider_unavailable", "message": "Способ оплаты временно недоступен" } } } } } } }, "get": { "tags": [ "Invoices" ], "operationId": "listInvoices", "summary": "Список счетов", "description": "Счета проекта от новых к старым с курсорной пагинацией. Фильтр orderId возвращает 0 или 1 элемент.", "parameters": [ { "name": "orderId", "in": "query", "schema": { "type": "string", "maxLength": 128 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "created", "pending", "paid", "failed", "expired", "refunded", "partially_refunded" ] } }, { "name": "from", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "ISO 8601, UTC" }, "description": "Создан не ранее (включительно)" }, { "name": "to", "in": "query", "schema": { "type": "string", "format": "date-time", "description": "ISO 8601, UTC" }, "description": "Создан ранее (исключительно)" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" }, "description": "nextCursor из предыдущего ответа" } ], "responses": { "200": { "description": "Страница списка", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceList" } } } }, "400": { "description": "Некорректные параметры", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "validation", "message": "Некорректные параметры" } } } } }, "401": { "description": "Неверный ключ или подпись", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Неверный ключ или подпись" } } } } }, "429": { "description": "Превышен лимит запросов", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Через сколько секунд повторить" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Превышен лимит запросов" } } } } } } } }, "/invoices/{id}": { "get": { "tags": [ "Invoices" ], "operationId": "getInvoice", "summary": "Получить счёт", "description": "Текущее состояние счёта. Опрос одного счёта — не чаще 1 раза в 3 секунды (иначе 429 с Retry-After); для уведомлений используйте вебхуки.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Счёт", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Invoice" } } } }, "401": { "description": "Неверный ключ или подпись", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Неверный ключ или подпись" } } } } }, "404": { "description": "Счёт не найден", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invoice_not_found", "message": "Счёт не найден" } } } } }, "429": { "description": "Слишком частый опрос", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Через сколько секунд повторить" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Слишком частый опрос" } } } } } } } }, "/invoices/{id}/refund": { "post": { "tags": [ "Refunds" ], "operationId": "refundInvoice", "summary": "Вернуть средства покупателю", "description": "Полный (без amount) или частичный возврат по оплаченному счёту. Сумма списывается с баланса мерчанта. Обрабатывается асинхронно: 202 + статус pending, итог — вебхук refund.succeeded / refund.failed.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Сумма возврата; по умолчанию — весь невозвращённый остаток", "examples": [ "1500.00" ] } } } } } }, "responses": { "202": { "description": "Возврат принят в обработку", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "401": { "description": "Неверный ключ или подпись", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Неверный ключ или подпись" } } } } }, "404": { "description": "Счёт не найден", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invoice_not_found", "message": "Счёт не найден" } } } } }, "409": { "description": "Счёт не в статусе paid / partially_refunded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "conflict", "message": "Счёт не в статусе paid / partially_refunded" } } } } }, "422": { "description": "Сумма превышает остаток или недостаточно средств на балансе", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "refund_exceeds_amount", "message": "Сумма превышает остаток или недостаточно средств на балансе" } } } } } } } }, "/refunds/{id}": { "get": { "tags": [ "Refunds" ], "operationId": "getRefund", "summary": "Получить возврат", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "examples": [ "rf_01J7ZK9Q2M4N6P8R0S2T4V6W8X" ] } } ], "responses": { "200": { "description": "Возврат", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Refund" } } } }, "401": { "description": "Неверный ключ или подпись", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Неверный ключ или подпись" } } } } }, "404": { "description": "Возврат не найден", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invoice_not_found", "message": "Возврат не найден" } } } } } } } }, "/methods": { "get": { "tags": [ "Reference" ], "operationId": "listMethods", "summary": "Доступные способы оплаты", "responses": { "200": { "description": "Список методов", "content": { "application/json": { "schema": { "type": "object", "required": [ "methods" ], "properties": { "methods": { "type": "array", "items": { "$ref": "#/components/schemas/Method" } } } } } } }, "401": { "description": "Неверный ключ или подпись", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Неверный ключ или подпись" } } } } } } } }, "/balance": { "get": { "tags": [ "Reference" ], "operationId": "getBalance", "summary": "Баланс мерчанта", "responses": { "200": { "description": "Баланс", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Balance" } } } }, "401": { "description": "Неверный ключ или подпись", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Неверный ключ или подпись" } } } } } } } } }, "webhooks": { "invoice.paid": { "post": { "tags": [ "Webhooks" ], "summary": "Счёт оплачен", "description": "POST на webhook_url проекта. Заголовки: X-Paydex-Signature (sha256=HMAC-SHA256(rawBody, webhook_secret)), X-Paydex-Timestamp, X-Paydex-Event, X-Paydex-Delivery-Id, X-Paydex-Test. Ответ 2xx за 10 с; иначе повторы через 1м, 5м, 30м, 2ч, 12ч, 24ч.", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceEvent" } } } }, "responses": { "200": { "description": "Принято" } } } }, "invoice.failed": { "post": { "tags": [ "Webhooks" ], "summary": "Платёж отклонён", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceEvent" } } } }, "responses": { "200": { "description": "Принято" } } } }, "invoice.expired": { "post": { "tags": [ "Webhooks" ], "summary": "Срок оплаты истёк", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvoiceEvent" } } } }, "responses": { "200": { "description": "Принято" } } } }, "refund.succeeded": { "post": { "tags": [ "Webhooks" ], "summary": "Возврат выполнен", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundEvent" } } } }, "responses": { "200": { "description": "Принято" } } } }, "refund.failed": { "post": { "tags": [ "Webhooks" ], "summary": "Возврат не удался", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefundEvent" } } } }, "responses": { "200": { "description": "Принято" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_live_… | sk_test_…", "description": "Секретный ключ проекта. sk_test_ — песочница." }, "publicId": { "type": "apiKey", "in": "header", "name": "X-Public-Id", "description": "публичный ключ pk_live_/pk_test_ (вместе с X-Signature)" }, "hmacSignature": { "type": "apiKey", "in": "header", "name": "X-Signature", "description": "hex(HMAC-SHA256(rawBody, webhook_secret проекта)). Принимается также в заголовке Signature." } }, "schemas": { "Money": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Сумма в рублях строкой с двумя знаками", "examples": [ "1500.00" ] }, "Customer": { "type": "object", "description": "Данные покупателя (все поля необязательны)", "properties": { "email": { "type": [ "string", "null" ], "format": "email" }, "phone": { "type": [ "string", "null" ], "description": "E.164" }, "userId": { "type": [ "string", "null" ], "description": "Идентификатор покупателя в вашей системе" }, "name": { "type": [ "string", "null" ] } } }, "CreateInvoiceRequest": { "type": "object", "required": [ "amount", "orderId" ], "properties": { "amount": { "oneOf": [ { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Сумма в рублях строкой с двумя знаками", "examples": [ "1500.00" ] }, { "type": "number" } ], "description": "Сумма в рублях; в ответах всегда строка" }, "orderId": { "type": "string", "maxLength": 128, "description": "Ваш номер заказа, уникален в рамках проекта (идемпотентность)" }, "description": { "type": "string", "maxLength": 255 }, "method": { "type": "string", "enum": [ "sbp", "card" ], "description": "Не передан — покупатель выбирает сам" }, "feePayer": { "type": "string", "enum": [ "merchant", "customer" ], "description": "Кто платит комиссию; по умолчанию — настройка проекта" }, "successUrl": { "type": "string", "format": "uri" }, "failUrl": { "type": "string", "format": "uri" }, "expire": { "type": "integer", "minimum": 1, "maximum": 1440, "default": 60, "description": "Срок жизни счёта, минуты" }, "customer": { "$ref": "#/components/schemas/Customer" }, "customFields": { "type": "object", "additionalProperties": true, "description": "Произвольный JSON до 2 КБ; возвращается как есть" }, "payerEmail": { "type": "string", "format": "email", "deprecated": true, "description": "Синоним customer.email" } } }, "InvoiceCreated": { "type": "object", "required": [ "id", "url", "status", "amount", "fee", "expiresAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri", "description": "Страница оплаты" }, "status": { "type": "string", "enum": [ "created", "pending", "paid", "failed", "expired", "refunded", "partially_refunded" ] }, "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Сумма в рублях строкой с двумя знаками", "examples": [ "1500.00" ] }, "fee": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Сумма в рублях строкой с двумя знаками", "examples": [ "1500.00" ] }, "expiresAt": { "type": "string", "format": "date-time", "description": "ISO 8601, UTC" } } }, "Invoice": { "type": "object", "required": [ "id", "url", "orderId", "status", "amount", "fee", "currency", "feePayer", "isTest", "createdAt", "expiresAt" ], "properties": { "id": { "type": "string", "format": "uuid" }, "url": { "type": "string", "format": "uri" }, "orderId": { "type": "string" }, "status": { "type": "string", "enum": [ "created", "pending", "paid", "failed", "expired", "refunded", "partially_refunded" ] }, "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Сумма в рублях строкой с двумя знаками", "examples": [ "1500.00" ] }, "fee": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Сумма в рублях строкой с двумя знаками", "examples": [ "1500.00" ] }, "currency": { "type": "string", "const": "RUB" }, "method": { "type": [ "string", "null" ], "enum": [ "sbp", "card", null ], "description": "null, пока покупатель не выбрал способ" }, "feePayer": { "type": "string", "enum": [ "merchant", "customer" ] }, "description": { "type": [ "string", "null" ] }, "customer": { "$ref": "#/components/schemas/Customer" }, "customFields": { "type": [ "object", "null" ], "additionalProperties": true }, "isTest": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601, UTC" }, "expiresAt": { "type": "string", "format": "date-time", "description": "ISO 8601, UTC" }, "paidAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, UTC" } } }, "InvoiceList": { "type": "object", "required": [ "items", "hasMore" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Invoice" } }, "nextCursor": { "type": [ "string", "null" ] }, "hasMore": { "type": "boolean" } } }, "Refund": { "type": "object", "required": [ "id", "invoiceId", "amount", "currency", "status", "createdAt" ], "properties": { "id": { "type": "string", "examples": [ "rf_01J7ZK9Q2M4N6P8R0S2T4V6W8X" ] }, "invoiceId": { "type": "string", "format": "uuid" }, "amount": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Сумма в рублях строкой с двумя знаками", "examples": [ "1500.00" ] }, "currency": { "type": "string", "const": "RUB" }, "status": { "type": "string", "enum": [ "pending", "succeeded", "failed" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601, UTC" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO 8601, UTC" } } }, "Method": { "type": "object", "required": [ "code", "title", "feePct", "min", "max", "currency", "enabled" ], "properties": { "code": { "type": "string", "enum": [ "sbp", "card", "crypto" ] }, "title": { "type": "string" }, "feePct": { "type": "string", "examples": [ "4.00" ] }, "min": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Сумма в рублях строкой с двумя знаками", "examples": [ "1500.00" ] }, "max": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Сумма в рублях строкой с двумя знаками", "examples": [ "1500.00" ] }, "currency": { "type": "string", "const": "RUB" }, "enabled": { "type": "boolean" } } }, "Balance": { "type": "object", "required": [ "available", "pending", "currency" ], "properties": { "available": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Сумма в рублях строкой с двумя знаками", "examples": [ "1500.00" ] }, "pending": { "type": "string", "pattern": "^\\d+\\.\\d{2}$", "description": "Сумма в рублях строкой с двумя знаками", "examples": [ "1500.00" ] }, "currency": { "type": "string", "const": "RUB" } } }, "InvoiceEvent": { "type": "object", "required": [ "id", "event", "createdAt", "data" ], "properties": { "id": { "type": "string", "description": "Идентификатор события; совпадает с X-Paydex-Delivery-Id" }, "event": { "type": "string", "enum": [ "invoice.paid", "invoice.failed", "invoice.expired" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601, UTC" }, "data": { "type": "object", "required": [ "invoice" ], "properties": { "invoice": { "$ref": "#/components/schemas/Invoice" } } } } }, "RefundEvent": { "type": "object", "required": [ "id", "event", "createdAt", "data" ], "properties": { "id": { "type": "string" }, "event": { "type": "string", "enum": [ "refund.succeeded", "refund.failed" ] }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO 8601, UTC" }, "data": { "type": "object", "required": [ "refund", "invoice" ], "properties": { "refund": { "$ref": "#/components/schemas/Refund" }, "invoice": { "$ref": "#/components/schemas/Invoice" } } } } }, "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "enum": [ "validation", "unauthorized", "signature_invalid", "project_not_active", "invoice_not_found", "order_id_conflict", "amount_out_of_range", "method_unavailable", "provider_unavailable", "refund_exceeds_amount", "insufficient_balance", "rate_limited", "internal" ] }, "message": { "type": "string" }, "param": { "type": "string", "description": "Поле запроса, к которому относится ошибка" }, "details": { "type": "array", "items": { "type": "object" } } } } } } } } }