Crypto payment API quickstart: from signup to your first payout

• Payaries runs on real mainnet networks only. There is no sandbox. Test-mode keys transact on the same chains as live keys, so plan the final test as a small real payment.
• You need a server. The API secret must never reach browser code.
• The API lives at https://bqpay-api-gateway.buildquick.tech. The contract is at https://www.payaries.com/openapi.json.

1. 01Create an account. Passwords need at least 10 characters and can't be a well-known one.
2. 02Create a test API key from the dashboard. The key and secret are shown once; store them as PAYARIES_API_KEY and PAYARIES_API_SECRET. A test key works immediately; live keys are issued once your account is approved.
3. 03Submit your business profile. This is mandatory before any invoice, test or live: until then POST /v1/invoices returns 403 with code: "ONBOARDING_REQUIRED". Submitting is enough to start testing.
4. 04Register your webhook URL (a public https:// address, no redirects) and create the webhook secret. It is shown once and is not the API secret.

GET /v1/chains is public and always authoritative. An asset appears only once it is actually configured.

{ "chains": [ { "chainId": "tron-mainnet", "name": "Tron Mainnet", "assets": ["TRX", "USDT_TRC20"] }, ... ] }

Every request is signed; the signing guide has the exact recipe and a test vector for Node, Python, Go and shell. referenceId is your idempotency key: sending the same one again returns the existing invoice, never a duplicate.

# body: {"referenceId":"order_10231","fiat":{"amount":"49.99","currency":"USD"},"crypto":{"asset":"USDT_TRC20","chainId":"tron-mainnet"}}
# X-Timestamp and X-Signature come from the signing guide's helper
curl -s -X POST https://bqpay-api-gateway.buildquick.tech/v1/invoices \
  -H "X-Api-Key: $PAYARIES_API_KEY" -H "X-Timestamp: $TS" -H "X-Signature: $SIG" \
  -H "Content-Type: application/json" \
  -d "$BODY"

The response carries the one-time depositAddress.value, the locked rate in crypto.rateLocked, the amount in crypto.amountDue, expiresAt (one hour by default) and a checkoutId. Show the customer the address and amount, or send them to /pay/<checkoutId>, a no-login payment page. To bring them back to your store afterwards, pass a successUrl and cancelUrl (hosted checkout). Never share the invoice id.

Common refusals: 400 for an unsupported or disabled asset, 400 BELOW_MINIMUM_INVOICE on chains where Payaries pays the gas (read minimumUsd from the error), 403 ONBOARDING_REQUIRED, 400 REDIRECT_URL_NOT_ALLOWED when a successUrl or cancelUrl host isn't one of your redirect domains, and 402 FEE_WALLET_INSUFFICIENT for assets that require a funded fee wallet.

Payaries POSTs a signed event on every status change. Verify X-Gateway-Signature against the raw body first (how), then dedupe on idempotencyKey and make your handler idempotent on (invoiceId, status).

{
  "event": "invoice.status_changed",
  "idempotencyKey": "3f9c1a...",
  "invoiceId": "66f...",
  "status": "confirmed",
  "referenceId": "order_10231",
  "timestamp": 1725700000000,
  "data": { "attempt": 0 }
}

Fulfil on confirmed, not on a wallet or explorer: a different token sent to the address, including a fake one with a real-looking name, is flagged on the invoice and never counted.

GET /v1/merchants/me/balance returns four buckets per chain and asset: available (withdrawable now), pendingSweep (credited, awaiting the sweep to your wallet), pending (reserved by a withdrawal in flight) and frozen (an admin hold, normally zero). A withdrawal is debited from available only; asking for more is a 409.

Quote first, then create the withdrawal with an Idempotency-Key. The details are in the withdrawals guide.

• Signing tested against a GET with a query string and a POST, using the published test vector.
• Every retry re-signs; every withdrawal retry reuses its Idempotency-Key.
• Webhook endpoint: public HTTPS, no redirects, verifies the signature on the raw body, dedupes, answers 2xx within 10 seconds.
• Order logic tolerates a status change out of expired, and alerts on unclaimedDeposits or latePaymentDetectedAt.
• If you use hosted checkout: redirect domains are registered, and the return route shows a result but fulfils only from the webhook.
• Secrets live in a secrets manager; the API-key IP whitelist is set to your servers.
• A small real payment ran end to end: create, pay, settled, withdraw.