开发者

API 文档

使用 AywaPay 接受加密货币所需的一切：创建账单、发起付款和验证回调。

快速开始

申请访问（目前处于内测阶段，收到邀请后即可开通账户），并添加一个商店，然后开启双重验证（2FA）。
打开商店的 API 标签页并创建密钥。可选择仅允许您服务器的 IP 访问。
设置商店的 Status URL：每次账单状态变化时，我们都会向该地址发送 POST 请求。
从您的服务器创建账单，并将客户引导至返回的 invoice_url。

Base URL

https://api.aywapay.com/api/v1

身份验证

api_key 作为查询参数附加在每个请求中。切勿将其放在浏览器或客户端应用中。

所有响应均为 JSON： { "status": "success", "data": { … } } 或 { "status": "error", "data": { "code": 103, "message": "…" } }。

Invoices

Create an invoice

GET/api/v1/invoices/new

Creates a payment request and returns the link of the hosted payment page. Price it in fiat (the customer picks the coin) or in one coin.

Parameter	Description
api_key*	Your store's secret key (Stores & API → API). Keep it on your server.
order_number*	Your order id. Unique per store; repeating it is refused unless return_existing=1.
order_name*	What the customer pays for, shown on the payment page.
source_currency + source_amount	Fiat price, e.g. USD and 49.99. Converted at the current rate.
currency + amount	Or a crypto price in one coin, e.g. BTC and 0.001. currency alone fixes the coin of a fiat invoice.
allowed_psys_cids	Comma list of coins the customer may choose, e.g. BTC,USDT_TRX. Coins whose minimum the order does not reach are left out.
callback_url	Where status changes are POSTed (default: the store's Status URL). Add ?json=true for a JSON body.
success_callback_url / fail_callback_url	Extra callbacks for paid and failed invoices.
success_invoice_url / fail_invoice_url	Where the payment page's "Back to store" button goes.
email	Customer email: the payment link and receipt are sent there.
description	Shown under the order name.
expire_min	Minutes before the invoice expires (default: the store's setting, else 60).
return_existing	1 = an existing order_number returns that invoice instead of an error.

Request

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

Response data

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

Get an invoice

GET/api/v1/invoices/:id

Full invoice: status, coin, address, amounts, confirmations and transactions.

Parameter	Description
api_key*	Your store's secret key (Stores & API → API). Keep it on your server.

Request

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

Response data

{
  "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

Send a withdrawal or a mass payout

GET/api/v1/operations/withdraw

Sends crypto from your balance. The network (gas) fee is taken in the same coin. Can be turned off per store (Stores & API → API).

Parameter	Description
api_key*	Your store's secret key (Stores & API → API). Keep it on your server.
psys_cid*	Coin, e.g. USDT_TRX.
type*	cash_out (one address) or mass_cash_out (many).
to*	Address, or comma list for mass_cash_out.
amount*	Amount, or comma list in the same order as to.
feePlan	normal (default) or priority.

Request

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

Response data

{ "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": [] }

Estimate the network fee

GET/api/v1/operations/fee/:psys_cid

Fee of a withdrawal before you send it.

Parameter	Description
api_key*	Your store's secret key (Stores & API → API). Keep it on your server.
addresses*	Comma list of recipients.
amounts*	Comma list of amounts.
feePlan	normal or priority.

Request

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

Response data

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

Fee and commission of a withdrawal

GET/api/v1/operations/commission/:psys_cid

What the withdrawal costs in total: network fee plus any commission.

Parameter	Description
api_key*	Your store's secret key (Stores & API → API). Keep it on your server.
addresses	Comma list of recipients.
amounts	Comma list of amounts.
type	cash_out or mass_cash_out.

Request

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

Response data

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

Fee plans of a coin

GET/api/v1/operations/fee-plan/:psys_cid

Details of the normal and priority plans.

Parameter	Description
api_key*	Your store's secret key (Stores & API → API). Keep it on your server.

Request

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

Response data

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

Balances, operations & coins

Balance of one coin

GET/api/v1/balances/:psys_cid

Available balance of your account in that coin.

Parameter	Description
api_key*	Your store's secret key (Stores & API → API). Keep it on your server.

Request

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

Response data

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

List operations

GET/api/v1/operations

Invoices, deposits and withdrawals, newest first.

Parameter	Description
api_key*	Your store's secret key (Stores & API → API). Keep it on your server.
page	Page number (default 1).
limit	Items per page (default 10).

Request

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

Response data

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

Get one operation

GET/api/v1/operations/:id

One invoice, deposit or withdrawal by id.

Parameter	Description
api_key*	Your store's secret key (Stores & API → API). Keep it on your server.

Request

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

Response data

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

Coins and rates

GET/api/v1/currencies/:fiat

Every coin you can accept, with its rate in a fiat currency (default USD) and minimum invoice.

Parameter	Description
api_key*	Your store's secret key (Stores & API → API). Keep it on your server.

Request

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

Response data

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

Your store

GET/api/v1/shops

The store the key belongs to.

Parameter	Description
api_key*	Your store's secret key (Stores & API → API). Keep it on your server.

Request

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

Response data

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

Deposit addresses (White Label)

Permanent address for one of your users

GET/api/v1/shops/deposit/new

A fixed address per user and coin. Every payment to it is credited to you and reported with a pay_in callback. White Label plan.

Parameter	Description
api_key*	Your store's secret key (Stores & API → API). Keep it on your server.
psys_cid*	Coin, or a comma list for several.
uid*	Your id of the user.

Request

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

Response data

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

List deposit addresses

GET/api/v1/shops/deposit

Addresses already given out.

Parameter	Description
api_key*	Your store's secret key (Stores & API → API). Keep it on your server.
uid	Only this user.
psys_cid	Only this coin.

Request

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

Response data

[ { "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.

Invoice callback

{
  "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": "…"
}

Withdrawal callback

{
  "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 (form post)

<?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);

Node.js (JSON)

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.

Create a test invoice

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 记录，约十分钟即可完成，无需开发人员。

设置步骤

将商店切换到白标方案（商店 → 常规）。
打开商店的“付款页面”标签。在“支付链接的打开位置”下，选择“我的自有域名”。
输入您拥有的子域名，例如 pay.yourshop.com（不能是 yourshop.com 本身）。如果显示了费用，请先阅读，然后保存。
复制屏幕上显示的记录，添加到管理您域名 DNS 的地方（Cloudflare、GoDaddy、Namecheap、Hostinger 等）。控制台中为每家服务商都提供了简短指南。
稍等片刻。我们每分钟检查一次：DNS → HTTPS 证书 → 已上线。通常需要 5 到 30 分钟；新的 DNS 记录可能需要几个小时。上线后我们会发邮件通知您。

DNS 记录

类型	名称	值
CNAME	pay	<your-code>.domains.aywapay.com

请从控制台复制准确的目标值：它是您商店专属的。大多数服务商只需要在名称中填写第一部分（pay）。

使用 Cloudflare？

请将记录设为“DNS only”（灰色云朵）。如果开启了橙色云朵，证书将无法签发，检查结果会提示该记录经过代理。

如果检查未通过

未找到记录：CNAME 尚未添加，或 DNS 尚未生效。请检查名称并等待几分钟。
指向了其他地方：另一条记录（A、AAAA 或旧的 CNAME）使用了相同的名称。请删除它，只保留 CNAME。
经过代理：Cloudflare 的橙色云朵已开启。请将记录改为“DNS only”。
证书签发中：DNS 已正确，HTTPS 证书通常几分钟内就会签发。

上线之后

新链接和现有链接都会在您的域名上打开。已发出的使用我们地址的链接仍然可用。
您可以随时一键切回 AywaPay 链接；您的域名会保留。
如果您的 DNS 连续 24 小时不再指向我们，链接会自动改回我们的地址，并且我们会发邮件通知您，因此不会丢失任何付款。
如果您的账户需要支付自有域名费用，费用会在保存前显示，并从您的余额中扣除。

看不到这个选项？它需要白标方案。如果您的商店已开通，请写信至 [email protected].

账单状态

new	Created, nothing received yet.
pending	Payment seen on the blockchain, waiting for confirmations.
completed	Paid in full and confirmed. Ship the order.
mismatch	Overpaid and confirmed: paid, the extra is in your balance too.
expired	Time ran out. With some money received it stays open for the rest of the payment.
cancelled	Cancelled before payment.
cancelled duplicate	The customer switched to another coin; the new copy carries on.
error	Something went wrong; contact support.

错误

Code	HTTP	Meaning
101	401	Wrong or missing api_key.
103	400	A parameter is missing or invalid (the message names it).
105	422	Coin not available for this store.
111	404	No such invoice or operation.
116	422	Balance too low for amount plus fee.
202	429	Too many requests; slow down.
210	422	Below the coin's minimum.
211	422	order_number already used.
213	422	Invalid address for this coin's network.
218	422	Saved addresses only is on and the address is not saved.
224	422	The address is blocked for compliance reasons (sanctions list).
225	422	Over a withdrawal limit. Check your own limits in Settings → Security, or contact support.
229	422	Not possible with the test key (withdrawals, deposit addresses): use the live key.
303	403	Request from an IP not in the store's allowed IPs.

有疑问？请发邮件至 [email protected]。