상품권 결제 연동
상품권 결제를 연동하면 상품권 계정 로그인 혹은 상품권 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(successUrl과 failUrl)은 필수 파라미터입니다.
통신사 정보(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
}