Skip to content
Lunaz Docs

Quickstart

This procedure takes you from a new account to a paid invoice. You need a Zcash wallet that can export an incoming viewing key (UIVK) or a Unified Full Viewing Key (UFVK).

Create your account and connect your wallet

Section titled “Create your account and connect your wallet”

  1. Open the Lunaz dashboard and go to the sign-in page.

  2. Enter your email.

    Lunaz sends a one-time code to your email through Magic. A new email creates a new account.

  3. Enter the code.

    You can set an account name later in Settings.

  4. Get the incoming viewing key from your wallet.

    With zcash-devtool, run wallet list-accounts. The command prints the UIVK on the UIVK: line. On mainnet the UIVK starts with uivk1. If your wallet exports only a UFVK (uview1), use the UFVK. Lunaz keeps only its incoming part.

  5. Make sure that the key is correct.

  6. Paste the key in the dashboard onboarding and save it.

  7. Open the API keys page and create an API key.

  8. Keep the key on your server.

Create your first invoice

Section titled “Create your first invoice”

An invoice amount is in zatoshi. 1 ZEC is 100000000 zatoshi.

  1. Send this request from your server. Replace the key with your API key.

    Create an invoice
    curl -X POST https://api.example.com/v1/invoices \
      -H "Authorization: Bearer lz_your_api_key" \
      -H "Content-Type: application/json" \
      -d '{"amount_zat": 5000000, "expires_in_secs": 900}'

    Use the API base URL that Lunaz gave you instead of api.example.com.

  2. Read the response.

    Response
    {
      "id": "8f14e45f-ceea-4672-9b2d-5c1d0a7e3b11",
      "address": "u1q8x4example7shieldedaddress",
      "amount_zat": 5000000,
      "zip321_uri": "zcash:u1q8x4example7shieldedaddress?amount=0.05&memo=bHVuYXo6OGYxNGU0NWY",
      "status": "pending",
      "expires_at": 1792000900
    }

  3. Save the id with your order.

Show the QR code

Section titled “Show the QR code”

  1. Encode the zip321_uri value as a QR code.

  2. Show the QR code to the buyer.

  3. Tell the buyer to scan it with a Zcash wallet.

The URI also contains the address and the amount. A wallet fills these fields when the buyer scans the code.

Receive the webhook

Section titled “Receive the webhook”

  1. Open the webhooks page in the dashboard.

  2. Enter the URL of your endpoint.

  3. Copy the signing secret.

  4. Send a test delivery from the dashboard.

  5. Make sure that your endpoint returns a 2xx status.

  6. Verify the X-Lunaz-Signature header of each request. See Webhooks.

  7. Wait for the invoice.paid webhook.

When the buyer pays, the status changes to detected and then to paid after one confirmation. Lunaz sends invoice.paid with this body.

invoice.paid
{
  "type": "invoice.paid",
  "invoice_id": "8f14e45f-ceea-4672-9b2d-5c1d0a7e3b11",
  "status": "paid",
  "amount_zat": 5000000,
  "received_zat": 5000000,
  "overpaid_zat": 0,
  "txid": "3b1c0f9e2a7d4c58b6e1a0f3d9c27b845e6a1f0d2c3b4a59687766554433221f",
  "swap": null
}

Next steps

Section titled “Next steps”