캐시 키오스크 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 = calculate)

Check 명령: 엑솔라 번호로 사용자 신원 확인

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

Pay 명령: 계정으로 정기 결제 사용자 신원 확인

Pay 명령: 프로젝트/v1/v2/v3으로 정기 결제 사용자 신원 확인

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

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 응답을 생성합니다.

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

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

API와의 상호 작용

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

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

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

API 방식 설명

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

URL API

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

URL 마스크 형성

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

가져오기

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

액세스 권한 받기

API 액세스 권한을 받으려면 고객 성공 매니저에게 연락하거나 csm@xsolla.com으로 이메일을 보내 고유 파트너 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 형식(쉼표 또는 세미콜론을 구분 기호로 사용)
• 이전에 동의한 이메일은 stats@xsolla.com으로 전송
• 이메일 제목: “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;vassilliy@mail.ru

예제 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;vassilliy@mail.ru

예제 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를 쿼리한 후에 엑솔라는 다음 매개변수를 수신해야 합니다.