Платежи
Попытки оплаты заказов и их исход. Здесь подтверждаются ручные платежи, ждущие денег.
Платежи
Объекты
Payment
idintegerобязательноID записи, уникальный среди записей своего вида в магазине.
order_idintegerобязательноID заказа.
pos_shift_idinteger или nullобязательноID кассовой смены (/v1/pos-shifts), принявшей деньги: по нему Z-отчёт относит платёж к смене. null — платёж не кассы.
legal_entity_idinteger или nullобязательноЮрлицо, получающее деньги (/v1/legal-entities), — юрлицо заказа; null — продажа не распределена между юрлицами, деньги получает юрлицо магазина по умолчанию.
methodstringобязательноСпособ оплаты. manual — ручной способ магазина (manual_payment_method_id); balance — баланс покупателя; on_account — в долг, сумму должен покупатель; gift_card — подарочная карта; остальные значения называют платёжного провайдера или вид оплаты.
- Значения:
cashmercadopagocryptobybittrc20balancemodopaywaymercadopago_qrmercadopago_pointmercadopago_transfergift_cardsubscriptiondepositexternalmanualoffseton_accountexchange_creditbonpuntoservice_package
manual_payment_method_idinteger или nullобязательноРучной способ оплаты магазина (/v1/manual-payment-methods), когда method — manual; иначе null.
statusstringобязательноpending — ждёт денег; processing — провайдер обрабатывает; succeeded — оплачен; failed — не прошёл; partially_refunded — частично возвращён; refunded — возвращён; expired — ссылка на оплату истекла; voided — отменён до прихода денег.
- Значения:
pendingprocessingsucceededfailedpartially_refundedrefundedexpiredvoided
currencystringобязательноВалюта сумм, код ISO 4217: валюта магазина.
amountintegerобязательноСумма к оплате по этому платежу.
received_amountinteger или nullобязательноФактически получено; null, пока деньги не пришли. Получено по заказу — сумма received_amount минус refunded_amount его платежей.
refunded_amountintegerобязательноВозвращено из полученного.
tip_amountintegerобязательноЧаевые сверх суммы заказа.
refunded_tip_amountintegerобязательноВозвращено из чаевых.
surcharge_amountintegerобязательноНадбавка за оплату в рассрочку сверх суммы заказа.
refunded_surcharge_amountintegerобязательноВозвращено из надбавки.
provider_fee_amountinteger или nullобязательноКомиссия платёжного провайдера, которую он списал из платежа до зачисления магазину. null — провайдер начислений не сообщает: наличные, ручной способ, платёж, деньги по которому не списаны.
refunded_provider_fee_amountinteger или nullобязательноДоля комиссии, которую провайдер вернул при возврате покупателю, — по его данным, а не пропорцией от refunded_amount: возврат мимо провайдера комиссию не возвращает.
provider_withheld_tax_amountinteger или nullобязательноНалог, который провайдер удержал из платежа как налоговый агент (у MercadoPago — Ingresos Brutos). Удержание с его юрисдикцией — в налоговом реестре магазина.
refunded_provider_withheld_tax_amountinteger или nullобязательноДоля удержанного налога, которую провайдер вернул.
tenderobject или nullобязательноОплата в валюте, отличной от валюты магазина: счёт в USDT, перевод в долларах, наличные в чужой валюте. null — платёж в валюте магазина. Суммы платежа (amount и остальные) остаются в валюте магазина, учёт ведётся по ним.
Поля · 5
currencystringобязательноВалюта способа оплаты: код ISO 4217 или код криптоактива, например USDT.
amountstringобязательноСумма счёта в валюте способа, десятичной строкой: покрывает amount вместе с чаевыми и надбавкой. Произведение на курс может не сойтись с amount на округлении и на части счёта, выставленной в валюте способа прямо из прайса.
received_amountstring или nullобязательноПолучено в валюте способа, десятичной строкой; null — полученное ведётся только в валюте магазина (received_amount) либо пришла другая монета (received_asset).
tendered_amountstring или nullобязательноНаличные в чужой валюте: сколько купюр дали, десятичной строкой. Сдачу выдают в валюте магазина. null у остальных способов.
exchange_rateobject или nullобязательноКурс, по которому сумма в валюте способа стала суммой платежа, — снимок на момент выставления; null, если курса нет.
Поля · 6
ratestringобязательноКурс десятичной строкой: 1 единица валюты способа = rate единиц валюты магазина.
modestring или nullобязательноКак получен курс: auto — рыночный курс источника с надбавкой магазина; fixed — курс задан магазином; pegged — магазин привязал валюту способа к другой валюте (peg), и курс — её курс, умноженный на коэффициент привязки. null у счетов, выставленных до правил курса.
- Значения:
autofixedpeggednull
sourcestring или nullобязательноИсточник рыночного курса: coingecko — агрегированная цена CoinGecko; criptoya_p2p — медиана P2P-площадок; ar_oficial, ar_blue, ar_mep, ar_ccl, ar_mayorista — курсы доллара в Аргентине; cbr — Банк России. null, если источник не записан.
- Значения:
coingeckocriptoya_p2par_oficialar_bluear_mepar_cclar_mayoristacbrnull
basestring или nullобязательноРыночный курс источника до надбавки магазина, десятичной строкой; null, если рыночной базы нет.
markup_bpsinteger или nullобязательноНадбавка магазина к рыночному курсу в базисных пунктах (100 — это 1 %), бывает отрицательной. null у курса, заданного магазином, и у счетов до правил курса.
pegobject или nullобязательноПривязка валюты способа к другой валюте: 1 единица валюты способа = peg.rate единиц peg.currency (например, 1 USDT = 1 USD). Цены, назначенные в этой валюте, входят в счёт как есть. null, если курс не привязан.
Поля · 2
currencystringобязательноВалюта, к которой привязана валюта способа (ISO 4217).
ratestringобязательноКоэффициент привязки десятичной строкой: сколько единиц peg.currency стоит единица валюты способа.
received_assetobject или nullобязательноМонета, которая пришла на самом деле, когда покупатель перевёл не то, что в счёте, и её оценили отдельно; null — пришло выставленное.
Поля · 6
assetstringобязательноКод монеты, например USDC.
amountstringобязательноСколько монет пришло, десятичной строкой.
ratestringобязательноКурс зачёта десятичной строкой: 1 монета = rate единиц валюты магазина.
rate_sourcestring или nullобязательноИсточник курса зачёта; manual — курс задан вручную.
rate_as_ofstring или nullобязательноМомент котировки или версии ручного курса.
tx_idstring или nullобязательноID перевода в блокчейне или на бирже — для сверки.
provider_payment_idstring или nullобязательноID операции у платёжного провайдера — для сверки с его выпиской; null, если провайдера нет.
payment_urlstring или nullобязательноСтраница оплаты у провайдера, пока платёж ждёт денег: ссылку можно отправить покупателю. null у оплаченного или отменённого платежа и у ручного способа.
confirmablebooleanобязательноПлатёж можно подтвердить вручную сейчас (POST /v1/payments/{payment}/confirm): он ждёт денег, приход которых подтверждает человек, а не провайдер.
replaces_payment_idinteger или nullобязательноПлатёж, который этот заменил при исправлении способа оплаты; иначе null.
confirmed_atstring (date-time) или nullобязательноКогда деньги получены; null, пока не получены.
created_atstring (date-time)обязательноКогда запись создана.
updated_atstring (date-time)обязательноКогда запись менялась последний раз.
Методы
Платежи по заказам, изменённые с указанного момента
get/payments
Scope: payments:read
Параметры
Строка запроса
limitintegerРазмер страницы: до 250 записей; по умолчанию 50.
- Минимум:
- 1
- Максимум:
- 250
cursorstringНепрозрачный курсор: next_cursor предыдущей страницы или sync_cursor последней страницы, сохранённый прошлой синхронизацией. Список идёт в порядке коммитов, поэтому курсор синхронизации позже отдаёт только изменённое после него.
- Макс. длина:
- 4096
updated_sincestring (date-time)Только записи, изменённые после этого момента, ISO 8601 с часовым поясом. Фильтр первой синхронизации; дальше — курсор.
- Шаблон:
^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,6})?(Z|[+-]\d{2}:\d{2})$
include_deletedbooleantrue — отдавать и удалённые записи: архивные с заполненным deleted_at и стёртые из базы — отметками об удалении {id, deleted_at} в продолжении по курсору синхронизации. Включайте для синхронизации.
order_idintegerТолько записи этого заказа.
- Минимум:
- 1
pos_shift_idintegerТолько записи, принятые этой кассовой сменой.
- Минимум:
- 1
Ответы
200Успешно
application/json
Записи страницы.
deletedмассив objectобязательноЗаписи, стёртые из базы с момента курсора, отметками об удалении: только с include_deleted=true в продолжении по курсору синхронизации.
Поля · 2
idintegerобязательноID стёртой записи.
deleted_atstring (date-time)обязательноКогда запись стёрта.
next_cursorstring или nullобязательноКурсор следующей страницы; null на последней.
has_morebooleanобязательноtrue, если есть следующая страница.
sync_cursorstring или nullобязательноНа последней странице — курсор, с которого продолжить позже: по нему придёт только изменённое после этой страницы. null на остальных.
401Токена нет, он неверен, истёк или отозван
Заголовки
WWW-AuthenticatestringобязательноСхема аутентификации (RFC 6750).
- Пример:
Bearer
application/problem+json
Возвращает Problem
403Запрос не разрешают тариф, IP-адрес или scopes токена
Заголовки
WWW-AuthenticatestringСхема аутентификации (RFC 6750).
- Пример:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Возвращает ForbiddenProblem
410Курсор синхронизации старше срока хранения удалений или выдан до восстановления базы
application/problem+json
Возвращает Problem
422Параметр неверен или неизвестен
application/problem+json
Возвращает ValidationProblem
429Лимит запросов исчерпан
Заголовки
Retry-AfterintegerобязательноСколько секунд подождать перед повтором.
- Минимум:
- 0
application/problem+json
Возвращает RateLimitProblem
503Магазин временно недоступен
Заголовки
Retry-AfterintegerСколько секунд подождать перед повтором.
- Минимум:
- 0
application/problem+json
Возвращает Problem
Отказы метода
Общие отказы — токен, доступ, проверка входа, лимит запросов — может вернуть любой метод, они собраны в каталоге: Ошибки
curl "https://api.saleya.app/v1/payments" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"data": [
{
"id": 0,
"order_id": 0,
"pos_shift_id": 0,
"legal_entity_id": 0,
"method": "cash",
"manual_payment_method_id": 0,
"status": "pending",
"currency": "string",
"amount": 0,
"received_amount": 0,
"refunded_amount": 0,
"tip_amount": 0,
"refunded_tip_amount": 0,
"surcharge_amount": 0,
"refunded_surcharge_amount": 0,
"provider_fee_amount": 0,
"refunded_provider_fee_amount": 0,
"provider_withheld_tax_amount": 0,
"refunded_provider_withheld_tax_amount": 0,
"tender": {
"currency": "string",
"amount": "string",
"received_amount": "string",
"tendered_amount": "string",
"exchange_rate": {
"rate": "string",
"mode": "auto",
"source": "coingecko",
"base": "string",
"markup_bps": 0,
"peg": {
"currency": "string",
"rate": "string"
}
}
},
"received_asset": {
"asset": "string",
"amount": "string",
"rate": "string",
"rate_source": "string",
"rate_as_of": "string",
"tx_id": "string"
},
"provider_payment_id": "string",
"payment_url": "string",
"confirmable": true,
"replaces_payment_id": 0,
"confirmed_at": "2026-01-15T12:00:00Z",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}
],
"deleted": [
{
"id": 0,
"deleted_at": "2026-01-15T12:00:00Z"
}
],
"next_cursor": "string",
"has_more": true,
"sync_cursor": "string"
}Платёж по заказу
get/payments/{payment}
Scope: payments:read
Параметры
Путь
paymentintegerобязательноID платежа.
Ответы
200Успешно
application/json
Возвращает Payment
401Токена нет, он неверен, истёк или отозван
Заголовки
WWW-AuthenticatestringобязательноСхема аутентификации (RFC 6750).
- Пример:
Bearer
application/problem+json
Возвращает Problem
403Запрос не разрешают тариф, IP-адрес или scopes токена
Заголовки
WWW-AuthenticatestringСхема аутентификации (RFC 6750).
- Пример:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Возвращает ForbiddenProblem
404Объекта нет или он недоступен приложению
application/problem+json
Возвращает Problem
422Параметр неверен или неизвестен
application/problem+json
Возвращает ValidationProblem
429Лимит запросов исчерпан
Заголовки
Retry-AfterintegerобязательноСколько секунд подождать перед повтором.
- Минимум:
- 0
application/problem+json
Возвращает RateLimitProblem
503Магазин временно недоступен
Заголовки
Retry-AfterintegerСколько секунд подождать перед повтором.
- Минимум:
- 0
application/problem+json
Возвращает Problem
Общие отказы — токен, доступ, проверка входа, лимит запросов — может вернуть любой метод, они собраны в каталоге: Ошибки
curl "https://api.saleya.app/v1/payments/{payment}" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"{
"id": 0,
"order_id": 0,
"pos_shift_id": 0,
"legal_entity_id": 0,
"method": "cash",
"manual_payment_method_id": 0,
"status": "pending",
"currency": "string",
"amount": 0,
"received_amount": 0,
"refunded_amount": 0,
"tip_amount": 0,
"refunded_tip_amount": 0,
"surcharge_amount": 0,
"refunded_surcharge_amount": 0,
"provider_fee_amount": 0,
"refunded_provider_fee_amount": 0,
"provider_withheld_tax_amount": 0,
"refunded_provider_withheld_tax_amount": 0,
"tender": {
"currency": "string",
"amount": "string",
"received_amount": "string",
"tendered_amount": "string",
"exchange_rate": {
"rate": "string",
"mode": "auto",
"source": "coingecko",
"base": "string",
"markup_bps": 0,
"peg": {
"currency": "string",
"rate": "string"
}
}
},
"received_asset": {
"asset": "string",
"amount": "string",
"rate": "string",
"rate_source": "string",
"rate_as_of": "string",
"tx_id": "string"
},
"provider_payment_id": "string",
"payment_url": "string",
"confirmable": true,
"replaces_payment_id": 0,
"confirmed_at": "2026-01-15T12:00:00Z",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}Подтвердить, что деньги по ожидающему счёту получены
post/payments/{payment}/confirm
Scope: payments:write
Параметры
Путь
paymentintegerобязательноID платежа.
Заголовок
Idempotency-KeystringУникальный ключ попытки, например UUID. Повтор с тем же ключом и телом получает сохранённый ответ вместо второй записи. Ключ живёт 24 часа.
- Мин. длина:
- 1
- Макс. длина:
- 255
- Пример:
8e03978e-40d5-43e8-bc93-6894a57f9324
Тело запроса application/json
commentstring или nullКомментарий к подтверждению, остаётся в истории заказа.
- Макс. длина:
- 500
Ответы
200Успешно
Заголовки
Idempotent-Replayedstringtrue, когда это сохранённый ответ более раннего запроса с тем же Idempotency-Key.
- Значения:
true
application/json
Возвращает Payment
401Токена нет, он неверен, истёк или отозван
Заголовки
WWW-AuthenticatestringобязательноСхема аутентификации (RFC 6750).
- Пример:
Bearer
application/problem+json
Возвращает Problem
403Запрос не разрешают тариф, IP-адрес или scopes токена
Заголовки
WWW-AuthenticatestringСхема аутентификации (RFC 6750).
- Пример:
Bearer error="insufficient_scope", scope="locations:read"
application/problem+json
Возвращает ForbiddenProblem
404Объекта нет или он недоступен приложению
application/problem+json
Возвращает Problem
409Запрос с тем же ключом идемпотентности ещё исполняется, данные изменились после чтения, внешний id у другой записи, исчерпан лимит тарифа или адресов вебхуков, или правке нужно согласие на последствия
Заголовки
Retry-AfterintegerСколько секунд подождать перед повтором.
- Минимум:
- 0
application/problem+json
Возвращает ConflictProblem
422Параметр неверен или неизвестен
application/problem+json
Возвращает ValidationProblem
429Лимит запросов исчерпан
Заголовки
Retry-AfterintegerобязательноСколько секунд подождать перед повтором.
- Минимум:
- 0
application/problem+json
Возвращает RateLimitProblem
503Магазин временно недоступен
Заголовки
Retry-AfterintegerСколько секунд подождать перед повтором.
- Минимум:
- 0
application/problem+json
Возвращает Problem
Отказы метода
- 409
idempotency_key_in_useЗапрос с этим ключом ещё исполняется - 409
payment_not_confirmableПлатёж нельзя подтвердить - 422
idempotency_key_reusedКлюч идемпотентности уже использован - 422
invalid_idempotency_keyКлюч идемпотентности неверен
Общие отказы — токен, доступ, проверка входа, лимит запросов — может вернуть любой метод, они собраны в каталоге: Ошибки
curl -X POST "https://api.saleya.app/v1/payments/{payment}/confirm" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H "Content-Type: application/json" \
-d @body.json{
"comment": "string"
}{
"id": 0,
"order_id": 0,
"pos_shift_id": 0,
"legal_entity_id": 0,
"method": "cash",
"manual_payment_method_id": 0,
"status": "pending",
"currency": "string",
"amount": 0,
"received_amount": 0,
"refunded_amount": 0,
"tip_amount": 0,
"refunded_tip_amount": 0,
"surcharge_amount": 0,
"refunded_surcharge_amount": 0,
"provider_fee_amount": 0,
"refunded_provider_fee_amount": 0,
"provider_withheld_tax_amount": 0,
"refunded_provider_withheld_tax_amount": 0,
"tender": {
"currency": "string",
"amount": "string",
"received_amount": "string",
"tendered_amount": "string",
"exchange_rate": {
"rate": "string",
"mode": "auto",
"source": "coingecko",
"base": "string",
"markup_bps": 0,
"peg": {
"currency": "string",
"rate": "string"
}
}
},
"received_asset": {
"asset": "string",
"amount": "string",
"rate": "string",
"rate_source": "string",
"rate_as_of": "string",
"tx_id": "string"
},
"provider_payment_id": "string",
"payment_url": "string",
"confirmable": true,
"replaces_payment_id": 0,
"confirmed_at": "2026-01-15T12:00:00Z",
"created_at": "2026-01-15T12:00:00Z",
"updated_at": "2026-01-15T12:00:00Z"
}