Данные заказов Shop Cash и сторонние интеграции

Когда клиент использует Shop Cash при оформлении заказа, Shop Cash рассматривается как способ оплаты. Это не скидка, не подарочная карта и не кредит магазина. Оставшийся баланс заказа оплачивается с помощью Shop Pay или Рассрочки Shop Pay.

Например, если клиент использует 25 USD в Shop Cash для заказа на сумму 100 USD, то заказ будет включать оплату Shop Cash на 25 USD и оплату Shop Pay на 75 USD. Данные о вашем заказе могут содержать несколько способов оплаты для одного заказа.

Shop Cash отображается как транзакция заказа со значением шлюза shop_cash (там, где доступны значения шлюза). Транзакция Shop Cash следует стандартному жизненному циклу транзакции, такому как авторизация, списание, аннулирование и возврат платежа. Shop Cash не использует комбинированный тип транзакции продажи.

Если клиент также использует предложение Shop в рамках Shop Campaigns, то сумма, финансируемая кампанией, включается в ту же транзакцию заказа shop_cash. Часть с баланса покупателя и часть, финансируемая кампанией, не отображаются как отдельные транзакции заказа. С января 2026 года затраты на кампании включаются в ваш счет Shopify, а не вычитаются из ваших выплат, поэтому транзакции счетов за кампании в истории выплат относятся только к кампаниям, которые проводились до этой даты. Дополнительные сведения см. в разделе Сборы, Shop Campaigns и Shop Cash.

Сторонние системы, которые импортируют заказы, транзакции, платежи, процессы выполнения, возвраты платежей или возвраты товаров, должны распознавать Shop Cash как способ оплаты. Если система не распознает Shop Cash, заказы с использованием Shop Cash могут не импортироваться, импортироваться с неполными платежными данными или требовать ручного сопоставления.

Изучите следующие требования вместе с поставщиком вашей сторонней системы:

• Система может поддерживать несколько способов оплаты в одном заказе.
• Система может сопоставить shop_cash как способ оплаты.
• Система не рассматривает Shop Cash как скидку, подарочную карту или кредит магазина.
• Система сохраняет идентификатор транзакции заказа для каждой авторизации, списания, аннулирования и возврата платежа Shop Cash.
• Система сохраняет полное значение авторизации Shop Cash без усечения, если это значение включено в данные, импортируемые системой.
• Система обрабатывает значения авторизации как непрозрачные строки и не анализирует, не декодирует, не нормализует, не хеширует и не извлекает из них смысл.
• Система может обрабатывать возвраты платежей, возвращающие средства как на Shop Pay, так и на Shop Cash.
• Система может выполнять сверку транзакций выплат Shop Cash отдельно от транзакций оплаты картой.
• Система не предполагает, что транзакции возвращаются в определенном порядке.

Если ваша сторонняя система предполагает, что у каждого заказа только один способ оплаты, свяжитесь с поставщиком перед обработкой заказов Shop Cash через эту систему.

Значение авторизации в транзакции Shop Cash — это непрозрачная строка переменной длины. Она не является коротким кодом авторизации карты и не предназначена для чтения человеком.

Если ваша ERP, OMS или другая сторонняя система импортирует значения авторизации Shop Cash, сохраняйте полное значение в точности так, как оно предоставлено. По возможности используйте текстовое поле переменной длины или без ограничений.

Если ваша система хранит значения авторизации Shop Cash, следуйте этим рекомендациям:

• Не усекайте значение до короткой фиксированной длины, например до 50 или 100 символов.
• Не анализируйте и не пытайтесь извлечь смысл из какой-либо части значения.
• Не используйте значение авторизации для идентификации транзакций при операциях API для списания, аннулирования или возврата платежа.

Усеченные значения авторизации могут привести к сбою стороннего импорта или последующей обработки в ERP и OMS.

Для поддержки списаний, аннулирований и возвратов платежей через Admin API сохраняйте идентификаторы транзакций заказа и связи с родительскими транзакциями. Операции списания и аннулирования в Admin API идентифицируют транзакцию авторизации с помощью parentTransactionId. Операции возврата платежа идентифицируют транзакцию списания, подлежащую возврату, с помощью parentId.

Если приложение или интеграция выполняет возврат платежа Shop Cash через API, этот возврат должен быть привязан к транзакции списания Shop Cash, а не к транзакции авторизации. Возвраты платежей, привязанные к транзакции авторизации, отклоняются.

Приложения для возврата платежей и обработчики вебхуков должны определять транзакцию списания Shop Cash, подлежащую возврату, рассчитывать оставшуюся сумму для возврата по этому списанию и создавать возврат платежа с использованием идентификатора транзакции списания.

При использовании Admin API, экспорта заказов, экспорта выплат или экспорта сторонних приложений относитесь к Shop Cash как к платежным данным. В зависимости от используемого экспорта или ресурса API, информация о Shop Cash может быть представлена через способ оплаты, шлюз, транзакцию заказа, транзакцию выплаты и данные возврата платежа.

При создании или обновлении интеграции сохраняйте следующую информацию для заказов, включающих Shop Cash:

• ID заказа и название заказа.
• Способ оплаты или значение шлюза, например shop_cash, если доступно.
• ID транзакций заказа для каждой платежной транзакции.
• Тип и статус транзакции, такие как авторизация, списание, возврат платежа или аннулирование.
• Сумма и валюта транзакции.
• Связи с родительской транзакцией, если они доступны.
• ID платежей, если они доступны.
• Полные значения авторизации, если ваша система их импортирует.
• ID выплат и ID транзакций баланса при сверке выплат.
• ID транзакций возврата платежа при сверке возвратов.

Для получения подробной информации о доступных полях Admin API обратитесь к документации разработчика по транзакциям заказов Admin API. Не полагайтесь на устаревшие поля, такие как OrderTransaction.authorizationCode, для новых интеграций.

В следующем упрощенном примере показан заказ на 100 USD, 75 USD из которых оплачены через Shopify Payments, а 25 USD — через Shop Cash. Значения приведены только для примера.

{
  "transactions": [
    {
      "kind": "authorization",
      "gateway": "shopify_payments",
      "status": "success",
      "amount": "75.00",
      "currency": "USD",
      "parent_id": null,
      "authorization": "ch_3OabcXYZ..."
    },
    {
      "kind": "authorization",
      "gateway": "shop_cash",
      "status": "success",
      "amount": "25.00",
      "currency": "USD",
      "parent_id": null,
      "authorization": "<long-opaque-variable-length-string>"
    },
    {
      "kind": "capture",
      "gateway": "shop_cash",
      "status": "success",
      "amount": "25.00",
      "currency": "USD",
      "parent_id": "<shop-cash-authorization-transaction-id>",
      "authorization": null
    }
  ]
}

Shop Cash может выглядеть похоже на другие платежные или рекламные значения, но ваши системы должны обрабатывать каждое значение отдельно:

Прежде чем использовать стороннюю систему для заказов, включающих Shop Cash, подтвердите соответствие следующим требованиям:

• Shop Cash сопоставлен как способ оплаты.
• Заказы с Shop Cash и Shop Pay импортируются с обоими способами оплаты.
• Логика способов оплаты не предполагает использование только одного способа оплаты на заказ.
• Значения авторизации хранятся как длинные непрозрачные строки и не усекаются.
• Логика возврата платежей может вернуть средства по правильной транзакции списания.
• Логика возврата платежей может вернуть средства на правильные способы оплаты.
• При сверке выплат могут учитываться такие типы транзакций Shop Cash, как кредит, возврат платежа и кампания.
• Рабочие процессы выполнения заказов, учета и возвратов не обрабатывают Shop Cash как скидку.

Если вы используете несколько систем, выполните эту проверку для каждой системы, получающей данные о заказах, транзакциях, выплатах, выполнении заказов, возвратах платежей или возвратах.