결제 웹훅에서 간편결제(BARCODE), 외부결제(EXTERNAL)의 카드와선불 구분 방법

[배빵빵펭귄]

어떤 제품을 사용하나요?

• 제품: Open API
• SDK 또는 API 버전: 결제 웹훅 payment.payment.approved.v1
• 환경: 운영

무엇이 궁금한가요?

결제 웹훅에서 간편결제(BARCODE)와 외부 결제수단(EXTERNAL)이 카드 결제인지
선불 결제인지 판별할 수 있는 필드가 있는지 궁금합니다.

저희는 웹훅으로 받은 결제를 자체 시스템의 결제수단(카드 / 계좌이체 / 현금)으로
변환해 저장합니다. 카드와 선불은 정산이 달라 섞이면 안 되어, 판별이 되는 건만
받고 나머지는 보류하도록 만들어 두었습니다.

현재 판별에 쓰는 값은 easyPayDetails.payType 입니다. 문서상 값은
CARD / ACCOUNT / UNDEFINED 로 안내되어 있고, 실제로 이 값이 오는 건은
정상 처리하고 있습니다.

문제는 payType 이 null 이거나 easyPayDetails 자체가 없는 건입니다.
운영에서 받은 웹훅을 전수로 살펴보니 아래 네 가지 형태가 있었습니다.

1. paymentMethod: "BARCODE" · easyPayDetails 없음 · externalDetails.source 에 카드사 이름
2. paymentMethod: "BARCODE" · easyPayDetails 는 있으나 payType: null,
   같은 객체의 acquirer 에 카드사 이름 · externalDetails.source 에도 카드사 이름
3. paymentMethod: "EXTERNAL" · easyPayDetails 없음 ·
   externalDetails.source 에 간편결제 서비스 이름(선결제)
4. paymentMethod: "BARCODE" · payType: "CARD" 또는 "ACCOUNT" (정상 처리 중)

이에 아래 세 가지 질문드립니다.

1. payType 이 null 로 오는 조건이 무엇인가요?
   문서의 UNDEFINED 와 같은 뜻으로 보면 되는지, 아니면 다른 상황인지 궁금합니다.
2. externalDetails.source 는 카드사 이름과 간편결제 서비스 이름이 같은 칸에
   들어오는 것으로 보입니다. 이 값의 가능한 형태가 정해져 있는지,
   문자열 비교로 카드 여부를 판단해도 되는지 알고 싶습니다.
3. 위 1~3번 같은 건을 카드인지 선불인지 가릴 수 있는 다른 필드가 있을까요?
   cardDetails 는 이 건들에서 모두 빈 객체로 왔습니다.
   (paymentMethod 가 IC·SAMSUNG_MST 등인 건은 cardDetails 에 값이 채워져 옵니다)

추가로, paymentMethod 의 가능한 값 전체 목록이 문서에 있으면 위치를 알려주시면
감사하겠습니다(또는 답글로 값 목록 회신 부탁드립니다). 현재 레퍼런스에는 예시 한 개만 나와 있어, 저희가 운영에서 관측한
값(IC, SAMSUNG_MST, SAMSUNG_NFC, MSR, APPLE_PAY, BARCODE, EXTERNAL,
ACCOUNT_TRANSFER, CASH)만 알고 있는 상태입니다.

[토스플레이스-개발자센터]

안녕하세요. 토스플레이스 개발자센터입니다.

문의하신 내용에 대해 안내 드립니다.

1. payType이 null로 전달되는 경우

VAN사·결제수단별로 제공되는 정보가 달라, 카드·계좌 여부를 식별할 수 없으면 null로 전달될 수 있습니다.

null과 UNDEFINED는 서로 다른 값이지만, 두 경우 모두 카드·선불 여부를 확정하는 근거로 사용할 수 없습니다.

2. externalDetails.source를 이용한 구분

해당 값은 결제수단명으로, 카드사명이나 간편결제·머니 명칭이 들어올 수 있으며 VAN사별 표기도 다릅니다.

따라서 카드사 이름이 포함되어 있다는 이유만으로 카드 결제로 분류하지 않도록 처리해 주세요.

3. 다른 필드를 이용한 구분

문의하신 것처럼 payType 정보가 없고 cardDetails도 비어 있다면, 토스플레이스에서도 해당 거래의 카드·선불 여부를 판단할 수 없습니다. 현재처럼 구분되지 않는 거래는 미분류·보류 처리해 주세요.

참고로 payType의 ACCOUNT는 계좌를 의미하며, 선불을 뜻하는 값은 아닙니다.

4. paymentMethod 전체 목록

paymentMethod의 전체 값 목록은 별도로 제공하지 않습니다. 공개된 sourceType과 결제수단별 상세 필드를 기준으로 처리하되, 구분 정보가 없는 거래를 임의로 분류하지 않도록 부탁 드립니다.

자세한 필드 설명은 결제 API 가이드를 참고해 주세요.

[배빵빵펭귄]

@토스플레이스-개발자센터

감사합니다. 답변주신 대로 판별 불가 건은 보류 처리하도록 유지하되 판별 가능한 범위를 좁혀보려 합니다. 세 가지 추가로 문의드립니다.

1. settlement 로 카드 매입 여부를 판별할 수 있는지

payType: null인 경우에도 settlement가 응답값에 포함되어 있습니다.

{
  "paymentMethod": "BARCODE",
  "cardDetails": null,
  "easyPayDetails": {
    "provider": "카카오페이",
    "acquirer": "우리",
    "acquirerId": "0103",
    "payType": null
  },
  "settlement": {
    "settlementType": "ACQUIRER",
    "settlementSubject": "우리"
  }
}

settlementType: "ACQUIRER"가 '매입사 정산 = 카드 매입 발생'을 의미한다고 봐도 되는지 궁금합니다.

다만 payType: "ACCOUNT"인 건도 settlementType은 동일하게 ACQUIRER였고 settlementSubject만 간편결제사명이었습니다. 그래서 settlementType단독으로는 판별이 불가능한 것 같아 보이는데, 맞는지 확인 부탁드립니다.

2. easyPayDetails.acquirer의 값 집합

문서 예시가 "토스머니" 입니다. 이 필드가 카드사명과 선불수단명을 모두 담는 자유 스트링으로 이해하면 될까요?

지금까지 저희 쪽에 들어온 데이터들은 전부 카드사명(우리·하나카드·비씨)이었으나, 표본이 적어 일반화하지 않으려 합니다.

앞선 답변의 externalDetails.source안내를 '스트링 비교로 카드 여부를 판정하지 말 것'으로 이해했는데, 같은 기준이 acquirer에도 적용되는지 궁금합니다.

3. acquirerId의 코드 체계

문서 예시는 "TS"인데 저희 수신값은 "0103", "0300"형태의 숫자 문자열입니다. 가맹점 VAN 은 KCP 입니다.

이 값이 VAN에서 그대로 받아온 값인지, 토스플레이스에서 정규화한 코드인지 궁금합니다. 전자라면 VAN사별로 체계가 달라지는지, 후자라면 전체 코드 목록을 확인할 수 있는지 알려주시면 감사하겠습니다.

[토스플레이스-개발자센터]

안녕하세요. 토스플레이스 개발자센터입니다.

추가로 문의 주신 세 가지 항목 안내 드립니다.

1. settlement로 카드 결제 여부를 판단할 수 있나요?

settlementType이 ACQUIRER라는 이유만으로 카드 결제로 판단할 수는 없습니다. 정산 정보와 결제 재원 구분은 서로 다른 정보이므로, payType이 없는 건을 settlement 값으로 카드·선불로 확정하지 말아 주세요.

2. easyPayDetails.acquirer도 문자열 비교로 판단하면 안 되나요?

네. acquirer는 매입사명을 전달하는 문자열 필드이며, 가이드에도 ‘토스머니’와 같은 값이 예시로 포함되어 있습니다. 카드사명만 내려오는 고정 목록이 아니므로, 해당 이름을 비교해 카드·선불을 구분하지 않는 것이 맞습니다.

3. acquirerId는 어떤 코드인가요?

acquirerId는 VAN사에서 전달한 값입니다. 토스플레이스의 공통 정규화 코드로 해석하지 말아 주세요. 별도의 코드표는 제공하지 않습니다.

따라서 기존에 안내 드린 것처럼, 구분 정보가 없는 건은 임의로 카드나 선불로 분류하지 않고 판별 보류로 처리해 주세요. 결제 데이터 가이드를 참고해 주세요.