Authentication

Authenticate every DigetPay request with the credential required by the API you are calling, then store and rotate that credential securely.

Authentication at a glance
Payment APIs use your merchant API key in the x-api-key header. Merchant portal APIs, such as credential, webhook, and SDK-token management, use a portal bearer token.

Choose the right credential

API type	Credential	Header	Use it for
Payment API	Merchant API key	`x-api-key: YOUR_MERCHANT_API_KEY`	Hosted Checkout, embedded payments, transaction status, and refunds.
Merchant portal API	Portal bearer token	`Authorization: Bearer YOUR_PORTAL_TOKEN`	API credentials, webhooks, and SDK-token management.
SoftPOS, SmartPOS, and mobile SDKs	SDK token	Product-specific secure provisioning	Device and app authentication.

Do not interchange credentials
Do not send a portal bearer token to a payment endpoint or send your payment API key to a portal endpoint. A 401 Unauthorized response can indicate that you used the wrong credential or environment.

Get your merchant API key

Complete Merchant Onboarding and wait for account activation.
Sign in to the dashboard for your environment:
- Fin staging: https://fin-admin.digetpay.com
- Production: https://admin.digetpay.com
Open Settings → API Credentials.
Store the key in a secrets manager or protected server environment variable.

Your Fin key works only with Fin staging. Your production key works only with production.

Authenticate payment API requests

Send x-api-key on every payment API request. Keep the request on your server; never expose this value in browser code, mobile apps, client-side logs, or source control.

curl --request POST \
  --url https://fin-api.digetpay.com/v1/payment/checkout/intiate \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: YOUR_STAGING_API_KEY' \
  --data '{
    "merchantOrderId": "ORDER-1001",
    "amount": 0.20,
    "currency": "SAR",
    "customerPhone": "501223324",
    "successUrl": "https://fin-admin.digetpay.com/pay/checkout/success",
    "failureUrl": "https://fin-admin.digetpay.com/pay/checkout/failure"
  }'

A successful request returns 201 and includes an id and redirectUrl.

{
  "id": "70471003-64ee-4ae7-a639-e607b45e890b",
  "redirectUrl": "https://fin-admin.digetpay.com/pay/checkout?sessionId=70471003-64ee-4ae7-a639-e607b45e890b"
}

Authenticate merchant portal API requests

Use a bearer token only with merchant portal endpoints. These endpoints manage account resources rather than customer payments.

GET /merchant/account/credentials HTTP/1.1
Host: fin-api.digetpay.com
Authorization: Bearer YOUR_PORTAL_TOKEN

Use the portal API to retrieve or rotate credentials, manage webhooks, or manage SDK tokens. See the Merchant API Reference for each endpoint’s requirements.

Use environment-specific credentials

Environment	Payment API base URL	Dashboard	Credential rule
Fin staging	`https://fin-api.digetpay.com/v1`	`https://fin-admin.digetpay.com`	Use only your Fin staging credentials.
Production	`https://api.digetpay.com/v1`	`https://admin.digetpay.com`	Use only your production credentials.

Protect production access
Production credentials can process real payments. Limit access to the smallest possible group, use environment-specific secrets, and review access when team members or vendors change.

Rotate a compromised API key

Rotate a key immediately if it appears in source control, a browser response, a log, a support ticket, or another untrusted location.

Generate or request a replacement key from Dashboard → Settings → API Credentials or the portal credential API.
Store the new key in your secrets manager.
Deploy the updated secret to every service that calls DigetPay.
Verify a Fin staging payment with the replacement staging key.
Revoke the old key after your services use the replacement.

Rotate safely
Treat a newly revealed plain-text API key as a secret shown once. Store it before you leave the dashboard or complete the rotation flow.

Handle authentication errors

HTTP status	Message	Likely cause	Action
`401`	`Missing API key`	The payment request has no `x-api-key` header.	Add the merchant API key on your server.
`401`	`Invalid API key`	The key is incorrect, inactive, or used with the wrong environment.	Check the secret value and match it to the API base URL.
`401`	`Merchant not found`	The merchant record is not synchronized to the key.	Contact DigetPay support with your merchant details.
`401`	`Unauthorized`	The portal token is missing, invalid, or used on the wrong API.	Use a valid portal bearer token for the portal endpoint.

Security checklist

Load credentials from a secrets manager or protected environment variable.
Keep payment API calls on your backend.
Mask credentials in logs and dashboards; show only a small suffix when needed for debugging.
Do not add API keys, portal tokens, SDK tokens, PAN, or CVV to error reports.
Use separate secrets for Fin staging and production.
Rotate credentials after suspected exposure, staff changes, or device loss.

Related guides

Quick Start — make your first Fin staging payment.
Environments — select the right base URL and checkout domain.
Dashboard Guide — manage API credentials and SDK tokens.
Webhooks — configure and process payment notifications.
Go-Live Checklist — validate production credentials before launch.