Shop Cash 주문 데이터 및 타사 연동

고객이 주문 시 Shop Cash를 사용하는 경우 Shop Cash는 결제 방법으로 취급됩니다. 이는 할인, 기프트 카드 또는 스토어 크레딧이 아닙니다. 남은 주문 잔액은 Shop Pay 또는 Shop Pay 할부로 결제됩니다.

예를 들어 고객이 USD100 주문에 대해 Shop Cash로 USD25를 사용하는 경우 해당 주문에는 USD25의 Shop Cash 결제 및 USD75의 Shop Pay 결제가 포함됩니다. 주문 데이터에는 동일한 주문에 대해 둘 이상의 결제 방법이 포함될 수 있습니다.

Shop Cash는 게이트웨이 값을 사용할 수 있는 경우 shop_cash 게이트웨이 값을 가진 주문 거래로 나타납니다. Shop Cash 거래는 권한 부여, 매입, 무효 처리 및 환불 등 표준 거래 수명 주기를 따릅니다. Shop Cash는 결합된 판매 거래 유형을 사용하지 않습니다.

고객이 Shop Campaigns의 Shop 혜택도 함께 사용하는 경우 캠페인 지원 금액은 동일한 shop_cash 주문 거래 금액에 포함됩니다. 구매자 잔액 및 캠페인 지원 부분은 별도의 주문 거래로 표시되지 않습니다. 2026년 1월부터 캠페인 비용은 지급액에서 차감되는 대신 Shopify 청구서로 청구되므로 지급액 활동의 캠페인 청구 거래는 해당 날짜 이전에 실행된 캠페인에만 적용됩니다. 자세한 내용은 수수료, Shop Campaigns 및 Shop Cash를 참조하십시오.

주문, 거래, 결제, 주문 처리, 환불 또는 반품을 가져오는 타사 시스템은 Shop Cash를 결제 방법으로 인식해야 합니다. 시스템이 Shop Cash를 인식하지 못하는 경우 Shop Cash가 포함된 주문 가져오기에 실패하거나 불완전한 결제 데이터와 함께 가져오거나 수동 매핑이 필요할 수 있습니다.

타사 시스템 제공업체와 다음 요구 사항을 검토하십시오.

• 시스템에서 하나의 주문에 대해 둘 이상의 결제 방법을 지원할 수 있습니다.
• 시스템에서 shop_cash를 결제 방법으로 매핑할 수 있습니다.
• 시스템에서 Shop Cash를 할인, 기프트 카드 또는 스토어 크레딧으로 취급하지 않습니다.
• 시스템에서 각 Shop Cash 권한 부여, 매입, 무효 처리 및 환불에 대한 주문 거래 ID를 저장합니다.
• Shop Cash 권한 부여 값이 시스템에서 가져오는 데이터에 포함된 경우 시스템에서 해당 값을 자르지 않고 전체 그대로 저장합니다.
• 시스템에서 권한 부여 값을 불투명한 문자열로 취급하며 해당 값에서 구문 분석, 디코딩, 정규화, 해싱 또는 의미를 추론하지 않습니다.
• 시스템에서 Shop Pay 및 Shop Cash 모두에 자금을 반환하는 환불을 처리할 수 있습니다.
• 시스템에서 Shop Cash 지급액 거래를 카드 결제 거래와 별도로 조정할 수 있습니다.
• 시스템에서 거래가 특정 순서로 반환된다고 가정하지 않습니다.

타사 시스템에서 각 주문에 하나의 결제 방법만 있다고 가정하는 경우 해당 시스템을 통해 Shop Cash 주문을 처리하기 전에 제공업체에 문의하십시오.

Shop Cash 거래의 권한 부여 값은 길이가 가변적인 불투명한 문자열입니다. 짧은 카드 권한 부여 코드가 아니며 사람이 읽을 수 없습니다.

ERP, OMS 또는 기타 타사 시스템에서 Shop Cash 권한 부여 값을 가져오는 경우 제공된 그대로 전체 값을 저장하십시오. 가능한 한 가변 길이 또는 무제한 텍스트 필드를 사용하십시오.

시스템에 Shop Cash 권한 부여 값을 저장할 때는 다음 지침을 따르십시오.

• 값을 50자 또는 100자와 같이 짧은 고정 길이로 자르지 마십시오.
• 값의 어느 부분에서도 구문을 분석하거나 의미를 추론하지 마십시오.
• 매입, 무효 처리 또는 환불 API 작업에 대한 거래를 식별하는 데 권한 부여 값을 사용하지 마십시오.

잘린 권한 부여 값으로 인해 타사 가져오기 또는 다운스트림 ERP 및 OMS 처리에 실패할 수 있습니다.

Admin API를 통해 매입, 무효 처리 및 환불을 지원하려면 주문 거래 ID와 상위 거래 관계를 저장하십시오. Admin API 매입 및 무효 처리 작업은 parentTransactionId로 권한 부여 거래를 식별합니다. 환불 작업은 parentId로 환불 가능한 매입 거래를 식별합니다.

앱 또는 연동 기능에서 API를 통해 Shop Cash 환불을 발행할 때 환불의 상위 항목은 Shop Cash 권한 부여 거래가 아니라 Shop Cash 매입 거래로 지정되어야 합니다. 권한 부여 거래에 대한 환불은 거부됩니다.

환불 앱 및 Webhook 핸들러는 환불 가능한 Shop Cash 매입 거래를 식별하고 해당 매입의 남은 환불 가능 금액을 계산하여 매입 거래 ID에 대한 환불을 생성해야 합니다.

Admin API, 주문 내보내기, 지급액 내보내기 또는 타사 앱 내보내기를 사용할 때 Shop Cash를 결제 데이터로 취급하십시오. 사용하는 내보내기 또는 API 리소스에 따라 Shop Cash 정보는 결제 방법, 게이트웨이, 주문 거래, 지급액 거래 및 환불 데이터를 통해 표시될 수 있습니다.

연동을 구축하거나 업데이트할 때 Shop Cash가 포함된 주문에 대해 다음 정보를 저장하십시오.

• 주문 ID 및 주문 이름.
• shop_cash 등 사용 가능한 결제 방법 또는 게이트웨이 값.
• 각 결제 거래의 주문 거래 ID.
• 승인, 매입, 환불 또는 무효 처리 등의 거래 종류 및 상태.
• 거래 금액 및 통화.
• 상위 거래 관계(사용 가능한 경우).
• 결제 ID(사용 가능한 경우).
• 전체 승인 값(시스템에서 가져오는 경우).
• 지급액 조정 시 지급액 ID 및 잔액 거래 ID.
• 반품 조정 시 환불 거래 ID.

사용 가능한 Admin API 필드에 대한 자세한 내용은 Admin API 주문 거래 개발자 설명서를 참조하십시오. 새로운 연동을 수행할 때 OrderTransaction.authorizationCode와 같이 더 이상 사용되지 않는 필드에 의존하지 마십시오.

다음 단순화된 예시에서는 Shopify Payments를 통해 USD75를, Shop Cash를 통해 USD25를 결제한 USD100의 주문을 보여줍니다. 이 값은 예시입니다.

{
  "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는 다른 결제 또는 프로모션 금액과 비슷해 보일 수 있지만, 시스템에서는 각 금액을 별도로 취급해야 합니다.

Shop Cash가 포함된 주문에 대해 타사 시스템을 이용하기 전에 다음 요구 사항을 확인하십시오.

• Shop Cash는 결제 방법으로 매핑됩니다.
• Shop Cash 및 Shop Pay가 포함된 주문은 두 가지 결제 방법 모두와 함께 가져옵니다.
• 결제 방법 로직은 주문당 하나의 결제 방법을 가정하지 않습니다.
• 승인 값은 긴 불투명 문자열로 저장되며 잘리지 않습니다.
• 환불 로직으로 올바른 매입 거래를 환불할 수 있습니다.
• 환불 로직으로 올바른 결제 방법으로 자금을 반환할 수 있습니다.
• 지급액 조정에 Shop Cash 크레딧, 환불 및 캠페인 거래 유형을 반영할 수 있습니다.
• 주문 처리, 회계 및 반품 워크플로에서는 Shop Cash를 할인으로 취급하지 않습니다.

여러 시스템을 사용하는 경우 주문, 거래, 지급액, 주문 처리, 환불 또는 반품 데이터를 수신하는 각 시스템에 대해 이 검토를 완료하십시오.