Skip to main content

Quickstart

Get ZKP2P Pay integrated in under 5 minutes.

Prerequisites​

  • A merchant account with API key (create one at merchant.pay.zkp2p.xyz)
  • Node.js 18+ for your backend
  • A wallet address to receive USDC

Installation​

npm install @zkp2p-pay/sdk

1. Create a Checkout Session​

On your backend, create a checkout session when a user is ready to pay:

import { createCheckoutSession } from '@zkp2p-pay/sdk';

const session = await createCheckoutSession(
  {
    merchantId: 'your_merchant_id',
    amountUsdc: '50.00',
    destinationChainId: 8453, // Base
    destinationToken: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913', // USDC
    recipientAddress: '0xYourWalletAddress',
    successUrl: 'https://yoursite.com/success',
    cancelUrl: 'https://yoursite.com/cancel',
    metadata: {
      orderId: 'order_123',
      customerId: 'cust_456',
    },
  },
  {
    apiBaseUrl: 'https://api.pay.zkp2p.xyz',
    apiKey: 'your_api_key',
  }
);

// session.checkoutUrl contains the URL to redirect the user to
console.log(session.checkoutUrl);

2. Open Checkout​

Open the checkoutUrl returned from createCheckoutSession:

// Option 1: Redirect in the same tab
window.location.href = session.checkoutUrl;

// Option 2: Open in a new tab
window.open(session.checkoutUrl, '_blank');

3. Handle Webhooks​

Set up a webhook endpoint to receive payment notifications:

import express from 'express';
import crypto from 'crypto';

const app = express();

app.post('/webhooks/zkp2p', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'] as string;
  const timestamp = req.headers['x-webhook-timestamp'] as string;
  const payload = req.body.toString();

  // Verify signature
  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET!)
    .update(`${timestamp}.${payload}`)
    .digest('hex');

  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(payload);

  switch (event.type) {
    case 'order.fulfilled':
      // Payment successful - fulfill the order
      console.log('Payment received:', event.data.order.id);
      console.log('Transaction hash:', event.data.txHash);
      break;
    case 'order.failed':
      // Payment failed
      console.log('Payment failed:', event.data.error);
      break;
  }

  // Respond quickly with 200
  res.status(200).send('OK');
});

4. Test Your Integration​

  1. Create a test checkout session
  2. Complete the checkout flow using the hosted UI
  3. Verify your webhook receives the order.fulfilled event
  4. Check that USDC arrived in your recipient wallet

Next Steps​

Live Demo​

Try the demo app to see a complete integration example.