Skip to content

Authentication ​

Gerbang Pay supports two authentication methods:

MethodUsed ByEndpoints
API KeyClient applications (payment flow)/v1/payments/*, /v1/active-methods
JWT RS256Dashboard / user loginAll management endpoints

API Key ​

API Keys are used by your client applications to create and retrieve payment data.

How to Generate an API Key ​

  1. Log in to the Gerbang Pay Dashboard
  2. Go to the Settings → API Keys menu
  3. Click Generate New API Key
  4. Choose the mode: Live or Test
  5. Save the key that appears — the key is only displayed once

Header Format ​

http
Authorization: ApiKey {api_key}

⚠️ Important: The authentication format for API Keys uses the prefix ApiKey, not Bearer. Using Bearer with an API Key will result in a 401 Invalid JWT token error.

Live Key vs Test Key ​

Key TypeFormatProvider Environment
Live Keygp_live_...Production (real transactions)
Test Keygp_test_...Sandbox (simulated transactions)

The system automatically determines whether a payment is routed to the Production or Sandbox environment based on the key type used. You do not need to change your code or endpoint URLs.

Example Request with API Key ​

bash
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) — For Dashboard ​

JWT is used for management operations: managing tenants, API keys, provider configurations, viewing reports, etc.

The JWT token uses the RS256 algorithm and contains the claims sub (tenant ID), role, and tier.

Login ​

http
POST /v1/auth/login

Request Body:

json
{
  "email": "[email protected]",
  "password": "your_password"
}

Response:

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

Refresh Token ​

http
POST /v1/auth/refresh

Request Body:

json
{
  "refresh_token": "rt_xxxxxxxxxxxxxxxx"
}

Logout ​

http
POST /v1/auth/logout

Request Body:

json
{
  "refresh_token": "rt_xxxxxxxxxxxxxxxx"
}

Using JWT ​

http
Authorization: Bearer eyJhbGciOiJSUzI1NiJ9...

Reset Password ​

If you forget your password:

http
POST /v1/auth/password-reset/request
json
{
  "tenant_id": "your-tenant-uuid",
  "email": "[email protected]"
}

Then confirm the reset with the received token:

http
POST /v1/auth/password-reset/confirm
json
{
  "token": "reset_token_from_email",
  "new_password": "new_password_min_8_chars"
}

Endpoints vs Authentication Methods ​

EndpointAPI KeyJWT
POST /v1/payments/create✅ (requires 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❌✅

💡 Note: Only tenants with the Client role can create payments. Tenants with Owner or Partner roles cannot call POST /v1/payments/create.


API Key Security ​

  • API Keys are stored as hashes (HMAC-SHA256) in the database — their original values cannot be recovered.
  • If a key is leaked, immediately revoke it from the dashboard and generate a new key.
  • Never place API Keys in a frontend/browser environment where users can inspect them.
  • Use environment variables to store API Keys on your server.

Gerbang Pay API Documentation