[프론트 플러그인] 무카드 취소의 VAN 거래 일련번호 제공 범위가 궁금합니다

[coffeeya]

어떤 제품을 사용하나요?

• 제품: 프론트 플러그인
• SDK 또는 API 버전: 프론트 SDK v0 (https://cdn.tossplace.com/toss-front-sdk/v0/index.js)
• 환경: 개발

무엇이 궁금한가요?

프론트 단말기의 카드 결제를 카드 인식 없이 취소하려면 requestCardlessPaymentCancel을 써야 하는 것으로 이해했습니다. 이 API는 vanTransactionKey가 필수이고, 문서의 지원 범위는 VAN NICE, 결제수단 CARD입니다.

승인 응답의 vanTransactionKey는 선택 값으로 안내되어 있습니다. VAN사와 결제 환경에 따라 내려오지 않을 수 있다고 되어 있고, 이 값을 요청하는 파라미터는 없습니다.

테스트 단말기는 VAN이 KSNET이고, 카드 승인 응답의 vanTransactionKey는 빈 문자열이었습니다. 그래서 무카드 취소는 호출하지 않고, 카드를 다시 읽는 requestPaymentCancel만 사용하고 있습니다.

가맹점에 프론트 단말기를 NICE VAN으로 요청하면 vanTransactionKey를 받을 수 있는지 알고 싶습니다. 받을 수 있다면, 그 값이 내려오는 카드사와 페이 범위를 정확히 알고 싶습니다.

확인을 요청드리는 내용입니다.

가맹점 프론트를 NICE로 계약하면 카드 승인 응답에 vanTransactionKey가 항상 오는지, 그래도 비어 있을 수 있는지
card.van이 NICE일 때만 오는지, NICEPAY도 포함되는지
결제수단 CARD 안에서 신용카드, 체크카드, 삼성페이, 애플페이가 모두 포함되는지
간편결제(BARCODE)인 토스페이, 네이버페이, 카카오페이, 알리페이, 위챗페이는 제외되는지
카드 발급사나 매입사에 따라 값이 빠지는 경우가 있는지
값을 받을 수 있는 범위만 알려주시면, 그 범위 밖은 카드를 다시 읽는 전액 취소로 두겠습니다.

감사합니다

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

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

무카드 취소의 지원 범위와 VAN 거래 일련번호 확인 기준을 안내 드립니다.

1. NICE 계약과 vanTransactionKey 반환
NICE로 계약하더라도 vanTransactionKey가 모든 승인 응답에 항상 반환되는 것은 보장하지 않습니다.
해당 값은 VAN사와 결제 환경에 따라 비어 있을 수 있으므로, 계약한 VAN만으로 판단하지 말고 실제 승인 응답에 값이 있는지 확인해 주세요. 값을 요청하기 위한 별도 파라미터를 추가하는 방식은 아닙니다.

2. VAN·결제수단별 적용 범위
requestCardlessPaymentCancel의 현재 지원 범위는 NICE·CARD입니다. NICEPAY와 KSNET은 이 API의 지원 범위에 포함되지 않습니다.
신용카드·체크카드와 삼성페이·애플페이는 결제 결과가 CARD로 반환된 경우 위 기준으로 판단하되, 해당 수단이라는 이유만으로 vanTransactionKey 수신을 보장하지는 않습니다.
토스페이·네이버페이·카카오페이·알리페이·위챗페이가 BARCODE로 처리된 거래는 이 무카드 취소 API의 대상이 아닙니다.

3. 발급사·매입사 구분과 취소 처리
발급사·매입사별로 값이 항상 제공되는 목록을 기준으로 구현하기보다는, NICE·CARD 여부와 실제 vanTransactionKey 수신 여부를 함께 확인해 분기해 주세요.
원 승인 응답에 유효한 값이 있으면 다른 원거래 정보와 함께 저장해 무카드 취소에 사용하고, 값이 없는 카드 거래는 현재 구현하신 requestPaymentCancel 방식으로 처리해 주세요.
BARCODE 거래의 취소는 해당 결제수단의 일반 취소 절차를 적용해야 하며, 카드 재인식 방식과는 구분해 주세요.

Payment API의 무카드 취소 및 승인 응답 안내를 참고해 주세요.