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

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

결제할 카드 번호 및 기타 카드 정보로 결제를 요청합니다. 토스페이먼츠와 계약할 때 비밀번호와 카드 소유자의 생년월일 필드를 필수 파라미터로 추가할 수 있습니다.

키인 결제는 구매자가 직접 카드 번호를 입력해서 결제해야 됩니다. 구매자의 카드번호를 저장하거나 토큰화 하여 저장하여 사용할 수 없습니다.

• 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에서 발생할 수 있는 에러를 살펴보세요.