Back to Developers

Integration Guides

Step-by-step tutorials to help you integrate Pulse2Pay into your application quickly and correctly.

Quick Start Guide

Step 1: Get Your API Keys

Sign up for a Pulse2Pay account and navigate to the API Settings section in your merchant dashboard. You'll receive:

  • API Key - Used to identify your account (safe to expose)
  • API Secret - Used to sign requests (keep secure!)

Important: Your API secret is only shown once. Store it securely!

Step 2: Create Your First Payment

Use the following code to create a payment request:

Node.js
const crypto = require('crypto');

const API_KEY = process.env.PULSE2PAY_KEY;
const API_SECRET = process.env.PULSE2PAY_SECRET;
const BASE_URL = 'https://api.pulse2pay.com/api/merchant/v1';

async function createPayment(amount, currency, network) {
  const timestamp = Date.now().toString();
  const path = '/api/merchant/v1/payments';
  const body = JSON.stringify({
    amount: amount,
    currency: currency,
    network: network,
    callbackUrl: 'https://yoursite.com/webhooks/pulse2pay'
  });

  // Generate signature: timestamp.METHOD.path.body
  const signatureData = timestamp + '.POST.' + path + '.' + body;
  const signature = crypto
    .createHmac('sha256', API_SECRET)
    .update(signatureData)
    .digest('hex');

  // Make request
  const response = await fetch(BASE_URL + '/payments', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Pulse2Pay-Key': API_KEY,
      'X-Pulse2Pay-Signature': signature,
      'X-Pulse2Pay-Timestamp': timestamp
    },
    body: body
  });

  return response.json();
}

// Usage
const payment = await createPayment('100.00', 'USDT', 'TRON');
console.log('Payment address:', payment.generatedAddress);

Step 3: Handle Webhook Events

Set up an endpoint to receive payment notifications:

Express.js
const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

app.post('/webhooks/pulse2pay', (req, res) => {
  // Verify signature
  const signature = req.headers['x-pulse2pay-signature'];
  const timestamp = req.headers['x-pulse2pay-timestamp'];
  const body = JSON.stringify(req.body);

  const expectedSignature = crypto
    .createHmac('sha256', process.env.PULSE2PAY_SECRET)
    .update(timestamp + '.' + body)
    .digest('hex');

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

  // Process the event (note: payload uses "type" not "event")
  const { type, data } = req.body;

  switch (type) {
    case 'payment.confirmed':
      // Mark order as paid
      console.log('Payment confirmed:', data.paymentId);
      break;
    case 'payment.expired':
      // Handle expired payment
      console.log('Payment expired:', data.paymentId);
      break;
    case 'payment.underpaid':
      // Handle underpaid payment
      console.log('Payment underpaid:', data.paymentId, 'Missing:', data.underpaidAmount);
      break;
  }

  // Always return 200 quickly
  res.status(200).json({ received: true });
});

Step 4: Test Your Integration

Before going live, test your integration using our sandbox environment:

  1. Request sandbox API credentials from support
  2. Create a test payment using sandbox credentials
  3. Use the sandbox dashboard to simulate payment confirmation
  4. Verify your webhook handler processes the event correctly
  5. Once verified, switch to production credentials

Best Practices

Idempotency

Always use unique idempotencyKey values. This allows you to safely retry requests and handle duplicate webhooks.

Error Handling

Implement proper error handling for network failures, signature verification errors, and API rate limits. Log errors for debugging.

Security

Never expose your API secret in client-side code. Store credentials securely using environment variables or a secrets manager.

Webhook Processing

Return 200 status quickly from webhooks. Process events asynchronously to avoid timeout issues and retry loops.