본 문서는 (주)메이즈 Open API 개발 연동을 위한 안내 문서입니다.
실제로 (주)메이즈 Open API를 사용하기 위해서는 (주)메이즈 API 계정으로 로그인 후 서 API Client ID, Client Secret 을 신청,
OpenAPI 연동까지 2단계의 절차가 있습니다.
Open API는 사전 승인등록된 게임사를 기준으로 사용이 가능합니다. 본 문서에는 게임사 제공 API의 내용이 기술되어 있습니다.
호출 도메인 주소는 https://{도메인}/api/{제공API} 형식이며 주소는 도메인 표를 확인해주세요.
Restful방식으로 호출이 가능하며 Method는 GET/POST 만 지원합니다.
통신 구간에 대한 암호화는 HTTPS 방식을 사용합니다. 통신 포맷은 JSON 규격으로 제공합니다.
구분 | URL | IP |
---|---|---|
테스트(Test) | test-api.maze.games | 106.249.36.18 |
라이브(Live) | api.maze.games | 117.52.84.85 |
구분 | API 명 | 1일 허용량 |
---|---|---|
회원 | 팬덤박스 회원 조회 | 제한 없음 |
결제 | 게임 결제정보 등록 | 제한 없음 |
게임 결제정보 취소처리 | 제한 없음 |
날짜 | 제목 | 변경 내용 |
---|---|---|
2023.10.02 | 최초 작성 | API 문서화 |
2023.10.18 | API 추가 | 결제취소 API 추가 |
2024.03.07 | API 문서 개편 | API 문서 템플릿 변경 |
2024.05.21 | API 문서 내용 수정 | API 문서 잘못된 안내문구 수정, 테스트 전용 accountId 표시 |
API의 인증 단계는 아래와 같습니다.
HMAC 서명 생성 및 API 호출
HMAC은 해시 메시지 인증코드(Hash Message Authentication Code)의 준말로써 RFC2104 표준 암호화 프로토콜입니다. 메이즈 API는
HMAC기반으로 제작되었으며 모든 request header의 Authorization에 생성한 HMAC signature를 함께 보내주셔야 합니다. 아래는 HMAC
signature 생성 및 API 호출 예시입니다.
항목 | 필수여부 | 자료형 | 길이 | 설명 |
---|---|---|---|---|
grant_type | O | string | - | 인증 방식 |
client_id | O | string | 40 | API Client ID |
client_secret | O | string | 40 | API Client Key |
scope | O | string | - | API 계정 |
username | O | string | - | API 사용자 계정 |
password | O | string | - | API 사용자 비밀번호 |
항목 | 필수여부 | 자료형 | 길이 | 설명 |
---|---|---|---|---|
token_type | O | string | 6 | 토큰 타입 |
expires_in | O | integer | 7 | 토큰 유효시간 |
access_token | O | string | - | 인증 토큰 |
refresh_token | O | string | - | 재인증 토큰 |
import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.util.HashMap;
import java.util.Map;
public class OAuthClient {
public static void main(String[] args) {
HttpClient client = HttpClient.newHttpClient();
Map data = new HashMap<>();
data.put("grant_type", "password");
data.put("client_id", "YOUR_CLIENT_ID");
data.put("client_secret", "YOUR_CLIENT_SECRET");
data.put("username", "USER_EMAIL");
data.put("password", "USER_PASSWORD");
data.put("scope", "");
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://{API 도메인 주소}/oauth/token"))
.headers("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(data.toString()))
.build();
try {
HttpResponse response = client.send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());
} catch (Exception e) {
e.printStackTrace();
}
}
}
import requests
data = {
'grant_type': 'password',
'client_id': 'YOUR_CLIENT_ID',
'client_secret': 'YOUR_CLIENT_SECRET',
'username': 'USER_EMAIL',
'password': 'USER_PASSWORD',
'scope': ''
}
response = requests.post('https://{API 도메인 주소}/oauth/token', json=data)
print(response.text)
$data = [
'grant_type' => 'password',
'client_id' => 'YOUR_CLIENT_ID',
'client_secret' => 'YOUR_CLIENT_SECRET',
'username' => 'USER_EMAIL',
'password' => 'USER_PASSWORD',
'scope' => ''
];
$ch = curl_init('https://{API 도메인 주소}/oauth/token');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
$response = curl_exec($ch);
curl_close($ch);
echo $response;
using System;
using System.Collections.Generic;
using System.Net.Http;
using System.Threading.Tasks;
class OAuthClient
{
static async Task Main(string[] args)
{
using (var client = new HttpClient())
{
var data = new Dictionary
{
{"grant_type", "password"},
{"client_id", "YOUR_CLIENT_ID"},
{"client_secret", "YOUR_CLIENT_SECRET"},
{"username", "USER_EMAIL"},
{"password", "USER_PASSWORD"},
{"scope", ""}
};
var response = await client.PostAsync("https://{API 도메인 주소}/oauth/token", new FormUrlEncodedContent(data));
var responseString = await response.Content.ReadAsStringAsync();
Console.WriteLine(responseString);
}
}
}
const axios = require('axios');
const data = {
grant_type: 'password',
client_id: 'YOUR_CLIENT_ID',
client_secret: 'YOUR_CLIENT_SECRET',
username: 'USER_EMAIL',
password: 'USER_PASSWORD',
scope: ''
};
axios.post('https://{API 도메인 주소}/oauth/token', data)
.then((response) => {
console.log(response.data);
})
.catch((error) => {
console.error(error);
});
"Authorization": "Bearer 인증키"
"Content-Type": "application/json"
"Accept": "application/json"
팬덤박스 회원의 사용자 ID 또는 후원코드로 사용자를 조회합니다.
항목 | 필수여부 | 자료형 | 길이 | 설명 |
---|---|---|---|---|
accountId | O | string | 15 | 팬덤박스 구글 ID 또는 후원코드(테스트 ID: maze) |
항목 | 필수여부 | 자료형 | 길이 | 설명 |
---|---|---|---|---|
success | O | integer | 1 | 요청 성공 여부 |
code | O | integer | 3 | 결과 코드 |
message | O | string | 50 | 결과 메시지 |
exists | O | boolean | - | 사용자 존재 여부 |
accountId | O | string | 15 | 조회된 사용자 ID 또는 후원코드 |
팬덤박스에 플랫폼 결제 정보 제공합니다.
항목 | 필수여부 | 자료형 | 길이 | 설명 |
---|---|---|---|---|
accountId | O | string | 15 | 팬덤박스 구글 ID 또는 후원코드 (테스트 ID: maze) |
orderId | O | string | 255 | 주문번호 |
marketplace | O | integer | 1 | 결제 플랫폼(1:구글, 2:애플, 3: MS, 4:갤럭시, 5:원스토어, 6:기타) |
gameCode | O | string | 6 | 메이즈 게임코드 (테스트 게임코드 : Bs9zev) |
orderPrice | O | integer | 10 | 결제 금액 |
항목 | 필수여부 | 자료형 | 길이 | 설명 |
---|---|---|---|---|
success | O | integer | 1 | 요청 성공 여부 |
code | O | integer | 3 | 결과 코드 |
message | O | string | 50 | 결과 메시지 |
팬덤박스에 제공한 결제 정보를 취소 처리합니다.(취소한 결제 정보는 재사용이 불가능합니다.)
항목 | 필수여부 | 자료형 | 길이 | 설명 |
---|---|---|---|---|
orderId | O | string | 50 | 주문번호 |
항목 | 필수여부 | 자료형 | 길이 | 설명 |
---|---|---|---|---|
success | O | integer | 1 | 요청 성공 여부 |
code | O | integer | 3 | 결과 코드 |
message | O | string | 50 | 결과 메시지 |
(주)메이즈 API 서비스에서 사용되는 결과코드에 대한 안내입니다.
응답코드 | 메세지 |
---|---|
101 | `accountId`를 입력해주세요. |
102 | `accountId`형식이 옳지않습니다. |
201 | `orderId`를 입력해주세요. |
202 | `orderId`형식이 옳지않습니다. |
203 | `orderId`는 최대 255자 이하이어야 합니다. |
204 | `orderId`는 존재하지 않습니다. |
301 | `marketplace`를 입력해주세요. |
302 | `marketplace`형식이 옳지않습니다. |
303 | `marketplace`는 허용되지 않는 값입니다. |
401 | `gameCode`를 입력해주세요. |
402 | `gameCode`형식이 옳지않습니다. |
501 | `orderPrice`를 입력해주세요. |
502 | `orderPrice`형식이 옳지않습니다. |
503 | `orderPrice`는 0원 이상이어야 합니다. |
에러코드 | 메세지 |
---|---|
1 | 구글 ID 또는 후원코드를 확인할 수 없습니다. |
2 | 가입 정보가 없는 게임 입니다. |
3 | 반환 가능한 적립금이 없습니다. |
4 | 이미 취소 처리된 주문입니다. |
5 | 피후원자 정보를 찾을 수 없습니다. |
6 | 차단된 회원입니다. |