Comment on page
📍
연동 유의사항
토스페이먼츠 (신 모듈) 연동 유의사항을 소개합니다.
아래 기능을 사용하시려면 토스페이먼츠에 사전 신청 후 계약이 완료되어야 합니다.
계약 하지 않은 경우 해당 기능 이용시 결제 승인에 실패하거나, 승인에 성공하더라도 의도한 바와는 다른 응답(결제창에서 에스크로 결제를 했으나 비-에스크로 결제 응답을 받음)을 얻게 될 수 있습니다.
- 간편결제 사용
- 면세 / 복합과세 사용
- 할부 사용
- 상점 부담 무이자 할부 사용
- 상품권 결제 사용
- 카드사 포인트 사용
- 에스크로 사용
display.card_quota 파라미터로 결제창에 렌더링 될 할부 개월수 리스트를 제어할 수 있습니다. 다른 PG사는 전달한 값만 렌더링 되지만, 토스페이먼츠의 경우에는 토스페이먼츠 자체 정책에 따라 일시불 ~ 전달한 값 중 최대값까지 모두 렌더링됩니다.
- 예1. 일시불만 허용display: {card_quota: [0]}
- 예2. 5개월만 허용display: {card_quota: [5]}
- 예3. [토스페이먼츠] 일시불 ~ 5개월까지 허용display: {card_quota: [3, 5] // 3과 5 중에 최대값이 5이기 때문에 일시불 ~ 5개월까지 모두 렌더링 된다}
- 예3. [타 PG사] 일시불 ~ 5개월까지 허용display: {card_quota: [0, 1, 2, 3, 4, 5]}
- 예4. [토스페이먼츠] 3개월과 5개월만 허용 → 불가능
- 예5. [타 PG사] 3개월과 5개월만 허용
가맹점은 토스페이먼츠와 사전 계약 또는 카드사 정책에 따라 무이자 할부 기능을 사용할 수 있습니다. 이에 따라 결제창 내에서 각 카드 사별 최대 무이자 할부 개월수에 따라 할부 개월수 옆에 “무이자” 또는 “무”라고 표기 됩니다.
- 예1. 삼성카드 - 최대 3개월 무이자 할부 적용 → 3개월까지 “무” 표기\
하지만 ISP 계열 카드의 경우에는 실제로 무이자 가 적용된다고 하더라도 “무이자” 여부가 표기되지 않습니다.
- 예2. BC카드 - 최대 12개월 무이자 할부 적용 → 표기 없음 → 실제 결제 승인시 무이자 할부 적용은 됨\
이는 ISP 계열 카드사 결제시 사용되는 페이북 앱 특성에 따른 것으로 실제 결제 승인시에는 정상적으로 무이자 할부가 적용됩니다.
모바일 웹 - 카드 결제시 토스페이먼츠 결제창 내에서 간편결제의 경우 할부 기간 선택이 불가능하고, 간편결제 외의 모든 카드사의 경우엔 할부 기간 선택이 가능합니다.
- 모바일 웹 - 간편결제 외 카드사: 할부 기간 선택 가능
- 모바일 웹 - 간편결제: 할부 기간 선택 불가능
반면, PC - 카드 결제 - ISP계열의 경우에는 토스페이먼츠 결제창 내에서도 할부 기간 선택이 불가능 하며, 대신 ISP 페이북 팝업에서는 선택이 가능합니다.
- PC - 카드결제 - ISP 선택: 할부 기간 선택 불가능
- PC - 카드결제 - ISP 선택 - 페이북 팝업: 할부 기간 선택 가능
다소 헷갈릴 수 있으나 간편결제는 간편결제 앱에서 할부 개월수를 선택할 수 있어 토스페이먼츠 결제창에서 선택할 수 없다는 토스 답변이 있었습니다.
토스페이먼츠는 카드사 다이렉트 호출시 quota 값을 전달하지 않는 경우에는 무조건 일시불로 결제가 됩니다.
따라서 카드사 다이렉트 호출시에는 반드시 구매자가 할부 개월수를 선택할 수 있는 UI/UX를 만들어주신 후 결제창 호출(IMP.request_pay)시 card.direct.quota값을 넘겨야 합니다.
- 예1. 현대카드 다이렉트 호출 → 무조건 일시불로 결제 됨card: {direct: {code: '367'}}
- 예2. 삼성카드 다이렉트 호출 + 5개월 고정 할부 개월수 지정 → 5개월 할부 적용{card: {direct: {code: '365',quota: 5}}}
카드사 다이렉트 호출시 quota 값을 보내도 실제로 카드사 결제창에서는 결제시 적용 될 할부 개월수를 확인할 수 없습니다. (물론 실제 승인시에는 전달한 quota값 만큼 할부 적용이 됨)
단, ISP 계열의 카드사인 경우에는 페이북 팝업에서 확인이 가능하며 이 값을 사용자가 변경 할 수는 없습니다.
- 예. BC카드 다이렉트 호출 + 5개월 고정 할부 개월수 지정\
card: {
direct: {
code: '361',
quota: 5
}
}
간편결제로는 여러가지 결제수단으로 결제 할 수도 있고 각 결제 수단을 혼합하여 복합 결제를 할 수도 있습니다. 이때 토스페이먼츠는 구매자가 정확히 어떤 방식으로 결제했는지 데이터를 내려주지 않으며 그 내용은 아래와 같습니다.
- 1.카드로 결제한 경우에는 카드 정보(카드사, 카드 유형 등)를 확인할 수 있습니다.
- 2.하지만 카드 외의 결제 수단으로 결제를 한 경우에는, 결제 수단 세부 정보(어떤 은행, 포인트, 머니인지)를 확인할 수 없습니다.
- 3.카드가 포함 된 결제 건인지 아닌지는 구분이 됩니다. 따라서 카드가 포함 된 결제 건이면 결제 수단을
card
로 기록합니다. - 4.하지만 계좌 / 포인트 / 머니 중 어떤 것으로 결제 됐는지 구분되지 않습니다. 따라서 카드가 포함 되지 않은 결제 건이면 결제 수단을
point
로 기록합니다. 실제로 등록된 계좌로 결제 됐다고 하더라도 포인트나 머니로 결제 된 것과 구분되지 않기 때문에 결제 수단을trans
로 저장하지 않습니다.
- 상품권 결제는 부분취소가 불가능
- 테스트 결제 건은 매출 전표 확인이 불가능
- 간편결제 - 카드 외의 결제 건은 매출 전표 확인이 불가능
- 간편결제 - L페이 결제창 배경 화면 투명도 이슈로 겹쳐보이는 현상
- cashReceiptType 파라미터로 인한 오동작 관련 이슈
IE 브라우저에서 결제 중단(결제 승인/실패 이전에 결제창을 명시적으로 닫을때)시 토스페이먼츠로부터 아래와 같이 인코딩 된 에러 메시지가 전달되는 이슈가 있습니다. (이를 디코딩해보면 “사용자가결제를취소하였습니다”라는 메시지)
%EC%82%AC%EC%9A%A9%EC%9E%90%EA%B0%80 %EA%B2%B0%EC%A0%9C%EB%A5%BC %EC%B7%A8%EC%86%8C%ED%95%98%EC%98%80%EC%8A%B5%EB%8B%88%EB%8B%A4
이에 대해 토스로부터 “IE 의 인코딩 이슈라서 저희가 수정해 드리기가 애매하고, 내부적으로 IE 는 fadeout 되어 더 이상 공식적으로 지원을 하지 않고 있습니다.”라는 답변을 받았습니다.
Last modified 6mo ago