Платежи

Попытки оплаты заказов и их исход. Здесь подтверждаются ручные платежи, ждущие денег.

Загружаем поисковый индекс…

Платежи

Объекты

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_deletedboolean

    true — отдавать и удалённые записи: архивные с заполненным deleted_at и стёртые из базы — отметками об удалении {id, deleted_at} в продолжении по курсору синхронизации. Включайте для синхронизации.

  • order_idinteger

    Только записи этого заказа.

    Минимум:
    1
  • pos_shift_idinteger

    Только записи, принятые этой кассовой сменой.

    Минимум:
    1

Ответы

200Успешно

application/json

  • dataмассив Paymentобязательно

    Записи страницы.

  • 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"
Пример ответа · 200
{
  "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"
Пример ответа · 200
{
  "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-Replayedstring

    true, когда это сохранённый ответ более раннего запроса с тем же 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

Отказы метода

Общие отказы — токен, доступ, проверка входа, лимит запросов — может вернуть любой метод, они собраны в каталоге: Ошибки

Пример запроса
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
Тело запроса — body.json
{
  "comment": "string"
}
Пример ответа · 200
{
  "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"
}