Datos de pedidos de Shop Cash e integraciones de apps externas

Cuando un cliente usa Shop Cash en un pedido, Shop Cash se trata como una forma de pago. No es un descuento, una tarjeta de regalo ni un crédito en tienda. Cualquier saldo restante del pedido se paga con Shop Pay o con Cuotas de Shop Pay.

Por ejemplo, si un cliente usa 25 USD en Shop Cash en un pedido de 100 USD, entonces el pedido incluye un pago con Shop Cash por 25 USD y un pago con Shop Pay por 75 USD. Los datos de tus pedidos pueden incluir más de una forma de pago para el mismo pedido.

Shop Cash aparece como una transacción de pedido con el valor de pasarela shop_cash donde los valores de pasarela están disponibles. La transacción de Shop Cash sigue el ciclo de vida estándar de una transacción (por ejemplo, autorización, captura, anulación y reembolso). Shop Cash no usa un tipo de transacción de venta combinada.

Si el cliente también usa una oferta de Shop de Shop Campaigns, entonces el valor financiado por la campaña se incluye en el mismo monto de la transacción de pedido shop_cash. Las partes correspondientes al saldo del comprador y las financiadas por la campaña no se representan como transacciones de pedido separadas. A partir de enero de 2026, los costos de la campaña se cargarán a tu factura de Shopify en lugar de deducirse de tus pagos; por lo tanto, las transacciones de facturación de campañas en la actividad de pagos se aplican solo a las campañas que se publicaron antes de esa fecha. Para obtener más información, consulta Cargos, Shop Campaigns y Shop Cash.

Los sistemas externos que importan pedidos, transacciones, pagos, preparaciones de pedidos, reembolsos o devoluciones deben reconocer Shop Cash como una forma de pago. Si un sistema no reconoce Shop Cash, es posible que los pedidos que incluyen Shop Cash fallen al importarse, se importen con datos de pago incompletos o requieran asignación manual.

Revisa los siguientes requisitos con tu proveedor de sistemas externos:

• El sistema es compatible con más de una forma de pago en un solo pedido.
• El sistema puede asignar shop_cash como una forma de pago.
• El sistema no trata Shop Cash como un descuento, tarjeta de regalo ni crédito en tienda.
• El sistema almacena la identificación (ID) de la transacción del pedido para cada autorización, captura, anulación y reembolso de Shop Cash.
• El sistema almacena el valor completo de la autorización de Shop Cash sin truncarlo, si el valor se incluye en los datos que el sistema importa.
• El sistema trata los valores de autorización como cadenas opacas y no los analiza, decodifica, normaliza, les aplica funciones hash ni infiere su significado.
• El sistema puede procesar reembolsos que devuelven fondos tanto a Shop Pay como a Shop Cash.
• El sistema puede conciliar las transacciones de pago de Shop Cash por separado de las transacciones de pago con tarjeta.
• El sistema no asume que las transacciones se devuelven en un orden específico.

Si tu sistema externo asume que cada pedido tiene una sola forma de pago, contacta al proveedor antes de procesar los pedidos de Shop Cash a través de ese sistema.

El valor de autorización en una transacción de Shop Cash es una cadena opaca de longitud variable. No es un código corto de autorización de tarjeta y no es legible por humanos.

Si tu ERP, OMS u otro sistema externo importa los valores de autorización de Shop Cash, almacena el valor completo exactamente como se proporciona. Usa un campo de texto de longitud variable o ilimitado siempre que sea posible.

Cuando tu sistema almacene valores de autorización de Shop Cash, sigue estas pautas:

• No trunques el valor a una longitud fija corta, como de 50 o 100 caracteres.
• No analices ni infieras el significado de ninguna parte del valor.
• No uses el valor de autorización para identificar transacciones en operaciones de la API para captura, anulación o reembolso.

Los valores de autorización truncados pueden hacer que fallen las importaciones de aplicaciones externas o el procesamiento posterior en ERP y OMS.

Para admitir las capturas, las anulaciones y los reembolsos a través de la Admin API, almacena los ID de transacciones de pedidos y las relaciones de las transacciones principales. Las operaciones de captura y anulación de la Admin API identifican la transacción de autorización con parentTransactionId. Las operaciones de reembolso identifican la transacción de captura reembolsable con parentId.

Cuando una app o integración emite un reembolso de Shop Cash a través de la API, el reembolso debe vincularse a la transacción de captura de Shop Cash, no a la transacción de autorización de Shop Cash. Los reembolsos de la transacción de autorización se rechazarán.

Las aplicaciones de reembolso y los gestores de webhooks deben identificar la transacción de captura de Shop Cash reembolsable, calcular el monto reembolsable restante de esa captura y crear el reembolso para el ID de la transacción de captura.

Cuando uses la Admin API, las exportaciones de pedidos, las exportaciones de pagos o las exportaciones de apps externas, trata a Shop Cash como datos de pago. Dependiendo de la exportación o el recurso de API que uses, la información de Shop Cash se puede representar a través de la forma de pago, la pasarela, la transacción del pedido, la transacción de pago y los datos de reembolso.

Cuando crees o actualices una integración, almacena la siguiente información para los pedidos que incluyen Shop Cash:

• Identificación y nombre del pedido.
• Forma de pago o valor de la pasarela, como shop_cash donde esté disponible.
• Identificaciones de las transacciones del pedido para cada transacción de pago.
• Tipo y estado de la transacción, como autorización, captura, reembolso o anulación.
• Monto y moneda de la transacción.
• Relaciones de transacciones principales, cuando estén disponibles.
• Identificaciones de pago, donde estén disponibles.
• Valores completos de autorización, si el sistema los importa.
• Identificaciones de pago y de transacciones de saldo cuando concilies los pagos.
• Identificaciones de transacciones de reembolso cuando concilies devoluciones.

Para obtener información sobre los campos disponibles de la Admin API, consulta la documentación para desarrolladores sobre la transacción de pedido de la Admin API. En el caso de las nuevas integraciones, evita depender de campos obsoletos como OrderTransaction.authorizationCode.

El siguiente ejemplo simplificado muestra un pedido de 100 USD pagado con 75 USD a través de Shopify Payments y 25 USD a través de Shop Cash. Los valores son solo 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
    }
  ]
}

Shop Cash puede parecer similar a otros valores de pago o promocionales, pero los sistemas deben tratar cada valor por separado:

Antes de depender de un sistema externo para los pedidos que incluyen Shop Cash, confirma los siguientes requisitos:

• Shop Cash se asigna como una forma de pago.
• Los pedidos con Shop Cash y Shop Pay se importan con ambas formas de pago.
• La lógica de la forma de pago no asume una forma de pago por pedido.
• Los valores de autorización se almacenan como cadenas opacas largas y no se truncan.
• La lógica de reembolso puede reembolsar la transacción de captura correcta.
• La lógica de reembolso puede devolver los fondos a las formas de pago correctas.
• La conciliación de pagos puede dar cuenta de los tipos de transacciones de crédito, reembolso y campaña de Shop Cash.
• Los flujos de trabajo de preparación de pedidos, contabilidad y devoluciones no tratan a Shop Cash como un descuento.

Si usas varios sistemas, completa esta revisión para cada sistema que reciba datos de pedidos, transacciones, pagos, preparación de pedidos, reembolsos o devoluciones.