Developers

API documentation

Everything to accept crypto with AywaPay: create invoices, send payouts and verify callbacks. The endpoints follow Plisio's, so existing Plisio code works with a new base URL.

Getting started

Create an account and a store, then turn on two-factor authentication.
Open the store's API tab and create its secret key. Optionally allow only your server's IPs.
Set the store's Status URL: that is where we POST every invoice change.
Create invoices from your server and send the customer to the returned invoice_url.

Base URL

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

Authentication

api_key query parameter on every request. Never put it in a browser or an app.

Every response is JSON: { "status": "success", "data": { … } } or { "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", "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…" } ]

Callbacks (webhooks)

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

Check the signature

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");
  if (verify_hash !== expected) return res.status(400).send("bad signature");

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

Invoice statuses

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.

Errors

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 your daily withdrawal limit; contact support to raise it.
303	403	Request from an IP not in the store's allowed IPs.

Questions? Write to support@aywapay.com.