Dokumentasi Integrasi API

Pelajari cara menghubungkan aplikasi Anda dengan PaymentHub. Endpoint berikut digunakan oleh Anda (Merchant) yang telah terdaftar.

Cara Kerja Berbelanja & Integrasi

  • 1
    User checkout dan menekan tombol Bayar di website e-commerce/aplikasi Anda.
  • 2
    Website Anda (Backend) memanggil API /api/create.php PaymentHub.
  • 3
    PaymentHub meneruskan request ke iPaymu pusat, lalu mengembalikan payment_url ke Backend Anda.
  • 4
    Anda me-redirect screen user ke payment_url (Halaman Checkout iPaymu).
  • 5
    User membayar, iPaymu webhook memberitahu PaymentHub bahwa tagihan lunas.
  • 6
    PaymentHub merubah status di dashboard, lalu (jika diset) PaymentHub memanggil Webhook URL milik sistem Anda untuk notifikasi lanjutan.
POST /api/create.php

Membuat Transaksi

Gunakan endpoint ini di backend Anda saat pelanggan menekan tombol pembayaran.

Endpoint URL:

POST http://ujicoba.sakuracloudid.com/php-payment-hub/api/create.php

Request Headers:

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY_DARI_DASHBOARD

Request Body (JSON):

{
    "external_id": "INV-20231018-001", // Wajib: ID Invoice di sistem Anda
    "amount": 50000,                  // Wajib: Angka nominal (tanpa titik/koma)
    "buyer_name": "John Doe",         // Wajib: Nama Pelanggan
    "buyer_email": "john@email.com",  // Wajib: Email Pelanggan
    "buyer_phone": "08123456789",     // Wajib: Telepon Pelanggan
    "return_url": "https://yourwebsite.com/payment/success", // Kembali jika sukses
    "cancel_url": "https://yourwebsite.com/payment/failed",  // Kembali jika batal (opsional)
    "notify_url": "https://yourwebsite.com/api/webhook"      // Webhook Anda (Opsional)
}

Response (Success):

{
    "success": true,
    "message": "Payment session created",
    "data": {
        "hub_transaction_id": "aa1234-bb56-uuid-hub",
        "external_id": "INV-20231018-001",
        "payment_url": "https://my.ipaymu.com/payment/xyz123"
    }
}

Langkah selanjutnya: Tangkap data.payment_url dari response di atas, lalu redirect browser pengunjung ke URL tersebut untuk memilih metode bayar di sisi iPaymu.

GET /api/status.php

Cek Status Manual (Opsional)

Jika Anda tidak punya sistem Webhook, Anda bisa melakukan pengecekkan manual via ID internal yang Anda kirim (external_id).

Endpoint URL:

GET http://ujicoba.sakuracloudid.com/php-payment-hub/api/status.php?external_id=INV-20231018-001

Request Headers:

Authorization: Bearer YOUR_API_KEY_DARI_DASHBOARD

Response Body:

{
    "success": true,
    "data": {
        "hub_transaction_id": "aa1234-bb56-uuid-hub",
        "external_id": "INV-20231018-001",
        "status": "success",     // bisa pending, success, failed, expired
        "payment_method": "va",
        "payment_channel": "bca",
        "total_amount": 50000,
        "created_at": "2023-10-18 10:25:00",
        "updated_at": "2023-10-18 10:30:00"
    }
}

Format Webhook dari Hub ke Klien

Jika Anda menyertakan notify_url pada saat Create transaksi, PaymentHub akan mengirim HTTP POST JSON ke URL webhook Anda setiap ada perubahan pembayaran (biasanya saat lunas / expired).

POST https://yourwebsite.com/api/webhook
Content-Type: application/json

{
    "external_id": "INV-20231018-001",
    "hub_transaction_id": "aa1234-bb56-uuid-hub",
    "status": "success",
    "paid_amount": "50000",
    "payment_method": "va",
    "payment_channel": "bca"
}

Validasi pastikan status === 'success' dan amount sesuai dengan database Anda sebelum memproses pesanan client.