APIドキュメント

はじめに

1. 利用を申請 （現在クローズドベータのため、届いた招待からアカウントを開設します） し、ストアを追加してから、2段階認証（2FA）を有効にします。
2. ストアの「API」タブを開き、シークレットキーを作成します。必要に応じて、自社サーバーのIPアドレスのみに利用を制限できます。
3. ストアのStatus URLを設定します。請求書に変更があるたびに、このURLへPOSTリクエストを送信します。
4. 自社サーバーから請求書を作成し、返されたinvoice_urlへお客様を誘導します。

すべてのレスポンスはJSON形式です： { "status": "success", "data": { … } } または { "status": "error", "data": { "code": 103, "message": "…" } }。

Invoices

curl -G "https://api.aywapay.com/api/v1/invoices/new" \
  -d source_currency=USD -d source_amount=49.99 \
  -d order_number=1042 --data-urlencode "order_name=Pro plan" \
  --data-urlencode "callback_url=https://yourshop.com/callback?json=true" \
  -d api_key=$AYWAPAY_SECRET_KEY

{
  "txn_id": "65f1c0ffee00000000000001",
  "invoice_url": "https://pay.aywapay.com/invoice/65f1c0ffee00000000000001",
  "invoice_total_sum": "0.5512"
}

curl -G "https://api.aywapay.com/api/v1/invoices/:id" -d api_key=$AYWAPAY_SECRET_KEY

{
  "invoice": { "txn_id": "…", "status": "completed", "psys_cid": "LTC",
    "amount": "0.5512", "received_amount": "0.5512",
    "remaining_amount": "0", "wallet_hash": "ltc1q…",
    "expected_confirmations": 6, "tx_url": ["…"], "tx_id": ["…"] },
  "active_invoice_id": "…"
}

Withdrawals & payouts

curl -G "https://api.aywapay.com/api/v1/operations/withdraw" -d api_key=$AYWAPAY_SECRET_KEY

{ "id": "65f1c0ffee00000000000002", "type": "cash_out", "status": "pending",
  "psys_cid": "USDT_TRX", "currency": "USDT", "amount": "25.00", "fee": "1.25",
  "wallet_hash": "T…", "tx_url": "", "tx_id": [] }

curl -G "https://api.aywapay.com/api/v1/operations/fee/:psys_cid" -d api_key=$AYWAPAY_SECRET_KEY

{ "fee": "0.0000021", "psys_cid": "LTC", "currency": "LTC", "plan": "normal" }

curl -G "https://api.aywapay.com/api/v1/operations/commission/:psys_cid" -d api_key=$AYWAPAY_SECRET_KEY

{ "commission": "0", "fee": "0.0000021", "feeUnit": "LTC", "plan": "normal",
  "plans": { "normal": { "value": "0.0000021" }, "priority": { "value": "0.0000042" } } }

curl -G "https://api.aywapay.com/api/v1/operations/fee-plan/:psys_cid" -d api_key=$AYWAPAY_SECRET_KEY

{ "normal": { … }, "priority": { … } }

Balances, operations & coins

curl -G "https://api.aywapay.com/api/v1/balances/:psys_cid" -d api_key=$AYWAPAY_SECRET_KEY

{ "psys_cid": "LTC", "currency": "LTC", "balance": "0.0510" }

curl -G "https://api.aywapay.com/api/v1/operations" -d api_key=$AYWAPAY_SECRET_KEY

{ "operations": [ … ], "_meta": { "totalCount": 3, "pageCount": 1, "currentPage": 1, "perPage": 10 } }

curl -G "https://api.aywapay.com/api/v1/operations/:id" -d api_key=$AYWAPAY_SECRET_KEY

{ "id": "…", "type": "invoice", "status": "completed", … }

curl -G "https://api.aywapay.com/api/v1/currencies/:fiat" -d api_key=$AYWAPAY_SECRET_KEY

[ { "cid": "BTC", "name": "Bitcoin", "rate_usd": "0.0000125", "min_sum_in": "0.0001", "min_withdraw": "0.0002", … } ]

curl -G "https://api.aywapay.com/api/v1/shops" -d api_key=$AYWAPAY_SECRET_KEY

{ "id": "…", "name": "My Shop", "plan": "api", … }

Deposit addresses (White Label)

curl -G "https://api.aywapay.com/api/v1/shops/deposit/new" -d api_key=$AYWAPAY_SECRET_KEY

{ "psys_cid": "USDT_TRX", "uid": "user-17", "hash": "T…" }

curl -G "https://api.aywapay.com/api/v1/shops/deposit" -d api_key=$AYWAPAY_SECRET_KEY

[ { "psys_cid": "BTC", "uid": "user-17", "hash": "bc1q…" } ]

コールバック（Webhook）

On every invoice status change we POST the invoice to its callback_url (or the store's Status URL). Withdrawals made with your API key are reported to the Status URL too, when they are sent, completed, fail or are cancelled. Add ?json=true to the URL to get JSON instead of a form post.

• Answer with HTTP 200. Anything else is retried 8 more times over about two days, then shown as Failed in your dashboard.
• Always check verify_hash before trusting a callback.
• Stores & API → Webhooks shows every attempt, lets you resend one, and sends a signed test.

{
  "txn_id": "65f1c0ffee00000000000001",
  "ipn_type": "invoice",
  "merchant": "My Shop",
  "merchant_id": "3f2a9c1e-…",
  "status": "completed",
  "amount": "0.5512",
  "currency": "LTC",
  "order_number": "1042",
  "order_name": "Pro plan",
  "confirmations": "6",
  "source_currency": "USD",
  "source_amount": "49.99",
  "invoice_total_sum": "0.5512",
  "verify_hash": "…"
}

{
  "txn_id": "65f1c0ffee00000000000002",
  "ipn_type": "cash_out",
  "merchant": "My Shop",
  "merchant_id": "3f2a9c1e-…",
  "status": "completed",          // pending | completed | error | cancelled
  "psys_cid": "USDT_TRX",
  "currency": "USDT",
  "amount": "25.00",
  "fee": "1.25",
  "to": "T…",
  "tx_id": "a1b2…",
  "comment": "",
  "verify_hash": "…"
}

署名の検証

verify_hash is an HMAC-SHA1 with your store's secret key: of PHP's serialize() of the key-sorted fields for form posts, or of JSON.stringify of the body without verify_hash for JSON.

<?php
// Your store's secret key (Stores & API → API)
$secretKey = getenv('AYWAPAY_SECRET_KEY');

$post = $_POST;                       // form-encoded callback
$received = $post['verify_hash'] ?? '';
unset($post['verify_hash']);
ksort($post);
$expected = hash_hmac('sha1', serialize($post), $secretKey);

if (!hash_equals($expected, $received)) {
    http_response_code(400);
    exit('bad signature');
}
if ($post['status'] === 'completed' || $post['status'] === 'mismatch') {
    // mark order $post['order_number'] as paid
}
http_response_code(200);

import crypto from "node:crypto";

// callback_url ends with ?json=true, so the body is JSON
app.post("/callback", express.json(), (req, res) => {
  const { verify_hash, ...body } = req.body;
  const expected = crypto
    .createHmac("sha1", process.env.AYWAPAY_SECRET_KEY)
    .update(JSON.stringify(body))
    .digest("hex");
  const given = Buffer.from(String(verify_hash ?? ""));
  const wanted = Buffer.from(expected);
  if (given.length !== wanted.length || !crypto.timingSafeEqual(given, wanted)) {
    return res.status(400).send("bad signature");
  }

  if (body.status === "completed" || body.status === "mismatch") {
    // mark order body.order_number as paid
  }
  res.sendStatus(200);
});

テストモード（サンドボックス）

Every store can have a test key next to its live key (Stores & API → API → Test key). It works with the same endpoints, with no real money:

• Invoices made with the test key are test invoices: no deposit address, nothing on a blockchain.
• Their payment page has Simulate buttons: paid, overpaid, underpaid, expire. Each fires your normal callback, with test=true and signed with the test key.
• Test invoices never touch your balance. Withdrawals and deposit addresses need the live key (error 229); balances read 0.
• Order numbers are separate: a test order never blocks a live one with the same number.

curl -G "https://api.aywapay.com/api/v1/invoices/new" \
  -d source_currency=USD -d source_amount=10 \
  -d order_number=test-1 -d order_name=Test \
  -d api_key=$AYWAPAY_TEST_KEY

独自の支払いドメイン（ホワイトラベル）

ホワイトラベルプランでは、請求書、支払いリンク、寄付ページ、支払いボタンを当社のアドレスではなく、pay.yourshop.com のような独自のアドレスで開けます。顧客にはあなたのドメインとブランドだけが表示されます。必要なのはDNSレコード1件と約10分だけで、開発者は不要です。

設定方法

1. ストアをホワイトラベルプランに切り替えます（ストア → 一般）。
2. ストアの「支払いページ」タブを開き、「支払いリンクを開く場所」で「独自ドメイン」を選びます。
3. 所有しているサブドメイン（例：pay.yourshop.com）を入力します（yourshop.com そのものは使えません）。手数料が表示された場合は内容を確認してから保存します。
4. 画面に表示されたレコードをコピーし、ドメインのDNSを管理しているところ（Cloudflare、GoDaddy、Namecheap、Hostinger など）に追加します。ダッシュボードにはそれぞれの簡単なガイドがあります。
5. あとは待つだけです。1分ごとに確認します：DNS → HTTPS証明書 → 公開中。通常5〜30分ほどですが、新しいDNSレコードは数時間かかることもあります。公開されたらメールでお知らせします。

DNSレコード

正確なターゲットはダッシュボードからコピーしてください。ストアごとに異なります。多くのプロバイダーでは、名前には最初の部分（pay）だけを入力します。

確認が通らない場合

• レコードが見つからない：CNAMEがまだ追加されていないか、DNSがまだ反映されていません。名前を確認して数分お待ちください。
• 別の場所を指している：同じ名前を別のレコード（A、AAAA、古いCNAME）が使っています。それを削除し、CNAMEだけを残してください。
• プロキシ経由：Cloudflare のオレンジの雲がオンになっています。レコードを「DNS only」に切り替えてください。
• 証明書の発行待ち：DNSは正しく設定されています。HTTPS証明書は通常数分で発行されます。

公開後

• 新しいリンクも既存のリンクも、あなたのドメインで開きます。当社のアドレスで送信済みのリンクも引き続き使えます。
• いつでもワンクリックで AywaPay のリンクに戻せます。ドメインは保存されたままです。
• DNSが24時間当社を指さなくなった場合、リンクは自動的に当社のアドレスに戻り、メールでお知らせします。支払いが失われることはありません。
• アカウントに独自ドメインの手数料が設定されている場合は、保存前に表示され、残高から差し引かれます。

このオプションが表示されませんか？ホワイトラベルプランが必要です。すでにホワイトラベルプランのストアの場合は、次の宛先までご連絡ください [email protected].

請求書のステータス

エラー

ご質問は [email protected]までお寄せください。