Skip to content

Guides

Practical guides for common Nivatio integration scenarios.

Available Guides

  • 💳 Payment Processing --- Complete guide to processing payments Read Guide

  • âš  Error Handling --- Handle errors gracefully in your integration Read Guide

  • 🧪 Testing & Sandbox --- Test your integration thoroughly Read Guide

Common Patterns

Idempotent Order Creation

Prevent duplicate orders by using idempotency keys:

const idempotencyKey = `order_${Date.now()}_${userId}`;

const order = await client.orders.create({
  amount: 100000,
  currency: 'NUSD',
  metadata: {
    idempotencyKey: idempotencyKey
  }
});

Verifying Payments On-Chain

For high-value orders, verify the transaction on-chain:

// After receiving webhook
const order = await client.orders.retrieve(orderId);

// Verify transaction on blockchain
const txReceipt = await provider.getTransactionReceipt(order.txHash);

if (txReceipt.confirmations >= 2) {
  // Payment confirmed
  fulfillOrder(order);
}

Handling Network Congestion

// Increase gas price for faster confirmation
const order = await client.orders.create({
  amount: 100000,
  currency: 'NUSD',
  metadata: {
    priority: 'high' // Nivatio can adjust gas accordingly
  }
});

Best Practices

  1. Always use HTTPS for webhook endpoints
  2. Implement idempotency in webhook handlers
  3. Store order metadata to link with your internal systems
  4. Test thoroughly in sandbox before going live
  5. Monitor webhook deliveries in dashboard
  6. Keep API keys secure - use environment variables
  7. Handle all webhook events - don't assume only payment.succeeded

Troubleshooting

Problem Solution
Order creation fails Check API key permissions, verify amount format (6 decimals)
Webhook not received Verify URL is HTTPS and publicly accessible
Payment stuck in PENDING Check if customer completed the checkout flow
Duplicate orders Implement idempotency keys
Wrong amount charged Remember NUSD has 6 decimals (100000 = 100.000 NUSD)

Next Steps