Dane zamówień Shop Cash i integracje z systemami zewnętrznymi

Gdy klient wykorzystuje Shop Cash w zamówieniu, Shop Cash jest traktowane jako metoda płatności. Nie jest to rabat, karta prezentowa ani kredyty sklepowe. Pozostałe saldo zamówienia jest opłacane za pomocą Shop Pay lub opcji Raty Shop Pay.

Na przykład, jeśli klient wykorzysta 25 USD w postaci Shop Cash w zamówieniu na kwotę 100 USD, to zamówienie będzie obejmować płatność Shop Cash w wysokości 25 USD oraz płatność Shop Pay w wysokości 75 USD. Dane zamówienia mogą zawierać więcej niż jedną metodę płatności dla tego samego zamówienia.

Shop Cash pojawia się jako transakcja zamówienia z bramką o wartości shop_cash tam, gdzie dostępne są wartości bramek. Transakcja Shop Cash podlega standardowemu cyklowi życia transakcji, obejmującemu autoryzację, przechwycenie, unieważnienie i zwrot kosztów. Shop Cash nie używa połączonego rodzaju transakcji sprzedaży.

Jeśli klient skorzysta również z oferty Shop w ramach Shop Campaign, wartość sfinansowana z kampanii zostanie uwzględniona w tej samej kwocie transakcji zamówienia shop_cash. Części pochodzące z salda kupującego i sfinansowane z kampanii nie są przedstawiane jako osobne transakcje zamówienia. Od stycznia 2026 r. koszty kampanii obciążają Twój rachunek Shopify, a nie są potrącane z Twoich wypłat, dlatego transakcje rozliczeniowe kampanii w aktywności dotyczącej wypłat mają zastosowanie tylko do kampanii przeprowadzonych przed tą datą. Aby uzyskać więcej informacji, zapoznaj się z sekcją Opłaty, Shop Campaigns i Shop Cash.

Systemy zewnętrzne, które importują zamówienia, transakcje, płatności, realizacje, zwroty kosztów lub zwroty, muszą rozpoznawać Shop Cash jako metodę płatności. Jeśli system nie rozpozna Shop Cash, zamówienia obejmujące Shop Cash mogą nie zostać zaimportowane, mogą zostać zaimportowane z niekompletnymi danymi płatności lub mogą wymagać ręcznego mapowania.

Skonsultuj z dostawcą swojego systemu zewnętrznego następujące wymagania:

• System może obsługiwać więcej niż jedną metodę płatności w jednym zamówieniu.
• System może zmapować shop_cash jako metodę płatności.
• System nie traktuje Shop Cash jako rabatu, karty prezentowej ani kredytów sklepowych.
• System przechowuje ID transakcji zamówienia dla każdej autoryzacji, przechwycenia, unieważnienia i zwrotu kosztów w Shop Cash.
• System przechowuje pełną wartość autoryzacji Shop Cash bez jej obcinania, jeśli wartość ta jest zawarta w danych importowanych przez system.
• System traktuje wartości autoryzacji jako nieprzejrzyste ciągi znaków i nie parsuje ich, nie dekoduje, nie normalizuje, nie haszuje ani nie przypisuje im znaczenia.
• System potrafi przetwarzać zwroty kosztów, które zwracają środki zarówno na Shop Pay, jak i na Shop Cash.
• System potrafi uzgadniać transakcje wypłat Shop Cash niezależnie od transakcji płatności kartą.
• System nie zakłada, że transakcje są zwracane w określonej kolejności.

Jeśli Twój system zewnętrzny zakłada, że każde zamówienie ma tylko jedną metodę płatności, skontaktuj się z dostawcą przed przetworzeniem zamówień Shop Cash w tym systemie.

Wartość autoryzacji w transakcji Shop Cash to nieprzejrzysty ciąg znaków o zmiennej długości. Nie jest to krótki kod autoryzacyjny karty ani nie jest czytelny dla człowieka.

Jeśli Twój system ERP, OMS lub inny system zewnętrzny importuje wartości autoryzacji Shop Cash, przechowuj pełną wartość dokładnie w takiej formie, w jakiej została podana. W miarę możliwości używaj pola tekstowego o zmiennej długości lub pola nieograniczonego.

Gdy Twój system przechowuje wartości autoryzacji Shop Cash, postępuj zgodnie z poniższymi wytycznymi:

• Nie obcinaj wartości do krótkiej, stałej długości, takiej jak 50 lub 100 znaków.
• Nie parsuj ani nie przypisuj znaczenia żadnej części tej wartości.
• Nie używaj wartości autoryzacji do identyfikacji transakcji w operacjach API przechwytywania, unieważniania ani zwrotu kosztów.

Obcięte wartości autoryzacji mogą spowodować niepowodzenie importu z systemów zewnętrznych lub dalszego przetwarzania w systemach ERP i OMS.

Aby obsługiwać przechwycenia, unieważnienia i zwroty kosztów za pośrednictwem Admin API, przechowuj ID transakcji zamówień oraz relacje z transakcjami nadrzędnymi. Operacje przechwytywania i unieważniania w Admin API identyfikują transakcję autoryzacyjną za pomocą parametru parentTransactionId. Operacje zwrotu kosztów identyfikują podlegającą zwrotowi kosztów transakcję przechwycenia za pomocą parametru parentId.

Gdy aplikacja lub integracja zleca zwrot kosztów Shop Cash przez API, zwrot ten musi być powiązany z transakcją przechwycenia Shop Cash jako transakcją nadrzędną, a nie z transakcją autoryzacji Shop Cash. Zwroty kosztów odnoszące się do transakcji autoryzacji są odrzucane.

Aplikacje do zwrotów kosztów i procedury obsługi elementów webhook powinny zidentyfikować podlegającą zwrotowi kosztów transakcję przechwycenia Shop Cash, obliczyć pozostałą kwotę podlegającą zwrotowi dla tego przechwycenia i utworzyć zwrot kosztów w odniesieniu do ID transakcji przechwycenia.

Kiedy korzystasz z Admin API, eksportów zamówień, eksportów wypłat lub eksportów do aplikacji firmy zewnętrznej, traktuj Shop Cash jako dane płatności. W zależności od używanego eksportu lub zasobu API informacje o Shop Cash mogą być reprezentowane przez dane metody płatności, bramki, transakcji zamówienia, transakcji wypłaty i zwrotu kosztów.

Podczas tworzenia lub uaktualniania integracji przechowuj następujące informacje dla zamówień obejmujących Shop Cash:

• ID zamówienia i nazwa zamówienia.
• Metoda płatności lub wartość bramki, np. shop_cash (tam, gdzie jest to dostępne).
• ID transakcji zamówienia dla każdej transakcji płatniczej.
• Rodzaj i status transakcji, takie jak autoryzacja, przechwycenie, zwrot kosztów lub unieważnienie.
• Kwota i waluta transakcji.
• Powiązania z transakcjami nadrzędnymi, jeśli są dostępne.
• ID płatności (jeśli są dostępne).
• Pełne wartości autoryzacji, jeśli system je importuje.
• ID wypłat i ID transakcji salda podczas uzgadniania wypłat.
• ID transakcji zwrotów kosztów podczas uzgadniania zwrotów.

Aby uzyskać szczegółowe informacje na temat dostępnych pól Admin API, zapoznaj się z dokumentacją dla programistów w sekcji Admin API order transaction. W nowych integracjach unikaj opierania się na przestarzałych polach, takich jak OrderTransaction.authorizationCode.

Poniższy uproszczony przykład przedstawia zamówienie na kwotę 100 USD opłacone kwotą 75 USD przez usługę Shopify Payments oraz kwotą 25 USD przez Shop Cash. Wartości mają charakter wyłącznie poglądowy.

{
  "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 może wyglądać podobnie do innych wartości płatności lub promocji, ale systemy powinny traktować każdą z nich osobno:

Zanim użyjesz systemu firmy zewnętrznej do zamówień obejmujących Shop Cash, potwierdź spełnienie poniższych wymagań:

• Shop Cash jest zmapowane jako metoda płatności.
• Zamówienia z Shop Cash i Shop Pay są importowane z obiema metodami płatności.
• Logika metod płatności nie zakłada jednej metody płatności na zamówienie.
• Wartości autoryzacji są przechowywane jako długie, nieprzezroczyste ciągi znaków i nie są skracane.
• Logika zwrotów potrafi dokonać zwrotu kosztów dla właściwej transakcji przechwycenia.
• Logika zwrotów potrafi zwrócić środki na właściwe metody płatności.
• Uzgodnienie wypłat potrafi uwzględnić rodzaje transakcji uznania z Shop Cash, zwrotów kosztów i kampanii.
• Przepływy pracy w zakresie realizacji, księgowości i zwrotów nie traktują Shop Cash jako rabatu.

Jeśli korzystasz z wielu systemów, przeprowadź ten przegląd dla każdego systemu, który odbiera dane dotyczące zamówień, transakcji, wypłat, realizacji, zwrotów kosztów lub zwrotów towaru.