Dados de pedido do Shop Cash e integrações de terceiros

Quando um cliente usa o Shop Cash em um pedido, o Shop Cash é tratado como uma forma de pagamento, e não como um desconto, cartão-presente ou crédito na loja. O saldo restante do pedido é pago com o Shop Pay ou com o Parcelamento do Shop Pay.

Por exemplo, se um cliente usa US$ 25 em Shop Cash em um pedido de US$ 100, o pedido inclui um pagamento de US$ 25 no Shop Cash e um pagamento de US$ 75 no Shop Pay. Os dados do pedido podem incluir mais de uma forma de pagamento para o mesmo pedido.

O Shop Cash aparece como uma transação de pedido com o valor de gateway shop_cash, caso os valores do gateway estejam disponíveis. A transação do Shop Cash segue o ciclo de vida padrão de transações, como autorização, captura, anulação e reembolso. O Shop Cash não usa um tipo de transação de venda combinada.

Se o cliente também usar uma oferta do Shop de um Shop Campaigns, o valor financiado pela campanha será incluído no mesmo valor de transação de pedido shop_cash. As partes do saldo do comprador e financiadas pela campanha não são representadas como transações de pedidos separadas. A partir de janeiro de 2026, os custos da campanha são cobrados na fatura da Shopify em vez de serem deduzidos dos pagamentos. Portanto, as transações de faturamento da campanha nas atividades de pagamento se aplicam apenas a campanhas executadas antes dessa data. Para ver mais informações, consulte Taxas, Shop Campaigns e Shop Cash.

Os sistemas de terceiros que importam pedidos, transações, pagamentos, processamentos de pedidos, reembolsos ou devoluções precisam reconhecer o Shop Cash como uma forma de pagamento. Se um sistema não reconhecer o Shop Cash, os pedidos que incluem o Shop Cash poderão falhar ao importar, poderão ser importados com dados de pagamento incompletos ou exigirão mapeamento manual.

Analise os seguintes requisitos com o provedor do sistema de terceiros:

• O sistema é compatível com mais de uma forma de pagamento em um pedido.
• O sistema pode mapear o shop_cash como uma forma de pagamento.
• O sistema não trata o Shop Cash como desconto, cartão-presente ou crédito na loja.
• O sistema armazena a ID da transação do pedido para cada autorização, captura, anulação e reembolso do Shop Cash.
• O sistema armazena o valor completo da autorização do Shop Cash sem truncá-lo se esse valor estiver incluído nos dados que o sistema importa.
• O sistema trata os valores de autorização como strings opacas e não analisa, não decodifica, não normaliza, não faz hash e não deduz significado deles.
• O sistema pode processar reembolsos que devolvem fundos para o Shop Pay e para o Shop Cash.
• O sistema pode conciliar transações de pagamento do Shop Cash separadamente das transações de pagamento com cartão.
• O sistema não pressupõe que as transações são retornadas em uma ordem específica.

Se o sistema de terceiros pressupõe que cada pedido tem apenas uma forma de pagamento, entre em contato com o provedor antes de processar pedidos com o Shop Cash por esse sistema.

O valor de autorização em uma transação do Shop Cash é uma string opaca de tamanho variável. Não é um código de autorização de cartão curto e não é legível por humanos.

Se o ERP, OMS ou outro sistema de terceiros importa valores de autorização do Shop Cash, armazene o valor completo exatamente como foi fornecido. Use um campo de texto de tamanho variável ou sem limite sempre que possível.

Quando o sistema armazenar valores de autorização do Shop Cash, siga estas diretrizes:

• Não trunque o valor para um tamanho fixo curto, como 50 ou 100 caracteres.
• Não analise nem deduza significado de nenhuma parte do valor.
• Não use o valor de autorização para identificar transações para as operações de captura, anulação ou reembolso da API.

Valores de autorização truncados podem fazer com que importações de terceiros ou o processamento em ERPs e OMSs falhem.

Para ser compatível com capturas, anulações e reembolsos por meio da Admin API, armazene as IDs de transação de pedido e as relações de transações primárias. As operações de captura e anulação da Admin API identificam a transação de autorização com parentTransactionId. As operações de reembolso identificam a transação de captura reembolsável com parentId.

Quando um app ou integração emite um reembolso do Shop Cash pela API, o reembolso deve estar vinculado à transação de captura do Shop Cash, não à transação de autorização. Os reembolsos na transação de autorização são rejeitados.

Apps de reembolso e manipuladores de webhook devem identificar a transação de captura reembolsável do Shop Cash, calcular o valor reembolsável restante dessa captura e criar o reembolso na ID da transação de captura.

Ao usar a Admin API, as exportações de pedidos, de pagamentos ou de apps de terceiros, trate o Shop Cash como dados de pagamento. A depender da exportação ou do recurso da API utilizado, as informações do Shop Cash podem ser representadas por forma de pagamento, gateway, transação de pedido, transação de pagamento e dados de reembolso.

Ao criar ou atualizar uma integração, armazene as seguintes informações referentes aos pedidos que incluem o Shop Cash:

• ID e nome do pedido.
• Forma de pagamento ou valor do gateway, como shop_cash, quando disponível.
• IDs de transação de pedido para cada transação de pagamento.
• Tipo e status da transação, como autorização, captura, reembolso ou anulação.
• Valor e moeda da transação.
• Relações da transação principal, quando disponíveis.
• IDs de pagamento, quando disponíveis.
• Valores totais de autorização, se importados pelo sistema.
• IDs de pagamento e IDs de transação de saldo ao conciliar pagamentos.
• IDs de transação de reembolso ao conciliar devoluções.

Para ver informações sobre os campos disponíveis da Admin API, consulte a documentação para desenvolvedores da transação de pedido da Admin API. Evite o uso de campos obsoletos, como OrderTransaction.authorizationCode, em novas integrações.

O exemplo simplificado a seguir exibe um pedido de US$ 100 pago com US$ 75 por meio do Shopify Payments e US$ 25 com o Shop Cash. Os valores são apenas ilustrativos.

{
  "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
    }
  ]
}

O Shop Cash pode ser parecido com outros valores promocionais ou de pagamento, mas os sistemas devem tratar cada valor separadamente:

Antes de depender de um sistema de terceiros para processar pedidos que incluam o Shop Cash, confirme os seguintes requisitos:

• O Shop Cash está mapeado como forma de pagamento.
• Os pedidos com o Shop Cash e o Shop Pay são importados com ambas as formas de pagamento.
• A lógica das formas de pagamento não supõe a exclusividade de uma forma de pagamento por pedido.
• Os valores de autorização são armazenados como strings opacas e longas, e não são truncados.
• A lógica de reembolsos consegue reembolsar a transação de captura correta.
• A lógica de reembolsos consegue devolver os fundos para as formas de pagamento corretas.
• A conciliação de pagamentos abrange os tipos de transação de crédito, reembolso e campanha do Shop Cash.
• Os fluxos de trabalho de devolução, contabilidade e processamento de pedidos não tratam o Shop Cash como desconto.

Se você usa vários sistemas, conclua esta análise para cada sistema que recebe dados de devolução, reembolso, processamento de pedidos, pagamento, transação ou pedido.