Autentikasi API Key

Semua endpoint Merchant API menggunakan autentikasi berbasis API Key melalui header X-API-Key.

Generate API Key dari CMS

1. Login ke CMS dengan akun merchant.
2. Buka menu API Keys.
3. Klik tombol Generate New API Key.
4. Salin dan simpan API Key yang ditampilkan — nilai ini hanya ditampilkan sekali.
5. API Key yang aktif dapat dinonaktifkan atau dihapus kapan saja dari halaman yang sama.

Keamanan: Jangan simpan API Key di repositori kode, file .env yang di-commit, atau tempat yang dapat diakses publik. Jika API Key bocor, segera nonaktifkan dan generate ulang melalui CMS.

Format API Key

apk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Header Wajib

Setiap request ke Merchant API harus menyertakan header berikut:

Header Opsional (jika Signature Validation aktif)

Lihat Signature Validation untuk detail lebih lanjut.

Contoh Request

POST /api/v1/merchant/ppob/phone-credit/transaction HTTP/1.1
Host: api-sandbox.alfakios.com
Content-Type: application/json
X-API-Key: apk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

{
  "req_id": "TXN-20240501-001",
  "product_id": "XL5",
  "cust_id": "08123456789"
}

Response Error Autentikasi

API Key tidak ada atau tidak valid

{
  "success": false,
  "message": "Unauthorized",
  "error": "Invalid or missing API Key"
}

HTTP Status: 401 Unauthorized

API Key tidak memiliki akses endpoint ini

{
  "success": false,
  "message": "Forbidden",
  "error": "API Key does not have permission to access this resource"
}

HTTP Status: 403 Forbidden

Akun merchant tidak aktif

{
  "success": false,
  "message": "Forbidden",
  "error": "Merchant account is inactive"
}

HTTP Status: 403 Forbidden

Validasi Tambahan

Selain API Key, sistem juga menerapkan:

• IP Restriction — jika merchant telah mendaftarkan IP whitelist, hanya request dari IP tersebut yang diterima.
• Rate Limiting — request dibatasi per merchant untuk mencegah abuse.
• Timeout — setiap request memiliki batas waktu pemrosesan 8 detik. Jika biller tidak merespons dalam 8 detik, sistem akan mengembalikan error.