캐시 키오스크 API v2.0

게임 카탈로그 API

게임 카탈로그를 제공하기 위해 설계된 API로 엑솔라 시스템에서 사용할 수 있는 모든 프로젝트의 목록으로 구성되어 있습니다. API는 프로젝트 이름, 프로젝트 아이콘, 결제 매개변수와 같은 각 프로젝트에 대한 기본 정보를 제공합니다. 위에서 언급한 정보는 프로젝트에 대한 결제 페이지를 생성할 때 사용할 수 있습니다.

게임 카탈로그 API는 캐시 키오스크를 통하거나 UI에 “게임 버튼” 배치하여 결제하는 데 유용하게 사용할 수 있습니다. 일반 “엑솔라” 버튼을 캐시 키오스크 화면의 “게임 버튼”으로 교체하면 사용자는 자신이 좋아하는 프로젝트에서 쉽고 일반적인 방식으로 결제를 수행할 수 있습니다.

URL API: https://api.xsolla.com/projects/list/index.php

요청 형식

게임 목록 조회 요청 매개 변수

서명 생성

서명은 결제 작업을 확인하고 수행하는 동안 보안을 유지하기 위해 고안되었습니다. 서명은 위에서 언급한 매개변수를 연결하여 생성한 문자열을 MD5 해시하여 형성하며 아래에 표시된 순서에 따라 “|“로 구분합니다.

1md5(<ID>|<secret_key>)

secret_key: 상대방의 비밀 키입니다.

예제: 비밀 키 “SecretKey"를 가진 상대방 #184에 대한 서명은 다음과 같이 형성됩니다.

$sign=md5(“184|SecretKey”)=0a8d9fb24fcbac2efafec5e51045d05c

요청 예제:

https://api.xsolla.com/projects/list/index.php?id=184&sign=0a8d9fb24fcbac2efafec5e51045d05c

응답 형식

요청에 대한 응답은 XML 형식으로 제출되며 각 게임에 대한 기본 정보와 게임 목록을 모두 포함합니다. XML 구조는 다음과 같습니다.

 1<projectlist>
 2   <project>
 3       <id>12345</id>
 4       <name>Game</name>
 5       <virtual_currency>Game of currency</virtual_currency>
 6       <logo>http://static.xsolla.com/img/game/12345.gif</logo>
 7       <limits>
 8           <min>Minimum of amount game of currency</min>
 9           <max>max of amount game of currency</max>
10       </limits>
11       <prompt>enter nickname of personage</prompt>
12       <v1>nickname of personage</v1>
13   </project>
14   ...
15</projectlist>

필드 설명

오류 발생 시 응답 형식

오류가 발생하면 API는 XML 메시지로 응답합니다.

1<error>
2    <description>Incorrect signature</description>
3</error>

오류 설명

에이전트와의 상호작용

개요

다음 두 가지 방식으로 상호작용할 수 있습니다.

• 엑솔라 버튼. 이 버튼은 에이전트 측에 배치됩니다. 버튼을 클릭하면 이전에 받은 번호를 입력하고 해당 번호로 결제하도록 사용자에게 안내합니다. 엑솔라 버튼 결제를 활성화하려면 account 입력란을 채웁니다(project, v1, v2, v3 입력란은 비워 두세요). account에는 9자리 엑솔라 번호가 있어야 합니다. 엑솔라 버튼을 설정하려면 담당자에게 문의해 로고와 번호를 발급받아야 합니다.

• 게임 버튼. 이 버튼은 에이전트 측에 배치되며, 각 버튼은 서로 다른 게임에 대응합니다. 사용자는 특정 게임의 버튼을 클릭한 뒤 로그인하여 본인 계정으로 결제합니다. 게임별 버튼으로 결제를 받으려면 project, v1, v2, v3 입력란을 채웁니다(account는 비워 두세요). 터미널에 특정 프로젝트(게임) 버튼을 구성한 후에 project, v1, v2, v3 입력란을 전송할 수 있습니다. project와 v1은 필수이고, v2와 v3는 선택이며 각 프로젝트에 따라 다릅니다. 게임 버튼을 설정하려면 담당자에게 문의해 각 게임의 로고, 내부 ID, 인증 방법(v1, v2, v3 입력 규칙) 등 필요한 정보를 받아야 합니다.

버튼은 에이전트 시스템의 구성 요소이며 버튼을 활성화하면 엑솔라 시스템을 통한 결제 기능을 사용할 수 있게 됩니다.

에이전트를 엑솔라 시스템에 연결하기 전에 다음 사항을 명확히 해야 합니다.

1. 엑솔라 시스템 내 파트너 번호(유형). 엑솔라의 고객 성공 매니저로부터 해당 정보를 받을 수 있습니다.
2. secret_key - 디지털 서명(MD5-문자열)을 구성하는데 필요한 기밀 문자열 매개변수입니다. 이는 고객 성공 매니저를 통해 관리자 페이지에서 확인할 수 있습니다.

HTTP 요청을 다음 API 게이트웨이 주소로 전송하여 API와 상호작용할 수 있습니다. 주소:

1https://ps.xsolla.com/api/gate

API는 GET 또는 POST 방식을 허용하며 모든 매개변수는 UTF-8로 인코딩되어야 합니다. 다른 문자 집합을 사용하면 서명 문제가 발생할 수 있습니다.

요청 형식

엑솔라로 다음 요청을 보낼 수 있습니다.

• 결제 가능 여부 확인(command = check)
• 결제 진행(command = pay)
• 결제가 성공했는지 확인(command = status)
• 비용과 게임 통화 금액 계산(command = calculate)

Check 명령

Check 명령: 엑솔라 번호로 사용자 식별

Check 명령: 프로젝트/v1/v2/v3으로 사용자 신원 확인

Pay 명령

Pay 명령: account로 가입자 식별

Pay 명령: project/v1/v2/v3로 가입자 식별

Status 명령

결제가 성공했는지 여부는 사용자 시스템의 거래 ID(id 매개 변수) 또는 엑솔라 측 거래 ID(invoice 매개 변수)로 확인할 수 있습니다. 두 매개 변수를 모두 전달하는 경우 동일한 결제 건에 속해야 하며, 그렇지 않으면 엑솔라는 유효성 검사 오류를 반환합니다.

Status 명령: 사용자 시스템의 거래 ID로 결제 성공 확인

예시:

1https://ps.xsolla.com/api/gate?command=status&id=xsollaid2&type=151&date=20060425180622&md5=0a8d9fb24fcbac2efafec5e51045d05c

Status 명령: 엑솔라 측 거래 ID로 결제 성공 확인

예시:

1https://ps.xsolla.com/api/gate?command=status&invoice=987654321&type=151&date=20060425180622&md5=0a8d9fb24fcbac2efafec5e51045d05c

Calculate 명령

MD5 필드 생성

서명은 안전한 결제 및 결제 진행을 보장합니다. 이는 옵션 매개변수와 엑솔라 고객 성공 매니저로부터 받을 수 있는 결제 시스템 개인 키 등 전송된 모든 매개변수 값을 연결하여 만든 문자열에서 비롯한 MD5 해시를 통해 요청이 오는 순서에 따라 차례대로 생성됩니다.

Check 명령

 1<?php
 2  $request['command']='check';
 3  $request['account']=1234567;
 4  $request['sum']=150.75;
 5  $request['type']=151;
 6  $request['date']='20110117000516';
 7  $md5='';
 8  foreach ($request as $value) {
 9  $md5.=$value;
10  }
11  $request['md5']=md5($md5.$secret_key);
12?>

라인:

check1234567150.7515120110117000516test

MD5:

1cad5a2c3457cffa8e857a507a7050ba

Pay 명령

 1<?php
 2$request['command']='pay';
 3$request['account']=1234567;
 4$request['sum']=150.75;
 5$request['id']=384957;
 6$request['type']=151;
 7$request['date']='20110117000516';
 8$md5='';
 9foreach ($request as $value) {
10$md5.=$value;
11}
12$request['md5']=md5($md5.$secret_key);
13?>

라인:

pay1234567150.7538495715120110117000516test

MD5:

7cfa05abde4ae2464142bf2ac7a72f32

Status 명령 서명 생성(사용자 시스템의 거래 ID로 확인)

 1$request['command'] = 'status';
 2$request['id']      = 'xsollaid2';
 3$request['type']    = 151;
 4$request['date']    = '20110117000516';
 5
 6$md5 = '';
 7foreach ($request as $value) {
 8    $md5 .= $value;
 9}
10$request['md5'] = md5($md5 . $secret_key);

라인:

statusxsollaid215120110117000516+secret_key

MD5:

7cfa05abde4ae2464142bf2ac7a72f32(예시)

Status 명령 서명 생성(엑솔라 측 거래 ID로 확인)

 1$request['command'] = 'status';
 2$request['invoice'] = 987654321;
 3$request['type']    = 151;
 4$request['date']    = '20110117000516';
 5
 6$md5 = '';
 7foreach ($request as $value) {
 8    $md5 .= $value;
 9}
10$request['md5'] = md5($md5 . $secret_key);

라인:

status98765432115120110117000516+secret_key

MD5:

7cfa05abde4ae2464142bf2ac7a72f32(예시)

Calculate 명령

 1<?php
 2  $request['command']='calculate';
 3  $request['project']=4783;
 4  $request['out']=12;
 5  $request['type']=151;
 6  $request['date']='20110117000516';
 7  $md5='';
 8  foreach ($request as $value) {
 9  $md5.=$value;
10  }
11  $request['md5']=md5($md5.$secret_key);
12?>

라인:

calculate47831215120110117000516test

MD5:

e73e11a9cad00e205358e05254905af5

응답

응답 코드

엑솔라는 result에 상태 코드를, comment에 설명을 포함하는 XML을 생성합니다.

오류가 포함된 응답 예시:

1<response>
2  <result>7</result>
3  <comment>md5 error</comment>
4</response>

성공 응답 코드

result가 0이면 응답에 결제에 대한 상세 정보가 담긴 payment 블록이 함께 포함됩니다. 결제 상태 코드는 status 매개 변수에서 전달됩니다.

상태 명령에 대한 성공 응답 예시:

 1<response>
 2  <payment>
 3    <invoice>123456789</invoice>
 4    <id>xsollaid2</id>
 5    <sum>100.98</sum>
 6    <project>4783</project>
 7    <v1>XsollaUser</v1>
 8    <date>2026-01-23 12:34:56</date>  <!-- present only when status is succeeded -->
 9    <status>1</status>
10    <comment>succeeded</comment>
11    <statusKioskUrl>https://secure.xsolla.com/pages/status-kiosk?id=123456789&key=9e07b3…</statusKioskUrl>
12  </payment>
13  <result>0</result>
14</response>

결제 시스템 거래 레지스트리 API

본 문서는 결제 시스템 거래 레지스트리 API를 사용하여 사용자가 프로젝트에서 가상 상품 및 서비스에 대한 비용을 지불하도록 하려는 개발자를 대상으로 합니다. 본 문서는 API, HTTP 요청 및 소프트웨어 아키텍처에 대한 기본 지식을 고려합니다.

API 연동

• 작업은 서버 투 서버 통합을 통해서만 가능합니다.

• 모든 매개변수는 UTF-8 코딩을 사용해야 합니다.

• 데이터는 CSV 형식으로 반환됩니다.

API 메서드 설명

• Get(가져오기) – 결제 데이터 수신 요청.

API URL

기본 URL: https://api.xsolla.com/payments/

URL 마스크

1https://api.xsolla.com/payments/v<number versions>/<command>?<parameter1=value1>&<parameter2=value2

받기

본 명령은 24시간 이내에 모든 결제 시스템으로부터 지정된 상대방에 해당하는 결제 데이터를 전송하라는 요청을 생성합니다.

API 액세스 권한 받기

API 액세스 권한을 받으려면 고객 성공 매니저에게 연락하거나 [email protected]으로 이메일을 보내 고유 파트너 ID와 비밀 키를 받아야 합니다.

요청 예시

https://api.xsolla.com/payments/v1/Get?date=2013-08-20&id=1234&sign=8f683701c03b03fe49e6ef7bbfafb8fb

입력 매개 변수

응답

회신은 CSV 형식으로 제공됩니다(구분 기호로 쉼표 “,” 사용).

69927355,95188933,394,2013-08-01T06:49:25+04:00,91.0000,RUB,done

필드 설명:

서명 생성

서명은 매개변수 값과 비밀 키를 연결하여 생성한 문자열을 MD5 해시한 결과물입니다(관리자로부터 방법을 배울 수 있습니다). 비밀 암호는 서명에도 필요합니다(비밀 암호는 관리자로부터 받을 수 있습니다). 구분 기호는 “|“입니다.

요청 예시

1date = 2013-08-20;
2id=1234;
3secret_key=password.

문자열은 다음과 같이 표시됩니다.

2013-08-20|1234|password

위 문자열의 MD5:

e8df0ff2e4360300a5142cc28d86b422

완료 코드 목록

결제 시스템과의 거래 조정

이메일 알림을 통한 조정

거래 조정은 특정 형식으로 된 첨부 파일이 있는 이메일을 전송하는 결제 시스템으로 구성되어 있습니다. 조정 빈도는 사전에 정해집니다.

조정 문서 형식

거래 조정 문서 형식:

• UTF-8 코딩 사용
• CSV 형식(쉼표 또는 세미콜론을 구분 기호로 사용)
• 이전에 동의한 이메일은 [email protected]으로 전송
• 이메일 제목: “stats registry”
• 첨부 파일 이름: stats_registry_period:기간: 2개 날짜. YYYY-MM-DD 형식: start_dateTend_date기간이 하루(24시간)로 구성되어 있는 경우 “T” 이후에 포함된 기간은 생략할 수 있습니다

문서 내용

레지스트리 예시

예제 1

197035765;6654448;10.00;9.50;RUB;done;2011-09-01 13:30:45;nickname
2
397035766;6634558;150.00;145.00;RUB;done;2011-09-01 16:43:54;[email protected]

예제 2(결제 시스템에 pid가 없는 경우)

1564;;10.00;9.50;RUB;done;2011-09-01 13:30:45;nickname
2
3456;;150.00;145.00;RUB;done;2011-09-01 16:43:54;[email protected]

예제 3(desc가 없는 경우 마지막에 세미콜론으로 메모를 남깁니다.)

1564;6654855;10.00;9.50;RUB;done;2011-09-01 13:30:45;
2
3456;4588554;150.00;145.00;RUB;done;2011-09-01 16:43:54;

결제 시스템 API를 통한 조정

결제 시스템의 HTTP(HTTPS) API를 사용하여 거래 조정을 수행할 수 있습니다. API를 쿼리한 후에 엑솔라는 다음 매개변수를 수신해야 합니다.