카페24 부분취소 API와 외부 정산 취소를 한 흐름으로 맞춘 사례

카페24 쇼핑몰에서 상품 일부만 취소하거나 환불하는 경우, 쇼핑몰의 주문 금액만 변경해서는 정산까지 자동으로 맞지 않을 수 있습니다.

특히 상품별 수수료, 후원 수당, 가맹점 수수료 등을 별도의 정산 시스템에서 관리하고 있다면 카페24의 부분취소와 외부 정산 금액을 함께 변경하는 연동이 필요할 수 있습니다.

이번 사례에서는 카페24 주문의 일부 상품만 취소했을 때 외부 정산 시스템에서도 같은 기준으로 금액이 취소되도록 카페24 부분취소 API와 외부 정산 API를 별도 서버에서 연결했습니다.

이번 사례는 카페24 쇼핑몰과 외부 정산 시스템을 함께 사용하는 쇼핑몰에서 발생했습니다.

하나의 주문에 여러 상품이 들어 있고, 상품마다 수수료와 후원 수당이 다르게 계산되는 구조였습니다.

예를 들어 한 주문에 상품 A와 상품 B가 함께 들어왔는데 상품 A만 취소했다면 카페24에서는 상품 A의 취소가 정상적으로 처리됩니다.

하지만 외부 정산 시스템에는 상품 A의 정산 금액이 그대로 남아 있을 수 있습니다.

결국 다음과 같은 문제가 발생합니다.

주문량이 많아지면 이런 수작업 보정은 누락이나 중복 처리로 이어질 가능성이 높아집니다.

카페24 부분취소 API는 주문 전체가 아니라 주문의 특정 상품이나 수량만 취소하는 작업을 시스템에서 처리할 수 있도록 하는 API입니다.

예를 들어 다음과 같은 주문이 있다고 가정해 보겠습니다.

이 중 상품 B만 취소해야 한다면 전체 주문을 취소하는 것이 아니라 상품 B에 해당하는 부분만 취소해야 합니다.

이때 외부 정산 시스템에서도 상품 B에 해당하는 정산 금액과 수당을 함께 조정해야 한다면 카페24의 취소 처리와 정산 취소를 연결해야 합니다.

이번 연동에서는 카페24에서 취소가 발생한 후 운영자가 별도로 정산 시스템을 수정하는 방식 대신, 별도 서버가 취소 과정 전체를 관리하도록 구성했습니다.

기본적인 처리 흐름은 다음과 같습니다.

① 취소 요청 접수

관리 화면 또는 연동된 이벤트를 통해 취소 요청을 받습니다.

↓

② 카페24 주문 확인

주문 상세 API를 이용해 현재 주문 상태와 취소 가능한 상품·수량을 확인합니다.

↓

③ 부분취소 금액 계산

상품, 옵션, 수량, 할인 등을 기준으로 실제 취소 대상 금액을 확인합니다.

↓

④ 카페24 부분취소 API 실행

검증된 내용을 기준으로 카페24에서 부분취소를 처리합니다.

↓

⑤ 외부 정산 취소

카페24 취소가 정상적으로 완료된 경우 외부 정산 시스템에서도 해당 상품의 수당·수수료·정산 금액을 취소합니다.

↓

⑥ 처리 결과 저장

성공, 실패, 재처리 필요 등의 상태를 서버에 기록합니다.

취소 요청이 들어왔다고 해서 항상 해당 상품을 그대로 취소할 수 있는 것은 아닙니다.

이미 일부 취소가 진행됐거나, 취소 가능한 수량이 달라졌을 수도 있기 때문입니다.

예를 들어 상품 A가 3개 주문됐고 이미 1개가 취소된 상태라면 현재 추가로 취소할 수 있는 수량은 2개입니다.

따라서 부분취소 API를 호출하기 전에 주문 상세 정보를 다시 확인해 다음 내용을 검증할 수 있습니다.

이러한 검증을 거친 후 카페24 부분취소 API를 호출하는 방식이 안전합니다.

두 시스템을 연결할 때는 어떤 작업을 먼저 실행할지도 중요합니다.

이번 사례에서는 다음과 같은 순서를 사용했습니다.

카페24 부분취소 성공 → 외부 정산 취소

카페24 취소가 실패했다면 외부 정산 취소를 실행하지 않습니다.

반대로 카페24 취소는 성공했지만 외부 정산 취소가 실패한 경우에는 해당 주문을 “정산 취소 재처리 필요” 상태로 남깁니다.

이렇게 하면 두 시스템 중 한쪽만 성공한 상황을 운영자가 확인할 수 있습니다.

정산 연동에서 특히 주의해야 하는 것이 중복 취소입니다.

예를 들어 같은 취소 요청이 실수로 두 번 전달되면 정산 금액이 두 번 차감될 수 있습니다.

이를 방지하기 위해 서버에서 취소 요청마다 고유한 멱등 키를 관리합니다.

예를 들어

주문번호 + 상품번호 + 취소 회차

와 같은 정보를 조합해 하나의 취소 작업을 식별할 수 있습니다.

이미 처리된 요청이라면 다시 정산 금액을 차감하지 않고 기존 처리 결과를 확인하도록 구성합니다.

이러한 방식으로 누락뿐 아니라 중복 처리도 방지할 수 있습니다.

부분취소에서 가장 먼저 정해야 할 부분 중 하나가 정산 금액 계산 기준입니다.

고객이 실제로 환불받는 금액과 외부 정산 시스템에서 차감해야 하는 금액이 항상 같지는 않기 때문입니다.

예를 들어 주문에 다음과 같은 금액이 포함될 수 있습니다.

이 중 어떤 금액을 상품별로 나눌 것인지에 따라 실제 정산 취소 금액이 달라질 수 있습니다.

따라서 개발 전에 “상품을 부분취소하면 정산에서는 어떤 금액을 차감하는가?”라는 기준을 먼저 정해야 합니다.

예를 들어 상품 A와 B를 함께 주문하면서 쿠폰 10,000원을 사용했다고 가정해 보겠습니다.

상품 A만 취소할 때 쿠폰 금액 10,000원을 전부 A에 적용할 것인지, 상품 A와 B에 나누어 적용할 것인지에 따라 취소 금액이 달라집니다.

배송비 역시 마찬가지입니다.

상품 일부를 취소해도 배송비가 그대로 남을 수 있고, 일정 조건에 따라 무료배송이 깨지면서 배송비가 다시 계산될 수도 있습니다.

따라서 부분취소 연동에서는 카페24에서 실제 환불되는 금액과 외부 정산에서 차감할 금액을 별도의 규칙으로 정의해야 합니다.

카페24 부분취소는 정상적으로 처리됐지만 외부 정산 시스템의 API 오류가 발생할 수도 있습니다.

이런 경우 카페24 주문을 다시 취소하는 방식으로 해결해서는 안 됩니다.

카페24 취소는 이미 완료된 상태이기 때문입니다.

대신 서버에 다음과 같이 상태를 기록할 수 있습니다.

카페24 취소 완료 → 정산 취소 실패 → 재처리 대기

운영자는 관리 화면에서 실패 사유를 확인하고 다시 정산 취소를 실행할 수 있습니다.

이렇게 하면 일시적인 API 오류나 네트워크 문제 때문에 정산 데이터가 영구적으로 누락되는 것을 줄일 수 있습니다.

금액과 직접 연결되는 시스템이기 때문에 단순 API 연결보다 오류 상황까지 고려해야 합니다.

주요 안전장치는 다음과 같습니다.

개발을 시작하기 전에 다음 내용을 정리하면 실제 개발 범위를 보다 정확하게 결정할 수 있습니다.

이 기준을 먼저 정해두면 개발 과정에서 취소 금액이나 정산 금액을 다시 해석하는 일을 줄일 수 있습니다.

상품 수가 적고 정산 구조가 단순하다면 카페24 관리자에서 부분취소를 처리하고 정산을 수동으로 관리하는 방법도 가능합니다.

반면 다음과 같은 쇼핑몰에서는 자동 연동의 필요성이 커질 수 있습니다.

특히 카페24 주문 취소와 외부 정산 데이터가 서로 다른 기준으로 관리되고 있다면, 두 시스템의 취소 기준을 하나의 서버에서 연결하는 방식을 검토할 수 있습니다.

옴니어스24는 카페24 엑스퍼트(Expert)를 통해 카페24 API와 외부 시스템을 연결하는 커스텀 개발을 진행합니다.

부분취소와 정산 연동은 단순히 API를 연결하는 것보다 어떤 상품이 취소됐는지, 얼마가 환불됐는지, 정산에서는 얼마를 차감해야 하는지를 먼저 정하는 것이 중요합니다.

따라서 개발 전에 카페24 주문 구조와 외부 정산 데이터를 확인하고, 상품·옵션과 정산 라인을 어떻게 연결할지 정합니다.

이후 별도 서버에서 취소 요청과 API 처리 상태를 관리하고, 중복 취소 방지와 실패 건 재처리까지 고려해 연동 구조를 구성할 수 있습니다.

테스트 환경에서 부분취소, 이미 취소된 상품, API 실패, 중복 요청 등의 상황을 먼저 확인한 뒤 실제 쇼핑몰에 적용하는 방식으로 진행할 수 있습니다.