가이드
목차

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

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

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

API 키 준비하기

API 개별 연동 키로 연동하세요.

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

JavaScript
// API 개별 테스트 연동 키
// 토스페이먼츠에 회원 가입하기 전이라면 아래 키는 문서 테스트 키입니다.
// 토스페이먼츠에 회원 가입하고 로그인한 상태라면 아래 키는 내 테스트 키입니다.
const clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq'
const secretKey = 'test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R'

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

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 인증 결과의 코드 값입니다.

응답

요청
curl --request POST \
--url https://api.tosspayments.com/v1/virtual-accounts \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"amount":15000,"orderId":"a4CWyWY5m89PNh7xJwhk1","orderName":"토스 티셔츠 외 2건","customerName":"김토스","bank":"20"}'
응답
JSON
{
"mId": "tosspayments",
"lastTransactionKey": "3317701984FAAF9314CA656D8445AC0C",
"paymentKey": "tviva20240213122236SiRN7",
"orderId": "MC4yMjk3NDUyMDUwMzk1",
"orderName": "토스 티셔츠 외 2건",
"taxExemptionAmount": 0,
"status": "WAITING_FOR_DEPOSIT",
"requestedAt": "2024-02-13T12:22:36+09:00",
"approvedAt": null,
"useEscrow": false,
"cultureExpense": false,
"card": null,
"virtualAccount": {
"accountNumber": "X6516292118962",
"accountType": "일반",
"bankCode": "20",
"customerName": "김토스",
"dueDate": "2024-02-20T12:22:36+09:00",
"expired": false,
"settlementStatus": "INCOMPLETED",
"refundStatus": "NONE",
"refundReceiveAccount": null
},
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": null,
"cashReceipts": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "NORMAL",
"easyPay": null,
"easyPayAmount": 0,
"easyPayDiscountAmount": 0,
"country": "KR",
"failure": null,
"isPartialCancelable": true,
"receipt": {
"url": "https://pgweb.tosspayments.com:9091/MpFlowCtrl?eventDiv1=search&eventDiv2=getCasReceiptList&trxid=tviva20240213122236SiRN7&SYSTEM=NEW"
},
"checkout": {
"url": "https://api.tosspayments.com/v1/payments/tviva20240213122236SiRN7/checkout"
},
"currency": "KRW",
"totalAmount": 1000,
"balanceAmount": 1000,
"suppliedAmount": 909,
"vat": 91,
"taxFreeAmount": 0,
"method": "가상계좌",
"version": "2022-11-16"
}
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    실시간 문의|이메일 보내기