11Pay Token

11Pay 토큰 (11Pay Token, 토큰)은 무엇인가요?

11Pay 토큰은 가맹점 인증 및 메시지 위변조 방지를 위해 JWT(JSON Web Token) 형식으로 암호 처리된 메시지입니다.

  • 11Pay 토큰을 생성하기 위해서는 11Pay에서 가맹점별 발급하는 가맹점 ID와 Secret 키 정보가 필요하며, 가맹점은 이 정보를 서버에 저장 후 가맹점 클라이언트 요청 시 사용하게 됩니다.
  • 11Pay 토큰은 사용 목적에 따라, “거래인증 토큰” “자동결제 등록 요청 토큰” “로그인 토큰” 등으로 구분됩니다.
  • 토큰을 생성하기 위한 서버 라이브러리는 개발 편의를 위해 11Pay에서 제공됩니다.
  • 토큰 생성에 필요한 Secret 키 정보는 보안을 강화하기 위해 개발 키 및 상용 키로 별도 발급/관리됩니다. 따라서, “개발환경” “상용환경” 적용 시 각 환경에 맞는 Secret 키를 사용해야 합니다.

1. 거래인증 요청 토큰

11Pay로 거래인증을 요청하기 위해 필요한 토큰(Token)입니다. 거래 인증을 요청하기 위해서는 거래와 관련된 정보를 토큰(Token)에 포함해야 하며, 필요할 경우 11Pay 자동로그인 처리를 위한 정보를 함께 포함합니다.

API Description

API Description
login 11Pay 로그인(또는 자동로그인)을 위해 반드시 필요한 API 입니다. login API를 호출 후 아래 API를 호출해야 합니다.
    withMerchantUserId 가맹점 회원의 고유 식별자를 Setting 합니다. 가맹점 회원의 고유 식별자는 반드시 유일해야 합니다. 가맹점 내부에서 관리하는 사용자 번호 또는 사용자가 인지할 수 있는 ID(예. 이메일 아이디) 등을 사용할 수 있습니다. 최대 길이는 255 Byte입니다.
    withSsoCredential Optional 11Pay로 SSO Credential 발급 요청 후, SSO Credential 정보를 전달 받았다면 해당 정보를 포함합니다. 최대 길이는 128 Byte입니다.
    isNotApplicableSso Optional 기본적으로 자동로그인 기능을 사용하지만, 가맹점 상황에 따라 자동로그인을 허용할 수 없는 경우에 이 함수를 호출 합니다.
(주) 자동로그인을 사용하지 않는 가맹점이나, 자동로그인을 예외 없이 모두 적용하는 가맹점은 이 함수를 호출하지 않아도 됩니다.
and login 관련 정보를 모두 입력 후 호출해야 합니다.
pay 11Pay 거래 인증 토큰(Token)을 생성하기 위해 해당 API를 호출해야 합니다. 아래 API들은 반드시 “pay API” 호출 이후 호출되어야 합니다.
    withOrderIdOfMerchant 가맹점에서 생성한 주문 ID을 설정합니다. 거래승인 요청 API에 들어가는 mctTransAuthId와 동일한 값입니다.
    withProductTitle 거래를 요청하는 상품의 제목을 설정합니다. 2개 이상의 상품을 거래 요청할 경우 “특정 상품제목 외 1건” 형태로 전달할 수 있습니다.
최대 512 Byte(한글 기준, 256 자)까지 허용됩니다.
    withProductUrls Optional 요청 상품의 Url 정보입니다. 2개 이상의 상품을 거래 요청할 경우 각각 설정할 수 있습니다.
    withLanguageForDisplay 표시 언어를 설정합니다. 한글은 PayConfigurer.Language.KO로 설정합니다.
    withAmount 결제 요청 금액을 설정합니다.
    withCurrency 요청 금액의 화폐 단위를 설정합니다. 원화는 PayConfigurer.Currency.KRW로 설정합니다.
    withShippingAddress Optional 요청 상품의 배송지를 설정합니다.
    withDeliveryPhoneNumber Optional 배송 받는 사람의 전화번호를 설정합니다.
    withDeliveryName Optional 배송 받는 사람의 이름을 설정합니다.
    withInstallmentPerCardInformation Optional 카드 코드 및 할부 정보를 설정합니다.
(주) 일반적인 경우 불필요하나, 일시불만 허용하는 상품이 있는 경우 등 가맹점의 특수 상황 시 사용됩니다. 상세 문의가 필요할 경우 11Pay 제휴 담당자에게 문의 부탁힙니다.)
    withBeAbleToExchangeToCash Optional 환금성 상품 여부를 설정합니다.
    withMerchantDefinedValue Optional 가맹점에서 정의한 임의의 정보. 해당 정보가 전달되면 거래 인증 결과 값에 해당 정보를 그대로 전달합니다. 가맹점 필요 시 선택적으로 활용 가능하며, 최대 1K Byte까지 사용할 수 있습니다.
(주) 개인정보 또는 거래에 중요한 정보 등 민감한 정보를 포함해서는 안 됩니다.
    withRestrictionOf Optional 결제와 관련된 제약사항을 설정할 수있습니다. 제약 사항이 복수일 경우 중복하여 API를 호출할 수 있습니다.
예. PayConfigurer.MatchedUser.CI_MATCHED_ONLY: 가맹점과 CI가 일치하는 경우만 거래를 허용합니다.
    withRestrictionPaymentTypeOf Optional 특정 결제수단으로만 결제를 제한할 경우 설정합니다. Default는 가맹점에 허용된 모든 결제수단을 허용합니다. 2개 이상일 경우, Semi-colon(;) 구분자를 사용합니다.
CARD:신용카드, MOBILE:휴대폰 결제, BANK:계좌이체
and generateTokenBy API를 호출하기 전에 반드시 호출해야 합니다.
generateTokenBy 전자서명된 토큰(Token) 생성을 위해 마지막에 호출합니다. 11Pay에서 발급한 가맹점 Secret 키 정보를 입력 값으로 전달해야 합니다.

토큰 생성 예제 코드

Java Sample Code
String token = new SyrupPayTokenBuilder().of("11Pay에서 발급/전달한 가맹점 ID")
  .login()
    .withMerchantUserId("가맹점의 회원 ID 또는 식별자")
    .withSsoCredential("발급 받은 SSO")
  .and()
  .pay()
    .withOrderIdOfMerchant("가맹점에서 관리하는 주문 ID")
    .withProductTitle("제품명 예. Macbook 27 인치 노트북 외 1건")
    .withProductUrls(
        "http://deal.11st.co.kr/product/prdNo=1122841340",
        "http://deal.11st.co.kr/product/prdNo=1265508741"
        ) // Optional
    .withLanguageForDisplay(PayConfigurer.Language.KO)  // 한글
    .withAmount(50000) // 결제요청 금액
    .withCurrency(PayConfigurer.Currency.KRW)  // 원화
    .withShippingAddress(
        new PayConfigurer.ShippingAddress("137-332",
           "서초구 잠원동 하나아파트", "1동 1호", "서울", "", "kr")
        ) // 배송지 Optional
    .withDeliveryPhoneNumber("01012345678") // 수신자 전화번호 Optional
    .withDeliveryName("배송 수신자") // 수신자 이름 Optional
    .withInstallmentPerCardInformation(
        new PayConfigurer.CardInstallmentInformation("카드구분 코드",
            "할부정보. ex. NN1;NN2;YY3;YY4;YY5;NH6")
        ) // Optional. 특정 카드만 허용 가능하게 설정할 수 있음
    .withBeAbleToExchangeToCash(false) // 환금성 상품 여부 Optional
    .withRestrictionPaymentTypeOf("MOBILE;BANK;CARD") // Optional, 결제수단 제약                                      
  .and()
  .generateTokenBy("11Pay에서 발급/전달한 가맹점 Secret");

PHP Sample Code
$builder = new new syruppay_token_SyrupPayTokenBuilder();
$token = $builder->of("11Pay에서 발급/전달한 가맹점 ID")
  ->login()
    ->withMerchantUserId("가맹점의 회원 ID 또는 식별자")
    ->withSsoCredential("발급 받은 SSO")
  ->next()
  ->pay()
    ->withOrderIdOfMerchant("가맹점에서 관리하는 주문 ID") // 가맹점 Transaction ID = mctTransAuthId
    ->withProductTitle("제품명")
    ->withProductUrls(array(
        "상품 URL",
        "상품 URL (2개 이상의 상품을 함께 결제하는 경우"
    )) // Optional
    ->withLanguageForDisplay(LANGUAGE_KO)
    ->withAmount(50000)
    ->withCurrency(CURRENCY_KRW)
    ->withShippingAddress(new syruppay_token_claims_elements_ShippingAddress("137-332", "서초구 잠원동 하나아파트", "1동 1호", "서울", "", "kr")) // Optional
    ->withDeliveryPhoneNumber("01012345678") // Optional
    ->withDeliveryName("배송 수신자") // Optional
    ->withBeAbleToExchangeToCash(false) // Optional. 환금성 여부
    ->withRestrictionPaymentType(array("MOBILE", "BANK"))  // Optional, 결제수단 제한을 사용할 경우.
  ->next()
  ->generateTokenBy("11Pay에서 발급/전달한 가맹점 Secret");
C# Sample Code
var token = new SyrupPayTokenBuilder().Of("11Pay에서 발급/전달한 가맹점 ID")
  .Login()
    .WithMerchantUserId("가맹점의 회원 ID 또는 식별자")
    .WithSsoCredential("발급 받은 SSO") //Optainal
  .And()
  .Pay()
    .WithOrderIdOfMerchant("가맹점에서 생성하는 주문 ID") // 가맹점 Transaction ID = mctTransAuthId
    .WithProductTitle("제품명")
    .WithProductUrls(
        "http://deal.11st.co.kr/product/prdNo=1122841340",
        "http://deal.11st.co.kr/product/prdNo=1265508741"
        ) // Optional
    .WithLanguageForDisplay(PayConfigurer<SyrupPayTokenBuilder>.Language.KO)
    .WithAmount(50000)
    .WithCurrency(PayConfigurer<SyrupPayTokenBuilder>.Currency.KRW)
    .WithShippingAddress(new PayConfigurer<SyrupPayTokenBuilder>.ShippingAddress("137-332",
        "서초구 잠원동 하나아파트", "1동 1호", "서울", "", "kr")) // Optional
    .WithDeliveryPhoneNumber("01012345678") // Optional
    .WithDeliveryName("배송 수신자") // Optional
    .WithBeAbleToExchangeToCash(false) // Optional
    .WithRestrictionPaymentTypeOf("MOBILE;BANK")  // Optional, 결제수단 제약
  .And()
  .GenerateTokenBy("11Pay에서 발급/전달한 가맹점 Secret");

ASP Sample Code
Option Explicit

Dim objMctTAToken
Dim token

Set objMctTAToken = Server.CreateObject("SyrupPay.MctTAToken")
With objMctTAToken
  .Iss = "가맹점 ID"
  .MctUserId = "가맹점의 회원 ID 또는 식별자"
  .SSOCredential = "발급 받은 SSO"             'optional
  .MctTransAuthId = "가맹점에서 생성하는 주문 ID"
  .ProductTitle = "제품명"
  .ProductUrl = "http://deal.11st.co.kr/product/prdNo=1122841340"         'optional
  .ProductUrl = "http://deal.11st.co.kr/product/prdNo=1265508741"         'optional
  .Lang = "ko"
  .CurrencyCode = "KRW"
  .PaymentAmt = 50000
  .ShippingAddress = "a2:kr|137-332|서울 서초구 잠원동 하나아파트|1동 1호||"     'optional
  .DeliveryPhoneNumber = "01011112222"            'optional
  .DeliveryName = "배송 수신자"                     'optional
  .IsExchangeable = false                          'optional
  .PaymentType = "MOBILE;BANK"
End With

'WScript.Echo objMctTAToken.ToJson()
token = objMctTAToken.Serialzie("11Pay에서 발급/전달한 가맹점 Secret")

Set objMctTAToken = Nothing

2. 자동결제 등록요청 토큰 생성

11Pay로 자동결제 등록 요청을 위한 토큰(Token)입니다. 자동결제 등록을 요청하기 위해서는 자동결제와 관련된 정보를 토큰(Token)에 포함해야 하며, 필요할 경우 11Pay 자동로그인 처리를 위한 정보를 함께 포함합니다.

API Description

API Description
login 11Pay 로그인을 위해서는 반드시 필요한 API 입니다. login API를 호출 후 아래 API를 호출해야 합니다.
    withMerchantUserId 가맹점 회원의 고유 식별자를 Setting 합니다. 가맹점 회원의 고유 식별자는 반드시 유일해야 합니다. 가맹점 내부에서 관리하는 사용자 번호 또는 사용자가 인지할 수 있는 ID(예. 이메일 아이디) 등을 사용할 수 있습니다. 최대 길이는 255 Byte입니다.
    withSsoCredential Optional 11Pay로 SSO Credential 발급 요청 후, SSO Credential 정보를 전달 받았다면 해당 정보를 포함합니다. 최대 길이는 128 Byte입니다.
    isNotApplicableSso Optional 기본적으로 자동로그인 기능을 사용하지만, 가맹점 상황에 따라 자동로그인을 허용할 수 없는 경우에 해당 함수를 호출 합니다.
(주) 자동로그인을 사용하지 않는 가맹점이나, 자동로그인을 예외 없이 모두 적용하는 가맹점은 해당 함수를 호출하지 않아도 됩니다.
subscription 자동결제를 위한 결제 수단 등록 또는 수정을 위해 반드시 해당 API를 호출해야 합니다.
    withAutoPaymentId Optional 11Pay로 자동결제 등록 후, 11Pay가 발행한 자동결제 ID입니다. 자동결제 결제수단을 변경하기 위해서는 반드시 이 정보가 전달되어야 합니다.
최대 길이는 50 Byte입니다.
    withMerchantSubscriptionRequestId Optional 가맹점 자동결제 요청 ID. 해당 정보는 자동결제 등록결과에 포함됩니다.
최대 길이는 255 Byte입니다.
    with(new SubscriptionConfigurer.Plan(“결제주기, “자동결제상품명”)) Optional 자동결제 상품정보(결제 주기 및 자동결제 상품 명)를 등록합니다. 결제주기는 다음과 같습니다.
SubscriptionConfigurer.Interval.ONDEMAND: 수시 결제
SubscriptionConfigurer.Interval.WEEKLY: 주 단위 결제
SubscriptionConfigurer.Interval.BIWEEKLY : 격주 단위 결제
SubscriptionConfigurer.Interval.MONTHLY: 월 단위 결제
    withRestrictionOf Optional 결제와 관련된 제약사항을 설정할 수 있습니다. 제약 사항이 복수일 경우, 중복하여 API를 사용할 수 있습니다.
PayConfigurer.MatchedUser.CI_MATCHED_ONLY : 가맹점과 CI가 일치하는 경우만 등록을 허용합니다.
PayConfigurer.MatchedUser.FIRST_SIGNUP_IN_LIFETIME_ONLY : 11Pay 생애 최초 회원 가입일 경우에 등록을 허용합니다.
and generateTokenBy API를 호출하기 전에 반드시 호출해야 합니다.
generateTokenBy 전자서명된 토큰(Token) 생성을 위해 마지막에 호출합니다. 11Pay에서 발급한 가맹점 Secret 키 정보를 입력 값으로 전달해야 합니다.

토큰 생성 예제 코드

Java Sample Code
String token = new SyrupPayTokenBuilder().of("11Pay가 발급/전달한 가맹점 ID")
  .login()
    .withMerchantUserId("가맹점의 회원 고유 식별자") // Required
    .withSsoCredential("11Pay로부터 발급 받은 SSO") //자동로그인 시 필수값
  .and()
  .subscription() // 자동결제를 위한 결제수단 등록
    .withAutoPaymentId("11Pay가 자동결제 등록후 전달한 자동결제 ID") // Optional.
    .withMerchantSubscriptionRequestId("가맹점에서 생성한 자동결제 요청 ID") // Optional  
    .withRestrictionOf(PayConfigurer.MatchedUser.CI_MATCHED_ONLY) // Optional   
    .with(new SubscriptionConfigurer.Plan(SubscriptionConfigurer.Interval.WEEKLY, "음악 정기이용권")) // Optional
  .and()
  .generateTokenBy("11Pay가 발급/전달한 가맹점 Secret");
PHP Sample Code
$builder = new syruppay_token_SyrupPayTokenBuilder();
$token = $builder->of("11Pay가 발급/전달한 가맹점 ID")
  ->login()
    ->withMerchantUserId("가맹점의 회원 고유 식별자") //Required
    ->withSsoCredential("11Pay로부터 발급 받은 SSO")  //Optional
  ->next()
    ->subscription() // 자동결제를 위한 결제수단 등록
    ->withAutoPaymentId("11Pay로 자동결제 등록 후, 전달한 자동결제 ID")  // Optional
  ->next()
  ->generateTokenBy("11Pay가 발급/전달한 가맹점 Secret");
C# Sample Code
String token = new SyrupPayTokenBuilder().Of("11Pay가 발급/전달한 가맹점 ID")
  .Login()
    .WithMerchantUserId("가맹점의 회원 고유 식별자")
    .WithSsoCredential("11Pay로부터 발급받은 SSO") //Optional
  .And()
  .Subscription()  // 자동결제를 위한 결제수단 등록
    .withAutoPaymentId("11Pay가 자동결제 등록 후 전달한 자동결제 ID")  // Optional
  .And()
  .generateTokenBy("11Pay가 발급/전달한 가맹점 Secret");
ASP Sample Code
Option Explicit

Dim objMctTAToken
Dim token

Set objMctTAToken = Server.CreateObject("SyrupPay.MctTAToken")
With objMctTAToken
.Iss = "가맹점 ID"
.MctUserId = "가맹점의 회원 ID 또는 식별자"
.SSOCredential = "발급 받은 SSO"             'optional
.AutoPaymentId = "11Pay가 자동결제 등록 후 전달한 자동결제 ID"        'optional
End With

'WScript.Echo objMctTAToken.ToJson()
token = objMctTAToken.Serialzie("11Pay가 발급/전달한 가맹점 Secret")

Set objMctTAToken = Nothing

3. 로그인 토큰 생성

11Pay 회원 가입 또는 매출전표 출력 등의 11Pay 기능을 사용할 경우 필요합니다.

API Description

API Description
login 11Pay 로그인을 위해서는 반드시 필요한 API입니다. login API를 호출 후, 아래 API를 순차적으로 호출해야 합니다.
    withMerchantUserId 가맹점 회원의 고유 식별자를 Setting 합니다. 가맹점 회원의 고유 식별자는 반드시 유일해야 합니다. 가맹점 내부에서 관리하는 사용자 번호 또는 사용자가 인지할 수 있는 ID(예. 이메일 아이디) 등을 사용할 수 있습니다. 최대 길이는 255 Byte입니다.
    withSsoCredential Optional 11Pay로 SSO Credential 발급 요청 후, SSO Credential 정보를 전달 받았다면 해당 정보를 포함합니다. 최대 길이는 128 Byte입니다.
    isNotApplicableSso Optional 기본적으로 자동로그인 기능을 사용하지만, 가맹점 상황에 따라 자동로그인을 허용할 수 없는 경우에 해당 함수를 호출 합니다.
(주) 자동로그인을 사용하지 않는 가맹점이나, 자동로그인을 예외 없이 모두 적용하는 가맹점은 해당 함수를 호출하지 않아도 됩니다.
and generateTokenBy API를 호출하기 전에 반드시 호출해야 합니다.
generateTokenBy 전자서명된 토큰(Token) 생성을 위해 마지막에 호출합니다. 11Pay에서 발급한 가맹점 Secret 키 정보를 입력 값으로 전달해야 합니다.

토큰 생성 예제 코드

Java Sample Code
String token = new SyrupPayTokenBuilder().of("11Pay가 발급/전달한 가맹점 ID")
  .login()
      .withMerchantUserId("가맹점의 회원 고유 식별자") // Required
      .withSsoCredential("11Pay로부터 발급받은 SSO") //Optional
  .and()
  .generateTokenBy("11Pay가 발급/전달한 가맹점 Secret");
PHP Sample Code
$builder = new syruppay_token_SyrupPayTokenBuilder();
$token = $builder->of("11Pay가 발급/전달한 가맹점 ID")
  ->login()
  ->withMerchantUserId("가맹점의 회원 고유 식별자") //Required
  ->withSsoCredential("11Pay로부터 발급받은 SSO")  //Optional
  ->next()
  ->generateTokenBy("11Pay가 발급/전달한 가맹점 Secret");
C# Sample Code
String token = new SyrupPayTokenBuilder().Of("11Pay가 발급/전달한 가맹점 ID")
  .Login()
    .WithMerchantUserId("가맹점의 회원 고유 식별자")
    .WithSsoCredential("11Pay로부터 발급받은 SSO") //Optional
  .And()
  .GenerateTokenBy("11Pay가 발급/전달한 가맹점 Secret");
ASP Sample Code
Option Explicit

Dim objMctTAToken
Dim token

Set objMctTAToken = Server.CreateObject("SyrupPay.MctTAToken")
With objMctTAToken
  .Iss = "11Pay가 발급/전달한 가맹점 ID"
  .MctUserId = "merchantId"
  .SSOCredential = "11Pay로부터 발급받은 SSO"       'optional
End With

'WScript.Echo objMctTAToken.ToJson()
token = objMctTAToken.Serialzie("11Pay가 발급/전달한 가맹점 Secret")

Set objMctTAToken = Nothing

4. 유효성 및 토큰 정보 확인

11Pay가 지원하는 개발 언어별로, 토큰(Token) 유효성 여부 및 토큰 내 포함된 정보를 확인할 수 있습니다.

11Pay 서버에서 응답으로 전달된 암호화된 메시지도 동일하게 확인 가능합니다.

토큰/메시지 유효성 확인 예제 코드

Java Sample Code
import com.skplanet.jose.Jose;
import com.skplanet.jose.JoseHeader;
import com.skplanet.jose.JoseBuilders;
import com.skplanet.jose.jwa.suites.JwsAlgorithmSuites;
import com.skplanet.jose.jws.JwsHeader;

String kid = "11Pay가 발급/전달한 가맹점 ID";
String key = "11Pay가 발급/전달한 가맹점 Secret";

// 검증 후, 원 (JSON) 데이터를 Return합니다.
String jsonData = new Jose().configuration(
        JoseBuilders.compactDeserializationBuilder()
            .serializedSource("11Pay가 생성/전달한 JWT 형태의 값")
            .key(key)
).deserialization();
PHP Sample Code
require_once('../../../vendor/autoload.php');

// NOTE: 실제 사용 시 연속된 두개의 백슬래쉬는 하나의 백슬래쉬로 대체해서 사용해야 합니다.
use com\\skplanet\\jose\\JoseHeader;
use com\\skplanet\\jose\\jwa\\Jwa;
use com\\skplanet\\jose\\Jose;
use com\\skplanet\\jose\\JoseBuilders;
use com\\skplanet\\jose\\JoseHeaderSpec;

$iss = '11Pay가 발급/전달한 가맹점 ID';
$key = '11Pay가 발급/전달한 가맹점 Secret';

$jose = new Jose();

// 검증 후, 원 (JSON) 데이터를 Return합니다.
$jsonData = $jose->configuration(
    syruppay_jose_JoseBuilders::compactDeserializationBuilder()
    ->serializedSource('11Pay가 생성/전달한 JWT 형태의 값')
    ->key($key)
)->deserialization();

var_dump($claims);
C# Sample Code
using SyrupPayJose;
using SyrupPayJose.Jwa;

var kid = "11Pay가 발급/전달한 가맹점 ID";
var key = "11Pay가 발급/전달한 가맹점 Secret";

// 검증 후, 원 (JSON) 데이터를 Return 합니다.
var jsonData = new Jose().Configuration(
                JoseBuilders.CompactDeserializationBuilder()
                  .SerializedSource("11Pay가 생성/전달한 JWT 형태의 값")
                  .Key(key)
                ).Deserialization();
ASP Sample Code
Option Explicit

Dim objJOSEDeserilaize
Dim sJsonData

Dim sKey

sKey = "11Pay가 발급/전달한 가맹점 Secret"

set objJOSEDeserilaize = Server.CreateObject("SyrupPay.JoseDeserializer")
sJsonData = objJOSEDeserilaize.fromJose(sKey, "11Pay가 생성/전달한 JWT 형태의 값")

'WScript.Echo sJsonData

Set objJOSEDeserilaize = Nothing
Zackery Lim 2017-07-19
Copyright © 2018 11Street Co.,Ltd.. All Rights Reserved. (ver. 1.3.1)