Skip to main content

Quickstart

Get ZKP2P Pay integrated in under 5 minutes.

Prerequisites​

  • A merchant account with API key
  • Node.js 18+ for your backend
  • A wallet address to receive USDC on Base

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.zkp2p-pay.xyz',
    apiKey: 'your_api_key',
  }
);

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

2. Redirect the User​

Redirect the user to the checkout URL:

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

// On the frontend
redirectToCheckout(session.session.id, {
  apiBaseUrl: 'https://api.zkp2p-pay.xyz',
  checkoutBaseUrl: 'https://checkout.zkp2p-pay.xyz',
  apiKey: 'your_api_key',
});

Or simply redirect using the URL:

window.location.href = session.checkoutUrl;

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​

Example Repository​

Check out the demo app for a complete integration example.