상품권 결제를 연동하면 상품권 계정 로그인 혹은 상품권 PIN 번호 입력으로 잔액을 조회하고, 조회한 잔액으로 결제할 수 있습니다.
SDK를 추가한 뒤 클라이언트 키를 사용해 객체를 초기화합니다.
<head>
<title>결제하기</title>
<script src="https://js.tosspayments.com/v1"></script>
</head>
<body>
<script>
var clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq'
var tossPayments = TossPayments(clientKey) // 클라이언트 키로 초기화하기
</script>
</body>
SDK 준비에 대한 더 자세한 설명은 연동 준비 페이지에서 확인할 수 있습니다.
객체가 초기화 되었다면 이제 SDK에 포함된 메서드를 실행할 수 있습니다. 결제창 호출에 사용되는 메서드는 requestPayment입니다.
아래와 같이 tossPayments.requestPayment(결제 수단, 결제 정보)
형식으로 파라미터를 넣고 실행하면 결제창이 열립니다.
tossPayments.requestPayment('도서문화상품권', {
// 결제 수단 파라미터
// 결제 정보 파라미터
amount: 15000,
orderId: '',
orderName: '토스 티셔츠 외 2건',
customerName: '박토스',
successUrl: 'http://localhost:8080/success',
failUrl: 'http://localhost:8080/fail',
})
requestPayment
메서드의 첫번째 파라미터는 결제 수단입니다. 결제 수단으로 상품권 종류(도서문화상품권
, 게임문화상품권
, 문화상품권
) 중 한 가지를 추가하세요.
두 번째 파라미터는 결제 정보입니다. 필수 파라미터인 결제 금액(amount
), 주문 ID(orderId
)과 같은 주문 정보와 결제 요청 결과에 따라 리다이렉트 될 URL(successUrl
, failUrl
)을 추가하세요. 자세한 파라미터 정보는 아래에서 확인할 수 있습니다.
결제창을 띄웠을 때 위와 같이 선택한 결제 수단인 상품권 결제창이 뜨고, 입력한 결제 정보가 잘 담겨있다면 결제 승인을 요청하세요.
- amount 필수 · number
결제되는 금액입니다.
- orderId 필수 · string
상점에서 주문 건을 구분하기 위해 발급한 고유 ID입니다.
- orderName 필수 · string
결제에 대한 주문명입니다. 예를 들면
생수 외 1건
같은 형식입니다. - successUrl 필수 · string
결제가 성공하고 나면 리다이렉트(Redirect)되는 URL입니다. 결제 승인 처리에 필요한 값들이 쿼리 파라미터(Query Parameter)로 함께 전달됩니다. 반드시 오리진(origin)을 포함해야 합니다. 예를 들면
https://www.example.com/success
와 같은 형태입니다. - failUrl 필수 · string
결제가 실패하면 리다이렉트되는 URL입니다. 에러 코드 및 에러 메시지가 쿼리 파라미터로 함께 전송됩니다. 반드시 오리진(origin)을 포함해야 합니다.
- windowTarget string
브라우저에서 결제창이 열리는 프레임을 지정합니다.
self
,iframe
중 하나입니다.값을 넣지 않으면 iframe에서 결제창이 열립니다. 현재창에서 결제창으로 이동시키는 방식을 사용하려면 값을
self
로 지정하세요.* 모바일 웹에서는
windowTarget
값과 상관없이 항상 현재창에서 결제창으로 이동합니다. - customerName string
고객의 이름입니다. 최소 1글자 이상 최대 10글자 이하여야 합니다.
- customerEmail string
고객의 이메일 주소입니다.
- taxFreeAmount number
전체 결제 금액 중 면세 금액입니다. 값이 `0`으로 돌아왔다면 전체 결제 금액이 과세 대상입니다.*일반 상점일 때는 모든 결제 금액이 과세에 해당하기 때문에
0
이 돌아옵니다. 면세 상점, 복합 과세 상점일 때만 면세 금액이 돌아옵니다. 더 자세한 내용은 복합 과세 처리하기에서 살펴보세요.
결제 정보 파라미터는 결제 수단에 따라 조금씩 달라집니다. 각 가이드에서 결제 수단별 파라미터 구성을 확인해보세요.
결제 요청이 성공하거나 실패하면 위에서 설정한 successUrl
, failUrl
로 이동합니다. URL에 포함된 쿼리 파라미터로 결제 승인을 요청할 수 있습니다.
결제 성공 리다이렉트 URL에는 paymentKey
, orderId
, amount
세 가지 쿼리 파라미터가 들어있습니다.
https://{ORIGIN}/success?paymentKey={PAYMENT_KEY}&orderId={ORDER_ID}&amount={AMOUNT}
paymentKey
: 결제 건에 대한 고유한 키 값입니다.orderId
: 상점에서 주문 건을 구분하기 위해 발급한 고유 ID입니다. 결제창을 열 때requestPayment
에 담아 보낸 값입니다.amount
: 실제로 결제된 금액입니다.
돌아온 파라미터를 이용해 결제 승인 요청 API를 호출할 수 있습니다.
결제 요청에 실패했다면 결제 실패 URL 리다이렉트를 살펴보세요.
결제창을 열 때 requestPayment
메서드에 담아 보냈던 amount
값과 리다이렉트 URL에 있는 실제 결제 금액인 amount
값이 같은지 확인해보세요. 값이 같다면 이제 결제 승인 API를 호출할 준비가 되었습니다.
결제 승인 API를 호출합니다. 리다이렉트 URL로 받은 paymentKey
, orderId
, amount
를 요청 본문으로 함께 보냅니다.
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.tosspayments.com/v1/payments/confirm"))
.header("Authorization", "Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==")
.header("Content-Type", "application/json")
.method("POST", HttpRequest.BodyPublishers.ofString("{\"paymentKey\":\"z9avtS5nquoLuSn__J3Kx\",\"amount\":15000,\"orderId\":\"DA-1fACXSHZErrEqvZ8c7\"}"))
.build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
successUrl
로 리다이렉트 된 후 10분 이내에 결제 승인 API를 호출해야 합니다.
API 호출 결과로 HTTP 상태 코드 200이 돌아오면 결제 승인 성공입니다.
상태 코드와 함께 아래와 같은 응답 본문이 함께 돌아옵니다. 상품권 결제 승인 응답에는 항상 giftCertificate
필드가 포함 되어 있어야 합니다.
{
"mId": "tosspayments",
"version": "2022-06-08",
"paymentKey": "",
"status": "DONE",
"transactionKey": "",
"lastTransactionKey": "",
"orderId": "",
"orderName": "토스 티셔츠 외 2건",
"requestedAt": "2022-06-08T15:40:09+09:00",
"approvedAt": "2022-06-08T15:40:49+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": null,
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": {
"approveNo": "00000000",
"settlementStatus": "INCOMPLETE"
},
"cashReceipt": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "NORMAL",
"easyPay": null,
"country": "KR",
"failure": null,
"isPartialCancelable": true,
"receipt": {
"url": ""
},
"currency": "KRW",
"totalAmount": 15000,
"balanceAmount": 15000,
"suppliedAmount": 13636,
"vat": 1364,
"taxFreeAmount": 0,
"method": "도서문화상품권"
}