Deposit Wallets

When to use deposit wallets

Use a deposit wallet when you need a persistent, per-customer address to receive Pi — top-ups, balances, recurring funding — rather than a single one-off purchase. For a one-time payment with a hosted page, use a checkout instead. Each wallet you create maps to one customer (or account) in your system, and you decide that mapping by storing the returned identifiers.

How deposit addresses work

Each wallet you create gives you a unique Pi deposit address dedicated to one customer. Hand that address to the customer, store its wallet_id against their account in your system, and ZyraPay automatically attributes any Pi sent to that address back to them — no polling or reconciliation on your side.

Create a wallet

Authenticate with your project API key in the x-api-key header. ZyraPay generates a new deposit address and returns it. The body is empty. Pass an Idempotency-Key header to make creation safely retryable.

curl -X POST https://api.zyrapay.net/v1/wallets \
  -H "x-api-key: $ZYRA_API_KEY" \
  -H "Idempotency-Key: customer_8821"

Response

{
  "status": "success",
  "data": {
    "wallet_address": "MA7QYNF7SOWQ3GLR2BGMZEHXAVIRZA4KVWLTJJFC7MGXUA74P7UJVAAAAAAAAAAAAFKQK",
    "wallet_id": "123456",
    "created_at": "2026-06-14T11:55:00.000Z"
  }
}

Errors: 401 if the x-api-key header is missing, and 403 if the API key is invalid.

How deposits are detected and credited

Once a wallet exists, the customer can send Pi to its wallet_address. You don't poll or reconcile anything — ZyraPay handles it for you.

1. 1

   ZyraPay detects the deposit

   ZyraPay watches the chain and picks up incoming payments to your deposit addresses automatically.
2. 2

   It's matched to the right customer

   The deposit is attributed to the wallet's wallet_id — and therefore the customer you mapped it to — so it always lands on the correct account.
3. 3

   It's recorded once and credited

   Each deposit is recorded a single time and credited automatically, so a payment is never double-counted, even if the network reports it more than once.
4. 4

   Your webhook fires

   ZyraPay sends a signed deposit webhook to your project's webhook URL so your backend can react in real time.

Webhook events

Set a webhook URL on your project to receive these events. Each webhook is HMAC-signed — verify the signature before trusting it (see the Webhooks guide).

{
  "type": "deposit",
  "data": {
    "projectId": "664f...",
    "amount": 25,
    "wallet_address": "MA7QYNF7...VAAAAAAAAAAAAFKQK",
    "wallet_id": "123456"
  },
  "timestamp": 1749902100000,
  "projectId": "664f..."
}