본문으로 건너뛰기

빌링에 구매 예약을 진행하며, 유저가 결제를 진행할 수 있는 XSOLLA 결제 URL을 요청

기본 정보​

  1. XSOLLA를 이용해서 유저가 결제를 진행할 수 있도록 결제 URL을 요청하는 API입니다
  2. XSOLLA의 ‘구매용 결제 토큰 생성하기’ API를 랩핑해서 제공해드립니다.
    • 빌링 API에서 제공하지 않는 기능이지만, 필요하다면 위 XSOLLA API 정의서를 참고하여 요청주시면 검토 후 개발 가능합니다.
항목내용비고
호출주체게임서버(s2s API)
도메인각 환경별 도메인
인증 방식HTTP 헤더 인증 정보
HTTP 메소드POST
Content-Typeapplication/x-www-form-urlencoded

Request​

HTTP Request end point​

POST https://각 환경별 빌링시스템 도메인/billing/api-game/v1/purchase/xsolla/reserve/withGetPaymentUrl

HTTP Request Header​

  • 아래의 HTTP Header들을 API 요청에 포함시켜야합니다.
이름값비고
X-Req-Pjid프로젝트ID기술 PM 등에게 전달받은 프로젝트ID
X-Auth-Access-Key인증용 키기술 PM 등에게 전달받은 해당 게임용 인증 키

HTTP Request Parameter​

  • 아래 파라미터들을 Content-Type: application/x-www-form-urlencoded 으로 호출하면 됩니다.
이름(Key)데이터 타입필수 Y/N설명예
reqIdString(100)Y중복 요청을 막거나 요청 추적을 위한 값userId_UUID 등과 같은 방식으로 생성
userId_reserve_98b50907-0928-493b-a816-dac8dbca1f53
pjidString(20)Y프로젝트ID
* 동일 게임이면 svcId가 달라도 동일		1202
svcIdString(20)Y서비스ID
* 플랫폼실 → 기술PM을 통해서 생성		120010101
imidString(40)YIMID
* 회원 플랫폼의 IMID로 로그인 후 얻을 수 있음
* playerId를 수집하지만 imid도 수집하는 이유는, 예약 단계에서 imid를 수집하여 한도 제한 기능 등을 구현할 때 사용
playerIdString(50)Y주문 완료를 진행하는 유저ID
ipCountryString(10)Y엑솔라 측에서 결제 통화 등을 판단하는데 국가코드가 중요하게 사용
player의 IP기반 국가코드로 법적 대응을 위해서 수집
서버IP 기반의 국가코드가 아니라, end 유저의 국가코드입니다.
* 3166-1 alpha-2 국가코드		KR
paymentString(20)Y결제가 진행된 수단, 스토어
* 돈을 지급한 행위가 발생한 결제수단의 코드로 스토어코드와 일치하지 않을수 도 있음		GOOGLE_PLAY, APPLE_APP, XSOLLA 등
appStoreString(20)Y앱을 다운로드한 플랫폼 스토어
* 개발사 입장에서는 배포한 스토어로 BIFROST 등		BIFROST 등
productIdString(200)Y구매 진행하는 상품ID(SKU와 같은 값)xsolla_test_gem_01
osString(10)Y구매가 진행되는 디바이스의 OS 종류코드표 OS참고
microPricelongY구매 금액 micro단위
* 사용측의 부동 소수점 오차를 방지하기 위해서 micro단위로 사용
* 국가별 한도처리 기능 제공을 위해서 예약 단계에서도 필요		구매 금액 micro단위(예. $0.99는 990,000 µ$. 100만을 곱함)
currencyString(10)Y구매 금액의 화폐 단위
* 3글자 포맷의 ISO-4217
* 국가별 한도처리 기능 제공을 위해서 필요		USD
playerNameValueString(250)Y엑솔라 결제 화면에서 보여지는 사용자 이름
* 인게임의 닉네임, 케릭터명 사용 가능		닉네임, 케릭터명
playerLangString(2)Y엑솔라 결제 인터페이스의 언어로 두 자리의 소문자 언어코드
* 엑솔라 페이 스테이션의 현지화 언어코드 지원(링크)
* 인게임내에서 지원하는 언어팩의 값을 활용 추천		ko, en, cn, tw 등

Response​

응답은 JSON형태로 전달됩니다.

Success sample​

  • 성공으로 응답하면 게임 서버는 게임 클라이언트에 paymentUrl을 리턴하여 웹브라우저(또는 웹뷰)를 이용해서 결제를 유도할 수 있습니다.
  • 웹뷰를 사용할 경우 페이지 이동이 자유롭지 않으면 결제가 진행되지 않을 수 있습니다.
  • 웹뷰 사용 시 해당 내용을 주의해야하며 특정 앱으로 이동하거나 새로운 창이 띄워지는 부분을 웹뷰에서 허용해야합니다
    • 즉, 상세한 테스트가 필요하기에 외부 브라우저 사용을 추천드립니다.
{
  "resultCode": "SUCCESS",
  "resultMessage": "request success",
  "resultData": {
    "xsollaEnv": "SANDBOX",
    "xsollaOrderId": 95132267,
    "xsollaToken": "ziqkqzWcKJkRyLASVlx562QuJDWWa1H6_lc_ko_bg_FFFFFF_tb_3D46F5",
    "paymentUrl": "https://sandbox-secure.xsolla.com/paystation4/?token=ziqkqzWcKJkRyLASVlx562QuJDWWa1H6_lc_ko_bg_FFFFFF_tb_3D46F5"
  }
}

Response property​

  • 응답 성공인 경우의 resultData에 json 필드 설명입니다.
keydata typedescriptionexample
boidString빌링에서 생성된 유니크한 id57
xsollaEnvString엑솔라 환경
* 빌링 시스템에 셋팅된 엑솔라 결제 환경		PROD 또는 SANDBOX
xsollaOrderIdint엑솔라 주문ID로 게임에는 참고 목적으로 응답
유저의 영수증에 표시되는 ID는 아님		12345
paymentUrlString(500)결제 URL(해당 URL을 유저에게 보여줘서 결제를 유도)결제 URL(Success sample 참고)

Error sample​

  • reqId 중복 요청
{
    "resultCode": "INVALID_PARAMETER",
    "resultMessage": "duplicated reqeust. Check your 'reqId' or duplicated request data."
}
  • 한도 제한으로 추가 처리가 필요한 경우 에러
    • PURCHASE_MONTHLY_LIMITED 에러코드가 리턴됩니다.
    • 게임쪽에서 추가 로직을 구현에 사용하실 수 있도록 해당 에러코드가 리턴되면 monthlyLimitedDetail을 추가로 응답합니다.
    • 추가 정보 필드들에 대한 설명
keydata typedescriptionexample
appliedPolicyString한도제한이 적용된 정책코드

  1. 한국

    1. KR_ADULT

      1. 한국 성인의 월 한도 제한 제약으로 차단됨

      2. 성인은 HYBE IM에서 제공하는 '계정센터를 통해서 한도 상향 가능

        1. SDK에서 제공하는 ‘계정센터 성인의 한도제한 변경 페이지로 유도’

    2. KR_MINOR

      1. 한국 미성년

        1. 한국 미성년은 한도 수정이 불가. 즉, 한도제한 변경 페이지로 유도하면 안됨

  2. 일본(성인은 한도제한 없음)

    1. JP_MINOR_UNDER_AGE_18_OVER_16

      1. 18세 미만 16세 이상

    2. JP_MINOR_UNDER_AGE_16

      1. 16세 미만
currencyString통화KRW, JPY
limitConfigMircoPriceLong설정된 한도 금액 micro단위30000000000
thisMonthAmountMircoPriceLong

이번달 구매 금액의 micro단위

  • 예) $0.99는 990,000 µ$. 100만을 곱함
29500000000
countryCreatedString

해당 유저 계정에 생성된 국가 코드

  • imid가 생성된 시점에 IP기반 국가코드
  • 정책이 계정 생성 시점을 기준으로 작동
JP, KR
debugMessageString

개발자 디버깅 참고용 응답 메시지

  • 주의: 해당 메시지로 로직 작성 X
일본 미성년자('16세') 한도 초과로 구매 중단. 한도 설정: '30000' | 이번달 구매한 대상 금액(JPY):'29500.0000' | 추가 구매하려는 금액:'550.950000' | 총합:'30050.950000
  • 한국 한도제한 적용됨: KR_MINOR
{
  "resultCode": "PURCHASE_MONTHLY_LIMITED",
  "resultMessage": "Requests exceeding the monthly purchase limit.",
  "resultData": {
    "monthlyLimitedDetail": {
      "appliedPolicy": "KR_MINOR",
      "limitConfigMircoPrice": 70000000000,
      "currency": "KRW",
      "thisMonthAmountMircoPrice": 68000000000,
      "countryCreated": "KR",
      "debugMessage": "한국 한도 초과로 구매 중단('9세'). 한도:'70000' | 이번달 구매한 대상 금액(특정 다운로드 앱 스토어 & KRW):68000.0000 | 추가 구매하려는 금액:'59000.000000' | 총합:127000.000000"
    }
  }
}
  • 한국 한도제한 적용됨: KR_ADULT
{
  "resultCode": "PURCHASE_MONTHLY_LIMITED",
  "resultMessage": "Requests exceeding the monthly purchase limit.",
  "resultData": {
    "monthlyLimitedDetail": {
      "appliedPolicy": "KR_ADULT",
      "limitConfigMircoPrice": 1000000000000,
      "currency": "KRW",
      "thisMonthAmountMircoPrice": 990000000000,
      "countryCreated": "KR",
      "debugMessage": "한국 한도 초과로 구매 중단('22세'). 한도:'1000000' | 이번달 구매한 대상 금액(특정 다운로드 앱 스토어 & KRW):990000.0000 | 추가 구매하려는 금액:'120000.000000' | 총합:1110000.000000"
    }
  }
}
  • 일본 한도제한 적용됨: JP_MINOR_UNDER_AGE_16
{
  "resultCode": "PURCHASE_MONTHLY_LIMITED",
  "resultMessage": "Requests exceeding the monthly purchase limit.",
  "resultData": {
    "monthlyLimitedDetail": {
      "appliedPolicy": "JP_MINOR_UNDER_AGE_16",
      "limitConfigMircoPrice": 5000000000,
      "currency": "JPY",
      "thisMonthAmountMircoPrice": 4800000000,
      "countryCreated": "JP",
      "debugMessage": "일본 미성년자('10세') 한도 초과로 구매 중단. 한도 설정: '5000' | 이번달 구매한 대상 금액(JPY):'4800.0000' | 추가 구매하려는 금액:'550.950000' | 총합:'5350.950000'"
    }
  }
}
  • 일본 한도제한 적용됨: JP_MINOR_UNDER_AGE_18_OVER_16
{
  "resultCode": "PURCHASE_MONTHLY_LIMITED",
  "resultMessage": "Requests exceeding the monthly purchase limit.",
  "resultData": {
    "monthlyLimitedDetail": {
      "appliedPolicy": "JP_MINOR_UNDER_AGE_18_OVER_16",
      "limitConfigMircoPrice": 30000000000,
      "currency": "JPY",
      "thisMonthAmountMircoPrice": 29500000000,
      "countryCreated": "JP",
      "debugMessage": "일본 미성년자('16세') 한도 초과로 구매 중단. 한도 설정: '30000' | 이번달 구매한 대상 금액(JPY):'29500.0000' | 추가 구매하려는 금액:'550.950000' | 총합:'30050.950000'"
    }
  }
}

에러 코드 정의​

  • 아래와 같은 에러코드가 resultCode에 응답될 수 있습니다.
  • 아래의 에러코드들은 모든 빌링 API에서 발생 가능한 에러 코드들입니다.
    • 해당 에러코드 외에 각 API에서만 발생가능한 에러코드들도 있습니다.
    • 각 에러 코드를 바탕으로 필요시 비즈니스 로직을 작성하시면 됩니다.
에러코드비고
SYSTEM_ERROR

빌링 API에서 발생한 시스템 에러

  • HTTP 상태코드 500 리턴
NOT_ALLOW_AUTHAPI 인증 헤더 누락이거나 기타 권한이 없는 요청에서 발생
  • 아래 에러 코드들은 해당 API에서 발생 가능한 추가 에러 코드들입니다.
  • 특정 결제 수단인 경우 아래와 같은 에러 코드가 resultCode에 응답될 수 있습니다.
  • 특정 국가에서 요구하는 월 구매금액 한도 제한을 빌링 시스템에서 제공하기 위한 에러코드가 포함됩니다.
    • 한국: ‘결제 한도 자율 규제’에 따라서 PC 자체 서비스에 대해서, 한국에서 생성된 계정에 대한 정책
    • 일본: ‘일본 청소년 소셜 게임 결제 자율 규제’에 따라서 1) 성인 2)18세 미만~16세 이상 3)16세 미만
에러코드비고
에러코드비고
INVALID_PARAMETER요청된 파라미터 오류
EXTERNAL_API_ERROR빌링 API가 호출하는 외부 API가 에러인 경우
JAPANESE_DATE_BIRTH_REQUIRED

일본 IP에서 생성된 계정(imid)인데 생년월일 정보를 입력하지 않아서 입력 필요

  • 로그인 과정에서 유저 이탈을 막기 위해서 결제 시점에 체크

  • 해당 에러 코드가 리턴되면 SDK를 통해서 제공되는 생년월일 입력 웹뷰를 호출해서 입력 유도

    • 상세 내용은 SDK 가이드 참고
    • 생년월일이 입력되면 구매 예약을 다시 시도했을 때 해당 에러코드가 리턴되지 않음
PURCHASE_MONTHLY_LIMITED

한국 또는 일본에서 생성된 계정이고, 한도 체크 대상에 포함되는 대상인데 이번달 결제 금액이 한도를 초과

  • 참고: 한국인인 경우 결제 한도 자율 규제에 따라서 성인은 ‘HYBE IM’의 계정센터 웹에서 한도 상향 가능

  • 일본 성인은 한도 제한 금액이 없음

    • 18세 미만 16세 이상은 3만엔
    • 16세 미만은 5천엔

요청 curl 샘플​

  • 도메인 및 인증 헤더 등은 변경 필요
curl -X 'POST' \
  '도메인/billing/api-game/v1/purchase/xsolla/reserve/withGetPaymentUrl' \
  -H 'accept: application/json;charset=UTF-8' \
  -H 'X-Req-Pjid: 입력필요' \
  -H 'X-Auth-Access-Key: 입력필요' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'appStore=BIFROST&os=WIN64&microPrice=990000&playerNameValue=%EB%8B%89%EB%84%A4%EC%9E%84&payment=XSOLLA&productId=xsolla_test_group_item_01&ipCountry=KR&playerLang=ko&currency=USD&pjid=1201&reqId=playerId_1reserve_98b50907-0928-493b-a816-dac8dbca1f53&svcId=12010020&playerId=test_playerId&imid=DJ883RWED6N2HYP5XGGA'