카드 결제 연동

결제창에서 카드사를 선택하고 카드사 인증을 거쳐 결제할 수 있도록 연동해보세요.

카드 결제 흐름도

1 먼저, SDK를 준비하세요

스크립트를 삽입해서 SDK를 추가합니다.

<head>
<title>결제하기</title>
<script src="https://js.tosspayments.com/v1"></script>
</head>

클라이언트 키를 사용해 객체를 초기화합니다.

var clientKey = 'test_ck_OEP59LybZ8Bdv6A1JxkV6GYo7pRe'
var tossPayments = TossPayments(clientKey)

SDK 준비에 대한 더 자세한 설명은 연동 준비 페이지에서 확인할 수 있어요.

2 결제창을 호출하세요 🚀

초기화 된 객체를 이용해서 SDK에 포함된 메서드를 사용할 수 있습니다.

결제창 호출에 사용되는 메서드는 requestPayment입니다. 이 메서드를 실행하면 결제창이 열립니다.

requestPayment는 다음과 같이 사용합니다.

tossPayments.requestPayment({ 결제수단 }, { 결제정보 })

메서드 호출 준비하기

첫번째 파라미터는 결제수단입니다. 결제수단으로 '카드'를 추가하세요.

tossPayments.requestPayment('카드', {
amount: 15000,
orderId: '',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: window.location.origin + '/success',
failUrl: window.location.origin + '/fail',
})

두번째 파라미터는 결제정보입니다. 주문정보, 결제정보, 그리고 결제요청 결과에 따라 리다이렉트(Redirect) 될 URL을 추가해보세요.

tossPayments.requestPayment('카드', {
amount: 15000,
orderId: '',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: window.location.origin + '/success',
failUrl: window.location.origin + '/fail',
})

결제금액(amount), 주문 ID(orderId) 같은 주문정보와 결제요청 결과에 따라 리다이렉트 될 URL(successUrlfailUrl)은 필수 파라미터입니다.

선택적으로 카드 회사(cardCompany)나 고객이름(customerName)과 같은 정보를 추가할 수 있습니다.

결제정보 파라미터

  • amount 필수 · number

    결제되는 금액입니다.

  • orderId 필수 · string

    가맹점에서 사용하는 해당 주문에 대한 ID입니다. 각 주문마다 유니크해야 합니다.

  • orderName 필수 · string

    결제에 대한 주문명입니다. 예를 들면 '생수 외 1건' 같은 형식입니다.

  • successUrl 필수 · string

    결제가 성공하고 나면 리다이렉트(Redirect)되는 URL입니다. 결제승인 처리에 필요한 값들이 쿼리 파라미터(Query Parameter)로 함께 전달됩니다. 반드시 오리진(origin)을 포함해야 합니다. 예를 들면 https://www.example.com/success와 같은 형태입니다.

  • failUrl 필수 · string

    결제가 실패하면 리다이렉트되는 URL입니다. 에러코드 및 에러 메시지가 쿼리 파라미터로 함께 전송됩니다. 반드시 오리진(origin)을 포함해야 합니다.

  • cardCompany string

    카드사 코드입니다. 값이 있으면 카드사가 고정된 상태로 결제창이 열립니다.

    예를 들어, BC라는 값을 주면 BC카드로 고정된 결제창이 열립니다. 카드사 코드를 참조하세요.

  • cardInstallmentPlan number

    할부 개월 수입니다. 값이 있으면 할부 개월 수가 고정된 상태로 결제창이 열립니다.

    값은 2부터 12까지 사용할 수 있습니다. 0이 들어가는 경우 할부가 아닌 일시불로 결제됩니다.

    값을 따로 넣지 않으면 결제창에서 전체 할부 개월 수를 선택할 수 있습니다.

  • maxCardInstallmentPlan number

    선택할 수 있는 최대 할부 개월 수를 제한하기 위해 사용합니다. 할부 개월 수를 고정하는 cardInstallmentPlan 와 같이 사용할 수 없습니다.

    값은 2부터 12까지 사용할 수 있습니다. 0이 들어가는 경우 할부가 아닌 일시불로 결제됩니다.

    만약 값이 6 이라면 일시불~6개월 사이로 할부 개월을 선택할 수 있습니다.

  • useCardPoint boolean

    카드사 포인트를 사용했는지 여부입니다. 값을 주지 않으면 사용자가 카드사 포인트 사용 여부를 결정할 수 있습니다.

    이 값을 true로 주면 카드사 포인트 사용이 체크된 상태로 결제창이 열립니다. 이 값을 false로 주면 사용자는 카드사 포인트를 사용할 수 없습니다.

  • useAppCardOnly boolean

    카드사 앱카드로만 결제할지 여부를 결정합니다. 이 값을 true로 주면 카드사의 앱카드 결제창만 열립니다.

    카드사가 국민, 농협, 롯데, 삼성, 신한, 현대인 경우에만 true 값을 사용할 수 있습니다.

  • customerName string

    고객의 이름입니다. 최소 1글자 이상 최대 10글자 이하여야 합니다.

  • customerEmail string

    고객의 이메일주소입니다.

  • customerMobilePhone string

    고객의 휴대폰 번호입니다.

  • taxFreeAmount number

    면세금액입니다.

  • useInternationalCardOnly boolean

    해외카드(Visa, MasterCard, UnionPay)로 결제할 지 여부입니다. 값이 true면 해외카드 결제가 가능한 영문 결제창이 열립니다.

  • flowMode string

    값으로 DIRECT를 넣고 cardCompany 파라미터 값을 채우면 결제창의 약관 동의, 카드 선택 페이지를 건너뛰고 특정 카드사의 결제로 바로 연결됩니다.

    DEFAULT, DIRECT 중 하나의 값이 들어올 수 있습니다.

  • easyPay string

    간편결제 타입입니다. flowMode 값이 DIRECT여야 합니다.

    토스결제, 페이코, 삼성페이 중 하나의 값이 들어올 수 있습니다.

  • discountCode string

    카드사의 할인 코드입니다. flowMode 값이 DIRECT여야 합니다.

    카드혜택 조회 API를 통해 적용할 수 있는 할인 코드의 목록을 조회할 수 있습니다.

  • appScheme string

    모바일 ISP 앱에서 가맹점 앱으로 돌아오기 위해 사용됩니다. 가맹점의 앱 스킴을 지정하면 됩니다. 예를 들면 testapp://같은 형태입니다.

결제정보 파라미터는 결제수단에 따라 조금씩 달라집니다. 각 가이드에서 결제수단별 파라미터 구성을 확인해보세요.

결제창 띄우기

결제창 호출 준비를 마치고 requestPayment 메서드를 실행하면 결제창이 열립니다.

결제창을 띄워 선택한 결제수단, 결제정보를 잘 담고 있는지 확인하고 결제승인 요청 단계를 진행하세요.

3 결제승인을 요청하세요

리다이렉트 URL 확인하기

결제요청이 성공하거나 실패하면 위에서 설정한 successUrl, failUrl 로 이동합니다. URL에 포함된 쿼리 파라미터로 결제승인을 요청할 수 있습니다.

결제 성공 리다이렉트 URL에는 paymentKey, orderId, amount 세가지 쿼리 파라미터가 들어있습니다.

https://{origin}/success?paymentKey={paymentKey}&orderId={orderId}&amount={amount}
  • paymentKey: 결제 건에 대한 고유한 키 값입니다.
  • orderId: 가맹점에서 발급된 고유한 주문 ID값 입니다. 결제창을 열 때 requestPayment에 담아 보낸 값입니다.
  • amount: 실제로 결제된 금액입니다.

돌아온 파라미터를 이용해 결제승인 요청 API를 호출할 수 있습니다.

결제금액이 같은지 검증하기

결제창을 열 때 requestPayment메서드에 담아 보냈던 amount값과 리다이렉트 URL에 있는 실제 결제금액인 amount값이 같은지 확인해보세요.

값이 같다면 이제 결제승인 API를 호출할 준비가 되었습니다.

결제승인 API 호출하기

결제승인 API를 호출합니다. 리다이렉트 URL로 받은 값 중 paymentKey는 결제승인 API에 Path 파라미터로 추가하고, orderId, amount 값은 요청 본문으로 함께 보냅니다.

요청
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.tosspayments.com/v1/payments/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"))
    .header("Authorization", "Basic dGVzdF9ha19aT1J6ZE1hcU4zd1FkNWs2eWdyNUFrWVhRR3d5Og==")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"amount\":15000,\"orderId\":\"EhSGaD-KEJz7aSa7d4GFw\"}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

successUrl로 리다이렉트 된 후 10분 이내에 결제승인 API를 호출해야 합니다.

4 결제를 성공적으로 완료하셨네요! 🎉

승인 응답을 확인해보세요. API 호출 결과로 HTTP 상태 코드 200이 돌아오면 결제승인 성공입니다.

상태 코드와 함께 아래와 같은 응답 본문이 함께 돌아옵니다. 카드 결제승인 응답에는 card 필드가 포함되어 있어야 합니다.

응답
{
"mId": "tosspayments",
"version": "1.3",
"paymentKey": "5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6",
"orderId": "",
"orderName": "토스 티셔츠 외 2건",
"currency": "KRW",
"method": "카드",
"totalAmount": 15000,
"balanceAmount": 15000,
"suppliedAmount": 13636,
"vat": 1364,
"status": "DONE",
"requestedAt": "2021-01-01T10:01:30+09:00",
"approvedAt": "2021-01-01T10:05:40+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": {
"company": "현대",
"number": "433012******1234",
"installmentPlanMonths": 0,
"isInterestFree": false,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY",
"receiptUrl": "https://merchants.tosspayments.com/web/serve/merchant/test_ck_OEP59LybZ8Bdv6A1JxkV6GYo7pRe/receipt/5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6"
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "NORMAL",
"easyPay": null
}

응답 필드는 API 버전에 따라 조금씩 달라집니다. 돌아온 응답에 원하는 필드가 없다면 개발 정보 페이지에 설정된 API 응답 버전을 확인한 뒤 필요한 버전으로 변경해보세요.

  • 더 궁금한 내용이 있나요?자주 묻는 질문
  • 코드 샘플을 참고하세요TossPayments GitHub
  • 기술지원이 필요한가요?디스코드 채팅|이메일 보내기