DigetPay uses different credentials depending on the API or product you are integrating with. Always use the credential required by the API you are calling, and store all credentials securely.

Authentication at a Glance

Important: Payment API keys and Portal Bearer tokens are different credentials and must not be interchanged. A 401 Unauthorized response can occur when the wrong credential or environment is used.

1. Payment API Authentication

Payment APIs are authenticated using the merchant API key in the x-api-key request header.

Get Your Merchant API Key

1. Complete Merchant Onboarding.
2. Sign in to the DigetPay staging or production dashboard.
3. Navigate to Settings → API Credentials.
4. Copy the API key for the required environment.
5. Store the key securely in your server-side secrets manager.

Never expose your API key in frontend code, mobile applications, browser JavaScript, or public repositories.

Example Request

curl -X POST "https://api.digetpay.com/v1/payment/checkout/intiate" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_STAGING_API_KEY" \
  -d '{
    "merchantOrderId": "ORDER-1001",
    "amount": 0.20,
    "currency": "SAR",
    "customerPhone": "501223324",
    "successUrl": "https://merchant.example.com/payment/success",
    "failureUrl": "https://merchant.example.com/payment/failure"
  }'

A successful request returns HTTP 201 and includes the transaction id and redirectUrl.

2. Merchant Portal API Authentication

Merchant Portal APIs use a Portal Bearer Token.

Include the token in the Authorization header:

Authorization: Bearer YOUR_PORTAL_TOKEN

Portal Bearer tokens are used for operations such as:

• Managing merchant API credentials
• Managing webhooks
• Managing SDK tokens
• Accessing merchant account management APIs
• Other Merchant Portal operations

Important: A Merchant API Key cannot be used as a Portal Bearer Token, and a Portal Bearer Token cannot be used as the x-api-key for payment APIs.

3. Obtain a Portal Bearer Token

Before calling Merchant Portal APIs, the merchant or authorized integration must obtain a valid Portal Bearer Token through the DigetPay Portal authentication flow.

Authentication Flow

1. Open the appropriate DigetPay Portal environment.
2. Authenticate using the merchant/partner Portal credentials.
3. Call the Portal authentication endpoint.
4. Receive the Portal Bearer Token from the authentication response.
5. Store the token securely.
6. Include the token in the Authorization header for subsequent Portal API requests.

Portal Authentication Endpoint

Implementation note: Use the authentication endpoint provided by the DigetPay Portal API/Swagger documentation.

POST <PORTAL_AUTHENTICATION_ENDPOINT>

Example request structure:

{
  "username": "YOUR_PORTAL_USERNAME",
  "password": "YOUR_PORTAL_PASSWORD"
}

The authentication response provides the Portal Bearer Token required to access protected Merchant Portal APIs.

Do not hard-code Portal credentials or tokens in source code. Use a secure secrets manager or equivalent credential store.

Use the Token in Portal API Requests

Once the token is obtained, include it in every protected Portal API request:

curl -X GET "https://fin-api.digetpay.com/v1/merchant/account/credentials" \
  -H "Authorization: Bearer YOUR_PORTAL_TOKEN"

4. Refresh a Portal Bearer Token

Portal Bearer Tokens may need to be refreshed or re-issued when they expire or become invalid.

The integration should:

1. Monitor the token lifetime or authentication response.
2. Request a new token using the DigetPay Portal authentication/refresh mechanism.
3. Replace the expired token in the secure credential store.
4. Retry the Portal API request using the new token.

Token Refresh Endpoint

Implementation note: Use the actual refresh/re-authentication endpoint and request format defined by the DigetPay Portal API/Swagger documentation.

POST <PORTAL_TOKEN_REFRESH_ENDPOINT>

If the Portal authentication implementation does not provide a dedicated refresh-token endpoint, perform the documented Portal authentication flow again to obtain a new Bearer Token.

Recommended Token Handling

Merchant / Integration
        |
        v
Authenticate with DigetPay Portal
        |
        v
Obtain Portal Bearer Token
        |
        v
Store Token Securely
        |
        v
Call Merchant Portal APIs
        |
        v
Token Expired / Invalid?
        |
      Yes
        |
        v
Refresh / Re-authenticate
        |
        v
Store New Token
        |
        v
Continue API Requests

Do not implement token refresh logic based on assumed endpoints or response fields. Always follow the authentication contract provided by the DigetPay Portal API.

5. Portal API Example

The following example shows how a valid Portal Bearer Token is used to access merchant credentials:

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

The Portal Bearer Token authenticates the request, while the merchant API key returned by the credentials API is used separately when calling Payment APIs.

6. Environments and Credentials

Credentials are environment-specific. Do not use staging credentials against production APIs or production credentials against staging APIs.

Environment Rule

Staging Dashboard
      ↓
Staging Credentials
      ↓
Staging API

Production Dashboard
      ↓
Production Credentials
      ↓
Production API

Never mix credentials between environments.

7. API Key Rotation

Merchant API keys should be rotated periodically and immediately if a credential is suspected to be compromised.

Recommended Rotation Process

1. Generate or request a replacement API key through the DigetPay Dashboard or authorized Portal API.
2. Store the new key securely.
3. Update the integration's secret configuration.
4. Deploy the updated configuration.
5. Verify that API requests are successful.
6. Revoke the old key when it is no longer required.

Merchant Portal
      |
      v
Generate / Rotate API Key
      |
      v
New API Credential
      |
      v
Update Secrets Manager
      |
      v
Deploy Integration
      |
      v
Verify API Requests
      |
      v
Revoke Old Credential

Important: API key rotation is separate from Portal Bearer Token refresh. Payment API keys authenticate Payment APIs, while Portal Bearer Tokens authenticate Merchant Portal APIs.

8. Authentication Errors

Troubleshooting Checklist

When receiving 401 Unauthorized:

1. Confirm that the correct authentication header is being sent.
2. Confirm that the credential belongs to the requested environment.
3. For Payment APIs, verify the x-api-key.
4. For Portal APIs, verify the Authorization: Bearer <token> header.
5. Check whether the Portal Bearer Token has expired or been revoked.
6. Refresh or re-authenticate to obtain a new Portal Bearer Token when required.
7. Confirm that the merchant has access to the requested API.
8. Retry the request after correcting the credential.

9. Security Best Practices

• Keep API keys and Portal Bearer Tokens server-side.
• Never expose credentials in frontend applications.
• Never commit credentials to source control.
• Store credentials in environment variables or a secure secrets manager.
• Use separate credentials for staging and production.
• Rotate compromised credentials immediately.
• Do not log complete API keys or Bearer Tokens.
• Mask credentials in application logs and monitoring systems.
• Limit access to credentials to authorized systems and personnel.
• Do not share credentials through email, chat, screenshots, or public documentation.
• Treat Portal Bearer Tokens as sensitive credentials.
• Re-authenticate or refresh Portal tokens according to their actual expiration policy.

10. Quick Reference

Payment API

x-api-key: YOUR_MERCHANT_API_KEY

Use for:

• Payment initiation
• Hosted Checkout
• Embedded payments
• Transaction status
• Refunds

Merchant Portal API

Authorization: Bearer YOUR_PORTAL_TOKEN

Use for:

• Merchant account management
• API credential management
• Webhook management
• SDK-token management

Related Guides

• Merchant Signup & KYC
• Account Activation
• Environments Overview
• API Key Management
• Dashboard API Credentials
• Merchant Portal API Reference
• Webhooks
• SDK Authentication

Integration note: The exact Portal authentication and token-refresh endpoint, request body, response fields, expiration behavior, and refresh-token mechanism must match the currently deployed DigetPay Portal API. Replace the placeholders in Sections 3 and 4 with the actual Swagger/API contract before publishing this page.