Autentikasi

Gerbang Pay mendukung dua metode autentikasi:

Metode	Digunakan Oleh	Endpoint
API Key	Aplikasi klien (payment flow)	/v1/payments/*, /v1/active-methods
JWT RS256	Dashboard / user login	Semua endpoint manajemen

---

API Key

API Key digunakan oleh aplikasi klien Anda untuk membuat dan mengambil data payment.

Cara Generate API Key

1. Login ke Dashboard Gerbang Pay
2. Masuk ke menu Settings → API Keys
3. Klik Generate New API Key
4. Pilih mode: Live atau Test
5. Simpan key yang muncul — key hanya ditampilkan sekali

Format Header

Authorization: ApiKey {api_key}

⚠️ Penting: Format autentikasi untuk API Key menggunakan prefix ApiKey, bukan Bearer. Menggunakan Bearer dengan API Key akan menghasilkan error 401 Invalid JWT token.

Live Key vs Test Key

Tipe Key	Format	Environment Provider
Live Key	gp_live_...	Production (transaksi nyata)
Test Key	gp_test_...	Sandbox (transaksi simulasi)

Sistem secara otomatis menentukan apakah payment dikirim ke environment Production atau Sandbox berdasarkan tipe key yang digunakan. Anda tidak perlu mengubah kode atau URL endpoint.

Contoh Request dengan API Key

curl -X POST https://gerbang-pay-api.gai.co.id/v1/payments/create \
  -H "Authorization: ApiKey gp_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: order-12345" \
  -d '{
    "amount": 10000000,
    "currency": "IDR",
    "method_type": "virtual_account",
    "method_detail": { "type": "virtual_account", "bank": "BCA" }
  }'

---

JWT (RS256) — Untuk Dashboard

JWT digunakan untuk operasi manajemen: mengelola tenant, API key, konfigurasi provider, melihat laporan, dll.

Token JWT menggunakan algoritma RS256 dan memiliki klaim sub (tenant ID), role, dan tier.

Login

POST /v1/auth/login

Request Body:

{
  "email": "[email protected]",
  "password": "password_anda"
}

Response:

{
  "success": true,
  "data": {
    "access_token": "eyJhbGciOiJSUzI1NiJ9...",
    "refresh_token": "rt_xxxxxxxxxxxxxxxx",
    "token_type": "Bearer",
    "expires_in": 3600
  }
}

Refresh Token

POST /v1/auth/refresh

Request Body:

{
  "refresh_token": "rt_xxxxxxxxxxxxxxxx"
}

Logout

POST /v1/auth/logout

Request Body:

{
  "refresh_token": "rt_xxxxxxxxxxxxxxxx"
}

Cara Pakai JWT

Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

Reset Password

Jika lupa password:

POST /v1/auth/password-reset/request

{
  "tenant_id": "uuid-tenant-anda",
  "email": "[email protected]"
}

Lalu konfirmasi reset dengan token yang diterima:

POST /v1/auth/password-reset/confirm

{
  "token": "reset_token_dari_email",
  "new_password": "password_baru_min_8_karakter"
}

---

Endpoint vs Metode Autentikasi

Endpoint	API Key	JWT
POST /v1/payments/create	✅ (wajib Client role)	❌
GET /v1/payments/{id}	✅	✅
POST /v1/payments/{id}/cancel	✅	✅
GET /v1/active-methods	✅	✅
GET /v1/payments/{id}/ledger	✅	✅
POST /v1/auth/login	❌ (public)	❌ (public)
POST /v1/auth/refresh	❌ (public)	❌ (public)
GET /v1/tenants/*	❌	✅ (Owner/Partner)
POST /v1/tenants/*/api-keys	❌	✅

💡 Catatan: Hanya tenant dengan role Client yang dapat membuat payment. Tenant dengan role Owner atau Partner tidak bisa memanggil POST /v1/payments/create.

---

Keamanan API Key

• API Key disimpan dalam bentuk hash (HMAC-SHA256) di database — nilai aslinya tidak dapat dipulihkan
• Jika key bocor, segera nonaktifkan dari dashboard dan generate key baru
• Jangan letakkan API Key di frontend/browser yang bisa diinspeksi user
• Gunakan environment variable untuk menyimpan API Key di server Anda