Datele comenzilor cu Shop Cash și integrările cu aplicații terțe

Când un client folosește Shop Cash pentru o comandă, Shop Cash este tratat ca metodă de plată. Nu este o reducere, un card cadou sau un credit magazin. Orice sold rămas al comenzii este plătit cu Shop Pay sau cu Plăți în rate cu Shop Pay.

De exemplu, dacă un client folosește 25 USD sub formă de Shop Cash pentru o comandă de 100 USD, atunci comanda include o plată Shop Cash de 25 USD și o plată Shop Pay de 75 USD. Datele comenzii dvs. pot include mai mult de o metodă de plată pentru aceeași comandă.

Shop Cash apare ca tranzacție a comenzii cu valoarea gateway-ului shop_cash acolo unde valorile gateway-ului sunt disponibile. Tranzacția Shop Cash urmează ciclul de viață standard al tranzacției, cum ar fi autorizarea, capturarea, anularea și restituirea. Shop Cash nu folosește un tip combinat de tranzacție de vânzare.

Dacă clientul folosește și o ofertă Shop dintr-o campanie Shop, atunci valoarea finanțată din campanie este inclusă în aceeași sumă a tranzacției comenzii shop_cash. Părțile din soldul cumpărătorului și cele finanțate din campanie nu sunt reprezentate ca tranzacții separate ale comenzii. Începând cu ianuarie 2026, costurile campaniei sunt prelevate de pe factura dvs. Shopify, în loc să fie deduse din primirile de plăți, astfel încât tranzacțiile de facturare a campaniei în activitatea de primire a plăților se aplică doar campaniilor care s-au desfășurat înainte de această dată. Pentru mai multe informații, consultați Taxe, Shop Campaigns și Shop Cash.

Sistemele terțe care importă comenzi, tranzacții, plăți, onorări ale comenzilor, restituiri sau retururi trebuie să recunoască Shop Cash ca metodă de plată. Dacă un sistem nu recunoaște Shop Cash, atunci comenzile care includ Shop Cash pot eșua la import, pot fi importate cu date de plată incomplete sau pot necesita cartografiere manuală.

Examinați următoarele cerințe împreună cu furnizorul sistemului terț:

• Sistemul poate accepta mai mult de o metodă de plată pentru o singură comandă.
• Sistemul poate asocia shop_cash ca metodă de plată.
• Sistemul nu tratează Shop Cash ca pe o reducere, ca pe un card cadou sau ca pe un credit magazin.
• Sistemul stochează ID-ul tranzacției comenzii pentru fiecare autorizare, capturare, anulare și restituire Shop Cash.
• Sistemul stochează valoarea completă de autorizare Shop Cash, fără a o trunchia, dacă valoarea este inclusă în datele pe care sistemul le importă.
• Sistemul tratează valorile de autorizare drept șiruri opace și nu le parsează, decodifică, normalizează, nu le convertește în hash-uri și nu deduce vreo semnificație din ele.
• Sistemul poate procesa restituirile care returnează fonduri atât către Shop Pay, cât și către Shop Cash.
• Sistemul poate reconcilia tranzacțiile de primire a plăților Shop Cash separat de tranzacțiile de plată cu cardul.
• Sistemul nu presupune că tranzacțiile sunt returnate într-o anumită ordine.

Dacă sistemul dvs. terț presupune că fiecare comandă are o singură metodă de plată, contactați furnizorul înainte de a procesa comenzile cu Shop Cash prin acel sistem.

Valoarea de autorizare a unei tranzacții Shop Cash este un șir opac, de lungime variabilă. Nu este un cod scurt de autorizare a cardului și nu poate fi citit de oameni.

Dacă sistemul dvs. ERP, OMS sau alt sistem terț importă valorile de autorizare Shop Cash, stocați valoarea completă exact așa cum este furnizată. Folosiți un câmp de text cu lungime variabilă sau nelimitată atunci când este posibil.

Atunci când sistemul dvs. stochează valorile de autorizare Shop Cash, urmați aceste îndrumări:

• Nu trunchiați valoarea la o lungime fixă scurtă, cum ar fi 50 sau 100 de caractere.
• Nu parsați și nu deduceți vreo semnificație din nicio parte a valorii.
• Nu folosiți valoarea de autorizare pentru a identifica tranzacțiile pentru operațiunile API de capturare, anulare sau restituire.

Valorile de autorizare trunchiate pot cauza eșuarea importurilor de la terți sau a procesării ulterioare în ERP și OMS.

Pentru a accepta capturările, anulările și restituirile prin Admin API, stocați ID-urile tranzacțiilor comenzii și relațiile cu tranzacțiile părinte. Operațiunile de capturare și anulare prin Admin API identifică tranzacția de autorizare prin intermediul parametrului parentTransactionId. Operațiunile de restituire identifică tranzacția de capturare rambursabilă prin intermediul parametrului parentId.

Când o aplicație sau integrare emite o restituire Shop Cash prin intermediul API, restituirea trebuie să fie subordonată tranzacției de capturare Shop Cash, nu tranzacției de autorizare Shop Cash. Restituirile asociate tranzacției de autorizare sunt respinse.

Aplicațiile de restituire și rutinele de tratare webhook ar trebui să identifice tranzacția de capturare Shop Cash rambursabilă, să calculeze suma rămasă rambursabilă pentru acea capturare și să creeze restituirea pe baza ID-ului tranzacției de capturare.

Când utilizați Admin API, exporturile comenzilor, exporturile primirilor de plăți sau exporturile din aplicații terțe, tratați Shop Cash ca date de plată. În funcție de resursa API sau de exportul pe care îl utilizați, informațiile Shop Cash pot fi reprezentate prin date despre metoda de plată, gateway, tranzacția comenzii, tranzacția primirii de plăți și restituire.

Când construiți sau actualizați o integrare, stocați următoarele informații pentru comenzile care includ Shop Cash:

• ID comandă și numele comenzii.
• Metoda de plată sau valoarea gateway, cum ar fi shop_cash acolo unde este disponibilă.
• ID-uri pentru tranzacțiile comenzii pentru fiecare tranzacție de plată.
• Tipul și starea tranzacției, cum ar fi autorizare, captare, restituire sau anulare.
• Suma și moneda tranzacției.
• Relațiile cu tranzacția părinte, atunci când sunt disponibile.
• ID-urile de plată, acolo unde sunt disponibile.
• Valorile complete de autorizare, dacă sistemul dumneavoastră le importă.
• ID-urile primirilor de plăți și ID-urile tranzacțiilor din sold atunci când reconciliați primirile de plăți.
• ID-urile tranzacțiilor de restituire atunci când reconciliați retururile.

Pentru detalii despre câmpurile Admin API disponibile, consultați documentația pentru dezvoltator Admin API order transaction. Evitați să vă bazați pe câmpurile perimate precum OrderTransaction.authorizationCode pentru integrările noi.

Următorul exemplu simplificat arată o comandă de 100 USD plătită cu 75 USD prin Shopify Payments și 25 USD prin Shop Cash. Valorile au doar rol ilustrativ.

{
  "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 poate părea similar altor valori de plată sau promoționale, dar sistemele dumneavoastră ar trebui să trateze fiecare valoare în mod separat:

Înainte de a vă baza pe un sistem terț pentru comenzile care includ Shop Cash, confirmați următoarele cerințe:

• Shop Cash este asociat ca metodă de plată.
• Comenzile cu Shop Cash și Shop Pay sunt importate cu ambele metode de plată.
• Logica metodei de plată nu presupune o singură metodă de plată per comandă.
• Valorile de autorizare sunt stocate ca șiruri opace lungi și nu sunt trunchiate.
• Logica de restituire poate restitui tranzacția de captare corectă.
• Logica de restituire poate returna fondurile către metodele de plată corecte.
• Reconcilierea primirilor de plăți poate lua în calcul tipurile de tranzacții de credit, de restituire și de campanie Shop Cash.
• Fluxurile de lucru pentru onorarea comenzilor, contabilitate și retururi nu tratează Shop Cash ca pe o reducere.

Dacă utilizați mai multe sisteme, finalizați această verificare pentru fiecare sistem care primește date despre comenzi, tranzacții, primiri de plăți, onorări, restituiri sau retururi.