Dati degli ordini Shop Cash e integrazioni di terze parti

Quando un cliente utilizza Shop Cash per un ordine, questo viene considerato come un metodo di pagamento. Non si tratta di uno sconto, di un buono regalo o di un credito in negozio. L'eventuale saldo rimanente dell'ordine viene pagato con Shop Pay o Shop Pay Installments.

Ad esempio, se un cliente utilizza 25 USD in Shop Cash su un ordine da 100 USD, l'ordine includerà un pagamento tramite Shop Cash per 25 USD e un pagamento con Shop Pay per 75 USD. I dati del tuo ordine possono includere più di un metodo di pagamento per lo stesso ordine.

Shop Cash viene visualizzato come transazione dell'ordine con il valore di gateway shop_cash (laddove questi valori siano disponibili). La transazione Shop Cash segue il ciclo di vita standard delle transazioni, che include autorizzazione, acquisizione, annullamento e rimborso. Shop Cash non utilizza un tipo di transazione di vendita combinata.

Se il cliente utilizza anche un'offerta Shop proveniente da Shop Campaigns, l'importo finanziato dalla campagna sarà incluso nello stesso importo della transazione dell'ordine shop_cash. Le porzioni relative al saldo dell'acquirente e al finanziamento della campagna non vengono rappresentate come transazioni dell'ordine separate. A partire da gennaio 2026, i costi della campagna verranno addebitati sulla tua fattura Shopify anziché essere detratti dai tuoi accrediti, pertanto le transazioni di fatturazione della campagna nelle attività di accredito si applicheranno solo alle campagne eseguite prima di tale data. Per maggiori informazioni, consulta Commissioni, Shop Campaigns e Shop Cash.

I sistemi di terze parti che importano ordini, transazioni, pagamenti, evasioni, rimborsi o resi devono riconoscere Shop Cash come metodo di pagamento. Se un sistema non riconosce Shop Cash, l'importazione degli ordini che lo includono potrebbe non andare a buon fine, i dati di pagamento importati potrebbero essere incompleti oppure potrebbe essere necessaria una mappatura manuale.

Verifica i seguenti requisiti con il fornitore del tuo sistema di terze parti:

• Il sistema è in grado di supportare più metodi di pagamento per un singolo ordine.
• Il sistema è in grado di mappare shop_cash come metodo di pagamento.
• Il sistema non tratta Shop Cash come uno sconto, un buono regalo o un credito in negozio.
• Il sistema archivia l'ID della transazione dell'ordine per ciascuna autorizzazione, acquisizione, annullamento e rimborso tramite Shop Cash.
• Il sistema archivia l'intero valore di autorizzazione di Shop Cash senza troncarlo, qualora il valore sia incluso nei dati importati dal sistema.
• Il sistema tratta i valori di autorizzazione come stringhe opache e non li analizza, decodifica, normalizza, converte in hash né ne deduce il significato.
• Il sistema è in grado di elaborare i rimborsi che restituiscono fondi sia a Shop Pay che a Shop Cash.
• Il sistema è in grado di riconciliare le transazioni di accredito di Shop Cash separatamente dalle transazioni con pagamento tramite carta.
• Il sistema non presuppone che le transazioni vengano restituite in un ordine specifico.

Se il tuo sistema di terze parti presuppone che ogni ordine abbia un solo metodo di pagamento, contatta il fornitore prima di elaborare gli ordini Shop Cash tramite quel sistema.

Il valore di autorizzazione di una transazione Shop Cash è una stringa opaca di lunghezza variabile. Non è un breve codice di autorizzazione per le carte e non è leggibile da un essere umano.

Se il tuo sistema ERP, OMS o un altro sistema di terze parti importa i valori di autorizzazione di Shop Cash, salva il valore completo esattamente come ti è stato fornito. Se possibile, utilizza un campo di testo di lunghezza variabile o illimitato.

Quando il tuo sistema archivia i valori di autorizzazione di Shop Cash, segui queste linee guida:

• Non troncare il valore a una lunghezza fissa breve, come 50 o 100 caratteri.
• Non analizzare né dedurre alcun significato da nessuna parte del valore.
• Non usare il valore di autorizzazione per identificare le transazioni per le operazioni API di acquisizione, annullamento o rimborso.

I valori di autorizzazione troncati possono causare il mancato completamento delle importazioni di terze parti o dell'elaborazione a valle da parte dei sistemi ERP e OMS.

Per supportare acquisizioni, annullamenti e rimborsi tramite le Admin API, archivia gli ID delle transazioni degli ordini e le relazioni con la transazione principale. Le operazioni di acquisizione e annullamento delle Admin API identificano la transazione di autorizzazione con parentTransactionId. Le operazioni di rimborso identificano la transazione di acquisizione rimborsabile con parentId.

Quando un'app o un'integrazione emette un rimborso Shop Cash tramite le API, il rimborso deve essere associato alla transazione di acquisizione di Shop Cash, non a quella di autorizzazione. I rimborsi associati alla transazione di autorizzazione verranno rifiutati.

Le app per i rimborsi e i gestori di webhook devono identificare la transazione di acquisizione rimborsabile di Shop Cash, calcolare l'importo rimborsabile rimanente per quell'acquisizione e creare il rimborso in associazione all'ID della transazione di acquisizione.

Quando usi le Admin API, le esportazioni di ordini e accrediti o le esportazioni di app di terze parti, considera Shop Cash come dati di pagamento. A seconda dell'esportazione o della risorsa API che usi, le informazioni su Shop Cash possono essere rappresentate tramite metodo di pagamento, gateway, transazione dell'ordine, transazione di accredito e dati di rimborso.

Quando crei o aggiorni un'integrazione, memorizza le seguenti informazioni per gli ordini che includono Shop Cash:

• ID ordine e nome ordine.
• Metodo di pagamento o valore del gateway, ad esempio shop_cash, dove disponibile.
• ID delle transazioni dell'ordine per ciascuna transazione di pagamento.
• Tipo e stato della transazione, ad esempio autorizzazione, acquisizione, rimborso o annullamento.
• Importo e valuta della transazione.
• Relazioni con le transazioni principali, dove disponibili.
• ID del pagamento, dove disponibili.
• Valori di autorizzazione completi, se il tuo sistema li importa.
• ID di accredito e ID delle transazioni di saldo durante la riconciliazione degli accrediti.
• ID della transazione di rimborso durante la riconciliazione dei resi.

Per i dettagli sui campi delle Admin API disponibili, consulta la documentazione per gli sviluppatori sulle transazioni dell'ordine tramite Admin API. Evita di fare affidamento su campi deprecati come OrderTransaction.authorizationCode per le nuove integrazioni.

Il seguente esempio semplificato mostra un ordine da 100 USD pagato con 75 USD tramite Shopify Payments e 25 USD tramite Shop Cash. I valori sono solo a scopo illustrativo.

{
  "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 può sembrare simile ad altri valori di pagamento o promozionali, ma i tuoi sistemi dovrebbero trattare ciascun valore separatamente:

Prima di affidarti a un sistema di terze parti per gli ordini che includono Shop Cash, conferma i seguenti requisiti:

• Shop Cash è mappato come metodo di pagamento.
• Gli ordini con Shop Cash e Shop Pay vengono importati con entrambi i metodi di pagamento.
• La logica del metodo di pagamento non presuppone un solo metodo di pagamento per ordine.
• I valori di autorizzazione sono memorizzati come lunghe stringhe opache e non vengono troncati.
• La logica di rimborso può rimborsare la transazione di acquisizione corretta.
• La logica di rimborso può restituire i fondi ai metodi di pagamento corretti.
• La riconciliazione degli accrediti può tenere conto dei tipi di transazione di credito, rimborso e campagna di Shop Cash.
• I flussi di lavoro di evasione, contabilità e reso non trattano Shop Cash come uno sconto.

Se usi più sistemi, completa questa revisione per ciascun sistema che riceve dati su ordini, transazioni, accrediti, evasione, rimborsi o resi.