Authentication

Hashpay memakai dua mekanisme: API key untuk endpoint transaksi (server-to-server) dan JWT untuk endpoint dashboard merchant. Setiap panggilan transaksi wajib menyertakan API key yang valid.

API key merchant

Dapatkan API key di dashboard: Settings → API Key. Key berbentuk hp_ + 64 karakter hex dan dapat dirotasi kapan saja (key lama langsung tidak berlaku).

Header

api-key: hp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

Kunci akses scoped (webview & payment link)

Halaman pembayaran (webview) dibuka di browser pelanggan, sehingga kami tidak pernah mengirim API key merchant ke sana. Setiap order yang Anda buat lewat API mengembalikan kredensial sementara di field key (tertanam otomatis di url), dan endpoint publik POST /order/payment-link mengembalikan api_key dengan sifat yang sama:

hanya berlaku 30 menit,
hanya untuk order tersebut,
disimpan dalam bentuk hash dan tidak dapat dipakai untuk settlement atau membuat order baru.

JWT untuk dashboard

Endpoint manajemen (profil, channel, CRUD payment link) memakai JWT dari login merchant.

POST/api/v2/auth/login

bash

curl -X POST https://api.hashpay.id/api/v2/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"merchant@example.com","password":"••••••••","user_type":"merchant"}'

# Respons berisi token (access) dan refresh_token
# Gunakan: Authorization: Bearer <token>

Access token berlaku singkat; tukar refresh token di POST /api/v2/auth/refresh untuk token baru. Logout mencabut token di sisi server (allowlist), jadi token yang sudah logout tidak bisa dipakai lagi.

Verifikasi webhook (HMAC-SHA256)

Setiap callback pembayaran ditandatangani memakai API key merchant Anda sebagai kunci HMAC atas raw body:

Header	Isi
`X-Hashpay-Signature`	`sha256=<hex HMAC-SHA256(body, api_key)>`
`X-Hashpay-Event`	mis. `transaction.success`
`X-Hashpay-Idempotency-Key`	hash transaksi on-chain (unik per pembayaran)

Go — verifikasi

func verifyHashpaySignature(rawBody []byte, signatureHeader, apiKey string) bool {
    mac := hmac.New(sha256.New, []byte(apiKey))
    mac.Write(rawBody)
    expected := "sha256=" + hex.EncodeToString(mac.Sum(nil))
    return hmac.Equal([]byte(expected), []byte(signatureHeader))
}

Rate limit

Endpoint publik dibatasi per IP; endpoint transaksi dibatasi per merchant. Jika melewati batas, API membalas 429 dengan pesan yang jelas. Terapkan retry dengan backoff eksponensial.