브랜드페이 인증하기

✅ 브랜드페이에서 Access Token을 발급하고 사용하는 방법을 안내합니다.

✅ 브랜드페이 인증은 OAuth 2.0 인증 프레임워크 기반으로 구현되어 있습니다.

Access Token은 결제위젯 SDK 및 API의 OAuth 2.0 인증에 필요한 토큰이에요. 구매자를 식별하고 보호된 구매자 정보에 접근할 때 사용해요. 예를 들어, 고객이 등록한 결제수단을 조회할 때 Access Token이 필요합니다.

결제위젯 SDK는 OAuth 인증을 내부적으로 지원하고 있어요. 구매자의 Access Token을 한번 발급하면, SDK를 통해서 해당 토큰으로 구매자 정보에 접근할 수 있어요. API로 연동하고 있다면 결제수단 삭제, 회원 탈퇴 등 구매자 정보에 접근하는 API를 사용할 때 Bearer 인증과 Access Token을 사용해요.

Access Token은 유효기간이 지나면 Refresh Token으로 재발급이 필요해요. 토큰과 유효기간을 별도로 관리하거나 결제 요청할 때 매번 새로운 Access Token을 발급받아서 사용하세요.

1. 결제위젯 SDK에서 인증을 요청합니다.
2. 고객이 이용 약관에 동의하면 Authorization Code(임시 인증 코드)를 받습니다.
3. Authorization Code를 사용해서 Access Token 발급 API를 호출하면 Access Token이 발급됩니다.
4. 결제수단 조회와 같이 민감한 고객 정보에 접근할 때 Access Token으로 권한을 인증해야 합니다.

이제 각 과정에 대한 더 자세한 설명을 연동 방식에 따라 살펴보세요.

결제위젯을 사용하면 일반결제와 브랜드페이를 한 번에 연동할 수 있어요.

결제 UI에서 고객이 결제수단을 등록하고 이용 약관에 동의하면 개발자센터에 등록한 리다이렉트 URL으로 이동합니다. 리다이렉트 URL 뒤에는 다음과 같이 임시 인증 코드와 customerKey가 반환됩니다.

https://{ORIGIN}/auth?code={CODE}&customerKey={CUSTOMER_KEY}

• code: Access Token 발급에 필요한 Authorization Code(임시 인증 코드)입니다.
• customerKey: 상점에서 만든 고객의 고유 ID입니다.

리다이렉트 URL의 쿼리 파라미터 정보로 브랜드페이 Access Token 발급 API를 호출하세요.

먼저 API 인증을 위해 아래와 같이 인증 헤더 값을 만듭니다. 결제위젯 연동 키 > 시크릿 키 뒤에 :을 추가하고 base64로 인코딩합니다. :을 빠트리지 않도록 주의하세요.

base64('test_gsk_docs_OaPz8L5KdmQXkzRz3y47BMw6:')
        ─────────────────┬─────────────────── ┬
                     secretKey                :
              결제위젯 연동 키 > 시크릿 키         콜론

인코딩된 값을 Basic 인증 헤더에 넣고 요청 본문도 추가하세요.

• 헤더에 Authorization을 추가하고 Basic {인코딩된 시크릿 키 값}을 넣어주세요. 아래 예제 코드를 참고하세요.
• 요청 본문으로는 앞 단계에서 리다이렉트 URL로 받은 code, customerKey를 넣어주세요. Access Token 최초 발급에는 grantType을 AuthorizationCode로 설정하세요.

응답으로 Access Token, Access Token의 유효기간, Refresh Token이 돌아옵니다. 각 토큰에 대한 자세한 설명은 인증 토큰의 종류 및 정책을 참고하세요.

이제 SDK에서 자동으로 결제 고객의 Access Token을 확인하고 사용합니다.

브랜드페이 API를 사용하면 직접 구현한 UI에 브랜드페이 서비스를 연동할 수 있습니다.

미동의 약관 조회 API로 결제 고객이 동의해야 하는 약관 정보를 확인하고 약관 동의 API를 호출해 약관 동의를 받습니다. 약관 동의 API의 성공 응답으로 Access Token 발급에 필요한 Authorization Code(임시 인증 코드)가 code로 돌아옵니다.

돌아온 Authorization Code(임시 인증 코드)로 브랜드페이 Access Token 발급 API를 호출하세요.

먼저 API 인증을 위해 아래와 같이 인증 헤더 값을 만듭니다. 브랜드페이 상점아이디(MID)에 할당된 API 개별 연동 키 > 시크릿 키 뒤에 :을 추가하고 base64로 인코딩합니다. :을 빠트리지 않도록 주의하세요.

base64('test_sk_zXLkKEypNArWmo50nX3lmeaxYG5R:')
        ─────────────────┬─────────────────── ┬
                     secretKey                :
              결제위젯 연동 키 > 시크릿 키         콜론

인코딩된 값을 Basic 인증 헤더에 넣고 요청 본문도 추가하세요.

• 헤더에 Authorization을 추가하고 Basic {인코딩된 시크릿 키 값}을 넣어주세요. 아래 예제 코드를 참고하세요.
• 요청 본문으로는 앞 단계에서 code와 구매자의 customerKey를 넣어주세요. Access Token 최초 발급에는 grantType을 AuthorizationCode로 설정하세요.

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"}'

응답으로 Access Token, Access Token의 유효기간, Refresh Token이 돌아옵니다. 각 토큰에 대한 자세한 설명은 인증 토큰의 종류 및 정책을 참고하세요.

Access Token은 고객 정보와 관련된 결제수단 조회, 카드 결제수단 삭제, 계좌 결제수단 삭제, 회원 탈퇴 처리 API를 호출할 때 인증 정보로 사용됩니다.

Access Token을 Bearer 인증 방식으로 사용하기 위해 아래와 같이 HTTP 헤더를 설정한 뒤 브랜드페이 API를 요청합니다.

Authorization: Bearer {ACCESS_TOKEN}

브랜드페이 인증 과정에 필요한 토큰의 종류 및 정책입니다. 모든 토큰은 영문, 숫자의 무작위 조합으로 인코딩된 문자열입니다.