Xepeng Client SDK

JavaScript SDK for integrating Xepeng payment gateway in browser/frontend applications.

Installation

NPM

npm install @xepeng/client-sdk

Yarn

yarn add @xepeng/client-sdk

CDN

<script src="https://cdn.jsdelivr.net/npm/@xepeng/client-sdk/dist/index.umd.js"></script>

Quick Start

import { XepengClientAPI } from '@xepeng/client-sdk';

// Initialize the SDK
const xepeng = new XepengClientAPI({
  clientId: 'xpg_your_client_id',
  clientSecret: 'your_client_secret',
  baseUrl: 'https://api.xepeng.com' // or 'https://staging-api.xepeng.com' for testing
});

// Create a payment
const payment = await xepeng.createPayment({
  amount: 100000,
  ref_id: 'INV-2024-001',
  purpose: 'Product Purchase',
  buyer_name: 'John Doe',
  buyer_phone: '+6281234567890',
  buyer_email: '[email protected]'
});

// Redirect user to payment page
window.location.href = payment.item.payment_url;

Documentation

For complete documentation, visit docs.xepeng.com

API Reference

XepengClientAPI

Constructor options:

| Option | Type | Required | Description | |--------|------|----------|-------------| | clientId | string | Yes | Your merchant client ID | | clientSecret | string | Yes | Your merchant client secret | | baseUrl | string | No | API base URL (default: production) | | timeout | number | No | Request timeout in ms (default: 30000) |

Methods

createPayment(data)

Create a new payment order and generate payment link.

const result = await xepeng.createPayment({
  amount: 100000,           // Required: Amount in smallest currency unit
  ref_id: 'INV-001',        // Required: Your reference ID
  purpose: 'Order Payment', // Required: Payment purpose/description
  buyer_name: 'John Doe',   // Required: Buyer's name
  buyer_phone: '+62812...',  // Required: Buyer's phone
  buyer_email: 'john@...',  // Required: Buyer's email
  buyer_address: '...',     // Optional: Buyer's address
  expired_at: '2024-12-31T23:59:59Z' // Optional: Expiration time
});

getPaymentStatus(uid)

Get the current status of a payment.

const status = await xepeng.getPaymentStatus('550e8400-e29b-41d4-a716-446655440000');

Campaign Methods

listCampaigns(options)

List all campaigns with pagination support.

const campaigns = await xepeng.listCampaigns({
  page: 1,
  limit: 10
});

// Response: { status: 'success', items: [...], pagination: {...} }

getCampaign(uid)

Get detailed information about a specific campaign.

const campaign = await xepeng.getCampaign('550e8400-e29b-41d4-a716-446655440000');

// Response includes: title, description, target_amount, raised_amount, donor_count, status, etc.

Donation Methods

listDonations(options)

List donations for a specific campaign with pagination support.

const donations = await xepeng.listDonations({
  campaign_uid: '550e8400-e29b-41d4-a716-446655440000',
  page: 1,
  limit: 10
});

// Response: { status: 'success', items: [...], pagination: {...} }

createDonation(data)

Create a new donation for a campaign.

const donation = await xepeng.createDonation({
  amount: 50000,              // Required: Donation amount in smallest currency unit
  campaign_uid: 'campaign-uid', // Required: Campaign UID to donate to
  donor_name: 'John Doe',     // Required: Donor's name
  donor_email: 'john@...',    // Required: Donor's email
  donor_phone: '+62812...',   // Required: Donor's phone
  message: 'Good luck!',      // Optional: Donation message
  is_anonymous: false,        // Optional: Hide donor name (default: false)
  payment_method: 'ewallet',  // Optional: Payment method (default: 'crypto')
  expired_at: '2024-12-31T23:59:59Z' // Optional: Expiration time
});

// Redirect to payment page
window.location.href = donation.item.payment_url;

Security

The Client API uses multiple security layers:

1. Origin Validation - Only requests from whitelisted domains are accepted
2. Browser Signature - HMAC-SHA256 signature using Client ID, Timestamp, User Agent, and Browser Fingerprint
3. Timestamp Validation - Requests expire after 5 minutes
4. HTTPS Only - All requests must use HTTPS in production

Examples

React Component

import React, { useState } from 'react';
import { XepengClientAPI } from '@xepeng/client-sdk';

const xepeng = new XepengClientAPI({
  clientId: process.env.REACT_APP_XEPENG_CLIENT_ID,
  clientSecret: process.env.REACT_APP_XEPENG_CLIENT_SECRET
});

function CheckoutButton({ amount, product, buyer }) {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  const handlePayment = async () => {
    setLoading(true);
    setError(null);

    try {
      const payment = await xepeng.createPayment({
        amount,
        ref_id: `ORDER-${Date.now()}`,
        purpose: product.name,
        buyer_name: buyer.name,
        buyer_phone: buyer.phone,
        buyer_email: buyer.email,
        buyer_address: buyer.address
      });

      window.location.href = payment.item.payment_url;
    } catch (err) {
      setError(err.message);
      setLoading(false);
    }
  };

  return (
    <div>
      {error && <div className="error">{error}</div>}
      <button onClick={handlePayment} disabled={loading}>
        {loading ? 'Processing...' : `Pay Rp ${amount.toLocaleString()}`}
      </button>
    </div>
  );
}

export default CheckoutButton;

React Component - Donation

import React, { useState } from 'react';
import { XepengClientAPI, XepengAPIError } from '@xepeng/client-sdk';

const xepeng = new XepengClientAPI({
  clientId: process.env.REACT_APP_XEPENG_CLIENT_ID,
  clientSecret: process.env.REACT_APP_XEPENG_CLIENT_SECRET
});

function DonationButton({ campaignUid, amount, donor }) {
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState(null);

  const handleDonation = async () => {
    setLoading(true);
    setError(null);

    try {
      const donation = await xepeng.createDonation({
        campaign_uid: campaignUid,
        amount,
        donor_name: donor.name,
        donor_email: donor.email,
        donor_phone: donor.phone,
        message: donor.message,
        is_anonymous: donor.isAnonymous || false
      });

      window.location.href = donation.item.payment_url;
    } catch (err) {
      if (err instanceof XepengAPIError) {
        setError(`Donation failed: ${err.message}`);
      }
      setLoading(false);
    }
  };

  return (
    <div>
      {error && <div className="error">{error}</div>}
      <button onClick={handleDonation} disabled={loading}>
        {loading ? 'Processing...' : `Donate Rp ${amount.toLocaleString()}`}
      </button>
    </div>
  );
}

export default DonationButton;

Vue.js Component

<template>
  <div>
    <div v-if="error" class="error">{{ error }}</div>
    <button @click="createPayment" :disabled="loading">
      {{ loading ? 'Processing...' : `Pay Rp ${amount.toLocaleString()}` }}
    </button>
  </div>
</template>

<script>
import { XepengClientAPI } from '@xepeng/client-sdk';

export default {
  props: ['amount', 'product', 'buyer'],
  data() {
    return {
      loading: false,
      error: null,
      xepeng: new XepengClientAPI({
        clientId: process.env.VUE_APP_XEPENG_CLIENT_ID,
        clientSecret: process.env.VUE_APP_XEPENG_CLIENT_SECRET
      })
    };
  },
  methods: {
    async createPayment() {
      this.loading = true;
      this.error = null;

      try {
        const payment = await this.xepeng.createPayment({
          amount: this.amount,
          ref_id: `ORDER-${Date.now()}`,
          purpose: this.product.name,
          buyer_name: this.buyer.name,
          buyer_phone: this.buyer.phone,
          buyer_email: this.buyer.email
        });

        window.location.href = payment.item.payment_url;
      } catch (err) {
        this.error = err.message;
        this.loading = false;
      }
    }
  }
};
</script>

Error Handling

The SDK throws XepengAPIError for API errors:

try {
  const payment = await xepeng.createPayment(data);
} catch (error) {
  if (error instanceof XepengAPIError) {
    console.error('API Error:', error.message);
    console.error('Status Code:', error.statusCode);
    console.error('Response:', error.response);
  }
}

Development

# Clone repository
git clone https://github.com/xepeng-dev/xepeng-client-sdk.git
cd xepeng-client-sdk

# Install dependencies
npm install

# Development mode with watch
npm run dev

# Run tests
npm test

# Build for production
npm run build

Support

• Documentation: https://docs.xepeng.com
• API Status: https://status.xepeng.com
• Email: [email protected]
• Issues: https://github.com/xepeng-dev/xepeng-client-sdk/issues

License

MIT © Xepeng