결제위젯에 브랜드페이 추가하기
✅ 브랜드페이로 내 상점만의 자체 간편결제 시스템을 구축하고 싶을 때
✅ 일반결제, 브랜드페이를 한 번에 연동하고 싶을 때
결제위젯에 브랜드페이 추가하기는 결제위젯 Pro 플랜 기능입니다. 결제위젯 Pro 플랜 계약은 상점관리자의 이용정보 > 결제·부가서비스 탭에서 문의해주세요. 브랜드페이 계약은 상점관리자에서 신청해주세요.
이해하기
이 가이드는 결제위젯으로 브랜드페이를 함께 연동하는 방법을 알려드려요. 브랜드페이를 별도로 연동하는 것 보다 훨씬 간편하게 연동할 수 있으며 아래와 같이 브랜드페이와 일반결제수단을 한 번에 보여줄 수 있습니다.
결제위젯, 브랜드페이는 각자 다른 상점아이디(MID)를 가지고 있어요. 각 MID에는 클라이언트 키, 시크릿 키가 발급돼요.
결제위젯 SDK, 코어 API에는 결제위젯 클라이언트 키, 시크릿 키를 사용하세요.
브랜드페이 SDK, 브랜드페이 API에는 브랜드페이 클라이언트 키, 시크릿 키를 사용하세요.
설정하기
상점관리자
상점관리자의 결제 UI 설정 메뉴에서 UI 환경을 선택해주세요. 선택 후 기능 > 브랜드페이 메뉴에서 브랜드페이 사용을 활성화하고 내 상점의 브랜드페이 MID를 선택하세요.
브랜드페이는 계약이 안 되어 있다면 위에 보이는 메뉴에서 브랜드페이 사용 대신 이용 신청하기를 할 수 있습니다.
개발자센터
개발자센터의 브랜드페이 페이지에서 리다이렉트 URL을 추가하세요.
연동하기
결제위젯에 브랜드페이를 추가하면 고객은 일반결제 또는 브랜드페이 결제를 선택할 수 있어요. 브랜드페이는 최초 결제에 사용자 등록이 필요하고, 결제 승인에 브랜드페이 API를 호출해야 돼요.
먼저 결제위젯을 연동하세요. 이제 간단한 클라이언트, 서버 작업만으로 결제위젯에 브랜드페이를 추가할 수 있어요.
클라이언트: 리다이렉트 URL 추가하기
결제위젯 객체를 초기화할 때 아래와 같이 options 파라미터로 브랜드페이 리다이렉트 URL을 추가하세요.
<head>
<meta charset="utf-8" />
<title>결제하기</title>
<script src="https://js.tosspayments.com/v1/payment-widget"></script>
</head>
<body>
<script>
const clientKey = 'test_ck_D5GePWvyJnrK0W0k6q8gLzN97Eoq' // 결제위젯 클라이언트 키
const customerKey = ''
const paymentWidget = PaymentWidget(clientKey, customerKey, {
brandpay: { // 결제위젯에 브랜드페이 추가하기
redirectUrl: '/brandpay/callback-auth' // Access Token 발급에 사용되는 리다이렉트 URL
}
})
</script>
</body>
초기화 파라미터
- clientKey 필수 · string
클라이언트 키는 브라우저에서 결제창을 연동할 때 사용합니다. 토스페이먼츠에서 발급합니다. API 키 페이지에서 결제위젯 MID로 발급된 키 값을 사용하세요.
- customerKey 필수 · string
고객 ID입니다. 충분히 무작위한 값을 직접 생성해서 사용하세요. 영문 대소문자, 숫자, 특수문자
-,_,=,.,@로 이루어진 1자 이상 50자 이하의 문자열입니다. 비회원 결제에는PaymentWidget.ANONYMOUS를 사용하세요. - options object
결제위젯에 추가할 옵션입니다.
- brandpay object
결제위젯에 브랜드페이를 추가할 때 설정합니다.
redirectUrl이 담긴 객체를 넘기세요.리다이렉트 URL에는 Access Token 발급 과정에 필요한 값이 돌아옵니다. Access Token은 브랜드페이 고객을 식별하고 고객의 결제 권한을 증명합니다. 값을 넣지 않으면 개발자센터 > 브랜드페이 페이지에 최초로 등록한 리다이렉트 URL이 기본값으로 들어갑니다.
클라이언트 작업 마무리하기
결제위젯 객체를 초기화했다면 아래와 같이 결제위젯을 렌더링하고 결제창을 띄워보세요.
paymentWidget.renderPaymentMethods('#payment-method', 15000);
paymentWidget.requestPayment({
orderId: 'AD8aZDpbzXs4EQa-UkIX6',
orderName: '토스 티셔츠 외 2건',
successUrl: 'http://localhost:8080/success', // 결제 승인에 사용되는 성공 리다이렉트 URL
failUrl: 'http://localhost:8080/fail', // 결제 승인에 사용되는 실패 리다이렉트 URL
})
서버: 브랜드페이 결제 연동하기
Access Token을 발급하고 브랜드페이 결제를 승인하는 로직을 추가해주세요.
1. Access Token 발급
브랜드페이를 최초로 사용하는 고객이 브랜드페이 결제를 선택하면 결제수단을 등록하고 이용 약관에 동의해요. 더 자세한 내용은 브랜드페이 인증 가이드에서 확인하세요. 이 과정에 성공하면 redirectUrl로 이동합니다.
https://{ORIGIN}/auth?code={CODE}&customerKey={CUSTOMER_KEY}
redirectUrl의 쿼리 파라미터 정보로 Access Token 발급 API를 호출하세요.
Basic 인증 헤더에는 브랜드페이 시크릿 키와 콜론을 base64로 인코딩해서 넣습니다.
curl --request POST \
--url https://api.tosspayments.com/v1/brandpay/authorizations/access-token \
--header 'Authorization: Basic dGVzdF9za19hQlg3emsyeWQ4eW9Yd29KMGdxVng5UE9McUtROg==' \
--header 'Content-Type: application/json' \
--data '{"grantType":"AuthorizationCode","customerKey":"c6thB674j9vCU4XsvcPk","code":"RnYX2w532omp6gDQgVNeyqAp"}'
2. 성공 리다이렉트 URL 확인하기
Access Token이 잘 발급되면 successUrl로 이동합니다.
https://{ORIGIN}/success?paymentKey={PAYMENT_KEY}&orderId={ORDER_ID}&amount={AMOUNT}&paymentType={PAYMENT_TYPE}
paymentType이NORMAL이라면 일반결제입니다. 코어 결제 승인 API를 호출하세요.paymentType이BRANDPAY라면 브랜드페이 결제입니다. 브랜드페이 결제 승인 API를 호출하세요.
요청한 결제 금액과 successUrl로 돌아온 amount 값이 같은지 반드시 확인해보세요. 만약 값이 다르다면 결제를 취소하고 구매자에게 알려주세요. 클라이언트에서 결제 금액을 조작하는 행위를 방지할 수 있습니다.
더 자세한 내용은 토스페이먼츠 공식 블로그 포스트를 참고하세요.
3. 브랜드페이 결제 승인 API 호출하기
브랜드페이 결제 승인 API 요청 본문에는 성공 리다이렉트 URL로 받은 paymentKey, orderId, amount와 customerKey를 넣습니다. Basic 인증 헤더에는 브랜드페이 시크릿 키와 콜론을 base64로 인코딩해서 넣습니다.
curl --request POST \
--url https://api.tosspayments.com/v1/brandpay/payments/confirm \
--header 'Authorization: Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==' \
--header 'Content-Type: application/json' \
--data '{"paymentKey":"5zJ4xY7m0kODnyRpQWGrN2xqGlNvLrKwv1M9ENjbeoPaZdL6","amount":"10000","customerKey":"c6thB674j9vCU4XsvcPk","orderId":"a4CWyWY5m89PNh7xJwhk1"}'