API Reference

Authentication

The ZyraPay API authenticates with a project API key sent in the x-api-key header. It is the only credential your server needs — there are no tokens to mint and no OAuth flow.

API key (gateway, checkout, wallets)

Server-to-server endpoints authenticate with a project API key sent in the x-api-key header (the legacy apikey header is also accepted). The key is a 64-character hex string. Each key resolves to exactly one project, so the project context is implied by the key — you never pass a project id on these requests.

x-api-key: 4f3c9a...e9

If the key is missing or invalid you receive:

{ "success": false, "message": "API key is required" }
{ "success": false, "message": "Invalid API key get your api key from the dashboard" }

The Idempotency-Key header

Money-moving and creation requests support an optional Idempotency-Key request header. Send a unique value (for example a UUID) and a replay returns the original response verbatim instead of performing the action twice — making retries safe over flaky networks.

The key is honored on the following endpoints, each scoped to a different collision namespace:

A request that is still in flight under the same key returns 409:

{ "success": false, "message": "A request with this Idempotency-Key is still being processed." }

Checkout

A checkout is a hosted payment page for a one-off purchase. You create it with your API key, redirect the customer to checkoutUrl, and receive signed webhooks as the payment lands. Checkouts default to a 30-minute expiry and accept overpayment and partial payment.

Create a checkout

Creates a checkout session, mints a deposit wallet for it, and (if a webhookUrl is supplied) fires a best-effort signed checkout.created webhook. Honors the Idempotency-Key header, scoped per project.

Body parameters

Item fields

curl https://api.zyrapay.net/v1/checkout \
  -H "x-api-key: $ZYRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "items": [
      { "name": "Pro plan", "amount": 5, "quantity": 1 },
      { "name": "Add-on seat", "amount": 2, "quantity": 4 }
    ],
    "currency": "PI",
    "expiresInMinutes": 30,
    "successUrl": "https://yourapp.com/success",
    "cancelUrl": "https://yourapp.com/cancel",
    "webhookUrl": "https://yourapp.com/webhooks/zyra"
  }'

List checkouts

Lists checkouts for the project tied to your API key, with filtering, sorting, and pagination. The project scope is fixed by the key.

Query parameters

curl "https://api.zyrapay.net/v1/checkout?status=completed&sort=totalAmount&order=desc&page=1&limit=20" \
  -H "x-api-key: $ZYRA_API_KEY"

Retrieve a checkout

Returns a single checkout populated with its project.name and the checkout's deposit address. This route is public (no auth) so the hosted checkout page can read it directly.

curl https://api.zyrapay.net/v1/checkout/chk_8f2a1c9b4d6e7f

Cancel a checkout

Cancels a checkout owned by your project. Only a pending checkout can be cancelled.

curl -X DELETE https://api.zyrapay.net/v1/checkout/chk_8f2a1c9b4d6e7f \
  -H "x-api-key: $ZYRA_API_KEY"

Wallets

A wallet is a per-customer deposit address. Generate one for each user or invoice, hand them the address, and receive a signed deposit webhook whenever Pi arrives on it.

Create a wallet

Generates a new deposit address for the project tied to your API key. Takes no body. Emits a wallet.created webhook to the project's configured webhookUrl if one is set. Honors the Idempotency-Key header, scoped per API key.

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

Transactions

Transactions are the ledger of every money movement on your project — deposits, withdrawals, payments, refunds, and fees. These endpoints authenticate with your x-api-key and return your project's transactions.

List transactions

Returns a paginated list of the caller's transactions, each with its referenced project populated (name, type).

Query parameters

curl "https://api.zyrapay.net/v1/transactions?type=deposit&status=completed&sort=amount&order=desc&page=1&limit=20" \
  -H "x-api-key: $ZYRA_API_KEY"

Retrieve a transaction

Returns a single transaction owned by the caller.

curl https://api.zyrapay.net/v1/transactions/trx_a1b2c3d4 \
  -H "x-api-key: $ZYRA_API_KEY"

Payments

Payment endpoints move Pi off your balance — sending funds to a recipient (withdraw) or returning a previously received payment (refund). Authenticate with your x-api-key like every other endpoint. Both honor the Idempotency-Key header, and on-chain transfers are serialized behind a lock so concurrent calls cannot double-spend.

Withdraw

Debits your balance atomically (a conditional update guarantees two concurrent withdrawals can't both pass a stale balance check), submits a Pi payment to recipient, and records a completed withdrawal transaction. If the on-chain transfer fails, the reserved balance is refunded automatically.

Body parameters

curl -X POST https://api.zyrapay.net/v1/payments/withdraw \
  -H "x-api-key: $ZYRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "recipient": "GBVYHIK3X4VQ2...",
    "amount": 10
  }'

Refund

Refunds a previously received payment. The original transaction must belong to you, be a payment or deposit, and be completed. Double refunds are blocked. Because the on-chain payer address is not stored on the transaction, you supply the recipient to refund to. Omit amount for a full refund, or pass a smaller value for a partial refund.

Body parameters

curl -X POST https://api.zyrapay.net/v1/payments/refund \
  -H "x-api-key: $ZYRA_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "trxId": "trx_a1b2c3d4",
    "recipient": "GBVYHIK3X4VQ2...",
    "amount": 5
  }'

Projects

A project owns an API key and groups its checkouts, wallets, and transactions. You can create projects in the dashboard; the endpoint below rotates a project's key and authenticates with your x-api-key.

Rotate an API key

Generates a fresh API key for the project, stores only its new SHA-256 hash and 8-character prefix, and returns the new plaintext key exactly once. The previous key stops working immediately — rotation is also how you revoke a leaked key.

curl -X POST https://api.zyrapay.net/v1/projects/650f1c.../rotate-key \
  -H "x-api-key: $ZYRA_API_KEY"

Webhook Events

ZyraPay delivers events to the webhookUrl configured on your project (or, for checkouts, the per-session webhookUrl). Every delivery is an HTTP POST with a JSON body in the SimpleWebhookPayload envelope and an HMAC-SHA256 signature you should verify before trusting it.

Event types

Payload shape

Every event uses the same envelope. type is one of the values above, timestamp is a Unix epoch (milliseconds), projectId identifies your project, and signature is the HMAC-SHA256 hex digest of the payload (also sent in the header). The data object varies by event type.

{
  "type": "checkout.paid",
  "data": {
    "projectId": "650f1c...",
    "checkoutId": "chk_8f2a1c9b4d6e7f",
    "transactionId": "trx_a1b2c3d4",
    "from": "GBVYHIK3X4VQ2...",
    "amount": 13,
    "metadata": {}
  },
  "timestamp": 1749902700000,
  "projectId": "650f1c...",
  "signature": "3a7f...hmac-sha256-hex"
}

The data fields differ per family: deposit carries address, transactionId, and amount; the checkout.paid / underpaid / overpaid events carry checkoutId, from, transactionId, and amount; and the lifecycle events (checkout.expired, checkout.cancelled) carry checkoutId and amount.

Verifying the signature

Each request carries an X-Zyra-Signature header of the form sha256=<hex>. Compute the HMAC-SHA256 of the raw request body using your webhook secret and compare it to the header. ZyraPay also sends X-Project-ID, X-Event-Type, and X-Timestamp headers for convenience.

import crypto from "crypto";

function verify(rawBody, signatureHeader, secret) {
  const expected =
    "sha256=" +
    crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signatureHeader)
  );
}

// Express: capture the raw body, then
app.post("/webhooks/zyra", (req, res) => {
  const ok = verify(req.rawBody, req.headers["x-zyra-signature"], process.env.WEBHOOK_SECRET);
  if (!ok) return res.status(400).send("bad signature");
  // handle req.body.type ...
  res.sendStatus(200);
});

Errors

ZyraPay uses conventional HTTP status codes: 2xx for success, 4xx for problems with the request (these are safe to surface to the caller), and 5xx for errors on ZyraPay's side.

Status codes

Error response shape

Error responses carry a success: false flag and a human-readable message. Some errors also include a machine-readable error code, the statusCode, and a details object with field-level information.

{
  "success": false,
  "error": "VALIDATION_ERROR",
  "message": "Invalid request data",
  "statusCode": 400,
  "details": {
    "errors": [
      { "field": "items", "message": "items must be a non-empty array" }
    ]
  }
}