커넥트페이 인증

커넥트페이 인증은 OAuth 2.0 인증 프레임워크를 기반으로 구현되어 있습니다. 모든 JavaScript SDK 요청은 결제할 고객을 식별하는 값인 Access Token이 있는지 확인한 뒤 진행됩니다.

Access Token이 발급되어 인증이 완료되면 커넥트페이 기능을 사용할 수 있습니다.

SDK 사용을 위한 인증 흐름

SDK 인증 흐름도

리다이렉트 URL

리다이렉트 URL이 개발 정보 페이지에 등록되어 있어야 인증 과정의 첫 단계인 임시 인증코드를 얻을 수 있습니다. 인증 요청 첫 단계에서 커넥트페이 서버는 가맹점에서 설정한 리다이렉트 URL에 고객을 식별할 customerKey와 함께 임시 인증 코드를 쿼리 파라미터로 포함해서 보내줍니다. 이 인증 코드가 Access Token 발급에 사용됩니다.

1 메서드 호출

SDK를 초기화 한 뒤 메서드로 원하는 기능을 실행하면 customerKey에 해당하는 고객이 커넥트페이 약관에 동의했는지 확인합니다.

약관에 이미 동의한 상태라면 바로 Access Token을 발급받습니다. 약관 동의가 아직 진행되지 않았다면 약관 동의 진행 후에 Access Token을 발급받는 과정이 이어서 진행됩니다.

https://{ORIGIN}/auth?code={AUTHORIZATION_CODE}&customerKey={CUSTOMER_KEY}
  • authorizationCode: Access Token 발급에 사용할 수 있는 임시 인증 코드입니다.
  • customerKey: 가맹점에서 고객을 식별하기 위해 사용하는 값입니다.

2 커넥트페이 Access Token 요청

가맹점 서버에서 위 값을 사용해 Access Token 발급 요청 API를 호출하는 부분을 구현해야 합니다.

인증

인증은 HTTP Basic 인증 방식을 사용합니다. 요청 시 인증 헤더(Authorization)는 시크릿 키를 콜론과 함께 base64로 인코딩하세요.

Authorization: Basic {BASE64_SECRET_KEY}

더 자세한 내용은 토스페이먼츠 API 인증 페이지를 참고하세요.

요청
HttpRequest request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.tosspayments.com/v1/connectpay/authorizations/access-token"))
    .header("Authorization", "Basic dGVzdF9za196WExrS0V5cE5BcldtbzUwblgzbG1lYXhZRzVSOg==")
    .header("Content-Type", "application/json")
    .method("POST", HttpRequest.BodyPublishers.ofString("{\"grantType\":\"AuthorizationCode\",\"code\":\"92LAa5PVblWx6Ad5J87YmpXy\",\"customerKey\":\"syJC-fP94bw-yXJ04e7z2\"}"))
    .build();
HttpResponse<String> response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Access Token 요청 파라미터

  • grantType 필수 · string

    요청하는 token의 타입입니다.

    code를 사용해 Access Token을 처음으로 요청할 때는 AuthorizationCode를, refreshToken을 사용해 만료된 Access Token을 새로 요청할 때는 RefreshToken을 명시하세요.

    • AuthorizationCode
    • RefreshToken
  • customerKey 필수 · string

    가맹점에서 고객을 식별하기 위해 사용되는 값입니다.

  • code string

    grantTypeAuthorizationCode인 경우 필수입니다.

    리다이렉트 URL의 쿼리 파라미터로 돌아온 임시 인증 코드(code) 값을 넣어줍니다.

  • refreshToken string

    Access Token이 만료되어 새로 획득할 때 필수로 설정합니다.

    grantTypeRefreshToken으로 설정하고 함께 전달해야 합니다.

  • customerIdentity object

    인증을 위한 고객 정보입니다. 가맹점에서 가지고 있는 고객 정보를 사용해서 값을 채울 수 있습니다.

    이 값이 있다면 본인인증 과정을 따로 거치지 않습니다. 이 값이 없다면 고객이 결제수단을 등록하는 시점에 휴대폰 본인인증이 진행됩니다.

    • ci 필수 · string

      고객의 연계정보(CI) 값입니다.

    • name 필수 · string

      고객 이름입니다.

    • rrn 필수 · string

      고객의 주민번호 앞 7자리(생년월일+성별코드)입니다.

연계정보(CI, Connecting Information)는 주민등록번호를 암호화해서 생성된 고유한 문자열입니다. 온라인에서 주민등록번호를 그대로 사용하지 않고 신원 확인 및 개인 식별을 하기 위해 본인인증기관을 통해 발급받아 사용합니다. 주민등록번호와 1:1로 매칭되기 때문에 값이 늘 고정되어 있습니다.

요청에 성공했다면 아래와 같이 Access Token이 포함된 응답이 돌아옵니다.

응답
{
"accessToken": "2YotnFZFEjr1zCsicMWpAqG81SA",
"refreshToken": "E8q9G8eeFiei1U01G3nTpq1AgiE",
"tokenType": "bearer",
"expiresIn": 259200
}
JSON
  • accessToken string

    사용자에 할당된 Access Token 입니다. customerKey와 연결되어 있는 값으로 고객이 탈퇴하거나 Refresh Token으로 새로 발급받지 않는 한 변하지 않습니다.

  • refreshToken string

    Access Token을 새로 발급 받을 때 사용할 토큰입니다.

  • tokenType string

    커넥트페이 API에 요청할 때 쓰는 인증 방식인 bearer 가 고정값으로 돌아옵니다.

  • expiresIn string

    Access Token의 유효기간을 초 단위로 나타낸 값입니다. 30일로 설정되어 있습니다.

토큰의 종류 및 정책

토큰 종류용도형식정책
Authorization Code (임시 인증 코드)Access Token을 발급할 때 사용됩니다. 리다이렉트 URL로 전달됩니다.영문, 숫자의 무작위 조합으로 인코딩한 문자열입니다.유효한 시간은 5분입니다. SDK로 연동하는 경우 Access Token을 새로 발급받기 위해 필요한 값입니다.
Access Token (사용자 식별 토큰)결제하려는 사용자 본인 식별을 위해 사용되는 토큰으로, 이 값으로 커넥트페이에 HTTP 요청을 보낼 수 있습니다.영문, 숫자의 무작위 조합으로 인코딩된 문자열입니다.30일 뒤 만료됩니다. API로만 연동하는 경우 매번 요청 헤더에 Bearer 토큰 값으로 설정되어야 합니다. 클라이언트에 노출하면 안되는 값입니다.
Refresh Token (Access Token 연장에 사용되는 토큰)Access Token을 새로 발급받을 때 사용하는 토큰입니다.영문, 숫자의 무작위 조합으로 인코딩된 문자열입니다.만료 기간은 없습니다. API로 요청할 때 Access Token을 새로 발급받기 위해 필요한 값입니다. 클라이언트에 노출하면 안되는 값입니다.
Customer Token(클라이언트 식별 토큰)Authorization Code를 인증하면 클라이언트에 발급되는 토큰입니다. 클라이언트는 이 토큰을 HTTP 요청 헤더로 보내서 로그인 된 사용자에 대한 API 호출 권한을 얻습니다. 일정 기간 동안 고객의 세션을 유지하는 1회성 토큰으로, 매 HTTP 요청마다 새로 발급됩니다.영문, 숫자의 무작위 조합으로 인코딩된 문자열입니다.1회 사용 후 폐기됩니다. 유효한 시간은 20분입니다. 클라이언트 전용입니다. 매 API 호출 마다 새로운 Customer Token을 재발급 받을 수 있습니다.
내용이 도움 되셨나요?
  • 더 궁금한 내용이 있나요?
  • 코드 샘플을 참고하세요
  • 기술지원이 필요한가요?
    디스코드 채팅|이메일 보내기