Données de commande Shop Cash et intégrations tierces

Lorsqu'un client utilise le Shop Cash pour une commande, le Shop Cash est traité comme un moyen de paiement. Il ne s'agit pas d'une réduction, d'une carte-cadeau ou d'un crédit en magasin. Tout solde de commande restant est réglé avec Shop Pay ou le Paiement en plusieurs fois avec Shop Pay.

Par exemple, si un client utilise 25 USD en Shop Cash pour une commande de 100 USD, la commande comprend alors un paiement Shop Cash de 25 USD et un paiement Shop Pay de 75 USD. Les données de votre commande peuvent comprendre plus d’un moyen de paiement pour la même commande.

Le Shop Cash s’affiche sous la forme d’une transaction de commande dont la valeur de passerelle est shop_cash, si de telles valeurs sont disponibles. La transaction Shop Cash suit le cycle de vie standard d'une transaction : autorisation, saisie, annulation et remboursement. Le Shop Cash n’utilise pas le type de transaction de vente combinée.

Si le client utilise également une offre Shop issue d’une campagne Shop Campaigns, la valeur financée par la campagne est incluse dans le même montant de transaction de commande shop_cash. Les portions relatives au solde de l'acheteur et au financement de la campagne ne sont pas représentées comme des transactions de commande distinctes. À partir de janvier 2026, les coûts des campagnes sont facturés sur votre facture Shopify au lieu d'être déduits de vos versements. Par conséquent, les transactions de facturation de campagne figurant dans l’activité de versement ne s’appliquent qu’aux campagnes antérieures à cette date. Pour en savoir plus, consultez la section Frais, Shop Campaigns et Shop Cash.

Les systèmes tiers qui importent des commandes, des transactions, des paiements, des traitements de commandes, des remboursements ou des retours doivent reconnaître le Shop Cash comme un moyen de paiement. Si un système ne reconnaît pas le Shop Cash, l’importation des commandes contenant du Shop Cash peut échouer, s’effectuer avec des données de paiement incomplètes ou nécessiter un mappage manuel.

Examinez les exigences suivantes avec votre fournisseur de système tiers :

• Le système peut prendre en charge plus d’un moyen de paiement pour une seule commande.
• Le système peut mapper shop_cash comme un moyen de paiement.
• Le système ne traite pas le Shop Cash comme une réduction, une carte-cadeau ou un crédit en magasin.
• Le système stocke l’ID de transaction de la commande pour chaque autorisation, saisie, annulation et remboursement par Shop Cash.
• Le système stocke la valeur d'autorisation Shop Cash complète sans la tronquer, si cette valeur figure dans les données qu'il importe.
• Le système traite les valeurs d'autorisation comme des chaînes opaques et n’essaie pas de les analyser, de les décoder, de les normaliser, de les hacher ou d'en déduire une signification.
• Le système peut traiter les remboursements qui restituent des fonds à la fois sur Shop Pay et sur Shop Cash.
• Le système peut rapprocher les transactions de versement Shop Cash séparément des transactions de paiement par carte.
• Le système ne suppose pas que les transactions sont renvoyées dans un ordre précis.

Si votre système tiers présume que chaque commande ne comporte qu’un seul moyen de paiement, veuillez contacter le fournisseur avant de traiter les commandes Shop Cash par l’intermédiaire de ce système.

La valeur d’autorisation d’une transaction Shop Cash est une chaîne opaque de longueur variable. Il ne s’agit pas d’un code d’autorisation de carte court et elle n'est pas lisible par un humain.

Si votre ERP, votre OMS ou un autre système tiers importe des valeurs d’autorisation Shop Cash, stockez la valeur complète exactement telle qu'elle est fournie. Utilisez un champ de texte de longueur variable ou illimité dans la mesure du possible.

Lorsque votre système stocke des valeurs d'autorisation Shop Cash, suivez ces directives :

• Ne tronquez pas la valeur à une longueur fixe courte, telle que 50 ou 100 caractères.
• N’analysez et ne déduisez aucune signification d’une quelconque partie de la valeur.
• N’utilisez pas la valeur d’autorisation pour identifier les transactions en vue d’opérations API de saisie, d’annulation ou de remboursement.

Les valeurs d’autorisation tronquées peuvent entraîner l’échec des importations tierces ou du traitement en aval par l’ERP et l’OMS.

Pour prendre en charge les saisies, les annulations et les remboursements par le biais de l’Admin API, stockez les ID de transaction de commande et les relations de transactions parentes. Les opérations de saisie et d’annulation de l’Admin API identifient la transaction d’autorisation avec parentTransactionId. Les opérations de remboursement identifient la transaction de saisie remboursable avec parentId.

Lorsqu’une appli ou une intégration émet un remboursement Shop Cash via l’API, le remboursement doit être rattaché à la transaction de saisie Shop Cash, et non à la transaction d’autorisation Shop Cash. Les remboursements effectués sur la transaction d’autorisation sont rejetés.

Les applis de remboursement et les gestionnaires de webhook doivent identifier la transaction de saisie Shop Cash remboursable, calculer le montant remboursable restant pour cette saisie et créer le remboursement pour l'ID de transaction de saisie.

Lorsque vous utilisez l’Admin API, les exportations de commandes, les exportations de versements ou les exportations d’applis tierces, traitez Shop Cash comme des données de paiement. Selon l’exportation ou la ressource d’API que vous utilisez, les informations Shop Cash peuvent être représentées par le moyen de paiement, la passerelle, la transaction de commande, la transaction de versement et les données de remboursement.

Lorsque vous créez ou mettez à jour une intégration, stockez les informations suivantes pour les commandes qui incluent Shop Cash :

• Référence et nom de la commande.
• Valeur du moyen de paiement ou de la passerelle, telle que shop_cash si elle est disponible.
• ID de transaction de commande pour chaque transaction de paiement.
• Type et statut de la transaction, comme l’autorisation, la saisie, le remboursement ou l’annulation.
• Montant et devise de la transaction.
• Relations de transaction parente, le cas échéant.
• ID de paiement, le cas échéant.
• Valeurs d’autorisation complètes, si votre système les importe.
• ID de versement et ID de transaction de solde lorsque vous rapprochez des versements.
• ID de transaction de remboursement lorsque vous rapprochez des retours.

Pour en savoir plus sur les champs de l’Admin API disponibles, consultez la documentation pour les développeurs sur les transactions de commande de l’Admin API. Évitez de vous fier aux champs obsolètes, tels que OrderTransaction.authorizationCode, pour les nouvelles intégrations.

L’exemple simplifié suivant illustre une commande de 100 USD payée avec 75 USD via Shopify Payments et 25 USD via Shop Cash. Les valeurs sont données à titre indicatif uniquement.

{
  "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 peut ressembler à d’autres valeurs de paiement ou promotionnelles, mais vos systèmes doivent traiter chaque valeur séparément :

Avant de vous appuyer sur un système tiers pour les commandes qui incluent Shop Cash, confirmez les exigences suivantes :

• Shop Cash est mappé comme moyen de paiement.
• Les commandes réglées avec Shop Cash et Shop Pay sont importées avec les deux moyens de paiement.
• La logique des moyens de paiement ne présuppose pas qu’il n’y a qu’un seul moyen de paiement par commande.
• Les valeurs d’autorisation sont stockées sous forme de longues chaînes opaques et ne sont pas tronquées.
• La logique de remboursement permet de rembourser la bonne transaction de saisie.
• La logique de remboursement permet de restituer les fonds aux bons moyens de paiement.
• Le rapprochement des versements peut prendre en compte les types de transactions de crédit, de remboursement et de campagne de Shop Cash.
• Les flux de travail de traitement des commandes, de comptabilité et de retour ne traitent pas Shop Cash comme une réduction.

Si vous utilisez plusieurs systèmes, effectuez cette vérification pour chaque système qui reçoit des données de commande, de transaction, de versement, de traitement des commandes, de remboursement ou de retour.