HamerzPay Core API

Send both credentials as headers on every request.

X-API-KEY:    hp_live_xxxxxxxxxxxxxxxxxxxxxxxx
X-API-SECRET: <48-character secret>

You receive the pair once, when the merchant is provisioned (or when the merchant rotates it from their panel). The secret is stored hashed on our side and cannot be shown again — store it at issue time.

Sign the exact raw request body with your secret.

X-API-KEY:    <your api key>
X-TIMESTAMP:  <unix seconds>
X-SIGNATURE:  hmac_sha256( "<X-TIMESTAMP>" + "." + <raw body>, <secret> )

Sign the bytes you actually send. Serialize the JSON once, sign that exact string, and transmit that same string — re-serializing after signing (different key order or spacing) produces a signature we will reject. For a GET, the body is the empty string.

ts=$(date +%s)
body='{"account_id":42,"amount":5000000,"reference_id":"INV-1","idempotency_key":"a1b2c3"}'
sig=$(printf '%s.%s' "$ts" "$body" | openssl dgst -sha256 -hmac "$SECRET" -r | cut -d' ' -f1)

curl -X POST https://hmzptest.ir/api/v1/corporate/credit/reserve \
  -H "X-API-KEY: $API_KEY" \
  -H "X-TIMESTAMP: $ts" \
  -H "X-SIGNATURE: $sig" \
  -H "Idempotency-Key: a1b2c3" \
  -H "Content-Type: application/json" \
  -d "$body"

Requests older than 300 seconds are rejected as expired_timestamp. During a secret rotation both the current and the previous secret are accepted, so you can roll over without downtime.

Every mutating corporate route additionally requires an Idempotency-Key header, and it must match the idempotency_key field in the body when the body carries one.

Browser-facing panel APIs — not for server-to-server use.

These authenticate with the panel session cookie established by an OTP login (password login for admin) and are CSRF-protected. They are meant for the panel front-ends. If you are integrating a system, use the POS, bank-partner or corporate API instead.

Inbound provider callbacks are signed the same way, with their own headers.

X-Provider-Event-Id:   <unique per event; used for deduplication>
X-Provider-Timestamp:  <unix seconds>
X-Provider-Signature:  hmac_sha256( "<timestamp>.<raw body>", <webhook secret> )

Replaying the same event id with an identical payload is safe and returns the original outcome. Replaying it with a different payload is rejected as an idempotency conflict. Bodies are capped at 64KB.

Start a POS credit purchase (sends an SMS confirmation code to the customer)

Machine-to-machine endpoint for a merchant's POS integration. Auth: X-API-KEY + X-API-SECRET headers, matched against the merchant's own merchant_api_keys credential (see the merchant panel's "Rotate API Key" action, or the api_credential returned by the bank-partner upsert call). Only the customer's personal bank credit account is ever considered (organization-scoped credit is a separate product and is never spent through POS). No credit is reserved at this step — it only validates eligibility and sends a one-time SMS code to the customer's own phone; the actual reservation happens atomically in /orders/confirm.

Confirm a POS purchase with the customer's SMS code (reserves and captures credit atomically)

Same auth as /orders/initiate.

Create an online-store checkout session for credit payment

Same merchant auth as the POS endpoints. Returns a checkout_url that the merchant's online store redirects the customer's browser to. The customer confirms their own mobile number and an SMS code on that hosted page before any credit is touched; this endpoint alone never reserves credit. Idempotent per idempotency_key.

Poll an online checkout session's status

Same merchant auth as session creation.

Register or sync a merchant from the external bank partner ("Hamerz Bank")

Machine-to-machine endpoint. Auth: X-API-KEY header (issued via php artisan bank-partner:credentials:issue) plus HMAC request signing — X-TIMESTAMP (unix seconds) and X-SIGNATURE = HMAC-SHA256(secret, "{X-TIMESTAMP}.{raw JSON body}"), tolerance window 300s by default. A replay-safe v2 scheme is also accepted (X-SIGNATURE-VERSION: 2 + X-NONCE, signing "METHOD\nPATH\nTIMESTAMP\nNONCE\nsha256(body)") — see docs/api/README.md §2-3. external_ref is the bank's own identifier for the business and is the real dedup key — the same owner_mobile may be reused across multiple external_refs for a person who owns several businesses; each becomes a separate merchant. A new merchant is created with status: pending and cannot transact until a HamerzPay admin activates it and sets its fee rate / credit sales cap. Repeat calls with an existing external_ref only update descriptive fields and never touch status, fee_rate, or credit_sales_cap.

Look up a bank-provisioned merchant's status

Same auth as the upsert endpoint (API key + HMAC signature).

Start a customer-consent request

Step 1 of the consent flow. Returns a consent_url to send the customer to. The customer proves who they are there with their own OTP and explicitly grants the requested scopes; nothing is readable until they do. redirect_uri must already be registered on the credential (exact match) — an unregistered value is refused, so the flow cannot be pointed at an attacker-controlled target.

Exchange the authorization code for tokens

Step 3, after the customer approves and is redirected back to your redirect_uri with ?code=...&state=.... The code is single-use and expires 60 seconds after approval.

Revoke the consent behind the presented access token

Immediately revokes the consent and every token issued under it. Requires the HMAC headers plus Authorization: Bearer <access_token>.

Rotate an access token using its refresh token

Refresh tokens rotate: the presented token is revoked as the new pair is issued, so replaying an old refresh token fails. Refresh tokens live 90 days, access tokens 60 minutes.

Read the consenting customer's credit

Requires the HMAC headers plus Authorization: Bearer <access_token>. There is deliberately no customer selector — not a path parameter, not a query string, not a body field. The customer is identified by the token the customer themselves authorised, so this endpoint cannot be walked over mobile numbers to discover who holds credit or to binary-search an available limit. Returns every credit line the customer holds: the personal bank credit plus any organization-backed credit, each with its own limit, consumption and scope.

Authenticated company's profile and facility summary

Status of the calling API credential (masked key, is_active, created_at)

List the company's active credit plans (read-only)

List/search the company's customers (paginated)

Create or update a customer by external_ref

Requires the Idempotency-Key header.

Get one customer by external_ref

Customer's corporate credit accounts + facility summary

Eligible corporate wallets for a prospective purchase amount

List a customer's uploaded documents

Upload a customer document (multipart file, or base64 JSON payload)

Requires the Idempotency-Key header. Max 10MB; pdf/jpg/jpeg/png/webp only.

Get one customer document's metadata

Request a new credit account for a customer (pending or needs_review)

Requires the Idempotency-Key header.

Activate a credit account immediately (or flag needs_review)

Requires the Idempotency-Key header.

Request a credit-limit change for an existing account

Requires the Idempotency-Key header.

Submit a self-reported settlement

Requires the Idempotency-Key header.

Get one settlement request's status

Dispatch a test webhook event to all of the company's active endpoints

Check corporate-credit eligibility (tenant-scoped by account_id)

Reserve corporate credit for a usage

Requires the Idempotency-Key header; account_id is tenant-scoped.

Capture a reserved corporate-credit usage

Requires the Idempotency-Key header; usage_id is tenant-scoped.

Cancel a reserved (not yet captured) corporate-credit usage

Requires the Idempotency-Key header; usage_id is tenant-scoped.

Record a settlement against a captured corporate-credit usage

Requires the Idempotency-Key header; usage_id is tenant-scoped.

List the company's revolving credit lines (Unified Credit Core) with utilization and collateral coverage

Read-only. Each line carries approved_limit, consumed/reserved/utilized/available amounts, eligible_collateral_value (sum of ACTIVE, unexpired collateral eligible values), collateral_backed_max_credit (= eligible × LTV) and within_collateral.

List the company's collateral records (paginated)

Register a collateral for one of the company's customers (created as PENDING; approval is done by HamerzPay)

Requires the Idempotency-Key header; the same key for the same customer replays the original record (200, replayed=true). credit_line_id is tenant-scoped: another company's line answers 404. eligible_value = nominal_value × (1 − haircut_percentage/100).

List the company's per-purchase receivables (paginated)

Register a (partial or full) payment against a receivable

Requires the Idempotency-Key header, unique per company: the same key replays the original payment (200, replayed=true) without deducting again; the same key with a different amount/receivable is rejected (422 corporate_credit_rule_violation). Over-payment and payments on PAID/WRITTEN_OFF receivables are rejected with 422. The receivable is tenant-scoped: another company's id answers 404. Paid principal frees the revolving line's limit; fees never do.

Hosted online-checkout page (customer-facing, not machine-callable)

Public HTML page (session + CSRF protected, throttled 20/min/IP), not part of the JSON API surface. The customer enters/confirms their mobile number, receives an SMS code, and confirms it here — the page then reserves and captures credit atomically and redirects to the merchant's callback_url (configured in merchant_settings), or shows a success message if none is configured. Returns 404 for an unknown code, 410 for an expired/cancelled session, 409 if the session was already completed.

Submit the customer's mobile number and trigger an SMS code

If the merchant pinned customer_mobile when creating the session, only that number is accepted; any other number is refused with an error flash rather than silently repointing the session.

Confirm the SMS code and complete the purchase (reserve + capture, atomic)

Inbound financial event callback from a payment/settlement/funding/payroll provider

Verified via HMAC-SHA256 over "{X-Provider-Timestamp}.{raw body}" using hamerzpay.finance.providers.{provider}.webhook_secret (with previous_webhook_secret accepted during rotation), not an API key. A 300-second freshness window applies and the raw body is capped at 64KB. Deduplicated by (provider, X-Provider-Event-Id) via the Inbox pattern — replays with the same event id and a different payload are rejected as an idempotency conflict.

Panel health check

Authenticated customer's own credit summary

Check purchase eligibility against the customer's own credit account

Reserve credit for a purchase (step 1 of 2)

Capture (finalize) a reserved order — step 2 of 2

Cancel a reservation before it is captured

Request a bank-credit underwriting decision

Activate a previously approved credit request

List the authenticated customer's own credit orders (paginated)

List the authenticated customer's own installments, with overdue/upcoming breakdown

Submit a repayment for one installment

Requires the Idempotency-Key header (not a body field).

Panel health check

Send a purchase-confirmation SMS code to a corporate customer

Step 1 of corporate-wallet checkout. The code goes to the corporate customer's own mobile; the customer reads it to the cashier in person. Rate limits and lockouts are the shared OTP policy. Requires merchant role owner/manager/branch_manager/cashier (merchant.corporate-checkout.create).

Exchange the customer's SMS code for a short-lived checkout_token

Step 2. The token is bound to (this merchant, this customer), lives 10 minutes, and authorises exactly one checkout (one idempotency_key; retries with the same key are allowed).

Corporate-wallet checkout (check + reserve + capture in one call)

For paying with a customer's *corporate* wallet credit specifically — unrelated to the bank-credit online checkout under /api/v1/pos/checkout. Contract change 2026-10-03: customer_id and checkout_token (from /otp/verify) are now required, and corporate_account_id must belong to that customer. The company must also explicitly allow this merchant (corporate_allowed_merchants); a company with no rows is now denied unless CORPORATE_ALLOW_ALL_MERCHANTS_WHEN_UNRESTRICTED=true.

List a customer's eligible corporate wallets for a prospective purchase

Contract change 2026-10-03: requires a checkout_token for this customer (query param or X-Checkout-Token header) obtained via /otp/verify.

Panel health check

Organization-wide credit/budget summary

Alias of /credit/summary (legacy path kept for backward compatibility)

Check purchase eligibility against an organization-scoped credit account

Allocate/update a member's credit limit

Caller must be owner, admin, manager, or a finance/HR operator of the organization. The organization is taken from the authenticated panel session; member_id and policy_id must both belong to it.

Reduce a member's allocation (owner/admin/finance-operator only, strictly a decrease)

List organization members and their credit status

Add a new member with an initial credit allocation (one-shot onboarding)

List the organization's credit policies

Panel health check

Admin KPI summary

Corporate settlement reconciliation report (read-only)

Requires the admin.corporate.data.view ability.

Corporate overdue-risk report (read-only)

Requires the admin.corporate.data.view ability.

Corporate production-operations health summary (locked accounts, failed settlements/webhooks, queue backlog)

Requires the admin.corporate.data.view ability.

Lock, unlock, suspend, or close a corporate credit account

Requires the admin.corporate.account.manage ability.

Manually retry a failed corporate webhook delivery

Requires the admin.corporate.webhook.manage ability.

Approve or reject a corporate customer's uploaded document

Requires the admin.corporate.customer.manage ability. Triggers a customer.document.{approved,rejected} partner webhook.

Mark a corporate settlement as failed

Requires the admin.corporate.settlement.manage ability.

Retry processing a corporate settlement

Requires the admin.corporate.settlement.manage ability.