Authentication

How authentication works

The Moyasar PG REST API uses Bearer authentication with acquirer API keys generated from the Acquirer Dashboard.

An acquirer API key has the following form:

acquirer_key_123

where 123 is a unique secure random string. The acquirer_key_ prefix is what identifies the token as an acquirer API key — send the full string, prefix included.

To authenticate an API call, add the following header to each request:

Authorization: Bearer <api_key>

Note: replace <api_key> with the actual key.

Every request authenticated with an acquirer API key is automatically scoped to your acquirer: the API only ever returns — and only ever modifies — merchants, orders, transactions, agreements, card authentications, payment controls, audit logs and EOD statements that belong to your acquirer. Resources of other acquirers behave as if they do not exist (HTTP 404).

If the key is missing, unknown or disabled, the API responds with HTTP 401:

{
  "message": "Invalid authentication information"
}

Keys can additionally be restricted to a set of IP addresses — see IP Whitelisting.

Getting an API key

API keys are managed from the Acquirer Dashboard by any acquirer user holding the acquirer_api_keys_create permission:

1. Log in to the Acquirer Dashboard.
2. Navigate to API Keys and click Create.
3. Give the key a description (e.g. "Reconciliation service").
4. Select the permissions the key needs — grant only what the integration actually uses.
5. Optionally restrict the key to your servers' IP addresses.
6. Save, then copy the generated acquirer_key_... value into your integration's secret store.

Keys do not expire, but they can be disabled at any time from the same page (disabling is permanent — create a new key to rotate). The key's permissions and IP whitelist can be edited after creation by users holding acquirer_api_keys_update.

Keep it secret

The API key carries the full authority of the permissions granted to it. Store it in a secrets manager, never commit it to source control, and rotate it immediately if it leaks.

Permissions

Each API key carries an explicit set of permissions and is only allowed to call the services selected when the key was created. Calling an endpoint without the required permission returns HTTP 403:

{
  "message": "Unauthorized"
}

A permission string is formed as <group>_<action>. The following permissions are available to acquirer API keys:

Permission	Grants
merchants_create	Create merchants
merchants_read	List and retrieve merchants
merchants_update	Update, activate and deactivate merchants
merchants_delete	Delete merchants
merchant_users_create	Create merchant users (sends invitation emails)
merchant_users_read	List and retrieve merchant users
merchant_users_update	Update merchant users and resend invitations
merchant_users_disable	Disable merchant users
merchant_users_enable	Enable merchant users
merchant_users_password_reset	Send password reset emails to merchant users
orders_read	List and retrieve orders, list transactions, and export transactions as CSV
3ds_read	List and retrieve card authentications (3-D Secure)
agreements_read	List and retrieve stored agreements
agreements_disable	Disable stored agreements
payment_controls_create	Create payment controls
payment_controls_read	List and retrieve payment controls
payment_controls_update	Update payment controls
payment_controls_delete	Delete payment controls
eod_list, eod_read	List and download End-of-Day statements
audit_logs_read	Query the audit trail of your acquirer and its merchants

The current permission catalogue can also be fetched programmatically from GET /v1/acquirer/api_keys/permissions using any authenticated principal, including the API key itself.