はじめに/認証
認証とリクエスト署名
プロジェクト UUID と API キーを使用して、HMAC-SHA256 で API リクエストに署名します。
すべての API リクエスト（受信 Webhook を除く）には、プロジェクト UUID とリクエスト署名を含める必要があります。署名は、リクエストがあなたから送信されたものであり、途中で誰にも改ざんされていないことを証明します。
API キー
2328.io は、同一の署名アルゴリズムを共有しつつ異なるエンドポイントに対応する 2 つのキー を使用します：
| Key | Used for |
|---|---|
| API key | 支払い、固定ウォレット、残高、為替レート、および支払い／固定ウォレット Webhook の検証 |
| Payout API key | すべての /v1/payout/* エンドポイントおよび出金 Webhook の検証 |
両方のキーは 2328.io のプロジェクト設定にあります。以下の例では便宜上「API key」と総称していますが、呼び出すエンドポイントに応じて適切なキーに置き換えてください。
絶対に 2 つのキーを混在させないでください。通常の API キーで出金リクエストに署名する（または出金キーで支払いリクエストに署名する）と署名エラーが返されます。
必須ヘッダー
| Header | Type | Required | Description |
|---|---|---|---|
Content-Type | string | yes | 常に application/json |
project | string | yes | プロジェクト UUID |
sign | string | yes | API キーで計算したリクエストの HMAC-SHA256 署名 |
User-Agent | string | はい | あなたのアプリケーションを識別します（例: MyShop/1.4 (+https://myshop.example)）。User-Agent がないリクエストはブロックされる場合があります。 |
署名の仕組み
署名はリクエストボディのフィンガープリントだと考えてください。次の手順で生成します：
- ボディを JSON にシリアライズします（コンパクト — 余分な空白なし）。
- その JSON を Base64 でエンコードします。この手順により、入力が言語間で正規化されます — 純粋な ASCII になれば、どの言語でも HMAC に対して同じバイト列が生成されます。
- API キーで Base64 文字列の HMAC-SHA256 を計算し、結果を小文字の 16 進数に変換します。
GET やボディを持たないその他のリクエストタイプでは、JSON の代わりに空文字列に署名します。
空文字列の署名は、ある API キーに対して定数になります。GET 呼び出しが多い場合はキャッシュできます。
実装例
PHP
<?php
function apiSign(array $data, string $apiKey): string {
$json = json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$base64 = base64_encode($json);
return hash_hmac('sha256', $base64, $apiKey);
}JavaScript
import crypto from "crypto";
export function apiSign(data, apiKey) {
const json = JSON.stringify(data);
const base64 = Buffer.from(json).toString("base64");
return crypto.createHmac("sha256", apiKey).update(base64).digest("hex");
}TypeScript
import { createHmac } from "crypto";
export function apiSign(data: object, apiKey: string): string {
const json = JSON.stringify(data);
const base64 = Buffer.from(json).toString("base64");
return createHmac("sha256", apiKey).update(base64).digest("hex");
}Python
import json
import hmac
import hashlib
import base64
def api_sign(data: dict, api_key: str) -> str:
# ensure_ascii=False keeps non-ASCII characters (Cyrillic, Chinese, …)
# as-is. Without it, Python escapes them to \uXXXX and the signature
# diverges from PHP / Node / Go.
body = json.dumps(data, separators=(",", ":"), ensure_ascii=False)
b64 = base64.b64encode(body.encode("utf-8")).decode()
return hmac.new(api_key.encode(), b64.encode(), hashlib.sha256).hexdigest()Go
package sign
import (
"bytes"
"crypto/hmac"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"encoding/json"
)
func ApiSign(data any, apiKey string) (string, error) {
// json.Encoder with SetEscapeHTML(false) — without it, Go escapes <, >, &
// to \u003c etc., which breaks compatibility with PHP / Node / Python.
var buf bytes.Buffer
enc := json.NewEncoder(&buf)
enc.SetEscapeHTML(false)
if err := enc.Encode(data); err != nil {
return "", err
}
// Encoder appends a trailing newline — drop it.
body := bytes.TrimRight(buf.Bytes(), "\n")
b64 := base64.StdEncoding.EncodeToString(body)
h := hmac.New(sha256.New, []byte(apiKey))
h.Write([]byte(b64))
return hex.EncodeToString(h.Sum(nil)), nil
}ボディなしリクエスト（GET）
ボディが空のリクエスト（例：GET /v1/payout/status/{uuid}）では、空文字列に署名します：
Shell
SIGN=$(printf '' | openssl dgst -sha256 -hmac "$API_KEY" -hex | awk '{print $NF}')PHP
$sign = hash_hmac('sha256', base64_encode(''), $apiKey);JavaScript
import { createHmac } from "crypto";
const sign = createHmac("sha256", apiKey)
.update(Buffer.from("").toString("base64"))
.digest("hex");TypeScript
import { createHmac } from "crypto";
const sign: string = createHmac("sha256", apiKey)
.update(Buffer.from("").toString("base64"))
.digest("hex");Python
import hmac
import hashlib
import base64
sign = hmac.new(
api_key.encode(),
base64.b64encode(b"").decode().encode(),
hashlib.sha256,
).hexdigest()Go
package sign
import (
"crypto/hmac"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
)
func EmptyBodySign(apiKey string) string {
b64 := base64.StdEncoding.EncodeToString([]byte(""))
h := hmac.New(sha256.New, []byte(apiKey))
h.Write([]byte(b64))
return hex.EncodeToString(h.Sum(nil))
}完全なリクエスト例
Shell
curl -X POST https://api.2328.io/api/v1/payment \
-H "Content-Type: application/json" \
-H "User-Agent: MyShop/1.0 (+https://myshop.example)" \
-H "project: YOUR_PROJECT_UUID" \
-H "sign: YOUR_HMAC_SIGNATURE" \
-d '{"amount":"100.00","currency":"USD","order_id":"ORDER-123"}'PHP
<?php
function apiSign(string $body, string $apiKey): string {
return hash_hmac('sha256', base64_encode($body), $apiKey);
}
$project = 'YOUR_PROJECT_UUID';
$apiKey = 'YOUR_API_KEY';
$data = [
'amount' => '100.00',
'currency' => 'USD',
'order_id' => 'ORDER-123',
];
$body = json_encode($data, JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$sign = apiSign($body, $apiKey);
$ch = curl_init('https://api.2328.io/api/v1/payment');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
'User-Agent: MyShop/1.0 (+https://myshop.example)',
"project: $project",
"sign: $sign",
],
]);
$response = json_decode(curl_exec($ch), true);JavaScript
import { createHmac } from "crypto";
function apiSign(body, apiKey) {
const base64 = Buffer.from(body, "utf8").toString("base64");
return createHmac("sha256", apiKey).update(base64).digest("hex");
}
const data = {
amount: "100.00",
currency: "USD",
order_id: "ORDER-123",
};
const body = JSON.stringify(data);
const sign = apiSign(body, process.env.API_KEY);
const res = await fetch("https://api.2328.io/api/v1/payment", {
method: "POST",
headers: {
"Content-Type": "application/json",
"User-Agent": "MyShop/1.0 (+https://myshop.example)",
project: process.env.PROJECT_UUID,
sign,
},
body,
});
const json = await res.json();TypeScript
import { createHmac } from "crypto";
function apiSign(body: string, apiKey: string): string {
const base64 = Buffer.from(body, "utf8").toString("base64");
return createHmac("sha256", apiKey).update(base64).digest("hex");
}
type CreatePaymentBody = {
amount: string;
currency: string;
order_id: string;
};
type CreatePaymentResponse = { state: number; result: unknown };
const data: CreatePaymentBody = {
amount: "100.00",
currency: "USD",
order_id: "ORDER-123",
};
const body = JSON.stringify(data);
const sign = apiSign(body, process.env.API_KEY!);
const res = await fetch("https://api.2328.io/api/v1/payment", {
method: "POST",
headers: {
"Content-Type": "application/json",
"User-Agent": "MyShop/1.0 (+https://myshop.example)",
project: process.env.PROJECT_UUID!,
sign,
},
body,
});
const json = (await res.json()) as CreatePaymentResponse;Python
import json
import hmac
import hashlib
import base64
import httpx
def api_sign(body: str, api_key: str) -> str:
b64 = base64.b64encode(body.encode("utf-8")).decode()
return hmac.new(api_key.encode(), b64.encode(), hashlib.sha256).hexdigest()
data = {
"amount": "100.00",
"currency": "USD",
"order_id": "ORDER-123",
}
body = json.dumps(data, separators=(",", ":"), ensure_ascii=False)
sign = api_sign(body, API_KEY)
r = httpx.post(
"https://api.2328.io/api/v1/payment",
headers={
"Content-Type": "application/json",
"User-Agent": "MyShop/1.0 (+https://myshop.example)",
"project": PROJECT_UUID,
"sign": sign,
},
content=body.encode("utf-8"),
)
response = r.json()Go
package main
import (
"bytes"
"crypto/hmac"
"crypto/sha256"
"encoding/base64"
"encoding/hex"
"encoding/json"
"net/http"
)
func ApiSign(body []byte, apiKey string) string {
b64 := base64.StdEncoding.EncodeToString(body)
h := hmac.New(sha256.New, []byte(apiKey))
h.Write([]byte(b64))
return hex.EncodeToString(h.Sum(nil))
}
func marshalCanonical(v any) ([]byte, error) {
var buf bytes.Buffer
enc := json.NewEncoder(&buf)
enc.SetEscapeHTML(false)
if err := enc.Encode(v); err != nil {
return nil, err
}
return bytes.TrimRight(buf.Bytes(), "\n"), nil
}
func main() {
data := struct {
Amount string `json:"amount"`
Currency string `json:"currency"`
OrderID string `json:"order_id"`
}{
Amount: "100.00",
Currency: "USD",
OrderID: "ORDER-123",
}
body, err := marshalCanonical(data)
if err != nil {
panic(err)
}
sign := ApiSign(body, apiKey)
req, _ := http.NewRequest("POST",
"https://api.2328.io/api/v1/payment",
bytes.NewReader(body))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("User-Agent", "MyShop/1.0 (+https://myshop.example)")
req.Header.Set("project", projectUUID)
req.Header.Set("sign", sign)
resp, err := http.DefaultClient.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
}API キーをクライアントサイドのコードに絶対に公開しないでください。 リクエストはバックエンドで署名してください。API キーが漏洩すると、誰でもマーチャントアカウントにフルアクセスできてしまいます。
Webhook 署名の検証
2328.io から Webhook が送信される際、同じアルゴリズムが逆向きに実行されます：
- ペイロードから
signフィールドを取り出します。 - 残りのフィールドを JSON エンコードします（コンパクト、空白なし）。
- その文字列を Base64 エンコードします。
- 適切なキーで
HMAC-SHA256を計算します。 - 受信した
signと 定数時間 の比較（hash_equals、crypto.timingSafeEqual、hmac.compare_digest、subtle.ConstantTimeCompare、OpenSSL.fixed_length_secure_compare）で比較します。
署名キーは Webhook の発生元によって異なります：
| Webhook | Key to verify with |
|---|---|
支払い／固定ウォレットの Webhook（/v1/payment、/v1/static-wallet） | API key |
出金 Webhook（/v1/payout） | Payout API key |
検証でよくある落とし穴。 あなたの JSON エンコーダーは送信側と完全に同じバイト列を生成する必要があります — そうでないと Base64 が変わり、署名が一致しません。
- Go:
json.NewEncoderを使い、SetEscapeHTML(false)を設定してください。デフォルトのjson.Marshalは<、>、&を<にエスケープし、署名を壊します。 - Python:
json.dumpsにensure_ascii=Falseを渡してください。これがないと、非 ASCII（キリル文字、中国語など）が\uXXXXにエスケープされます。 - コンパクト JSON: フィールド間に空白を入れないこと（Python では
separators=(",", ":")）。 - フィールド順序（Go）: 素の
map[string]anyは再エンコード時にキーをランダム化します。json.RawMessage、順序付き struct を使うか、生バイトからsignを取り除いてください。
検証が失敗し続ける場合は、ペイロードに対して自分で apiSign を実行してみてください — 受信した sign と同じ 16 進文字列を生成する必要があります。
有効な署名はリプレイを防ぎません。 署名は webhook が 2328.io から来たことを証明するだけで — 攻撃者がキャプチャした webhook を後から再送信するのを防ぐものではありません。資金を入金する前に、必ず uuid（静的ウォレットの場合は txid）で冪等性を確認してください。署名が欠落しているか不正な場合は HTTP 401 で拒否してください。
完全なコード例は Webhook 通知 にあります。リトライ処理と冪等性のルールは ベストプラクティス を参照してください。