✅ 브랜드페이 JavaScript SDK로 브랜드페이 위젯을 생성하고 관리할 수 있어요.
✅ 빠르게 시작할 수 있는 위젯 샘플 프로젝트를 기반으로 작성된 가이드입니다.
토스페이먼츠에 회원가입하기 전이라면, 다음 문서 테스트 키로 결제위젯을 연동할 수 있어요.
토스페이먼츠에 회원가입했다면, 로그인 후 다음 내 테스트 키로 결제위젯을 연동하고 개발자센터에서 테스트 결제내역을 확인하세요.
// 문서 테스트 키
// 토스페이먼츠에 회원 가입하기 전이라면 아래 키로 자동결제를 연동하세요.
const clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq'
const secretKey = 'test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R'
// 내 테스트 키
// 토스페이먼츠에 회원 가입하고 자동결제를 추가 계약한 뒤 아래 키로 자동결제를 연동하세요.
// 로그인하면 문서의 API 키가 모두 내 테스트 키로 변경됩니다.
const clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq'
const secretKey = 'test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R'
토스페이먼츠와 계약을 완료했다면 상점 테스트 키로 브랜드페이를 연동하세요. 상점 테스트 키는 '상점관리자 > 매출 · 정산 관리 > 내 상점 이름 > 개발 정보'에서 확인하세요.
계약 문의는 토스페이먼츠 고객센터(1544-7772, support@tosspayments.com)로 해주세요.
토스페이먼츠에 회원가입했다면, 개발자센터의 브랜드페이 메뉴에서 리다이렉트 URL을 등록하세요. 리다이렉트 URL은 브랜드페이 사용자를 인증하는 과정에 필요합니다.
아래 예제 코드는 주문서 페이지에 브랜드페이 위젯을 그립니다. 아래와 같이 HTML에 브랜드페이 SDK를 추가하거나 @tosspayments/brandpay-sdk
npm 패키지를 사용해주세요. 실제로 결제되지 않으니 안심하세요.
<!DOCTYPE html>
<html lang="ko">
<head>
<meta charset="utf-8" />
<!--결제위젯 SDK 추가 -->
<script src="https://js.tosspayments.com/v1/brandpay"></script>
<link rel="stylesheet" type="text/css" href="/src/style" />
</head>
<body>
<div id="payment-method"></div>
<!-- 결제하기 버튼 -->
<button id="payment-button">결제하기</button>
</div>
<script>
const clientKey = "test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq";
const customerKey = ""; // 상점에서 고객을 구분하기 위해 발급한 고객의 고유 ID로 변경하세요.
const button = document.getElementById("payment-button");
// ------ 브랜드페이 초기화 ------
// 브랜드페이 MID와 연결된 clientKey를 입력하세요.
// customerKey로 나중에 해당 고객의 결제수단, 가입 상태를 관리할 수 있어요.
// redirectUrl은 인증에 필요합니다. 개발자센터에 등록된 URL을 입력해주세요.
const brandpay = BrandPay(clientKey, customerKey, {
redirectUrl: "https://my-store.com/callback-auth"
});
// ------ 브랜드페이 위젯 객체 생성 ------
// 결제 금액을 파라미터로 넣어주세요.
paymentMethodsWidget = brandpay.createPaymentMethodsWidget({
amount: 50000
});
// ------ 브랜드페이 렌더링 ------
// 위젯을 렌더링할 영역을 지정하는 CSS 선택자와 UI 옵션을 설정하세요.
paymentMethodsWidget.render("#payment-method");
// ------ 결제 금액 업데이트 ------
// 쿠폰 적용이나 할인 프로모션 등의 이유로 결제금액을 변경해야 된다면 updateAmount()를 사용하세요.
async function updateAmount(e) {
e.preventDefault();
paymentMethodsWidget.updateAmount(45000);
}
// ------ '결제하기' 버튼 누르면 결제창 띄우기 ------
// 더 많은 결제 정보 파라미터는 SDK 메서드에서 확인하세요.
button.addEventListener("click", handleSubmit);
async function handleSubmit(e) {
e.preventDefault();
// ------ 위젯 결제 정보 불러오기 ------
// 결제 금액, 카드 할부 정보 등 결제 구매자가 설정한 결제 정보입니다.
const widgetPaymentParams = paymentMethodsWidget.getPaymentParams();
await brandpay
.requestPayment({
orderId: "",
orderName: "테스트",
// successUrl: "https://my-store.com/success" // 리다이렉트 URL 방식을 사용할 때만 successUrl을 설정하세요
// failUrl: "https://my-store.com/fail" // 리다이렉트 URL 방식을 사용할 때만 failUrl을 설정하세요
...widgetPaymentParams
})
.then(function (data) {
// 결제 승인 API 호출
})
.catch(function (error) {
// 결제 요청 실패 처리
});
}
</script>
</body>
</html>
위젯 UI의 옵션을 설정하는 선택 파라미터와 파라미터 설정에 따라 달라지는 화면은 브랜드페이 위젯 SDK를 참고하세요.
만약에 브랜드페이를 처음 사용하는 구매자라면, '결제하기' 버튼을 눌렀을 때 본인인증을 하고 결제수단을 등록할 수 있어요. 성공적으로 결제수단이 등록되면 바로 결제창이 나와요.
이미 브랜드페이를 사용한 구매자라면, 아래와 같이 등록된 결제수단이 보이고 '결제하기'를 누르면 바로 결제창이 나와요.
결제 요청 결과를 확인할 차례에요. 결제 요청이 성공하면 requestPayment()
의 파라미터로 설정했던 (successUrl
)의 쿼리 파라미터 또는 Promise를 통해 결제 데이터를 받습니다.
https://my-store.com/success?paymentKey={PAYMENT_KEY}&orderId={ORDER_ID}&amount={AMOUNT}
paymentKey
: 결제의 키 값입니다. 결제를 식별하는 역할로, 중복되지 않는 고유한 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 결제 상태가 변해도 값이 유지됩니다. 결제 승인에 사용됩니다.orderId
:주문 ID입니다. 주문한 결제를 식별하는 역할로, 결제를 요청할 때 가맹점에서 만들어서requestPayment()
에 담아 보낸 값입니다. 결제 데이터 관리를 위해 반드시 저장해야 합니다. 중복되지 않는 고유한 값을 발급해야 합니다. 결제 상태가 변해도 값이 유지됩니다.amount
: 실제로 결제된 금액입니다.
createPaymentMethodsWidget()
메서드에 담아 보낸 결제 금액과 응답으로 돌아온 amount
값이 같은지 반드시 확인해보세요. 클라이언트에서 결제 금액을 조작해 승인하는 행위를 방지할 수 있습니다.
만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요. 적립금이나 쿠폰이 적용된 금액이 맞는지도 확인해보세요.
결제 요청이 실패하면 설정했던 결제 실패 페이지(failUrl
)로 이동하거나 에러 객체를 Promise로 받습니다. 에러 목록을 확인하세요.
https://my-store.com/fail?code={ERROR_CODE}&message={ERROR_MESSAGE}&orderId={ORDER_ID}
브랜드페이 결제 승인 API를 호출해서 마지막 단계를 완료합니다. 먼저 API 인증을 위해 아래와 같이 인증 헤더 값을 만듭니다.
시크릿 키 뒤에 :
을 추가하고 base64로 인코딩합니다. :
을 빠트리지 않도록 주의하세요.
base64('test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R:')
─────────────────┬───────────────── ┬
secretKey :
발급받은 시크릿 키 콜론
아래 명령어를 터미널에서 실행하면 인코딩된 값을 얻을 수 있습니다.
echo -n 'test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R:' | base64
인코딩된 값을 Basic 인증 헤더에 넣고 요청 본문도 추가하세요. 앞 단계에서 리다이렉트 URL로 받은 paymentKey
, orderId
, amount
를 넣어주세요.
아래 예제 코드에는 내 테스트 결제의 paymentKey
값을 넣어 실행해주세요.
curl --request POST \
--url https://api.tosspayments.com/v1/brandpay/payments/confirm \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"paymentKey":"{PAYMENT_KEY}","amount":50000,"orderId":"QndBgcRl0rs_vM-SOnud-"}'
결제 승인에 성공하면 HTTP 200 OK
와 Payment 객체를 받습니다.
{
"mId": "tosspayments",
"version": "2022-11-16",
"paymentKey": "",
"status": "DONE",
"lastTransactionKey": "",
"orderId": "",
"orderName": "토스 티셔츠 외 2건",
"requestedAt": "2022-06-07T17:20:48+09:00",
"approvedAt": "2022-06-07T17:21:21+09:00",
"useEscrow": false,
"cultureExpense": false,
"card": {
"issuerCode": "61",
"acquirerCode": "31",
"number": "43301234****123*",
"installmentPlanMonths": 0,
"isInterestFree": false,
"interestPayer": null,
"approveNo": "00000000",
"useCardPoint": false,
"cardType": "신용",
"ownerType": "개인",
"acquireStatus": "READY",
"amount": 50000
},
"virtualAccount": null,
"transfer": null,
"mobilePhone": null,
"giftCertificate": null,
"cashReceipt": null,
"cashReceipts": null,
"discount": null,
"cancels": null,
"secret": null,
"type": "BRANDPAY",
"easyPay": null,
"country": "KR",
"failure": null,
"isPartialCancelable": true,
"receipt": {
"url": "https://api.tosspayments.com/v1/payments//checkout"
},
"currency": "KRW",
"totalAmount": 10000,
"balanceAmount": 10000,
"suppliedAmount": 9091,
"vat": 909,
"taxFreeAmount": 0,
"method": "카드"
}
브랜드페이 위젯은 브랜드페이 SDK에서 제공하는 기능으로 결제수단을 등록하고 선택하는 UI, 결제수단마다 달라지는 프로모션 정보를 보여주는 UI를 제공합니다.
브랜드페이 위젯을 생성합니다. createPaymentMethodsWidget()
으로 생성된 객체는 브랜드페이 위젯을 관리할 수 있는 네 가지 메서드를 제공합니다.
render()
: 브랜드페이 위젯 렌더destroy()
: 브랜드페이 위젯 제거updateAmount()
: 브랜드페이 위젯의 금액 정보 업데이트getPaymentParams()
: 브랜드페이 위젯에서 선택한 결제 정보 제공
// brandpay 객체 생성
var brandpay = BrandPay(clientKey, customerKey, {
redirectUrl: 'http://example.com'
})
// paymentMethodsWidget 객체 생성
var paymentMethodsWidget = brandpay.createPaymentMethodsWidget({ amount: 10000 })
// render() 메서드로 브랜드페이 위젯 렌더
paymentMethodsWidget.render('#payment-methods-widget')
- amount 필수 · number
결제할 금액입니다. 이 금액에 따라 선택한 결제수단에서 적용할 수 있는 할부 개월 수, 카드 프로모션 정보가 다르게 표시됩니다.
브랜드페이 위젯이 설정한 영역에 렌더됩니다. 렌더 영역은 selector
파라미터로 추가하세요.
// 위젯 렌더
paymentMethodsWidget.render('#payment-methods-widget')
- selector 필수 · string
브랜드페이 위젯을 렌더링할 위치를 지정합니다.
<div>
와 같은 HTML 요소를 선택할 수 있는 CSS 선택자를 사용합니다.예를 들어
<div id="payment-methods-widget">
에 브랜드페이 위젯을 렌더링하려면,#payment-methods-widget
을 전달해야 합니다. - options string
브랜드페이 위젯에 보여줄 결제수단과 UI 설정입니다.
- methodType string
위젯에 보여줄 결제수단을 선택합니다.
카드
,계좌
중 하나입니다. 예를 들어카드
를 선택하면 등록한 결제수단 중 카드만 노출됩니다. - methodId
위젯에서 기본 결제수단으로 선택할 결제수단의 ID입니다.
- ui object
위젯 UI를 변경할 수 있는 옵션입니다. 각 UI 옵션에 따라 달라지는 위젯 화면은 이미지를 참고하세요.
- ui.promotionSection.summary.visible boolean
혜택 배지 영역을 보여주거나 숨깁니다. 혜택 배지 영역에서는 즉시 할인 대상 카드 정보 등을 간략히 보여줍니다. 기본값은
true
입니다. - ui.promotionSection.description.visible boolean
결제 혜택 영역을 보여주거나 숨깁니다. 기본값은
true
입니다. - ui.promotionSection.description.defaultOpen boolean
결제 혜택의 상세 설명을 보여주거나 숨깁니다. 각 카드사의 결제 혜택을 자세히 설명합니다. 기본값은
false
입니다.
options.ui
파라미터 값에 따라 달라지는 위젯을 아래 이미지로 확인해보세요.
렌더된 브랜드페이 위젯을 제거합니다.
// 생성된 위젯 제거
paymentMethodsWidget.destroy()
초기화할 때 설정한 결제 금액을 변경합니다. 쿠폰 적용 등으로 결제 금액이 바뀌었을 때 사용합니다.
메서드를 실행하면 위젯에 새로운 금액 정보가 반영됩니다.
paymentMethodsWidget.updateAmount(50000)
- amount 필수 · number
새 결제 금액입니다. 이 금액이 위젯에 반영됩니다.
브랜드페이 위젯의 결제 정보가 돌아옵니다.
paymentMethodsWidget.getPaymentParams()
- amount number
결제 금액입니다.
- cardInstallmentPlan number
신용 카드의 할부 개월 수입니다. 값을 넣으면 해당 할부 개월 수로 결제가 진행됩니다. 값을 넣지 않으면 고객이 할부 개월 수를 선택할 수 있습니다.
2
부터12
사이의 값을 사용할 수 있고,0
이 들어가면 할부가 아닌 일시불로 결제됩니다.- 결제 금액(
amount
)이 5만원 이상일 때만 할부가 적용됩니다.
- discountCode string
카드사 즉시 할인 코드입니다.
- methodId string
위젯에서 기본 결제수단으로 선택할 결제수단의 ID입니다.
- useCardPoint nullable · boolean
카드사 포인트 사용 여부입니다.
- cashReceipt nullable · object
현금영수증 정보입니다. 계좌로 결제할 때만 값이 있습니다.
- type string
현금영수증의 종류입니다.
소득공제
,지출증빙
,미발행
중 하나입니다. - registrationNumberType string
현금영수증 번호 타입입니다.
MOBILE
(휴대폰 번호),BUSINESS_REGISTRATION
(사업자등록번호),CASH_RECEIPT_CARD
(현금영수증 카드 번호) 중 하나입니다. - registrationNumber number
현금영수증 발급에 필요한 소비자 인증수단입니다. 현금영수증을 발급한 주체를 식별합니다. 현금영수증 종류에 따라 휴대폰 번호, 주민등록번호, 사업자등록번호, 현금영수증 카드 번호 등을 입력할 수 있습니다.