Authentication
ZarPay24 expects for the access token to be included in all API requests to the server in a header that looks like the following:
Authorization: Bearer client_access_token
Refresh Token
curl --location --request GET '{MERCHANT_BASE_URL}/users/refresh/' \
--header 'Authorization: Bearer client_refresh_token' \
--header 'Content-Type: application/json'
The above command returns JSON structured like this:
{
"access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzM5OTU0NDk1LCJpYXQiOjE3MzkzNDk2OTUsImp0aSI6IjhhODM4ZWZlZDNiYzRlMjQ5ZjZjNjU3ZWQyY2VhMGU5IiwidXNlcl9pZCI6MTUzLCJtZXJjaGFudF9pZCI6MTR9.bxQ_RYaerOk1mV5G14NHKjaJD944RPXpWH3vE0iEDQY"
}
Use this endpoint to generate new access_token for your client based on client_refresh_token you've been provided here.
HTTP Request
GET {MERCHANT_BASE_URL}/users/refresh/
KYC
Get Profile(include KYC state)
curl --location --request GET '{MERCHANT_BASE_URL}/users/profile/' \
--header 'Authorization: Bearer client_access_token' \
--header 'Content-Type: application/json'
The above command returns JSON structured like this:
{
"_id": "200002",
"full_name": "ایمان اشراقی",
"email": "",
"phone_number": "+98912****873",
"phone_number_str": "0912****873",
"invite_code": "XGvy",
"national_number": "******1234",
"is_blocked": false,
"is_banned": false,
"first_name": "ایمان",
"last_name": "اشراقی",
"kyc": "DN",
}
This endpoint retrieves user profile detail which includes KYC state.
HTTP Request
GET {MERCHANT_BASE_URL}/users/profile/
Proceed KYC (register personal info)
curl --location '{MERCHANT_BASE_URL}/users/personal-info/' \
--header 'Authorization: Bearer client_access_token' \
--header 'Content-Type: application/json' \
--data '{
"national_number": "0010859684",
"birth_date": "1998-01-12"
}'
The above command returns JSON structured like this:
{
"_id": "200002",
"full_name": "ایمان اشراقی",
"email": "",
"phone_number": "+98912****873",
"phone_number_str": "0912****873",
"invite_code": "XGvy",
"national_number": "******1234",
"is_blocked": false,
"is_banned": false,
"first_name": "ایمان",
"last_name": "اشراقی",
"kyc": "DN",
}
This endpoint allows you ti submit client personal-info and proceed KYC.
HTTP Request
POST {MERCHANT_BASE_URL}/users/personal-info/
Request Body
| Parameter | Description |
|---|---|
| national_number | 10 numbers length. |
| birth_date | The gregorian birth_date in %Y-%M-%D format. |
Balance
Get Balance of all coins
curl --location --request GET '{MERCHANT_BASE_URL}/portfolio/assets/fiat-balance/' \
--header 'Authorization: Bearer client_access_token' \
--header 'Content-Type: application/json'
The above command returns JSON structured like this:
[
{
"symbol": "IRT",
"balance": "200000",
"blocked": "0"
},
{
"symbol": "GOLD",
"balance": "25.3157",
"blocked": "0"
}
]
This endpoint retrieves client balance of each asset.
HTTP Request
GET {MERCHANT_BASE_URL}/assets/fiat-balance/
Get Single Coin balance
curl --location --request GET '{MERCHANT_BASE_URL}/portfolio/assets/fiat-balance/?symbol=SILVER' \
--header 'Authorization: Bearer client_access_token' \
--header 'Content-Type: application/json'
The above command returns JSON structured like this:
{
"balance": "200000",
"blocked": "0"
},
This endpoint retrieves client balance of an specific coin.
HTTP Request
GET {MERCHANT_BASE_URL}portfolio/assets/fiat-balance/?symbol={COIN_SYMBOL}
Cards
Get Verified Cards
curl --location --request GET '{MERCHANT_BASE_URL}/users/verified-cards/' \
--header 'Authorization: Bearer client_access_token' \
--header 'Content-Type: application/json'
The above command returns JSON structured like this:
[
{
"number": "6219861929783016",
"id": 4,
"state": "DN",
"iban": "IR720560611828005347224101",
"bank_name": "سامان",
"bank_code": "056"
},
{
"number": "5859831216890185",
"id": 5,
"state": "DN",
"iban": "IR900180000000136234069882",
"bank_name": "تجارت",
"bank_code": "018"
}
]
This endpoint retrieves list of client verified cards which will be used for cash out
HTTP Request
GET {MERCHANT_BASE_URL}/users/verified-cards/
Add new card
curl --location '{MERCHANT_BASE_URL}/users/cards/' \
--header 'Authorization: Bearer client_access_token' \
--header 'Content-Type: application/json' \
--data '{
"number": "0010859684",
}'
The above command returns JSON structured like this:
{
"number":"6219861076488716",
"id":22,
"state":"DN",
"iban":"IR350560213780004605786001",
"bank_name":"سامان",
"bank_code":"056"
}
This endpoint allows you ti submit client personal-info and proceed KYC.
HTTP Request
POST {MERCHANT_BASE_URL}/users/cards/
Request Body
| Parameter | Description |
|---|---|
| number | 10 digits card number. |
Market
Get Coins Data (Pricing)
curl --location --request GET '{MERCHANT_BASE_URL}/market/coins/' \
--header 'Authorization: Bearer client_access_token' \
--header 'Content-Type: application/json'
The above command returns JSON structured like this:
[
{
"id": 2,
"symbol": "GOLD",
"persian_name": "طلا آبشده",
"buy_active": true,
"sell_active": true,
"max_order_qty": "100",
"buy_price": "5531187",
"sell_price": "5519645",
"fee_percentage": "1.00",
"unit": "گرم",
"decimal_places": 4
},
{
"id": 4,
"symbol": "SILVER",
"persian_name": "نقره",
"buy_active": true,
"sell_active": true,
"max_order_qty": "250",
"buy_price": "102000",
"sell_price": "101000",
"fee_percentage": "2.00",
"unit": "گرم",
"decimal_places": 0
},
]
This endpoint retrieves detailed information about a specific coin.
HTTP Request
GET {MERCHANT_BASE_URL}/market/coins/
Buy Coin with Quantity
curl --location '{MERCHANT_BASE_URL}/market/buy/' \
--header 'Authorization: Bearer client_access_token' \
--header 'Content-Type: application/json' \
--data '{
"coin_id":1,
"quantity":"12.00"
}'
The above command returns JSON structured like this:
{
"id": 291,
"coin": 1,
"quantity": "2.0000",
"quote": "8000000",
"quote_with_fee": "8080000",
"fee": 80000.0,
"coin_price": "1000.00",
"side": "buy",
"state": "done",
"request_type": 2,
"source": "merchant",
"user_tracker": null,
"created_at": "2025-01-03T12:46:18.321695Z",
"finalized_at": "2025-01-03T12:46:18.319125Z",
"coin_name": "طلا آبشده"
}
This endpoint allows you to purchase a coin by specifying the desired quantity.
HTTP Request
GET {MERCHANT_BASE_URL}/market/buy/
Request Body
| Parameter | Description |
|---|---|
| coin_id | The id of coin to buy. |
| quantity | The quantity of coin to buy. |
Sell Coin with Quantity
curl --location '{MERCHANT_BASE_URL}/market/sell/' \
--header 'Authorization: Bearer client_access_token' \
--header 'Content-Type: application/json' \
--data '{
"coin_id":1,
"quantity":"12.00"
}'
The above command returns JSON structured like this:
{
"id": 291,
"coin": 1,
"quantity": "2.0000",
"quote": "8000000",
"quote_with_fee": "8080000",
"fee": 80000.0,
"coin_price": "1000.00",
"side": "sell",
"state": "done",
"request_type": 2,
"source": "merchant",
"user_tracker": null,
"created_at": "2025-01-03T12:46:18.321695Z",
"finalized_at": "2025-01-03T12:46:18.319125Z",
"coin_name": "طلا آبشده"
}
This endpoint allows you to sell a coin by specifying the desired quantity.
HTTP Request
GET {MERCHANT_BASE_URL}/market/sell/
Request Body
| Parameter | Description |
|---|---|
| coin_id | The id of coin to sell. |
| quantity | The quantity of coin to sell. |
Buy Coin with Quote
curl --location '{MERCHANT_BASE_URL}/market/buy/' \
--header 'Authorization: Bearer client_access_token' \
--header 'Content-Type: application/json' \
--data '{
"coin_id":1,
"quote":"50000"
}'
The above command returns JSON structured like this:
{
"id": 291,
"coin": 1,
"quantity": "2.0000",
"quote": "8000000",
"quote_with_fee": "8080000",
"fee": 80000.0,
"coin_price": "1000.00",
"side": "buy",
"state": "done",
"request_type": 2,
"source": "merchant",
"user_tracker": null,
"created_at": "2025-01-03T12:46:18.321695Z",
"finalized_at": "2025-01-03T12:46:18.319125Z",
"coin_name": "طلا آبشده"
}
This endpoint creates an order to buy a coin by specifying the desired quote amount.
HTTP Request
GET {MERCHANT_BASE_URL}/market/buy/
Request Body
| Parameter | Description |
|---|---|
| coin_id | The id of coin to buy. |
| quote | Amount of quote currency to spend. |
Sell Coin with Quote
curl --location '{MERCHANT_BASE_URL}/market/sell/' \
--header 'Authorization: Bearer client_access_token' \
--header 'Content-Type: application/json' \
--data '{
"coin_id":1,
"quote":"50000"
}'
The above command returns JSON structured like this:
{
"id": 291,
"coin": 1,
"quantity": "2.0000",
"quote": "8000000",
"quote_with_fee": "8080000",
"fee": 80000.0,
"coin_price": "1000.00",
"side": "sell",
"state": "done",
"request_type": 2,
"source": "merchant",
"user_tracker": null,
"created_at": "2025-01-03T12:46:18.321695Z",
"finalized_at": "2025-01-03T12:46:18.319125Z",
"coin_name": "طلا آبشده"
}
This endpoint creates an order to sell a coin by specifying the desired quote amount.
HTTP Request
GET {MERCHANT_BASE_URL}/market/sell/
Request Body
| Parameter | Description |
|---|---|
| coin_id | The id of coin to sell. |
| quote | Amount of quote currency to receive. |
Sell & Cash Out
curl --location '{MERCHANT_BASE_URL}/market/sell/cash-out/' \
--header 'Authorization: Bearer client_access_token' \
--header 'Content-Type: application/json' \
--data '{
"coin_id":1,
"quote":"50000"
"card_id":53
}'
The above command returns JSON structured like this:
{
"id": 291,
"coin": 1,
"quantity": "2.0000",
"quote": "8000000",
"quote_with_fee": "8080000",
"fee": 80000.0,
"coin_price": "1000.00",
"side": "sell",
"state": "done",
"request_type": 2,
"source": "merchant",
"user_tracker": null,
"created_at": "2025-01-03T12:46:18.321695Z",
"finalized_at": "2025-01-03T12:46:18.319125Z",
"coin_name": "طلا آبشده"
}
The final quote_with_fee of this order would be directly withdraw to user bank account (card_id).
HTTP Request
POST {MERCHANT_BASE_URL}/market/sell/cash-out/
Request Body
| Parameter | Description |
|---|---|
| coin_id | The id of coin to sell. |
| quote | Amount of quote currency to receive. |
| card_id | The id of verified card of client. |
Sell & Settle by merchant
curl --location '{MERCHANT_BASE_URL}/market/sell/settle-by-merchant/' \
--header 'Authorization: Bearer client_access_token' \
--header 'Content-Type: application/json' \
--data '{
"coin_id":1,
"quote":"50000"
}'
The above command returns JSON structured like this:
{
"id": 291,
"coin": 1,
"quantity": "2.0000",
"quote": "8000000",
"quote_with_fee": "8080000",
"fee": 80000.0,
"coin_price": "1000.00",
"side": "sell",
"state": "done",
"request_type": 2,
"source": "merchant",
"user_tracker": null,
"created_at": "2025-01-03T12:46:18.321695Z",
"finalized_at": "2025-01-03T12:46:18.319125Z",
"coin_name": "طلا آبشده"
}
The final quote_with_fee of this order would be added to merchant account balances.
HTTP Request
POST {MERCHANT_BASE_URL}/market/sell/settle-by-merchant/
Request Body
| Parameter | Description |
|---|---|
| coin_id | The id of coin to sell. |
| quote | Amount of quote currency to receive. |
Get Orders
curl --location '{MERCHANT_BASE_URL}/market/orders/' \
--header 'Authorization: Bearer client_access_token' \
--header 'Content-Type: application/json'
The above command returns JSON structured like this:
{
"page": 1,
"page_size": "10",
"total_pages": 1,
"total_items": 1,
"data": [
{
"id": 1,
"coin": 2,
"quantity": "1.0000",
"quote": "470358",
"quote_with_fee": "4662264",
"fee": 47094.0,
"coin_price": "4708.00",
"side": "sell",
"state": "done",
"request_type": 2,
"source": "merchant",
"created_at": "2024-10-30T10:55:52.949253Z",
"finalized_at": "2024-10-30T10:55:52.948687Z",
"coin_name": "طلا آبشده"
}
]
}
This endpoint retrieves a list of orders with pagination.
HTTP Request
GET {MERCHANT_BASE_URL}/market/orders/
Query Parameters
| Parameter | Description |
|---|---|
| page | The page number to retrieve (default: 1). |
| page_size | The number of items per page (default: 10). |
Get Order by User Tracker
curl --location '{MERCHANT_BASE_URL}/market/orders/by-tracker/<user_tracker>/' \
--header 'Authorization: Bearer client_access_token' \
--header 'Content-Type: application/json'
The above command returns JSON structured like this:
{
"page": 1,
"page_size": "10",
"total_pages": 1,
"total_items": 1,
"data": [
{
"id": 1,
"coin": 2,
"quantity": "1.0000",
"quote": "470358",
"quote_with_fee": "4662264",
"fee": 47094.0,
"coin_price": "4708.00",
"side": "sell",
"state": "done",
"request_type": 2,
"source": "merchant",
"created_at": "2024-10-30T10:55:52.949253Z",
"finalized_at": "2024-10-30T10:55:52.948687Z",
"coin_name": "طلا آبشده"
}
]
}
This endpoint retrieves the details of a specific order using the user_tracker identifier.
HTTP Request
GET {MERCHANT_BASE_URL}/market/orders/by-tracker/<user_tracker>/
URL Parameters
| Parameter | Description |
|---|---|
| user_tracker | Unique tracker ID of the order to fetch details for. |
Errors
The ZarPay24 API uses the following error codes:
| Error Code | Meaning |
|---|---|
| 400 | Bad Request -- Your request is invalid. |
| 401 | Unauthorized -- Your API key is wrong. |
| 403 | Forbidden -- The IP you are requesting from is not valid. |
| 404 | Not Found -- The specified source could not be found. |
| 405 | Method Not Allowed -- You tried to access a source with an invalid method. |
| 406 | Not Acceptable -- You requested a format that isn't json. |
| 429 | Too Many Requests -- You're requesting too many kittens! Slow down! |
| 500 | Internal Server Error -- We had a problem with our server. Try again later. |
| 503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |