Orderdata för Shop Cash och tredjepartsintegrationer

När en kund använder Shop Cash för en order behandlas Shop Cash som en betalningsmetod. Det är varken en rabatt, ett presentkort eller en värdecheck. Eventuellt återstående ordersaldo betalas med Shop Pay eller avbetalning med Shop Pay.

Om en kund till exempel använder 25 USD i Shop Cash för en order på 100 USD innehåller ordern en Shop Cash-betalning på 25 USD och en Shop Pay-betalning på 75 USD. Din orderdata kan innehålla mer än en betalningsmetod för samma order.

Shop Cash visas som en ordertransaktion med gateway-värdet shop_cash där gateway-värden är tillgängliga. Shop Cash-transaktionen följer standardlivscykeln för transaktioner, såsom auktorisering, debitering, ogiltigförklaring och återbetalning. Shop Cash använder inte en kombinerad försäljningstransaktionstyp.

Om kunden också använder ett Shop-erbjudande från en Shop Campaigns-kampanj inkluderas det kampanjfinansierade värdet i samma belopp för shop_cash-ordertransaktionen. Delarna för köparens saldo och kampanjfinansiering representeras inte som separata ordertransaktioner. Från och med januari 2026 debiteras kampanjkostnader på din Shopify-faktura i stället för att dras av från dina utbetalningar, så kampanjfaktureringstransaktioner i utbetalningsaktivitet gäller endast för kampanjer som kördes före det datumet. Mer information finns i Avgifter, Shop Campaigns och Shop Cash.

Tredjepartssystem som importerar ordrar, transaktioner, betalningar, distributioner, återbetalningar eller returer måste känna igen Shop Cash som en betalningsmetod. Om ett system inte känner igen Shop Cash kan ordrar som innehåller Shop Cash misslyckas med att importeras, importeras med ofullständig betalningsdata eller kräva manuell mappning.

Gå igenom följande krav med leverantören av ditt tredjepartssystem:

• Systemet kan stödja mer än en betalningsmetod för en order.
• Systemet kan mappa shop_cash som en betalningsmetod.
• Systemet behandlar inte Shop Cash som en rabatt, ett presentkort eller en värdecheck.
• Systemet lagrar ordertransaktions-ID:t för varje auktorisering, debitering, ogiltigförklaring och återbetalning med Shop Cash.
• Systemet lagrar det fullständiga Shop Cash-auktoriseringsvärdet utan att trunkera det, om värdet ingår i den data som systemet importerar.
• Systemet behandlar auktoriseringsvärden som opaka strängar och tolkar, avkodar, normaliserar, hashar eller härleder inte innebörd från dem.
• Systemet kan behandla återbetalningar som returnerar medel till både Shop Pay och Shop Cash.
• Systemet kan stämma av utbetalningstransaktioner för Shop Cash separat från kortbetalningstransaktioner.
• Systemet förutsätter inte att transaktioner returneras i en specifik ordning.

Om ditt tredjepartssystem förutsätter att varje order bara har en betalningsmetod kontaktar du leverantören innan du behandlar Shop Cash-ordrar genom det systemet.

Auktoriseringsvärdet i en Shop Cash-transaktion är en opak sträng med variabel längd. Den är inte en kort auktoriseringskod för kort och är inte läsbar för människor.

Om ditt ERP, OMS eller ett annat tredjepartssystem importerar auktoriseringsvärden för Shop Cash ska det fullständiga värdet lagras exakt som det anges. Använd ett textfält med variabel längd eller ett obegränsat textfält i de fall det är möjligt.

Följ dessa riktlinjer när ditt system lagrar Shop Cash-auktoriseringsvärden:

• Trunkera inte värdet till en kort, fast längd, såsom 50 eller 100 tecken.
• Tolka inte och härled inte innebörd från någon del av värdet.
• Använd inte auktoriseringsvärdet för att identifiera transaktioner för API-åtgärder avseende debitering, ogiltigförklaring eller återbetalning.

Trunkerade auktoriseringsvärden kan orsaka att tredjepartsimporter eller nedströmsbehandling i ERP och OMS misslyckas.

Lagra ordertransaktions-ID:n och relationer till överordnade transaktioner för att stödja debiteringar, ogiltigförklaringar och återbetalningar via Admin API. Admin API-åtgärder för debitering och ogiltigförklaring identifierar auktoriseringstransaktionen med parentTransactionId. Återbetalningsåtgärder identifierar den debiteringsstransaktion som kan återbetalas med parentId.

När en app eller integration utfärdar en Shop Cash-återbetalning via API:et måste återbetalningen vara underordnad Shop Cash-debiteringstransaktionen, inte Shop Cash-auktoriseringstransaktionen. Återbetalningar mot auktoriseringstransaktionen avvisas.

Appar för återbetalning och webhook-hanterare bör identifiera den Shop Cash-debiteringstransaktion som kan återbetalas, beräkna det återstående beloppet som kan återbetalas för den debiteringen och skapa återbetalningen mot debiteringstransaktionens ID.

När du använder Admin API, orderexporter, utbetalningsexporter eller exporter från tredjepartsappar ska du hantera Shop Cash som betalningsdata. Beroende på vilken export eller API-resurs du använder kan Shop Cash-information representeras genom betalningsmetod, gateway, ordertransaktion, utbetalningstransaktion och återbetalningsdata.

När du bygger eller uppdaterar en integration ska du spara följande information för ordrar som inkluderar Shop Cash:

• Order-ID och ordernamn.
• Betalningsmetod eller gatewayvärde, till exempel shop_cash där det är tillgängligt.
• Ordertransaktions-ID:n för varje betalningstransaktion.
• Transaktionstyp och status, till exempel auktorisering, debitering, återbetalning eller ogiltigförklaring.
• Transaktionsbelopp och valuta.
• Överordnade transaktionsrelationer, när de är tillgängliga.
• Betalnings-ID:n, där det är tillgängligt.
• Fullständiga auktoriseringsvärden, om de importeras av ditt system.
• Utbetalnings-ID:n och saldotransaktions-ID:n när du stämmer av utbetalningar.
• Återbetalningstransaktions-ID:n när du stämmer av returer.

Mer information om tillgängliga fält i Admin API finns i utvecklardokumentationen för Admin API-ordertransaktion. Undvik att förlita dig på föråldrade fält som OrderTransaction.authorizationCode för nya integrationer.

Följande förenklade exempel visar en order på 100 USD som betalats med 75 USD via Shopify Payments och 25 USD via Shop Cash. Värdena är endast illustrativa.

{
  "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 kan se ut som andra betalnings- eller kampanjvärden, men dina system bör hantera varje värde separat:

Innan du förlitar dig på ett tredjepartssystem för ordrar som inkluderar Shop Cash bör du bekräfta följande krav:

• Shop Cash är mappad som en betalningsmetod.
• Ordrar med Shop Cash och Shop Pay importeras med båda betalningsmetoderna.
• Logiken för betalningsmetoder förutsätter inte en betalningsmetod per order.
• Auktoriseringsvärden sparas som långa opaka strängar och förkortas inte.
• Logiken för återbetalningar kan återbetala rätt debiteringstransaktion.
• Logiken för återbetalningar kan returnera medel till rätt betalningsmetoder.
• Utbetalningsavstämning kan ta hänsyn till transaktionstyper för Shop Cash-krediter, återbetalningar och kampanjer.
• Arbetsflöden för distribution, bokföring och returer hanterar inte Shop Cash som en rabatt.

Om du använder flera system ska du slutföra denna granskning för varje system som tar emot data om order, transaktion, utbetalning, distribution, återbetalning eller retur.