Documentação da API

Primeiros passos

1. Solicite acesso (estamos em beta privado; o convite libera a criação da conta). Crie a conta e uma loja. Depois, ative a autenticação de dois fatores.
2. Abra a aba API da loja e crie a chave secreta. Se quiser, permita apenas os IPs do seu servidor.
3. Defina a Status URL da loja: é para lá que enviamos um POST a cada mudança de uma fatura.
4. Crie faturas a partir do seu servidor e envie o cliente para o invoice_url retornado.

Toda resposta é em JSON: { "status": "success", "data": { … } } ou { "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…" } ]

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.

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

Validar a assinatura

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

Modo de teste (sandbox)

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

Seu próprio domínio de pagamento (white label)

No plano White label, suas faturas, links de pagamento, páginas de doação e botões de pagamento podem abrir no seu próprio endereço, como pay.yourshop.com, em vez do nosso. Os clientes veem só o seu domínio e a sua marca. Basta um registro DNS e uns dez minutos, sem precisar de desenvolvedor.

Como configurar

1. Mude a loja para o plano White label (loja → Geral).
2. Abra a aba Página de pagamento da loja. Em “Onde os links de pagamento abrem”, escolha Meu próprio domínio.
3. Digite um subdomínio seu, como pay.yourshop.com (não o próprio yourshop.com). Leia as taxas, se aparecerem, e salve.
4. Copie o registro mostrado na tela e adicione-o onde o DNS do seu domínio é gerenciado (Cloudflare, GoDaddy, Namecheap, Hostinger etc.). O painel tem guias rápidos para cada um.
5. Aguarde. Verificamos a cada minuto: DNS → Certificado HTTPS → No ar. Costuma levar de 5 a 30 minutos; registros DNS novos podem levar algumas horas. Avisamos por e-mail quando estiver no ar.

O registro DNS

Copie o destino exato do seu painel: ele é único para a sua loja. A maioria dos provedores pede só a primeira parte (pay) como nome.

Se a verificação não passar

• Registro não encontrado: o CNAME ainda não existe ou o DNS ainda não se propagou. Confira o nome e aguarde alguns minutos.
• Aponta para outro lugar: outro registro (A, AAAA ou um CNAME antigo) usa o mesmo nome. Apague-o e deixe só o CNAME.
• Atrás do proxy: a nuvem laranja da Cloudflare está ligada. Mude o registro para “DNS only”.
• Certificado pendente: o DNS está certo, e o certificado HTTPS costuma sair em poucos minutos.

Quando estiver no ar

• Links novos e existentes abrem no seu domínio. Links já enviados com o nosso endereço continuam funcionando.
• Você pode voltar ao link da AywaPay a qualquer momento com um clique; seu domínio fica salvo.
• Se o seu DNS deixar de apontar para nós por 24 horas, os links voltam sozinhos para o nosso endereço e avisamos você por e-mail, então nenhum pagamento se perde.
• Se a sua conta tiver taxas por domínio próprio, elas aparecem antes de salvar e são descontadas do seu saldo.

Não vê a opção? Ela exige o plano White label. Se a sua loja já tem, escreva para [email protected].

Status das faturas

Erros

Dúvidas? Escreva para [email protected].