결제 테스트 가이드

프론트 플러그인에서 결제 기능을 테스트하는 방법과 주의사항을 안내합니다.

결제 시스템 구조

결제 처리 흐름

1. 플러그인: 결제 요청 및 결과 처리
2. 프론트 SDK: 플러그인과 결제앱 연결
3. 결제앱: 실제 결제 처리 (카드 리더기 등)
4. VAN: 결제 네트워크 중계
5. 카드사: 최종 승인 처리

주의 사항

프론트에서 카드 결제 테스트 시 실제 승인이 발생하여 주의가 필요합니다.

주의 사항

[카드 결제 테스트 시]

• 테스트 후 반드시 즉시 취소 처리 필요
• 결제 응답의 paymentKey, approvalNumber, timestamp 등 승인 취소를 위한 값을 저장하여 취소에 활용

[권장 테스트 방법]

• 동작 확인 목적이라면 현금 결제 > 현금영수증 미발급으로 테스트 권장
• 실제 금전적 부담 없이 결제 플로우 확인 가능

결제 API

결제/결제 취소 API는 여기서 확인하실 수 있습니다.

결제 기능 구현 예시

기본 결제 요청

const paymentKey = ""; // 최대 64자리 랜덤 문자열 (내부 관리 필요)
const amount = 1004;
const tax = Math.floor(amount / 11);
const supplyValue = amount - tax;

try {
    const result = await sdk.payment.requestPayment({
        paymentKey,
        tax,
        supplyValue,
        tip: 0,
        timeoutMs: 60000,
    });

    if (result.type === "SUCCESS") {
        return handlePaymentSuccess(result.response);
    } else {
        return handlePaymentFailure(result.type);
    }
} catch (error) {
    console.error("결제 요청 실패:", error);
    handlePaymentError(error);
    throw error;
}

지원 결제수단

1. 카드 결제:

   • IC카드 (권장)
   • 마그네틱 카드
   • NFC 결제 (삼성페이, 애플페이 등)

2. 간편결제:

   • QR/바코드 (토스페이, 카카오페이, 네이버페이 등)

3. 현금:

   • 현금영수증 발행 가능

승인 취소 기능 구현 예시

승인 취소

try {
    const result = await sdk.payment.requestPaymentCancel({
        paymentKey,  // 승인 시 요청한 paymentKey
        paymentMethod,  // 승인 시 사용한 paymentMethod
        tax,
        supplyValue,
        tip: 0,
        timestamp: 1723628943812,  // 승인 결과로 받은 timestamp
        approvalNumber: "000000000",  // 승인 결과로 받은 approvalNumber
        installment: 0,  // 승인 결과로 받은 installment
        timeoutMs: 60000,
        extraData: originalPayment.extraData
    });

    if (result.type === "SUCCESS") {
        return handleCancelSuccess(result.response);
    } else {
        return handleCancelFailure(result.type);
    }
} catch (error) {
    console.error("취소 요청 실패:", error);
    handleCancelError(error);
    throw error;
}

취소 제약사항

• 전액 취소: 부분 취소는 지원하지 않음

제품 출시 전 확인사항

필수 체크리스트

• [ ] 모든 결제수단 정상 동작 확인
• [ ] 부가세 계산 정확성 확인
• [ ] 취소 기능 정상 동작 확인
• [ ] 에러 상황별 적절한 메시지 표시
• [ ] 결제 데이터 정확한 저장/전송
• [ ] 네트워크 오류 시 안정적 처리

운영 고려사항

1. 로그 관리: 결제 관련 모든 이벤트 로깅
2. 보안: 결제 정보 암호화 전송
3. 모니터링: 결제 성공률 실시간 모니터링
4. 백업: 중요 결제 데이터 백업 체계

문의사항

결제 테스트 관련 문의는 developer-support@tossplace.com으로 연락주세요.