Version 1

카드 번호 결제(키인 결제) API로 연동하기

결제창 SDK v1은 더 이상 업데이트되지 않습니다. 토스페이먼츠 SDK v2 연동을 추천합니다.

✅ 카드 번호 결제 API로 카드 번호 결제를 연동하세요. (서버 투 서버)

✅ 카드 번호 결제는 직접 카드 번호를 입력해서 결제하는 비인증 결제로 '수기 결제', '키인(Key-in) 결제'라고 불리기도 합니다.

카드 번호 결제 API는 추가 심사 후 사용할 수 있습니다. 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

API 키 준비하기

토스페이먼츠에 회원가입하기 전이라면, 다음 문서 테스트 키로 연동할 수 있어요. 토스페이먼츠에 회원가입했다면, 로그인 후 다음 내 테스트 키로 결제를 연동하고 개발자센터에서 테스트 결제내역을 확인하세요.

토스페이먼츠와 계약할 때 비밀번호와 카드 소유자의 생년월일 필드를 필수 파라미터로 추가할 수 있는 옵션을 선택하면 해당 필드도 필수 파라미터가 됩니다. 계약할 때 선택한 옵션에 따라 필수 파라미터를 추가해주세요.

API 호출하기

POST/v1/payments/key-in

* 카드 번호 결제 API는 추가 계약 후 사용할 수 있습니다. 추가 계약을 하고 싶다면 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 문의해주세요.

결제할 카드 번호 및 기타 카드 정보로 결제를 요청합니다.

Request Body 파라미터

amount 필수 · integer
결제할 금액입니다.
orderId 필수 · string
주문번호입니다. 주문한 결제를 식별합니다. 충분히 무작위한 값을 생성해서 각 주문마다 고유한 값을 넣어주세요. 영문 대소문자, 숫자, 특수문자 -, _로 이루어진 6자 이상 64자 이하의 문자열이어야 합니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다.
cardNumber 필수 · string
카드 번호입니다. 최대 길이는 20자입니다.
cardExpirationYear 필수 · string
카드 유효 연도입니다.
cardExpirationMonth 필수 · string
카드 유효 월입니다.
orderName 필수 · string
구매상품입니다. 예를 들면 생수 외 1건 같은 형식입니다. 최대 길이는 100자입니다.
customerIdentityNumber 필수 · string
카드 소유자 정보입니다. 생년월일 6자리(YYMMDD) 혹은 사업자등록번호 10자리가 들어갑니다.
cardPassword string
카드 비밀번호 앞 두 자리입니다.
cardInstallmentPlan integer
신용 카드의 할부 개월 수입니다. 값을 넣으면 해당 할부 개월 수로 결제가 진행됩니다. 2부터 12사이의 값을 사용할 수 있고, 0이 들어가면 할부가 아닌 일시불로 결제됩니다. 결제 금액이 5만원 이상일 때만 할부가 적용됩니다.
useFreeInstallmentPlan boolean
카드사 무이자 할부 적용 여부입니다. 기본값은 false입니다.
값이 true이면 cardInstallmentPlan에 지정한 할부 개월로 무이자 할부가 적용됩니다.
* 이 파라미터로 적용된 무이자 할부 비용은 상점이 부담합니다.
taxFreeAmount integer
결제할 금액 중 면세 금액입니다. 값을 넣지 않으면 기본값인 0으로 설정됩니다.
* 면세 상점 혹은 복합 과세 상점일 때만 설정한 금액이 적용되고, 일반 과세 상점에는 적용되지 않습니다. 더 자세한 내용은 세금 처리하기에서 살펴보세요.
customerEmail string
구매자의 이메일 주소입니다. 결제 상태가 바뀌면 이메일 주소로 결제내역이 전송됩니다. 최대 길이는 100자입니다.
customerName string
구매자명입니다. 최대 길이는 100자입니다.
vbv string
해외 카드 결제의 3DS 인증에 사용합니다. 3DS 인증 결과를 전송해야 되면 필수입니다.
cavv string
3D Secure 인증 세션의 인증 값입니다.
xid string
트랜잭션 ID입니다.
eci string
3DS 인증 결과의 코드 값입니다.

응답

성공

카드 번호 결제에 성공하면 Payment 객체가 돌아옵니다.

실패

카드 번호 결제에 실패했다면 HTTP 상태 코드와 함께 에러 객체가 돌아옵니다.

카드 번호 결제 API에서 발생할 수 있는 에러를 살펴보세요.