Shop Cash-bestelgegevens en integraties van externe partijen

Wanneer een klant Shop Cash gebruikt bij een bestelling, wordt Shop Cash behandeld als een betaalmethode. Het is geen korting, cadeaubon of winkeltegoed. Een eventueel resterend bestelsaldo wordt betaald met Shop Pay of Shop Pay-termijnbetalingen.

Als een klant bijvoorbeeld $ 25 USD aan Shop Cash gebruikt bij een bestelling van $ 100 USD, omvat de bestelling een Shop Cash-betaling van $ 25 USD en een Shop Pay-betaling van $ 75 USD. Je bestelgegevens kunnen meer dan één betaalmethode bevatten voor dezelfde bestelling.

Shop Cash wordt weergegeven als een besteltransactie met de gateway-waarde shop_cash waar gateway-waarden beschikbaar zijn. De Shop Cash-transactie volgt de standaard levenscyclus van transacties, zoals autorisatie, vastlegging, ongeldigverklaring en terugbetaling. Shop Cash gebruikt geen gecombineerd type verkooptransactie.

Als de klant ook een Shop-aanbieding van een Shop Campaign gebruikt, is de door de campagne gefinancierde waarde inbegrepen in hetzelfde shop_cash-besteltransactiebedrag. De delen van het koperssaldo en de campagnefinanciering worden niet weergegeven als afzonderlijke besteltransacties. Vanaf januari 2026 worden campagnekosten in rekening gebracht op je Shopify-factuur in plaats van ingehouden op je uitbetalingen, dus campagnefactureringstransacties in uitbetalingsactiviteit zijn alleen van toepassing op campagnes die vóór die datum liepen. Raadpleeg Kosten, Shop Campaigns en Shop Cash voor meer informatie.

Externe systemen die bestellingen, transacties, betalingen, fulfilments, terugbetalingen of retouren importeren, moeten Shop Cash herkennen als een betaalmethode. Als een systeem Shop Cash niet herkent, kunnen bestellingen met Shop Cash mogelijk niet worden geïmporteerd, worden ze geïmporteerd met onvolledige betalingsgegevens of vereisen ze handmatige toewijzing.

Neem de volgende vereisten door met de aanbieder van je externe systeem:

• Het systeem kan meer dan één betaalmethode voor één bestelling ondersteunen.
• Het systeem kan shop_cash toewijzen als betaalmethode.
• Het systeem behandelt Shop Cash niet als korting, cadeaubon of winkeltegoed.
• Het systeem slaat de besteltransactie-ID op voor elke autorisatie, vastlegging, ongeldigverklaring en terugbetaling van Shop Cash.
• Het systeem slaat de volledige Shop Cash-autorisatiewaarde op zonder deze af te kappen, als de waarde is opgenomen in de gegevens die het systeem importeert.
• Het systeem behandelt autorisatiewaarden als opake tekenreeksen en parseert, decodeert, normaliseert of hasht deze niet en leidt er geen betekenis uit af.
• Het systeem kan terugbetalingen verwerken die geld terugstorten naar zowel Shop Pay als Shop Cash.
• Het systeem kan Shop Cash-uitbetalingstransacties afzonderlijk van kaartbetalingstransacties reconciliëren.
• Het systeem gaat er niet van uit dat transacties in een specifieke volgorde worden geretourneerd.

Als je externe systeem ervan uitgaat dat elke bestelling slechts één betaalmethode heeft, neem dan contact op met de aanbieder voordat je Shop Cash-bestellingen via dat systeem verwerkt.

De autorisatiewaarde van een Shop Cash-transactie is een opake tekenreeks met een variabele lengte. Het is geen korte autorisatiecode van een kaart en is niet leesbaar voor mensen.

Als je ERP, OMS of een ander extern systeem Shop Cash-autorisatiewaarden importeert, sla de volledige waarde dan precies zo op als deze wordt verstrekt. Gebruik waar mogelijk een tekstveld met variabele lengte of zonder limiet.

Volg deze richtlijnen wanneer je systeem Shop Cash-autorisatiewaarden opslaat:

• Kap de waarde niet af tot een korte vaste lengte, zoals 50 of 100 tekens.
• Parseer geen enkel deel van de waarde en leid er geen betekenis uit af.
• Gebruik de autorisatiewaarde niet om transacties te identificeren voor API-bewerkingen voor vastlegging, ongeldigverklaring of terugbetaling.

Afgekapte autorisatiewaarden kunnen ertoe leiden dat de import van externe partijen of de verdere ERP- en OMS-verwerking mislukt.

Sla besteltransactie-ID's en bovenliggende transactierelaties op om vastleggingen, ongeldigverklaringen en terugbetalingen via de Admin API te ondersteunen. Vastleggings- en ongeldigverklaringsbewerkingen van de Admin API identificeren de autorisatietransactie met parentTransactionId. Terugbetalingsbewerkingen identificeren de restitueerbare vastleggingstransactie met parentId.

Wanneer een app of integratie via de API een Shop Cash-terugbetaling uitvoert, moet de terugbetaling gekoppeld worden aan de Shop Cash-vastleggingstransactie als bovenliggende, niet de Shop Cash-autorisatietransactie. Terugbetalingen voor de autorisatietransactie worden afgewezen.

Terugbetalingsapps en webhook-handlers moeten de restitueerbare Shop Cash-vastleggingstransactie identificeren, het resterende restitueerbare bedrag voor die vastlegging berekenen en de terugbetaling aanmaken voor de vastleggingstransactie-ID.

Wanneer je de Admin API, bestellingsexports, uitbetalingsexports of exports van apps van derden gebruikt, behandel je Shop Cash als betalingsgegevens. Afhankelijk van de export of API-resource die je gebruikt, kunnen Shop Cash-gegevens worden weergegeven via de betaalmethode, gateway, bestellingstransactie, uitbetalingstransactie en terugbetalingsgegevens.

Wanneer je een integratie bouwt of updatet, sla je de volgende gegevens op voor bestellingen die Shop Cash bevatten:

• Bestellings-ID en naam bestelling.
• Betaalmethode of gateway-waarde, zoals shop_cash waar beschikbaar.
• Bestellingstransactie-ID's voor elke betalingstransactie.
• Transactietype en -status, zoals autorisatie, vastlegging, terugbetaling of ongeldigverklaring.
• Transactiebedrag en valuta.
• Relaties met bovenliggende transacties, indien beschikbaar.
• Betalings-ID's, waar beschikbaar.
• Volledige autorisatiewaarden, als je systeem deze importeert.
• Uitbetalings-ID's en saldotransactie-ID's wanneer je uitbetalingen reconcilieert.
• Terugbetalingstransactie-ID's wanneer je retouren reconcilieert.

Raadpleeg de Admin API order transaction-documentatie voor ontwikkelaars voor informatie over beschikbare Admin API-velden. Vertrouw voor nieuwe integraties niet op afgeschafte velden zoals OrderTransaction.authorizationCode.

Het volgende vereenvoudigde voorbeeld toont een bestelling van $ 100 USD die is betaald met $ 75 USD via Shopify Payments en $ 25 USD via Shop Cash. Waarden zijn slechts ter illustratie.

{
  "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 op andere betalings- of actiewaarden lijken, maar je systemen moeten elke waarde afzonderlijk behandelen:

Voordat je voor bestellingen met Shop Cash vertrouwt op een systeem van een externe partij, moet je de volgende vereisten bevestigen:

• Shop Cash is toegewezen als een betaalmethode.
• Bestellingen met Shop Cash en Shop Pay worden met beide betaalmethoden geïmporteerd.
• De logica voor betaalmethoden gaat niet uit van één betaalmethode per bestelling.
• Autorisatiewaarden worden opgeslagen als lange, ondoorzichtige tekenreeksen en worden niet ingekort.
• Terugbetalingslogica kan de juiste vastleggingstransactie terugbetalen.
• Terugbetalingslogica kan geld terugstorten naar de juiste betaalmethoden.
• Uitbetalingsreconciliatie kan rekening houden met de Shop Cash-transactietypen tegoed, terugbetaling en campagne.
• Workflows voor fulfilment, boekhouding en retouren behandelen Shop Cash niet als een korting.

Als je meerdere systemen gebruikt, voltooi je deze beoordeling voor elk systeem dat gegevens ontvangt over bestellingen, transacties, uitbetalingen, fulfilment, terugbetalingen of retouren.