Getting started

Your first payment in 6 steps.

From zero to a working integration. Each step builds on the last, mark them complete as you go and your progress saves automatically.

0 of 6 complete

Install the SDK

Step 1 of 6

Add Payvra to your project. Pick your language above, the install command and every code example on this page will update.

Step 1, Node.js

1# Install via npm (or yarn / pnpm)
2npm install payvra
3
4# Verify it installed
5node -e "console.log(require('payvra').VERSION)"

Create a sandbox API key

Step 2 of 6

Log into the Payvra dashboard and generate a test-mode API key. Test keys start with sk_test_ and only work against the sandbox, no real funds are ever moved.

Open Dashboard

Step 2, Node.js

1// Your test key looks like this:
2// sk_test_abc123...
3
4// Set it as an environment variable:
5// export PAYVRA_TEST_KEY=sk_test_abc123...
6
7import { Payvra } from "payvra";
8
9const payvra = new Payvra(process.env.PAYVRA_TEST_KEY!);
10
11// Verify your key works
12const keys = await payvra.apiKeys.list();
13console.log("Authenticated:", keys.length, "key(s) found");

Create your first payment

Step 3 of 6

Use the SDK to create a payment. You'll get back a payment object with a checkout URL that your customers would visit to pay.

Step 3, Node.js

1import { Payvra } from "payvra";
2
3const payvra = new Payvra(process.env.PAYVRA_TEST_KEY!);
4
5const payment = await payvra.payments.create({
6  amount: "49.99",
7  currency: "USDC",
8  chain: "solana",
9  metadata: { orderId: "order_123" },
10});
11
12console.log("Payment ID:", payment.id);
13console.log("Status:", payment.status);
14console.log("Checkout URL:", payment.checkoutUrl);

Handle the webhook

Step 4 of 6

When a payment completes, Payvra sends a webhook to your server. Set up a handler that verifies the signature and processes the event.

Step 4, Node.js

1import express from "express";
2import crypto from "crypto";
3
4const app = express();
5app.use(express.raw({ type: "application/json" }));
6
7const WEBHOOK_SECRET = process.env.PAYVRA_WEBHOOK_SECRET!;
8
9app.post("/webhooks/payvra", (req, res) => {
10  const payload = req.body.toString();
11  const webhookId = req.headers["webhook-id"] as string;
12  const timestamp = req.headers["webhook-timestamp"] as string;
13  const signature = req.headers["webhook-signature"] as string;
14
15  // Reject stale events (> 5 min)
16  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
17  if (age > 300) return res.status(400).send("Timestamp too old");
18
19  // Verify signature
20  const signed = `${webhookId}.${timestamp}.${payload}`;
21  const expected = crypto
22    .createHmac("sha256", WEBHOOK_SECRET)
23    .update(signed)
24    .digest("base64");
25  const received = signature.replace("v1,", "");
26
27  if (!crypto.timingSafeEqual(
28    Buffer.from(expected, "base64"),
29    Buffer.from(received, "base64"),
30  )) {
31    return res.status(400).send("Invalid signature");
32  }
33
34  const event = JSON.parse(payload);
35  console.log("Event:", event.type, event.data.id);
36
37  // Handle the event
38  if (event.type === "payment.completed") {
39    // Fulfill the order
40    console.log("Payment completed:", event.data.id);
41  }
42
43  res.json({ received: true });
44});
45
46app.listen(4242, () => console.log("Webhook server on :4242"));

Verify the payment

Step 5 of 6

After your webhook handler processes the event, retrieve the payment to confirm its status. This is the belt-and-suspenders check, never rely on webhooks alone for fulfillment.

Step 5, Node.js

1import { Payvra } from "payvra";
2
3const payvra = new Payvra(process.env.PAYVRA_TEST_KEY!);
4
5// Use the payment ID from step 3
6const payment = await payvra.payments.retrieve("pay_...");
7
8console.log("Payment ID:", payment.id);
9console.log("Status:", payment.status);       // "completed"
10console.log("Amount:", payment.amount);        // "49.99"
11console.log("Currency:", payment.currency);    // "USDC"
12console.log("Chain:", payment.chain);          // "solana"
13console.log("Settled at:", payment.settledAt);
14console.log("Tx hash:", payment.txHash);

Go live

Step 6 of 6

You've built and tested the full flow. Now swap your test key for a live key and you're accepting real payments.

Step 6, Node.js

1// Before (sandbox):
2const payvra = new Payvra("sk_test_abc123...");
3
4// After (production):
5const payvra = new Payvra(process.env.PAYVRA_LIVE_KEY!);
6// That's it. Same code, real payments.
7
8// Checklist before going live:
9// 1. Replace sk_test_ with sk_live_ (use env vars!)
10// 2. Set your production webhook URL in the dashboard
11// 3. Verify your webhook endpoint returns 200
12// 4. Set your settlement currency and payout address
13// 5. Test one small live payment to confirm the flow

1// Your test key looks like this: 2// sk_test_abc123... 3 4// Set it as an environment variable: 5// export PAYVRA_TEST_KEY=sk_test_abc123... 6 7import { Payvra } from "payvra"; 8 9const payvra = new Payvra(process.env.PAYVRA_TEST_KEY!); 10 11// Verify your key works 12const keys = await payvra.apiKeys.list(); 13console.log("Authenticated:", keys.length, "key(s) found");

1import { Payvra } from "payvra"; 2 3const payvra = new Payvra(process.env.PAYVRA_TEST_KEY!); 4 5const payment = await payvra.payments.create({ 6 amount: "49.99", 7 currency: "USDC", 8 chain: "solana", 9 metadata: { orderId: "order_123" }, 10}); 11 12console.log("Payment ID:", payment.id); 13console.log("Status:", payment.status); 14console.log("Checkout URL:", payment.checkoutUrl);

1import express from "express"; 2import crypto from "crypto"; 3 4const app = express(); 5app.use(express.raw({ type: "application/json" })); 6 7const WEBHOOK_SECRET = process.env.PAYVRA_WEBHOOK_SECRET!; 8 9app.post("/webhooks/payvra", (req, res) => { 10 const payload = req.body.toString(); 11 const webhookId = req.headers["webhook-id"] as string; 12 const timestamp = req.headers["webhook-timestamp"] as string; 13 const signature = req.headers["webhook-signature"] as string; 14 15 // Reject stale events (> 5 min) 16 const age = Math.abs(Date.now() / 1000 - Number(timestamp)); 17 if (age > 300) return res.status(400).send("Timestamp too old"); 18 19 // Verify signature 20 const signed = `${webhookId}.${timestamp}.${payload}`; 21 const expected = crypto 22 .createHmac("sha256", WEBHOOK_SECRET) 23 .update(signed) 24 .digest("base64"); 25 const received = signature.replace("v1,", ""); 26 27 if (!crypto.timingSafeEqual( 28 Buffer.from(expected, "base64"), 29 Buffer.from(received, "base64"), 30 )) { 31 return res.status(400).send("Invalid signature"); 32 } 33 34 const event = JSON.parse(payload); 35 console.log("Event:", event.type, event.data.id); 36 37 // Handle the event 38 if (event.type === "payment.completed") { 39 // Fulfill the order 40 console.log("Payment completed:", event.data.id); 41 } 42 43 res.json({ received: true }); 44}); 45 46app.listen(4242, () => console.log("Webhook server on :4242"));

1import { Payvra } from "payvra"; 2 3const payvra = new Payvra(process.env.PAYVRA_TEST_KEY!); 4 5// Use the payment ID from step 3 6const payment = await payvra.payments.retrieve("pay_..."); 7 8console.log("Payment ID:", payment.id); 9console.log("Status:", payment.status); // "completed" 10console.log("Amount:", payment.amount); // "49.99" 11console.log("Currency:", payment.currency); // "USDC" 12console.log("Chain:", payment.chain); // "solana" 13console.log("Settled at:", payment.settledAt); 14console.log("Tx hash:", payment.txHash);

1// Before (sandbox): 2const payvra = new Payvra("sk_test_abc123..."); 3 4// After (production): 5const payvra = new Payvra(process.env.PAYVRA_LIVE_KEY!); 6// That's it. Same code, real payments. 7 8// Checklist before going live: 9// 1. Replace sk_test_ with sk_live_ (use env vars!) 10// 2. Set your production webhook URL in the dashboard 11// 3. Verify your webhook endpoint returns 200 12// 4. Set your settlement currency and payout address 13// 5. Test one small live payment to confirm the flow