ホワイトラベルAPI:自社サイトで支払い
使うべき場面
通常は、顧客をArionPayの決済ページであるinvoice_urlに誘導します。ホワイトラベルAPIを使うと、代わりにあなた自身のページが支払い画面を表示します。独自のデザイン、言語、ドメインで、顧客はあなたのサイトから離れません。資金はこれまでどおりご自身のウォレットに直接届き、ArionPayはこれまでどおりブロックチェーンを監視して、請求書が支払われたことをお知らせします。手数料も同じく、1回の支払いにつき0.5%です。概要はホワイトラベルのページをご覧ください。
1. コインを指定して請求書を作成
まず、あなたのページで顧客にコインを選んでもらいます。次に、assetにそのコイン(例:USDT_TRC20、USDC_POLYGON、BTC)を指定して、サーバーからPOST /api/v1/invoicesを送信します。ストアで使えるコードはGET /api/v1/currenciesに一覧があります。レスポンスには、ページに必要な情報がすべて含まれています:
data.amount_crypto:送金すべき正確な金額。末尾の桁で、支払いがどの請求書のものかを判別します。data.address:支払先のアドレス。どのネットワークでも、ウォレットのメインアドレスです。data.expires_at:請求書の有効期限(デフォルトは30分。expiresMinで5〜1440を指定できます)。data.id:次のステップで使う請求書ID。
一時的な理由でアドレスを割り当てられない場合は、ステータス503が返されます。idempotencyKeyがない場合、その請求書はキャンセルされ、再試行すると新しい請求書が作成されます。idempotencyKeyがある場合、請求書は保持されます。同じキーで再試行すると、その請求書が完了します。
2. ページに表示
- 金額はすべての桁を省略せずに表示し、コピーボタンも付けてください。丸められた金額は自動で照合できず、Payment Radarに回って、あなたの判断を待つことになります。
- アドレス、QRコード、ネットワーク(例:「TRON(TRC-20)上のUSDT」)を表示します。
expires_atまでのカウントダウンを表示します。- 「うまくいかない場合はArionPayのページで支払う」のような、
invoice_urlへのリンクを追加します。そのページには、ウォレットアプリ用のボタン、9言語の表示、トランザクションIDを報告するフォームがあります。
3. 支払いを追跡
- Webhook:支払いが検知されると
invoice.pending、ネットワークで承認されるとinvoice.paidが届きます。署名を確認してから、invoice.paidで注文を確定してください(Webhookの検証方法)。 - 顧客があなたのページにいる間、サーバーから
GET /api/v1/invoices/:idにstatus(例:NEW、PENDING、PAID、EXPIRED)、amountReceived、confirmations、requiredConfirmationsを問い合わせることもできます。問い合わせると、誰かが待っていることがArionPayに伝わるため、支払いがより頻繁に確認されます。
安全に、制限の範囲内で
- APIはサーバーからのみ呼び出してください。APIシークレットは決してブラウザに渡さないでください。ページはあなた自身のサーバーに問い合わせ、サーバーがArionPayに問い合わせます。
- 有効な請求書ごとに約10秒間隔で問い合わせ、顧客がページを離れたら停止してください。署名付きリクエストはそれぞれ1回しか受け付けられず、1台のサーバーから送信できるのは1分あたり約120件です(ストアごとでは1分あたり300件)。
- まずはテストを。
test: trueではアドレスがTEST-MODE-DO-NOT-SEND-FUNDSになり、POST /api/v1/invoices/:id/simulateで架空の支払いを行えます。詳しくはテストモードをご覧ください。
// Node.js 18+, as an ES module (for example checkout.mjs), on your server only:
// the API secret must never reach the browser
import crypto from 'node:crypto';
async function arionpay(method, path, payload) {
const ts = Math.floor(Date.now() / 1000);
const body = payload ? JSON.stringify(payload) : '';
// POST is signed over "timestamp.body", GET over "timestamp.GET path"
const signed = method === 'GET' ? `${ts}.GET ${path}` : `${ts}.${body}`;
const signature = crypto.createHmac('sha256', process.env.ARIONPAY_API_SECRET).update(signed).digest('hex');
// ARIONPAY_BASE_URL: the API address from the docs
const res = await fetch(process.env.ARIONPAY_BASE_URL + path, {
method,
headers: {
'Content-Type': 'application/json',
'x-api-key': process.env.ARIONPAY_API_KEY, // pk_...
'x-timestamp': String(ts),
'x-signature': signature,
},
body: payload ? body : undefined,
});
if (!res.ok) throw new Error(`ArionPay answered ${res.status}`);
return res.json();
}
// 1. The customer chose USDT on TRON on your page
const { data } = await arionpay('POST', '/api/v1/invoices', {
amount: '49.00', currency: 'USD', orderId: 'ORD-1042', asset: 'USDT_TRC20',
});
// show data.amount_crypto, data.address and data.expires_at; keep data.id
// 2. While the customer waits (about every 10 seconds), or wait for the invoice.paid webhook
const invoice = await arionpay('GET', `/api/v1/invoices/${data.id}`);
if (invoice.status === 'PAID') {
// release the order
}