Cara Menggunakan iPay API untuk Integrasi Pembayaran di Tahun 2026

Ringkasan

API iPay memungkinkan pengembang untuk mengintegrasikan pemrosesan pembayaran, faktur, dan transaksi keuangan secara terprogram. API ini menggunakan otentikasi OAuth 2.0 dan kunci API, endpoint RESTful untuk pembayaran, pengembalian dana, transaksi, dan rekonsiliasi, dengan persyaratan kepatuhan PCI DSS dan batas laju standar industri. Panduan ini mencakup pengaturan otentikasi, pemrosesan pembayaran, integrasi webhook, kepatuhan keamanan, dan strategi penerapan produksi.

Pendahuluan

Pemrosesan pembayaran digital menangani lebih dari $8 triliun setiap tahun di seluruh dunia. Bagi pengembang yang membangun platform e-commerce, aplikasi SaaS, atau solusi marketplace, integrasi API pembayaran bukan lagi pilihan—tetapi penting untuk menerima pembayaran pelanggan secara aman dan sesuai.

Inilah kenyataannya: bisnis kehilangan 5-10% pendapatan karena pembayaran yang gagal, rekonsiliasi manual, dan penipuan pembayaran. Integrasi API pembayaran yang solid mengotomatiskan pemrosesan pembayaran, mengurangi kegagalan dengan logika coba lagi yang cerdas, memungkinkan rekonsiliasi otomatis, dan menerapkan deteksi penipuan.

Panduan ini akan memandu Anda melalui seluruh proses integrasi API pembayaran. Anda akan mempelajari pengaturan otentikasi, pemrosesan pembayaran, manajemen pengembalian dana, penanganan webhook, kepatuhan PCI DSS, praktik terbaik keamanan, dan strategi penerapan produksi. Pada akhirnya, Anda akan memiliki integrasi pembayaran yang siap produksi.

Catatan: Panduan ini mencakup pola integrasi API pembayaran umum yang berlaku untuk iPay dan pemroses pembayaran serupa. URL endpoint spesifik dan detail otentikasi mungkin bervariasi—selalu merujuk pada dokumentasi resmi iPay untuk detail implementasi.

Apa itu API iPay?

API pembayaran seperti iPay menyediakan antarmuka RESTful untuk memproses transaksi keuangan. API ini menangani:

• Otorisasi dan penangkapan pembayaran
• Pengembalian dana dan chargeback
• Riwayat transaksi dan pelaporan
• Tokenisasi pelanggan (vault)
• Langganan dan penagihan berulang
• Pembuatan dan manajemen faktur
• Rekonsiliasi dan penyelesaian
• Deteksi dan pencegahan penipuan

Fitur Utama

Gambaran Umum Alur Pembayaran

┌─────────────┐    ┌─────────────┐    ┌─────────────┐
│   Pelanggan │───▶│   Pedagang  │───▶│   Gerbang   │
│   (Peramban)│    │   (Server)  │    │  Pembayaran │
└─────────────┘    └─────────────┘    └─────────────┘
     │                    │                    │
     │  1. Masukkan Kartu │                    │
     │───────────────────▶│                    │
     │                    │                    │
     │  2. Tokenisasi     │                    │
     │───────────────────▶│  3. Buat Niat     │
     │                    │───────────────────▶│
     │                    │                    │
     │                    │  4. Konfirmasi Pembayaran│
     │                    │───────────────────▶│
     │                    │                    │
     │                    │  5. Hasil          │
     │                    │◀───────────────────│
     │                    │                    │
     │  6. Resi           │                    │
     │◀───────────────────│                    │

Lingkungan API

Memulai: Pengaturan Otentikasi

Langkah 1: Buat Akun iPay

Sebelum mengakses API:

1. Kunjungi registrasi merchant iPay
2. Selesaikan verifikasi bisnis (KYB)
3. Kirim dokumen yang diperlukan:

• Registrasi bisnis
• Detail rekening bank
• ID pemerintah

1. Tunggu persetujuan (1-3 hari kerja)

Langkah 2: Dapatkan Kredensial API

Hasilkan kredensial API:

1. Masuk ke Dasbor Merchant iPay
2. Navigasi ke Pengaturan > Kunci API
3. Buat kunci API baru
4. Salin kredensial dengan aman

# file .env (JANGAN PERNAH di-commit ke git)
IPAY_API_KEY="live_xxxxxxxxxxxxxxxxxxxx"
IPAY_API_SECRET="secret_xxxxxxxxxxxxxxxxxxxx"
IPAY_WEBHOOK_SECRET="whsec_xxxxxxxxxxxxxxxxxxxx"

Catatan keamanan: Gunakan kunci terpisah untuk sandbox dan produksi.

Langkah 3: Pahami Metode Otentikasi

iPay mendukung beberapa metode otentikasi:

Langkah 4: Lakukan Panggilan API Terotentikasi

Buat klien API yang dapat digunakan kembali:

const IPAY_BASE_URL = process.env.IPAY_SANDBOX
  ? 'https://sandbox.ipay.com/api'
  : 'https://api.ipay.com/api';

const ipayRequest = async (endpoint, options = {}) => {
  const apiKey = process.env.IPAY_API_KEY;
  const apiSecret = process.env.IPAY_API_SECRET;

  // Basic authentication (Base64 encoded)
  const authHeader = Buffer.from(`${apiKey}:${apiSecret}`).toString('base64');

  const response = await fetch(`${IPAY_BASE_URL}${endpoint}`, {
    ...options,
    headers: {
      'Authorization': `Basic ${authHeader}`,
      'Content-Type': 'application/json',
      'Idempotency-Key': options.idempotencyKey || generateIdempotencyKey(),
      ...options.headers
    }
  });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(`iPay API Error: ${error.message}`);
  }

  return response.json();
};

function generateIdempotencyKey() {
  return `req_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
}

// Penggunaan
const account = await ipayRequest('/account');
console.log(`Merchant: ${account.business_name}`);

Pemrosesan Pembayaran

Membuat Niat Pembayaran

Inisialisasi pembayaran:

const createPayment = async (paymentData) => {
  const payment = {
    amount: paymentData.amount, // Dalam satuan mata uang terkecil (sen)
    currency: paymentData.currency || 'USD',
    customer: paymentData.customerId,
    payment_method: paymentData.paymentMethodId,
    confirm: true,
    description: paymentData.description,
    metadata: {
      orderId: paymentData.orderId,
      customerId: paymentData.customerId
    },
    capture_method: paymentData.captureMethod || 'automatic', // 'automatic' atau 'manual'
    statement_descriptor: paymentData.statementDescriptor || 'MYCOMPANY'
  };

  const response = await ipayRequest('/payments', {
    method: 'POST',
    body: JSON.stringify(payment),
    idempotencyKey: paymentData.idempotencyKey
  });

  return response;
};

// Penggunaan
const payment = await createPayment({
  amount: 2999, // $29.99
  currency: 'USD',
  customerId: 'cus_12345',
  paymentMethodId: 'pm_67890',
  description: 'Order #ORD-001',
  orderId: 'ORD-001',
  statementDescriptor: 'MYCOMPANY INC'
});

console.log(`Status pembayaran: ${payment.status}`);
console.log(`ID Pembayaran: ${payment.id}`);

Alur Status Pembayaran

membutuhkan_metode_pembayaran → membutuhkan_konfirmasi → membutuhkan_tindakan
                               → memproses              → membutuhkan_penangkapan → berhasil
                                                                                  → gagal
                                                                                  → dibatalkan

Metode Pembayaran

Membuat Token Detail Kartu

Simpan kartu dengan aman untuk penggunaan di masa mendatang:

const tokenizeCard = async (cardData) => {
  // JANGAN PERNAH mengirim data kartu mentah ke server Anda
  // Gunakan tokenisasi sisi klien sebagai gantinya

  // Sisi klien (peramban/seluler)
  const response = await fetch(`${IPAY_BASE_URL}/tokens`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${CLIENT_PUBLISHABLE_KEY}`
    },
    body: JSON.stringify({
      card: {
        number: cardData.number,
        exp_month: cardData.expMonth,
        exp_year: cardData.expYear,
        cvc: cardData.cvc
      }
    })
  });

  const token = await response.json();
  return token; // Kirim token.id ke server Anda
};

// Sisi server: Gunakan token untuk membuat metode pembayaran
const createPaymentMethod = async (tokenId, customerId) => {
  const response = await ipayRequest('/payment_methods', {
    method: 'POST',
    body: JSON.stringify({
      type: 'card',
      token: tokenId,
      customer: customerId
    })
  });

  return response;
};

Otentikasi 3D Secure

Implementasikan kepatuhan SCA:

const createPaymentWith3DS = async (paymentData) => {
  const payment = await createPayment({
    ...paymentData,
    confirmation_token: true // Mengembalikan client secret untuk 3DS
  });

  if (payment.status === 'requires_action') {
    // Klien harus menyelesaikan tantangan 3DS
    return {
      requiresAction: true,
      clientSecret: payment.client_secret,
      nextAction: payment.next_action
    };
  }

  return { success: true, payment };
};

// Sisi klien: Tangani tantangan 3DS
// Gunakan iPay.js atau SDK seluler untuk menampilkan tantangan otentikasi

Manajemen Pengembalian Dana

Memproses Pengembalian Dana Penuh

Mengembalikan seluruh pembayaran:

const refundPayment = async (paymentId, reason = null) => {
  const refund = {
    payment: paymentId,
    reason: reason || 'requested_by_customer'
  };

  const response = await ipayRequest('/refunds', {
    method: 'POST',
    body: JSON.stringify(refund),
    idempotencyKey: `refund_${paymentId}_${Date.now()}`
  });

  return response;
};

// Penggunaan
const refund = await refundPayment('pay_12345', 'duplicate');
console.log(`Status pengembalian dana: ${refund.status}`);
console.log(`ID Pengembalian Dana: ${refund.id}`);

Memproses Pengembalian Dana Sebagian

Mengembalikan sebagian pembayaran:

const partialRefund = async (paymentId, amount, reason = null) => {
  const refund = {
    payment: paymentId,
    amount: amount, // Dalam satuan mata uang terkecil
    reason: reason || 'requested_by_customer'
  };

  const response = await ipayRequest('/refunds', {
    method: 'POST',
    body: JSON.stringify(refund),
    idempotencyKey: `refund_${paymentId}_${amount}_${Date.now()}`
  });

  return response;
};

// Penggunaan - Mengembalikan $15.00 dari pembayaran $29.99
const refund = await partialRefund('pay_12345', 1500, 'partial_ship');
console.log(`Dikembalikan: $${refund.amount / 100}`);

Alasan Pengembalian Dana

Manajemen Pelanggan

Membuat Pelanggan

Simpan pelanggan untuk pembayaran berulang:

const createCustomer = async (customerData) => {
  const customer = {
    email: customerData.email,
    name: customerData.name,
    phone: customerData.phone,
    metadata: {
      internalId: customerData.internalId,
      tier: customerData.tier
    }
  };

  const response = await ipayRequest('/customers', {
    method: 'POST',
    body: JSON.stringify(customer)
  });

  return response;
};

// Penggunaan
const customer = await createCustomer({
  email: 'customer@example.com',
  name: 'John Doe',
  phone: '+1-555-0123',
  internalId: 'USR-12345',
  tier: 'premium'
});

console.log(`Pelanggan dibuat: ${customer.id}`);

Melampirkan Metode Pembayaran ke Pelanggan

Simpan kartu untuk penggunaan di masa mendatang:

const attachPaymentMethod = async (paymentMethodId, customerId) => {
  const response = await ipayRequest(`/payment_methods/${paymentMethodId}/attach`, {
    method: 'POST',
    body: JSON.stringify({
      customer: customerId
    })
  });

  return response;
};

// Penggunaan
await attachPaymentMethod('pm_67890', 'cus_12345');

Mencantumkan Metode Pembayaran Pelanggan

Dapatkan kartu yang tersimpan:

const getCustomerPaymentMethods = async (customerId) => {
  const response = await ipayRequest(`/customers/${customerId}/payment_methods`);
  return response;
};

// Penggunaan
const methods = await getCustomerPaymentMethods('cus_12345');
methods.data.forEach(method => {
  console.log(`${method.card.brand} berakhir di ${method.card.last4}`);
  console.log(`Kedaluwarsa: ${method.card.exp_month}/${method.card.exp_year}`);
});

Webhook

Mengonfigurasi Webhook

Siapkan endpoint webhook:

1. Masuk ke Dasbor iPay
2. Navigasi ke Pengembang > Webhooks
3. Klik Tambahkan Endpoint
4. Masukkan URL HTTPS Anda
5. Pilih acara yang akan disubscribe

Kejadian Webhook

Menangani Webhook

const express = require('express');
const crypto = require('crypto');
const app = express();

app.post('/webhooks/ipay', express.raw({ type: 'application/json' }), async (req, res) => {
  const signature = req.headers['ipay-signature'];
  const payload = req.body;

  // Verifikasi tanda tangan webhook
  const isValid = verifyWebhookSignature(payload, signature, process.env.IPAY_WEBHOOK_SECRET);

  if (!isValid) {
    console.error('Tanda tangan webhook tidak valid');
    return res.status(401).send('Tidak Sah');
  }

  const event = JSON.parse(payload.toString());

  // Arahkan ke penangan yang sesuai
  switch (event.type) {
    case 'payment.succeeded':
      await handlePaymentSucceeded(event.data);
      break;
    case 'payment.failed':
      await handlePaymentFailed(event.data);
      break;
    case 'payment.refunded':
      await handlePaymentRefunded(event.data);
      break;
    case 'payment.disputed':
      await handlePaymentDisputed(event.data);
      break;
    default:
      console.log('Jenis acara tidak tertangani:', event.type);
  }

  // Akui penerimaan
  res.status(200).send('OK');
});

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

async function handlePaymentSucceeded(data) {
  console.log(`Pembayaran berhasil: ${data.id}`);

  // Perbarui status pesanan
  await db.orders.update(data.metadata.orderId, {
    status: 'paid',
    paymentId: data.id,
    paidAt: new Date()
  });

  // Kirim email konfirmasi
  await sendOrderConfirmation(data.metadata.orderId);
}

async function handlePaymentFailed(data) {
  console.log(`Pembayaran gagal: ${data.id} - ${data.failure_code}`);

  // Beri tahu pelanggan
  await sendPaymentFailedEmail(data.customer, data.failure_message);

  // Logika coba lagi atau tandai pesanan sebagai gagal
  await db.orders.update(data.metadata.orderId, {
    status: 'payment_failed',
    failureReason: data.failure_message
  });
}

Keamanan dan Kepatuhan

Persyaratan PCI DSS

Integrasi pembayaran harus mematuhi PCI DSS:

Praktik Terbaik Keamanan

// 1. Gunakan tokenisasi - JANGAN PERNAH menangani data kartu mentah
const token = await tokenizeCard(cardData); // Sisi klien

// 2. Terapkan idempotensi untuk semua operasi pembayaran
const idempotencyKey = `pay_${orderId}_${Date.now()}`;

// 3. Validasi jumlah di sisi server
if (req.body.amount !== calculatedAmount) {
  throw new Error('Ketidaksesuaian jumlah - kemungkinan perusakan');
}

// 4. Catat semua operasi pembayaran (tanpa data sensitif)
logger.info('Upaya pembayaran', {
  orderId,
  amount,
  currency,
  customerId,
  timestamp: new Date().toISOString()
  // JANGAN PERNAH mencatat: nomor kartu, CVV, detail metode pembayaran lengkap
});

// 5. Gunakan variabel lingkungan untuk rahasia
const apiKey = process.env.IPAY_API_KEY; // Tidak dikodekan secara langsung

// 6. Terapkan pembatasan laju pada endpoint pembayaran
const paymentLimiter = rateLimit({
  windowMs: 60000,
  max: 10 // 10 upaya pembayaran per menit
});

Daftar Periksa Penerapan Produksi

Sebelum memproses pembayaran langsung:

• [ ] Lengkapi Kuesioner Penilaian Mandiri PCI DSS
• [ ] Gunakan HTTPS untuk semua endpoint
• [ ] Simpan kunci API dalam manajemen rahasia yang aman
• [ ] Terapkan verifikasi tanda tangan webhook
• [ ] Tambahkan idempotensi untuk semua operasi pembayaran
• [ ] Siapkan pencatatan yang komprehensif (tanpa data sensitif)
• [ ] Konfigurasi aturan deteksi penipuan
• [ ] Uji alur pengembalian dana dan sengketa
• [ ] Buat runbook untuk kegagalan pembayaran
• [ ] Siapkan pemantauan dan peringatan
• [ ] Terapkan pemroses pembayaran cadangan

Kasus Penggunaan Dunia Nyata

Checkout E-commerce

Pengecer online mengintegrasikan pembayaran:

• Tantangan: Pemrosesan pembayaran manual, tingkat pengabaian tinggi
• Solusi: Checkout satu halaman dengan kartu tokenisasi
• Hasil: Peningkatan konversi 35%, pembayaran instan

Penagihan Langganan SaaS

Perusahaan perangkat lunak mengotomatiskan penagihan:

• Tantangan: Pembuatan dan pengumpulan faktur manual
• Solusi: Pembayaran berulang dengan coba lagi otomatis
• Hasil: Pembayaran tepat waktu 95%, penghematan waktu admin 80%

Escrow Marketplace

Platform menangani pembayaran multipihak:

• Tantangan: Pembayaran terpisah yang kompleks antar vendor
• Solusi: Niat pembayaran dengan penjadwalan transfer
• Hasil: Pembayaran vendor otomatis, pengurangan penipuan

Kesimpulan

Integrasi API pembayaran memerlukan perhatian cermat terhadap keamanan, kepatuhan, dan penanganan kesalahan. Poin-poin penting:

• Jangan pernah menangani data kartu mentah—gunakan tokenisasi
• Terapkan idempotensi untuk semua operasi pembayaran
• Verifikasi tanda tangan webhook untuk mencegah penipuan
• Patuhi persyaratan PCI DSS
• Uji secara menyeluruh dalam kotak pasir (sandbox) sebelum produksi
• Apidog menyederhanakan pengujian API dan kolaborasi tim

Bagian FAQ

Bagaimana cara melakukan otentikasi dengan API iPay?

Gunakan otentikasi Dasar dengan kunci API dan rahasia, atau OAuth 2.0 untuk aplikasi multi-penyewa.

Bisakah saya menyimpan detail kartu pelanggan?

Ya, tetapi Anda harus patuh terhadap PCI DSS. Gunakan tokenisasi untuk menyimpan kartu dengan aman di vault iPay.

Bagaimana cara menangani pembayaran yang gagal?

Terapkan logika coba lagi dengan backoff eksponensial, beri tahu pelanggan, dan sediakan metode pembayaran alternatif.

Apa itu idempotensi dan mengapa penting?

Idempotensi memastikan permintaan duplikat dengan kunci yang sama menghasilkan hasil yang sama, mencegah biaya duplikat.

Bagaimana cara menguji pembayaran tanpa mengenakan biaya pada kartu?

Gunakan mode kotak pasir (sandbox) dengan nomor kartu uji yang disediakan dalam dokumentasi iPay.

Apa itu tanda tangan webhook?

Tanda tangan kriptografi yang memverifikasi webhook berasal dari iPay, bukan dari aktor jahat.