PonponPay
Advanced15 min read

Full Integration (API Key Mode)

Use API Key to securely create and manage orders on the server side, with full control over the payment flow.

Overview

API Key mode is suitable for scenarios requiring full control over the payment flow:

  • Create, query, cancel orders
  • Receive Webhook callback notifications
  • Query transaction records and statistics
  • Manage refunds and disputes

Get Your API Key

  1. Log in to PonponPay merchant dashboard
  2. Go to "API Keys" page
  3. Click "Create Key"
  4. Securely save the generated API Key

⚠️ API Key is only shown once. Save it immediately. If lost, you need to regenerate.

Create Order Example

import { PonponPay } from '@ponponpay/sdk';

const ponponpay = new PonponPay({
  apiKey: process.env.PONPONPAY_API_KEY
});

// 创建订单
const order = await ponponpay.orders.create({
  amount: 100,
  currency: 'USDT',
  network: 'tron',
  mchOrderId: 'ORDER_123',
  notifyUrl: 'https://your-site.com/webhook',
  redirectUrl: 'https://your-site.com/success'
});

console.log('Payment URL:', order.paymentUrl);

Webhook Callbacks

When order status changes, we send HTTP POST requests to your configured URL.

Event Types

EventDescription
order.paidOrder has been paid
order.expiredOrder has expired
order.cancelledOrder has been cancelled

Signature Verification

We include a signature in the request header. Verify it to ensure the request is from PonponPay.

import crypto from 'crypto';

// Express.js Webhook 处理示例
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-ponponpay-signature'];
  const payload = req.body;
  
  // 验证签名
  const expectedSignature = crypto
    .createHmac('sha256', process.env.WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');
  
  if (signature !== expectedSignature) {
    return res.status(401).send('Invalid signature');
  }
  
  const event = JSON.parse(payload);
  
  switch (event.type) {
    case 'order.paid':
      // 处理支付成功
      await handleOrderPaid(event.data);
      break;
    case 'order.expired':
      // 处理订单过期
      await handleOrderExpired(event.data);
      break;
  }
  
  res.status(200).send('OK');
});

Security Best Practices

Protect API Key

Never expose API Key in frontend code, Git repos, or logs.

Use Environment Variables

Store API Key in environment variables, not hardcoded.

Verify Webhook Signatures

Always verify Webhook request signatures to prevent forgery.

Use HTTPS

Ensure your Webhook endpoint uses HTTPS.

Implement Idempotency

Webhooks may be sent multiple times. Ensure your logic is idempotent.

SDK Documentation

We provide SDKs in multiple languages to help you integrate quickly:

JavaScript/TypeScriptPHP.NET (C#)Python