1. 개요
본 문서는 해외 개발자 들이 국내 카드, 국내 간편결제(토스페이, 네이버페이, 카카오페이)를 비롯한 다양한 국내 결제 수단에 대해 연동 후 테스트를 진행할 때 참고하도록 제공되는 가이드 입니다.
여기에서 제공되는 안내사항은 모두 관련 계약을 진행한 MID 의 test 키를 이용할 때만 가능하고, live 키를 사용할때는 동작되지 않습니다. 개발 연동 테스트 상점의 MID 로는 정상적으로 테스트 가능하지 않을 수 있습니다.
live 에서는 테스트를 하시려면, 실제 해당 결제수단이 있어야 가능합니다.
연동문서는 docs.tosspayments.com 에서 확인하시면 됩니다. 만약 해당 페이지에서 찾을수 없는 경우 해당 결제수단에 대해 계약을 진행하시고 techsupport@tosspayments.com 으로 계약하신 MID 정보와 함께 요청하시면 받으실 수 있습니다.
2. 결제 모듈별 가이드
현재 지원하는 방식은 모든 개발 수단에 대해 사용이 가능하지만 응답은 카드 결제로 고정되어 하고 있습니다. 인증, 승인 과정을 연동하기 위한 용도로 사용해 주셔야 하며, 실제 응답의 정합성은 라이브 환경에 실제 결제수단으로 해주시기 바랍니다.
2-1. 결제창, SDK V1, requestPayments() method
requestPayments 를 호출하는 JSON 파라미터에
1.
“_skipAuth” : “FORCE_SUCCESS”
를 추가해서 호출하면 결제창 UI 를 스킵하고 바로 인증이 성공된 것으로 처리 되어 아래와 같이 동작합니다.
- Promise 방식 : RequestPaymentResult 를 반환
- Redirect 방식 : successURL 로 이동
2.
“_skipAuth” : “FORCE_FAIL”
를 추가해서 호출하면 결제창 UI 를 스킵하고 바로 인증이 실패된 것으로 처리 되어 아래 에러가 고정으로 반환됩니다.
- Promise 방식 : {"code":"REJECT_CARD_COMPANY", "message" : "카드사 거절"} 를 반환
- Redirect 방식 : code=REJECT_CARD_COMPANY&message=카드사 거절 와 함께 failURL 로 이동
이후에 confirm API 를 호출하면 요청한 결제수단과 무관하게 모두 카드 결제수단으로 응답은 표시 됩니다. 카드 정보는 아래와 같이 더미 값으로 고정됩니다.
"issuerCode":"61","acquirerCode":"61","number":"94313300***123*","installmentPlanMonths":0,"isInterestFree":false,"interestPayer":null,"approveNo":"00000000","useCardPoint":false,"cardType":"신용","ownerType":"개인"
2-2. 결제위젯, SDK V1, requestPayments() method
requestPayments 를 호출하는 JSON 파라미터에
1.
“_skipAuth” : “FORCE_SUCCESS”
를 추가해서 호출하면 결제창 UI 를 스킵하고 바로 인증이 성공된 것으로 처리 되어 아래와 같이 동작합니다.
- Promise 방식 : RequestPaymentResult 를 반환
- Redirect 방식 : successURL 로 이동
2.
“_skipAuth” : “FORCE_FAIL”
를 추가해서 호출하면 결제창 UI 를 스킵하고 바로 인증이 실패된 것으로 처리 되어 아래 에러가 고정으로 반환됩니다.
- Promise 방식 : {"code":"REJECT_CARD_COMPANY", "message" : "카드사 거절"} 를 반환
- Redirect 방식 : code=REJECT_CARD_COMPANY&message=카드사 거절 와 함께 failURL 로 이동
이후에 confirm API 를 호출하면 요청한 결제수단과 무관하게 모두 카드 결제수단으로 응답은 표시 됩니다. 카드 정보는 아래와 같이 더미 값으로 고정됩니다.
"issuerCode":"61","acquirerCode":"61","number":"94313300***123*","installmentPlanMonths":0,"isInterestFree":false,"interestPayer":null,"approveNo":"00000000","useCardPoint":false,"cardType":"신용","ownerType":"개인"
2-3. 결제창, SDK V2, requestPayments() method
requestPayments 를 호출하는 JSON 파라미터에
1.
sandbox: {paymentResult: 'SUCCESS'}
를 추가해서 호출하면 결제창 UI 를 스킵하고 바로 인증이 성공된 것으로 처리 되어 아래와 같이 동작합니다.
- Promise 방식 : RequestPaymentResult 를 반환
- Redirect 방식 : successURL 로 이동
2.
sandbox: {paymentResult: 'FAIL'}
를 추가해서 호출하면 결제창 UI 를 스킵하고 바로 인증이 실패된 것으로 처리 되어 아래 에러가 고정으로 반환됩니다.
- Promise 방식 : {"code":"REJECT_CARD_COMPANY", "message" : "카드사 거절"} 를 반환
- Redirect 방식 : code=REJECT_CARD_COMPANY&message=카드사 거절 와 함께 failURL 로 이동
이후에 confirm API 를 호출하면 요청한 결제수단과 무관하게 모두 카드 결제수단으로 응답은 표시 됩니다. 카드 정보는 아래와 같이 더미 값으로 고정됩니다.
"issuerCode":"61","acquirerCode":"61","number":"94313300***123*","installmentPlanMonths":0,"isInterestFree":false,"interestPayer":null,"approveNo":"00000000","useCardPoint":false,"cardType":"신용","ownerType":"개인"
2-4. 결제위젯, SDK V2, requestPayments() method
requestPayments 를 호출하는 JSON 파라미터에
1.
sandbox: {paymentResult: 'SUCCESS'}
를 추가해서 호출하면 결제창 UI 를 스킵하고 바로 인증이 성공된 것으로 처리 되어 아래와 같이 동작합니다.
- Promise 방식 : RequestPaymentResult 를 반환
- Redirect 방식 : successURL 로 이동
2.
sandbox: {paymentResult: 'FAIL'}
를 추가해서 호출하면 결제창 UI 를 스킵하고 바로 인증이 실패된 것으로 처리 되어 아래 에러가 고정으로 반환됩니다.
- Promise 방식 : {"code":"REJECT_CARD_COMPANY", "message" : "카드사 거절"} 를 반환
- Redirect 방식 : code=REJECT_CARD_COMPANY&message=카드사 거절 와 함께 failURL 로 이동
이후에 confirm API 를 호출하면 요청한 결제수단과 무관하게 모두 카드 결제수단으로 응답은 표시 됩니다. 카드 정보는 아래와 같이 더미 값으로 고정됩니다.
"issuerCode":"61","acquirerCode":"61","number":"94313300***123*","installmentPlanMonths":0,"isInterestFree":false,"interestPayer":null,"approveNo":"00000000","useCardPoint":false,"cardType":"신용","ownerType":"개인"
2-5. 빌링, SDK V1, requestPayments() method
토스페이먼츠 빌링 결제창을 통해 테스트로 빌링키를 발급하기 위한 과정을 설명합니다.
결제창에 아래와 같이 정보를 입력합니다.
•
개인카드 선택
•
카드 번호는 한국에서 발급한 유효한 BIN 번호이기만 하면 다른 번호는 아무렇게나 넣어도 관계없습니다.
•
유효기간은 미래의 월/년을 넣습니다.
•
이름은 임의로 아무값이나 넣습니다.
•
주민등록 번호는 000101-1 로 넣습니다.
•
통신사는 아무거나 선택한 후 휴대폰 번호는 01000001234 로 입력합니다.
•
인증번호는 000000 으로 넣으면 됩니다.
2-6. 빌링, SDK V2, requestPayments() method
토스페이먼츠 빌링 결제창을 통해 테스트로 빌링키를 발급하기 위한 과정을 설명합니다.
결제창에 아래와 같이 정보를 입력합니다.
•
개인카드 선택
•
카드 번호는 한국에서 발급한 유효한 BIN 번호이기만 하면 다른 번호는 아무렇게나 넣어도 관계없습니다.
•
유효기간은 미래의 월/년을 넣습니다.
•
이름은 임의로 아무값이나 넣습니다.
•
주민등록 번호는 000101-1 로 넣습니다.
•
통신사는 아무거나 선택한 후 휴대폰 번호는 01000001234 로 입력합니다.
•
인증번호는 000000 으로 넣으면 됩니다.
3. 결제 API별 가이드
3-1. 키인 API
키인 API 를 이용해서 카드 결제를 연동하는 경우 테스트 하는 방법에 대해 설명합니다.
국내카드의 경우
•
카드 번호는 한국에서 발급한 유효한 BIN 번호이기만 하면 다른 번호는 아무렇게나 넣어도 관계없습니다.
•
유효기간은 미래의 월/년을 넣습니다.
•
생년월일은 000101 로 입력합니다.
를 넣고 결제를 진행합니다.
이 때, 잘못된 BIN 을 보내게 되면 아래와 같은 에러가 응답됩니다.
정상적으로 호출되었다면 보낸 카드 번호를 기반으로 결제 성공 응답을 받을 수 있습니다.
3-2. 빌링 API
빌링 API 를 이용해서 빌링키를 발급받는 경우 테스트 하는 방법에 대해 설명합니다.
빌링 API 도 빌링 결제창과 동일한 정보가 필요합니다. 다만 본인인증은 하지 않습니다.
•
카드 번호는 한국에서 발급한 유효한 BIN 번호이기만 하면 다른 번호는 아무렇게나 넣어도 관계없습니다.
•
유효기간은 미래의 월/년을 넣습니다.
•
생년월일은 000101 로 입력합니다.
를 넣고 빌링키 요청을 진행합니다.
이 때, 잘못된 BIN 을 보내게 되면 아래와 같은 에러가 응답됩니다.
정상적으로 호출되었다면 보낸 카드 번호를 기반으로 빌링키 발급 성공 응답을 받을 수 있습니다.
해당 빌링키로 자동결제 API 를 통해 결제를 요청하면 됩니다