api

Dokumentasi API

Panduan lengkap integrasi Sekalipay Payment Gateway ke dalam aplikasi bisnis Anda. Aman, cepat, dan mudah diimplementasikan.

Mulai Cepat Referensi Endpoint

Getting Started

Pengantar Otentikasi Base URL

Endpoints

Merchant Info Buat Pembayaran Cek Status Metode Pembayaran Request Penarikan

Pengantar

API Sekalipay memungkinkan Anda untuk menerima pembayaran secara otomatis dan real-time. API kami dirancang dengan prinsip RESTful, menggunakan respons JSON standar, dan kode status HTTP konvensional.

Catatan: Semua request ke API harus menggunakan protokol HTTPS. Request HTTP biasa akan ditolak untuk keamanan data transaksi Anda.

Otentikasi & Keamanan

Keamanan adalah prioritas utama kami. Sekalipay mendukung dua mode autentikasi: IP Whitelist (default, untuk server statis) dan Enhanced HMAC (untuk serverless seperti Cloudflare Workers, AWS Lambda).

key API Key

Digunakan untuk identifikasi merchant.

lock Secret Key

Digunakan untuk membuat signature request. Jangan pernah membagikan key ini!

Membuat Signature

Setiap request memerlukan header X-API-Key. Yang ditandatangani di header X-Signature berbeda per mode:

IP Whitelist

Hanya request POST (pembayaran & penarikan). HMAC-SHA256 atas body JSON mentah — string yang ditandatangani harus sama persis dengan yang dikirim.

HMAC_SHA256(body_json, secret_key)

Enhanced HMAC

Semua request, ditambah header X-Timestamp (Unix detik, berlaku 5 menit). Bukan body JSON: PARAMS adalah seluruh parameter yang diurutkan per key lalu di-encode seperti http_build_query() PHP. Path tanpa garis miring di depan.

HMAC_SHA256(METHOD|PATH|PARAMS|TIMESTAMP, secret_key)

Contoh lengkap Enhanced HMAC — termasuk JavaScript untuk Cloudflare Workers — tersedia di dokumentasi dasbor merchant. Contoh di bawah untuk mode IP Whitelist.

PHP Example

        // Payload body (JSON string)
        $body = json_encode([
            'merchant_ref_id' => 'TRX-123456',
            'amount' => 100000,
            'return_url' => 'https://merchant.test/checkout/success',
            // ... other fields
        ]);

        // Your Secret Key from Dashboard
        $secretKey = 'sk_...';

        // Generate Signature (IP Whitelist mode: HMAC of the raw JSON body)
        $signature = hash_hmac('sha256', $body, $secretKey);

        // Send Request — kirim $body itu sendiri, jangan di-encode ulang
        $response = Http::withHeaders([
            'X-API-Key' => 'mk_...',
            'X-Signature' => $signature,
        ])->withBody($body, 'application/json')
          ->post('https://alfaprem.com/api/v1/gateway/payment');

Base URL

https://alfaprem.com/api/v1/gateway

GET

/merchant/info

Mendapatkan informasi akun merchant Anda, termasuk saldo aktif dan status akun.
Auth: IP Whitelist only (No signature required)

Response Example (200 OK)

{
    "status": 1,
    "rc": 200,
    "message": "Success",
    "data": {
        "merchant_code": "MCH-A1B2C3",
        "nama_toko": "Toko Online Saya",
        "saldo_tersedia": 1500000,
        "saldo_tertahan": 250000,
        "total_revenue": 15000000,
        "status": "active",
        "is_sandbox": false
    },
    "ts": 1703395200
}

POST

/payment

Membuat transaksi pembayaran baru. Rate limit: 10 request/menit.
Requires Signature

Catatan integrasi: callback_url dipakai untuk webhook backend, sedangkan return_url dipakai untuk mengarahkan browser customer kembali ke website Anda setelah pembayaran sukses.

Request Body

Field	Type	Required	Description
merchant_ref_id	string	Yes	ID unik referensi dari sistem Anda (Max 50 char)
amount	integer	Yes	Nominal pembayaran (Min sesuai metode pembayaran)
payment_code	string	Yes	Kode metode pembayaran (e.g., 'QRIS', 'VA_BCA')
customer_name	string	Yes	Nama pelanggan
customer_email	string	Yes	Email pelanggan untuk notifikasi
customer_phone	string	Yes	Nomor HP pelanggan
callback_url	string	No	Override webhook callback URL untuk transaksi ini
return_url	string	No	Override URL redirect browser customer setelah pembayaran sukses
metadata	object	No	Metadata tambahan untuk kebutuhan internal merchant

Flow redirect: Jika return_url dikirim pada request, hosted payment page akan memakainya. Jika tidak, sistem memakai Return URL default di dashboard merchant. Jika keduanya kosong, customer tetap di halaman invoice/hosted page internal Sekalipay.

Response Example (201 Created)

{
    "status": true,
    "message": "OK",
    "data": {
        "merchant_ref_id": "TRX-123456",
        "invoice": "INV/20231224/KWL/12345",
        "amount": 100000,
        "fee": 700,
        "total": 100700,
        "payment_code": "QRIS",
        "payment_link": "https://alfaprem.com/payment/INV/20231224/KWL/12345",
        "qr_link": "https://qr.sekalipay.com/example.png",
        "virtual_account": null,
        "checkout_url": null,
        "payment_guide": null,
        "expired_at": "2023-12-24T15:30:00.000000Z",
        "status": "pending",
        "is_sandbox": false
    }
}

GET

/payment/{merchant_ref_id}

Mengecek status pembayaran berdasarkan merchant_ref_id Anda. Rate limit: 30 request/menit.

Response Example (200 OK)

{
    "status": true,
    "message": "OK",
    "data": {
        "merchant_ref_id": "TRX-123456",
        "invoice": "INV/20231224/KWL/12345",
        "status": "paid",
        "amount": 100000,
        "fee": 700,
        "total": 100700,
        "payment_code": "QRIS",
        "payment_link": "https://alfaprem.com/payment/INV/20231224/KWL/12345",
        "qr_link": "https://qr.sekalipay.com/example.png",
        "virtual_account": null,
        "checkout_url": null,
        "payment_guide": null,
        "expired_at": "2023-12-24T15:30:00.000000Z",
        "created_at": "2023-12-24T15:00:00.000000Z",
        "paid_at": "2023-12-24T15:05:12.000000Z"
    }
}

GET

/payment-methods

Mendapatkan daftar metode pembayaran yang aktif beserta informasi biaya dan limit.

Response Example (200 OK)

{
    "status": true,
    "message": "OK",
    "data": [
        {
            "payment_code": "QRIS",
            "payment_name": "QRIS",
            "payment_type": "qris",
            "image": "https://alfaprem.com/images/payments/qris.png",
            "min_amount": 1000,
            "max_amount": 5000000,
            "settlement_time": "H+0",
            "fee_info": {
                "type": "percent",
                "description": "0.7%"
            }
        },
        {
            "payment_code": "BCAVA",
            "payment_name": "BCA Virtual Account",
            "payment_type": "va",
            "image": "https://alfaprem.com/images/payments/bca.png",
            "min_amount": 10000,
            "max_amount": 50000000,
            "settlement_time": "H+0",
            "fee_info": {
                "type": "flat",
                "description": "Rp 4.000"
            }
        }
    ]
}

POST

/withdrawal

Mengajukan penarikan dana ke rekening bank terdaftar. Rate limit: 5 request/menit.
Requires Signature

Syarat: Rekening bank harus sudah diverifikasi di dashboard. Min penarikan Rp 10.000. Biaya admin Rp 3.000.

Request Body

{
    "amount": 50000
}

Response Example (200 OK)

{
    "status": true,
    "message": "Withdrawal request submitted successfully",
    "data": {
        "settlement_id": 123,
        "settlement_number": "WD20260424001",
        "net_amount": 50000,
        "withdrawal_fee": 3000,
        "gross_amount": 53000,
        "total_deducted": 53000,
        "status": "pending",
        "requested_at": "2024-12-18 10:30:00",
        "estimated_processed_at": "2024-12-19 10:30:00",
        "bank_account": {
            "bank_name": "BCA",
            "account_number": "1234****7890",
            "account_holder": "John Doe",
            "verified_at": "2024-12-15 14:20:00"
        },
        "balance": {
            "available": 447000,
            "pending": 53000
        },
        "info": "You will receive Rp 50.000 (withdrawal fee Rp 3.000 has been deducted)"
    }
}