Zeal Acquirer API
REST endpoints for partners to manage merchants (branches) and payment terminals
on Zeal. Every request is authenticated with an API key on the API-KEY header.
Authentication
Send your acquirer API key in the API-KEY header on every request. Obtain your
key from the Zeal dashboard. Keys must be kept server-side; never expose them in
client code.
curl "https://zms.getzealapi.com/ext/api/v1/merchants" \
-H "API-KEY: $ZEAL_API_KEY"
Errors
The API uses conventional HTTP status codes. Validation problems return 422
with an errors array.
- 200 - Request succeeded.
- 201 - Resource created successfully.
- 400 - Bad request - invalid input or business rule.
- 401 - Unauthorized - missing or invalid API-KEY.
- 404 - Resource not found or not accessible to acquirer.
- 422 - Validation errors - see
errorsarray.
List merchants (branches)
Returns a paginated list of branches (merchants) accessible to the authenticated acquirer.
Query parameters
sort enum · default desc per_page integer · default 10 page integer Responses
Create a merchant (branch)
Create a new merchant branch. When acquirer type is DISTRIBUTOR, payment_provider is required. Either existing_master_merchant (existing business UUID) or master_merchant_id (new business) is required. Optionally include terminals (array with at least one item).
Body
mid string REQUIRED branch_name string area string city string payment_provider uuid distributor uuid existing_master_merchant uuid master_merchant_id string master_merchant_name string email email country_code string phone string mcc string country string terminals[] array terminals[].terminal_id string terminals[].terminal_model string Responses
Get merchant by MID
Returns a single branch (merchant) by its Merchant ID (MID) if accessible to the authenticated acquirer.
Path parameters
mid string REQUIRED Responses
Archive a merchant
Archives the merchant identified by MID. The branch must belong to the authenticated acquirer. Once archived, the branch and its payment terminals are no longer active. Terminals linked to the branch are also archived.
Path parameters
mid string REQUIRED Responses
List terminals for a merchant
Returns a paginated list of payment terminals for the branch identified by MID. The MID must belong to a merchant accessible by the authenticated acquirer.
Path parameters
mid string REQUIRED Query parameters
sort enum · default desc per_page integer · default 10 page integer Responses
Create terminals for a merchant
Creates one or more payment terminals for the branch identified by MID. The MID must belong to a merchant accessible by the authenticated acquirer. terminal_id must be unique across payment_terminals.
Path parameters
mid string REQUIRED Body
terminals[] array REQUIRED terminals[].terminal_id string REQUIRED terminals[].serial_no string terminals[].terminal_model string terminals[].payment_app string terminals[].acquirer_name string Responses
Update a terminal
Updates the payment terminal identified by TID. The terminal must belong to a branch (MID) accessible by the authenticated acquirer. All request body fields are optional; only provided fields are updated.
Path parameters
tid string REQUIRED Body
serial_no string terminal_model string payment_app string acquirer_name string Responses
Delete a terminal
Deletes the payment terminal identified by TID. The terminal must belong to a branch accessible by the authenticated acquirer (distributor or payment provider).
Path parameters
tid string REQUIRED Responses
Archive a terminal
Archives the payment terminal identified by TID. A reason for archiving is required. Once archived, the terminal is no longer active for processing.
Path parameters
tid string REQUIRED Body
reason string REQUIRED Responses
Restore an archived terminal
Restores a previously archived payment terminal. The terminal must be in archived status. Once restored, the terminal becomes active again for processing.
Path parameters
tid string REQUIRED Responses
Reassign terminal to another MID
Moves a payment terminal (TID) from its current merchant (MID) to a different MID. Both the current terminal's MID and the target MID must belong to the requesting PSP. The terminal must not already be under the target MID.
Path parameters
tid string REQUIRED Body
mid string REQUIRED Responses
Lookup reference data
Returns a list of key/text pairs for the given lookup method. Used to populate dropdowns when creating merchants or terminals.
Path parameters
method enum REQUIRED Query parameters
search string Responses
Member check
Check if the member is identified and has available rewards or not. Authenticated via the `API-KEY` header.
Body
amount number REQUIRED card_id string REQUIRED card_pseudo_token string REQUIRED currency string REQUIRED terminal_id string REQUIRED acquirer_id string REQUIRED Responses
Request
GET /ext/api/v1/merchantscurl -X GET "https://zms.getzealapi.com/ext/api/v1/merchants?per_page=10&page=1" \ -H "API-KEY: $ZEAL_API_KEY"
Response
200{
"data": [
{
"mid": "BRANCH001",
"merchant_name": "Downtown Branch",
"area": "Central",
"city": "Cairo",
"master_merchant_name": "Acme Coffee",
"master_merchant_id": "MERCHANT001",
"status": "active"
}
],
"links": { "first": "...", "last": "...", "prev": null, "next": "..." },
"meta": { "current_page": 1, "per_page": 10, "total": 47 }
}