Code Examples

Ready-to-use code examples for integrating UltraPay into your application. Choose your preferred language below.

javascript
const axios = require('axios');


class UltraPay {
  constructor(publicKey, secretKey) {
    this.client = axios.create({
      baseURL: 'https://pay.ultrapay.cc',
      headers: {
        'X-Public-Key': publicKey,
        'X-Secret-Key': secretKey,
        'Content-Type': 'application/json',
      },
    });
  }


  async createPayment(amount, currency, successUrl, cancelUrl, options = {}) {
    const { data } = await this.client.post('/api/v1/payments/create', {
      amount,
      currency,
      successUrl,
      cancelUrl,
      ...options,
    });


    if (!data.success) {
      throw new Error(data.error.message);
    }


    return data.data;
  }


  async getPayment(transactionId) {
    const { data } = await this.client.get(`/api/v1/payments/${transactionId}`);
    return data;
  }


  async cancelPayment(transactionId) {
    const { data } = await this.client.delete(`/api/v1/payments/${transactionId}`);
    return data;
  }
}


// Usage
const ultrapay = new UltraPay('upp_your_public_key', 'ups_your_secret_key');


const payment = await ultrapay.createPayment(
  5000,
  'usd',
  'https://yoursite.com/thank-you',
  'https://yoursite.com/checkout',
  {
    customerEmail: 'customer@example.com',
    description: 'Order #12345',
  }
);


console.log('Redirect to:', payment.paymentUrl);

Best Practices

1. Never Use Iframes

Always redirect customers to the payment URL using a full page redirect. Never embed in an iframe:

javascript
// ✅ Correct - Full page redirect
window.location.href = payment.paymentUrl;


// ❌ Wrong - Never do this!
// <iframe src={payment.paymentUrl} />  // Will fail!

2. Always Verify Payments Server-Side

Never trust client-side confirmation. Always call GET /api/v1/payments/:id to verify:

javascript
// When customer returns to your success URL
const payment = await ultrapay.getPayment(transactionId);


if (payment.data.status === 'succeeded') {
  // ✅ Safe to fulfill order
  await fulfillOrder(orderId);
}

3. Use Webhooks for Async Updates

Webhooks notify you of refunds, disputes, and async events:

javascript
// Handle webhook
app.post('/api/webhooks/ultrapay', (req, res) => {
  const { event, transactionId, metadata } = req.body;


  switch (event) {
    case 'payment.refunded':
      // Handle refund
      processRefund(metadata.orderId);
      break;
    case 'payment.disputed':
      // Handle dispute
      handleDispute(metadata.orderId);
      break;
  }


  res.json({ received: true });
});

4. Store Transaction IDs

Always save the transactionId with your order for reference:

javascript
// Save transaction ID with order
await db.orders.update({
  where: { id: orderId },
  data: { ultrapayTransactionId: payment.transactionId },
});

5. Handle Cart Changes

If a customer's cart changes, cancel the old payment and create a new one:

javascript
// Cancel old payment
await ultrapay.cancelPayment(oldTransactionId);


// Create new payment with updated amount
const newPayment = await ultrapay.createPayment(
  newAmount,
  'usd',
  successUrl,
  cancelUrl
);


// Redirect to new checkout
res.redirect(newPayment.paymentUrl);
↑ ↓ navigate↵ select