상품권 결제 연동

상품권 결제를 연동하면 상품권 계정 로그인 혹은 상품권 PIN 번호 입력으로 잔액을 조회하고, 조회한 잔액으로 결제할 수 있습니다.

상품권 결제 흐름도

1 먼저, SDK를 준비하세요

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

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

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

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

2 결제창을 호출하세요 🚀

결제창 호출에 사용되는 메서드는 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)은 필수 파라미터입니다. 통신사 정보(mobileCarrier)항목은 선택적으로 넣을 수 있습니다.

결제정보 파라미터

  • amount 필수 · number

    결제되는 금액입니다.

  • orderId 필수 · string

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

  • orderName 필수 · string

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

  • successUrl 필수 · string

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

  • failUrl 필수 · string

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

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

결제창 띄우기

결제창 호출 준비를 마치고 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\":\"_kJ1AQFv1S7Xc1HUGfz6v\"}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

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

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

API 호출 결과로 HTTP 상태 코드 200이 돌아오면 결제승인 성공입니다.

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

응답
{
"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": null,
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": {
"approveNo": "00000000"
},
"cashReceipt": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "NORMAL",
"easyPay": null
}

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

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