The complete API surface of the eCardo global financial platform — merchant payment gateway, user & agent app APIs, hosted checkout, gateway webhooks, and platform data endpoints.
eCardo is a multi-role financial platform. The API is organized by role — each account type (User, Merchant, Agent) gets its own route prefix under /api, guarded by Sanctum tokens and a role middleware:
/api/user/* | End-customer app (wallet, cards, remittance, P2P, bills, tickets…) |
/api/merchant/* | Merchant app + external payment gateway (access-token, make-payment, IPN) |
/api/agent/* | Agent / exchange-office app (cash-in, exchange, settlement) |
/api/auth/* | Authentication (login, register, 2FA, password reset) — no token required |
/api/* (other) | Public platform data (currencies, banks, settings, app version, website content) |
/pay/*, /pro-pay/*, /ipn/* | Hosted checkout pages and gateway callbacks (browser / server-to-server) |
Everything is served by a single Laravel application fronted by nginx + Cloudflare. Money movement is double-entry ledgered, every wallet operation is idempotent-protected, and all sensitive endpoints are KYC-gated.
Two independent credential systems: (A) app accounts (User / Merchant / Agent) use Sanctum Bearer tokens; (B) external merchant websites use public_key / secret_key to obtain a short-lived gateway access token.
Register or log in, then send the token on every request:
POST https://origin-api.ecardo.ir/api/auth/user/login
Content-Type: application/json
{ "email": "user@example.com", "password": "secret" }
{
"status": "success",
"data": { "token": "1|abcDEF...", "user": { "id": 1, "name": "Ali", "uid": "U-1001", ... } }
}
# every subsequent request Authorization: Bearer 1|abcDEF... Accept: application/json
| Endpoint | Description |
|---|---|
| POST /api/auth/user/register | Register a new user account (email + password + profile fields). Triggers email verification. |
| POST /api/auth/user/login | Login. Returns Sanctum token + user payload. Rate-limited (brute-force protection). |
| POST /api/auth/user/logout | Invalidate the current token. |
| POST /api/auth/user/refresh | Rotate the current token (long-lived sessions). |
| GET /api/auth/user/get | Get the currently authenticated user profile. |
| POST /api/auth/user/forgot-password | Request a password-reset OTP / email. |
| POST /api/auth/user/reset-verify-otp | Verify the reset OTP. |
| POST /api/auth/user/reset-password | Set the new password. |
| POST /api/auth/user/send-verify-email | Re-send email verification link. |
| POST /api/auth/user/validate-verify-email | Validate the email verification token. |
| POST /api/auth/user/2fa/verify | Verify Google Authenticator 2FA code when enabled on the account. |
| POST /api/auth/user/personal-info-update | Update profile fields (name, phone, …). |
Merchant & Agent accounts use the identical flow under /api/auth/merchant/* and /api/auth/agent/* (register, login, logout, profile, forgot-password, 2FA/verify, personal-info-update). The token returned is scoped to that role — a merchant token cannot call /api/user/* endpoints.
Merchants who accept payments on their own website use the public_key / secret_key pair generated in Merchant panel → API Credentials (endpoints GET /api/merchant/access-keys and POST /api/merchant/access-keys/regenerate). See §4.
| Header | Where | Purpose |
|---|---|---|
Authorization: Bearer <token> | All role APIs | Sanctum token obtained at login. |
Accept: application/json | All APIs | Forces JSON error responses instead of HTML redirects. |
Content-Type: application/json | POST/PUT | JSON body (multipart for file uploads). |
Idempotency-Key: <uuid> | Money-moving POSTs | Optional but recommended. Same user + route + key within 24h replays the original result instead of double-charging. |
// success
{ "status": "success", "data": { ... } }
// validation / business error
{ "status": "error", "message": "Insufficient balance.", "errors": { "amount": ["The amount must be greater than 0."] } }
Money features are gated by KYC level + feature flags. If the account's KYC is below the required level the endpoint returns 403 with a message such as "KYC level 2 required". Gated features:
Active: IRT (Iranian Rial Token), USD, CNY, USDT. IRR and RMB are retired (no active methods). Decimal rules: IRT/CNY display 0 decimals, USDT 8, USD 2. All amounts are numeric; currency codes are case-insensitive.
| Scope | Limit |
|---|---|
| Auth endpoints (login/register/forgot) | Throttled per IP — brute-force protection |
| Exchange rate / calculate | 30 requests / minute |
| Passcode verify | 5 attempts / minute |
| Payment status poll | 30 requests / minute |
| Merchant API (all) | 30 requests / minute per IP |
Accept eCardo wallet, gift and bank-gateway payments on your website with a few API calls. Your users pay on ecardo.ir — PCI-DSS is our problem, not yours.
payment_urlcurl -X POST https://origin-api.ecardo.ir/api/merchant/access-token \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"public_key": "YOUR_PUBLIC_KEY",
"secret_key": "YOUR_SECRET_KEY"
}'
{
"status": "success",
"token": "eyJ0eXAiOiJK...", // use as Bearer token
"expires_in": "2026-09-12 14:30:00" // token expiry (UTC), valid for 30 minutes
}
| Field | Type | Required | Description |
|---|---|---|---|
| amount | numeric | Yes | Payment amount |
| currency | string (3-4) | Yes | IRR, IRT, USD, CNY … (a wallet of yours in this currency must exist — case-insensitive) |
| transaction_id | string ≤ 12 | Yes | Your unique order reference |
| description | string ≤ 20 | Yes | Shown to the payer |
| callback_url | url | No | Public HTTPS URL for user return after payment |
| ipn_url | url | No | Server-to-server webhook URL |
| customer_name | string ≤ 50 | No | Payer name |
| customer_email | string ≤ 50 | No | Payer email |
curl -X POST https://origin-api.ecardo.ir/api/merchant/make-payment \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{
"amount": 1010,
"currency": "IRR",
"transaction_id": "ORD-1001",
"description": "Order 1001",
"callback_url": "https://your-site.com/checkout/callback",
"ipn_url": "https://your-site.com/api/ecardo-ipn",
"customer_name": "Ali Test",
"customer_email": "ali@example.com"
}'
{
"status": "success",
"payment_url": "https://origin-api.ecardo.ir/pay/TRXUWEIDH650P"
}
payment_url is the hosted checkout page. Redirect the user there, or embed it (see §4.8).Multi-currency behaviour: the hosted page charges the payer in the exact currency you requested — no conversion, no surprises. Payers can settle from their eCardo wallet, a gift code in the same currency, or a bank/gateway supporting that currency. If a gift covers more than the amount, the leftover is credited back to the payer's wallet automatically.
After a successful payment the user sees SUCCESS — Payment has been completed. with an 8-second countdown. They are redirected automatically to your callback_url (a manual Return to Sender Site Now button is also shown). Query params appended: ?tnx=TRX...&status=success.
callback_url already contains a ?, the params are appended with &.ipn_urlWhen the payment succeeds we POST form data to your ipn_url:
status=success signature=HMAC_SHA256(transaction_id + final_amount, merchant_secret_key) data[amount]=1000.00 data[charge]=10.00 data[total_amount]=1010.00 data[transaction_id]=ORD-1001 data[currency]=IRR data[customer_name]=Ali Test data[customer_email]=ali@example.com
Verify in your language of choice:
// PHP
$expected = hash_hmac('sha256', $txId . $total, MERCHANT_SECRET_KEY);
if (hash_equals($expected, $signature)) { /* payment verified */ }
// Python
import hmac, hashlib
expected = hmac.new(secret_key.encode(), (tx_id + total).encode(), hashlib.sha256).digest()
if hmac.compare_digest(expected, signature): # verified
Public JSON endpoint as a backup to the IPN — returns the live transaction status:
{
"status": "success", // "success" | "failed"
"data": { "tnx": "TRXUWEIDH650P", "amount": "1000", "final_amount": "1010",
"pay_currency": "IRR", "method": "API", "status": "SUCCESS", … }
}
callback_url?tnx=…&status=success) and match data.manual_field_data.transaction_id against your order before delivering goods.On the hosted page the payer can select Pay Via Gift and pay with an eCardo gift code for the currency you requested — no extra API parameters, no merchant-side configuration.
You receive the result exactly like a wallet payment — same callback, same IPN, same status endpoint.
The payment page sends X-Frame-Options: ALLOWALL and can be embedded:
<iframe src="https://origin-api.ecardo.ir/pay/TRXUWEIDH650P"
style="width:100%;height:720px;border:0;border-radius:12px"
title="eCardo Secure Checkout"></iframe>
Merchants also use the app/panel API with their Sanctum token:
| Endpoint | Description |
|---|---|
| GET /api/merchant/transactions | Merchant transaction list (payments received, exchange, withdrawals). |
| GET /api/merchant/activity-chart | Time-series activity for dashboard charts. |
| GET /api/merchant/circle-chart | Category breakdown (pie chart data). |
| GET /api/merchant/qrcode | Merchant QR payload (UID / phone) for wallet top-ups. |
| GET /api/merchant/mark-as-read-notification | Mark in-app notifications as read. |
| GET /api/merchant/wallets | List merchant wallets (per currency). |
| POST /api/merchant/wallets | Open a new wallet for a supported currency. |
| DELETE /api/merchant/wallets/{wallet} | Close a wallet (only when balance is zero). |
| GET /api/merchant/access-keys | Current public_key / secret_key pair. |
| POST /api/merchant/access-keys/regenerate | Rotate credentials — old keys stop working immediately. |
| GET /api/merchant/exchange/config | Available exchange pairs & limits. |
| GET /api/merchant/exchange/rate | Live exchange rate (30 req/min). |
| POST /api/merchant/exchange/calculate | Quote: how much you receive for an amount (no execution). |
| POST /api/merchant/exchange | Execute a currency exchange between your wallets (KYC-gated, idempotent). |
| GET /api/merchant/exchange/history | Exchange history. |
| GET /api/merchant/exchange/{id} | Single exchange detail. |
| GET /api/merchant/invoices/config | Invoice settings (number prefix, etc.). |
| GET /api/merchant/invoices | List invoices. |
| POST /api/merchant/invoices | Create an invoice (amount, currency, due date, customer). |
| GET /api/merchant/invoices/{invoice} | Invoice detail. |
| PUT /api/merchant/invoices/{invoice} | Update an unpaid invoice. |
| DELETE /api/merchant/invoices/{invoice} | Delete an unpaid invoice. |
| GET /api/merchant/withdraw-accounts/config | Withdrawal configuration & limits. |
| GET /api/merchant/withdraw-accounts/methods/list | Available payout methods (Shaba, SWIFT, …). |
| GET /api/merchant/withdraw-accounts/methods/{id}/details | Fields required by a specific payout method. |
| GET /api/merchant/withdraw-accounts | List saved payout accounts. |
| POST /api/merchant/withdraw-accounts | Save a payout account (IBAN / SWIFT / …). |
| GET /api/merchant/withdraw-accounts/{withdraw_account} | Payout account detail. |
| PUT /api/merchant/withdraw-accounts/{withdraw_account} | Update a payout account. |
| DELETE /api/merchant/withdraw-accounts/{withdraw_account} | Delete a payout account. |
| POST /api/merchant/withdraw | Request a payout to a saved account (KYC-gated, idempotent, approval-based). |
| GET /api/merchant/kyc | Current KYC status. |
| POST /api/merchant/kyc | Submit KYC documents. |
| GET /api/merchant/kyc/history | KYC submission history. |
| GET /api/merchant/kyc/rejected-data | Rejected document details (for resubmission). |
| GET /api/merchant/kyc-level/levels | All KYC levels & their requirements. |
| GET /api/merchant/kyc-level/badge | Current level badge payload. |
| GET /api/merchant/kyc-level/status | Current level + next level + required documents. |
| POST /api/merchant/kyc-level/submit | Apply for the next KYC level. |
| POST /api/merchant/settings/profile | Update profile. |
| POST /api/merchant/settings/2fa/{type} | Enable/disable 2FA (google / email). |
| POST /api/merchant/settings/change-password | Change password. |
| GET /api/merchant/ticket/config | Support-ticket categories. |
| GET /api/merchant/ticket | List support tickets. |
| POST /api/merchant/ticket | Open a support ticket. |
| GET /api/merchant/ticket/{ticket} | Ticket detail + replies. |
| POST /api/merchant/ticket/reply/{uuid} | Reply to a ticket. |
| POST /api/merchant/ticket/action/{uuid} | Close / reopen a ticket. |
All endpoints require Authorization: Bearer <user-token>. Money-moving POSTs accept an optional Idempotency-Key header. Gated endpoints return 403 until the account's KYC level is sufficient.
| Endpoint | Description |
|---|---|
| GET /api/user/dashboard | Home payload: balances, pending items, quick stats. |
| GET /api/user/statistics | Aggregate statistics (totals, counts by type/status). |
| GET /api/user/transactions | Paginated transaction list (filter by type, status, date). |
| GET /api/user/transaction/{tnx} | Full detail of one transaction by tnx reference. |
| GET /api/user/qrcode | User QR payload (UID / phone) — used for receiving wallet top-ups. |
| GET /api/user/activity-chart | Time-series activity for the dashboard chart. |
| Endpoint | Description |
|---|---|
| GET /api/user/wallets | List all wallets with balances (IRT, USD, CNY, USDT). |
| POST /api/user/wallets | Open a wallet for a new currency { "currency": "USD" }. |
| DELETE /api/user/wallets/{wallet} | Close a wallet (must be zero balance). |
| Endpoint | Description |
|---|---|
| GET /api/user/add-money | Available top-up methods & limits (Shaparak banks, QR, …). |
| POST /api/user/add-money | Create a top-up request { "amount", "currency", "method" } → returns gateway redirect URL. KYC-gated. |
| Endpoint | Description |
|---|---|
| GET /api/user/payment/settings | Payment settings (default currency, limits). |
| POST /api/user/payment/make | Pay from wallet to a UID / phone / beneficiary (KYC-gated). |
| GET /api/user/payment/history | Payment history. |
| GET /api/user/payment-status/{tnx} | Live status of any transaction (30 req/min) — used by the app after a gateway return. |
| Endpoint | Description |
|---|---|
| GET /api/user/pay-bill/services/{country}/{type} | Bill services available for a country/type (electricity, water, …). |
| POST /api/user/pay-bill | Pay a bill { "service", "bill_number", "amount", "currency" }. Idempotent, KYC-gated. |
| GET /api/user/pay-bill/history | Bill payment history. |
The transaction PIN is not the login password and not 2FA — it protects money movement.
| Endpoint | Description |
|---|---|
| GET /api/user/passcode/status | has_passcode + feature flags. |
| POST /api/user/passcode | Set the PIN the first time { "passcode", "passcode_confirmation" }. |
| POST /api/user/passcode/change | Change the PIN { "old_passcode", "passcode", "passcode_confirmation" }. |
| POST /api/user/passcode/disable | Disable the PIN (requires the login password). |
| POST /api/user/passcode/verify | Verify a PIN (5 attempts/min). |
| Endpoint | Description |
|---|---|
| GET /api/user/invoices/config | Invoice configuration. |
| GET /api/user/invoices | List invoices. |
| POST /api/user/invoices | Create an invoice. |
| GET /api/user/invoices/{invoice} | Invoice detail. |
| PUT /api/user/invoices/{invoice} | Update an unpaid invoice. |
| DELETE /api/user/invoices/{invoice} | Delete an unpaid invoice. |
| POST /api/user/invoices/{id}/pay | Pay an invoice from wallet (KYC-gated). |
| Endpoint | Description |
|---|---|
| POST /api/user/payment-links/create | Create a shareable payment link { "amount", "currency", "description" } → returns a public URL anyone can pay. KYC-gated. |
| GET /api/user/payment-links/history | Your payment links with paid/pending status. |
| Endpoint | Description |
|---|---|
| GET /api/user/request-money/config | Feature config & limits. |
| POST /api/user/request-money | Send a money request to a UID/phone { "to", "amount", "currency", "note" }. KYC-gated. |
| GET /api/user/request-money/history | Requests sent & received. |
| POST /api/user/request-money/{id}/action | Accept / reject a request. Accepting debits the payer immediately. KYC-gated. |
| Endpoint | Description |
|---|---|
| GET /api/user/gifts/config | Gift feature config. |
| POST /api/user/gifts | Create a gift code { "amount", "currency", "to_uid", "message" }. Idempotent, KYC-gated. |
| POST /api/user/gifts/redeem | Redeem a gift code into your wallet { "code" }. Idempotent, KYC-gated. |
| GET /api/user/gifts/history | Gifts you created / received. |
| GET /api/user/gifts/redeem/history | Redemption history. |
| Endpoint | Description |
|---|---|
| GET /api/user/transfer/config | Transfer limits & config. |
| POST /api/user/transfer | Transfer between users { "to", "amount", "currency", "passcode" }. Idempotent, KYC-gated. |
| GET /api/user/transfer/history | Transfer history. |
| Endpoint | Description |
|---|---|
| GET /api/user/beneficiaries | List saved beneficiaries. |
| POST /api/user/beneficiaries | Add a beneficiary { "name", "uid_or_phone", "currency" }. |
| GET /api/user/beneficiaries/{beneficiary} | Beneficiary detail. |
| PUT /api/user/beneficiaries/{beneficiary} | Update a beneficiary. |
| DELETE /api/user/beneficiaries/{beneficiary} | Delete a beneficiary. |
| Endpoint | Description |
|---|---|
| GET /api/user/cashout/config | Cashout limits & methods. |
| POST /api/user/cashout | Cash out to a beneficiary/agent { "to", "amount", "currency", "passcode" }. Idempotent, KYC-gated. |
| GET /api/user/cashout/history | Cashout history. |
| Endpoint | Description |
|---|---|
| GET /api/user/withdraw-accounts/config | Withdrawal configuration & limits. |
| GET /api/user/withdraw-accounts/methods/list | Payout methods (Shaba, SWIFT, …). |
| GET /api/user/withdraw-accounts/methods/{id}/details | Fields required by a method. |
| GET /api/user/withdraw-accounts | List saved payout accounts. |
| POST /api/user/withdraw-accounts | Save a payout account. |
| GET /api/user/withdraw-accounts/{withdraw_account} | Payout account detail. |
| PUT /api/user/withdraw-accounts/{withdraw_account} | Update a payout account. |
| DELETE /api/user/withdraw-accounts/{withdraw_account} | Delete a payout account. |
| POST /api/user/withdraw | Request a payout { "withdraw_account_id", "amount", "currency" }. Idempotent, KYC-gated, approval-based. |
| Endpoint | Description |
|---|---|
| GET /api/user/exchange/config | Available pairs & limits. |
| GET /api/user/exchange/rate | Live rate (30 req/min). |
| POST /api/user/exchange/calculate | Quote without executing { "from", "to", "amount" }. |
| POST /api/user/exchange | Execute exchange between your wallets. Idempotent, KYC-gated. |
| GET /api/user/exchange/history | Exchange history. |
| GET /api/user/exchange/{id} | Single exchange detail. |
| Endpoint | Description |
|---|---|
| GET /api/user/referral/info | Your referral link, code, totals & commission settings. |
| GET /api/user/referral/direct | Direct referrals list. |
| GET /api/user/referral/tree | Full referral tree (multi-level). |
| Endpoint | Description |
|---|---|
| POST /api/user/settings/profile | Update profile fields. |
| POST /api/user/settings/2fa/{type} | Enable/disable 2FA (google / email). |
| POST /api/user/settings/passcode/verify | Verify transaction PIN (5 attempts/min). |
| POST /api/user/settings/change-password | Change login password. |
| POST /api/user/settings/account-close | Request account closure (admin review). |
| GET /api/user/settings/notification-prefs | Notification preferences. |
| POST /api/user/settings/notification-prefs | Update notification preferences. |
| Endpoint | Description |
|---|---|
| GET /api/user/kyc | Current KYC status. |
| POST /api/user/kyc | Submit KYC documents (multipart: national ID, selfie, …). |
| GET /api/user/kyc/history | Submission history. |
| GET /api/user/kyc/rejected-data | Rejected document details. |
| GET /api/user/kyc-level/levels | All levels & requirements. |
| GET /api/user/kyc-level/badge | Current level badge. |
| GET /api/user/kyc-level/status | Current + next level + required docs. |
| POST /api/user/kyc-level/submit | Apply for next level. |
| Endpoint | Description |
|---|---|
| GET /api/user/ticket/config | Categories & config. |
| GET /api/user/ticket | List tickets. |
| POST /api/user/ticket | Open a ticket. |
| GET /api/user/ticket/{ticket} | Ticket detail + replies. |
| POST /api/user/ticket/reply/{uuid} | Reply. |
| POST /api/user/ticket/action/{uuid} | Close / reopen. |
| Endpoint | Description |
|---|---|
| GET /api/user/remittance/methods | Available corridors & methods (country, currency, limits). |
| POST /api/user/remittance/quote | Server-side quote { "from_currency", "to_currency", "amount", "method" } — includes fee & rate snapshot. |
| POST /api/user/remittance/store | Create a remittance from a quote { "quote_id", "receiver", "documents" }. KYC level 2, idempotent. |
| GET /api/user/remittance/history | Remittance history. |
| GET /api/user/remittance/{uuid} | Remittance detail (state machine: pending → approved → settled / refunded). |
| POST /api/user/remittance/{uuid}/upload | Upload missing documents (multipart). KYC level 2. |
| Endpoint | Description |
|---|---|
| GET /api/user/card-products | Available card products. |
| GET /api/user/card-products/{product} | Card product detail. |
| GET /api/user/cardholders | Cardholders. |
| GET /api/user/cards | List your cards. |
| POST /api/user/cards | Order a new card. |
| GET /api/user/cards/{card} | Card detail. |
| POST /api/user/cards/balance/topup/{id} | Top up a card balance from a wallet. |
| POST /api/user/cards/{card}/irr-topup | Top up a card in IRR. |
| GET /api/user/cards/transactions/{card_id} | Card transactions. |
| POST /api/user/cards/update-status/{card_id} | Activate / freeze / close a card. |
| POST /api/user/card-orders | Card order (product flow). |
| GET /api/user/card-orders/{order} | Card order status. |
| GET /api/user/bsicards/cards/details/{card} | BSI card details (bin, expiry, status). |
| Endpoint | Description |
|---|---|
| GET /api/user/gift-cards/categories | Gift card categories. |
| GET /api/user/gift-cards/countries | Available countries. |
| GET /api/user/gift-cards/products | Gift card products (Steam, Amazon, …). |
| GET /api/user/gift-cards/product-details/{product_id} | Product detail & denominations. |
| POST /api/user/gift-cards/product/order | Order a gift card { "product_id", "denomination", "quantity" }. |
| GET /api/user/gift-cards/purchased-history | Purchase history. |
| Endpoint | Description |
|---|---|
| GET /api/user/p2p/marketplace | Marketplace ads (buy/sell). |
| GET /api/user/p2p/marketplace/config | Marketplace config. |
| GET /api/user/p2p/marketplace/{id} | Ad detail. |
| GET /api/user/p2p/ads | Your ads. |
| POST /api/user/p2p/ads | Create an ad { "side", "currency", "price", "min_amount", "max_amount" }. |
| GET /api/user/p2p/ads/{ad} | Ad detail. |
| PUT /api/user/p2p/ads/{ad} | Update an ad. |
| DELETE /api/user/p2p/ads/{ad} | Delete an ad. |
| GET /api/user/p2p/ads/eligibility | Can this user trade? (KYC + flags). |
| GET /api/user/p2p/ads/highest-order-price | Best (highest) order price on the market. |
| GET /api/user/p2p/ads/{id}/payment-methods | Seller's payment methods for an ad. |
| PATCH /api/user/p2p/ads/{id}/status-update | Update ad status (active/paused). |
| GET /api/user/p2p/orders | Your P2P orders. |
| POST /api/user/p2p/orders | Create an order against an ad (funds escrowed). |
| GET /api/user/p2p/orders/{id} | Order detail. |
| POST /api/user/p2p/orders/{id}/cancel | Cancel an order. |
| POST /api/user/p2p/orders/{id}/dispute | Open a dispute. |
| POST /api/user/p2p/orders/{id}/mark-paid | Buyer marks bank payment as sent. |
| POST /api/user/p2p/orders/{id}/release | Seller releases escrowed funds (KYC level 2). |
| PATCH /api/user/p2p/orders/{id}/payment-method | Set the payment method for an order. |
| GET /api/user/p2p/orders/{id}/messages | Order chat messages. |
| POST /api/user/p2p/orders/{id}/messages | Send a chat message. |
| GET /api/user/p2p/payment-accounts | Your P2P payment accounts (bank accounts used in P2P). |
| POST /api/user/p2p/payment-accounts | Add a P2P payment account. |
| GET /api/user/p2p/payment-accounts/{payment_account} | Payment account detail. |
| PUT /api/user/p2p/payment-accounts/{payment_account} | Update a payment account. |
| DELETE /api/user/p2p/payment-accounts/{payment_account} | Delete a payment account. |
| GET /api/user/p2p/payment-methods | Available P2P payment methods. |
| POST /api/user/p2p/verified-trader-application/apply | Apply for verified-trader status. |
| GET /api/user/p2p/verified-trader-application/status | Application status. |
Agents (exchange offices / cash-in operators) use Authorization: Bearer <agent-token>. Same conventions as the User API (envelope, idempotency, KYC gates).
| Endpoint | Description |
|---|---|
| GET /api/agent/dashboard | Agent home payload (balances, pending settlements). |
| GET /api/agent/transactions | Agent transaction list. |
| GET /api/agent/circle-charts | Category breakdown. |
| GET /api/agent/transaction-chart | Time-series activity. |
| GET /api/agent/qrcode | Agent QR payload (for receiving cash-in). |
| GET /api/agent/mark-as-read-notification | Mark notifications read. |
| GET /api/agent/wallets | Agent wallets. |
| POST /api/agent/wallets | Open a wallet. |
| DELETE /api/agent/wallets/{wallet} | Close a wallet. |
| GET /api/agent/add-money | Top-up methods for the agent. |
| POST /api/agent/add-money | Create a top-up request. KYC-gated. |
| GET /api/agent/cashin/config | Cash-in config & limits. |
| POST /api/agent/cashin | Record a cash-in for a user { "user", "amount", "currency", "reference" }. Idempotent, KYC-gated. |
| GET /api/agent/cashin/history | Cash-in history. |
| GET /api/agent/exchange/config | Exchange pairs & limits. |
| GET /api/agent/exchange/rate | Live rate (30 req/min). |
| POST /api/agent/exchange/calculate | Quote. |
| POST /api/agent/exchange | Execute exchange. Idempotent, KYC-gated. |
| GET /api/agent/exchange/history | Exchange history. |
| GET /api/agent/exchange/{id} | Exchange detail. |
| GET /api/agent/withdraw-accounts/config | Withdrawal config. |
| GET /api/agent/withdraw-accounts/methods/list | Payout methods. |
| GET /api/agent/withdraw-accounts/methods/{id}/details | Method fields. |
| GET /api/agent/withdraw-accounts | List payout accounts. |
| POST /api/agent/withdraw-accounts | Save a payout account. |
| GET /api/agent/withdraw-accounts/{withdraw_account} | Payout account detail. |
| PUT /api/agent/withdraw-accounts/{withdraw_account} | Update a payout account. |
| DELETE /api/agent/withdraw-accounts/{withdraw_account} | Delete a payout account. |
| POST /api/agent/withdraw | Request settlement payout. Idempotent, KYC-gated. |
| GET /api/agent/kyc | KYC status. |
| POST /api/agent/kyc | Submit KYC documents. |
| GET /api/agent/kyc/history | KYC history. |
| GET /api/agent/kyc/rejected-data | Rejected documents. |
| GET /api/agent/kyc-level/levels | Levels & requirements. |
| GET /api/agent/kyc-level/badge | Current badge. |
| GET /api/agent/kyc-level/status | Current + next level. |
| POST /api/agent/kyc-level/submit | Apply for next level. |
| POST /api/agent/settings/profile | Update profile. |
| POST /api/agent/settings/2fa/{type} | Enable/disable 2FA. |
| POST /api/agent/settings/passcode/verify | Verify transaction PIN. |
| POST /api/agent/settings/account-close | Request account closure. |
| POST /api/agent/settings/change-password | Change password. |
| GET /api/agent/ticket/config | Ticket config. |
| GET /api/agent/ticket | List tickets. |
| POST /api/agent/ticket | Open a ticket. |
| GET /api/agent/ticket/{ticket} | Ticket detail. |
| POST /api/agent/ticket/reply/{uuid} | Reply. |
| POST /api/agent/ticket/action/{uuid} | Close / reopen. |
These endpoints need no token (or only the user token where noted). They power the landing page, onboarding, and the hosted checkout.
| Endpoint | Description |
|---|---|
| GET /api/get-currencies | All currencies with symbols & decimal rules. |
| GET /api/get-countries | Countries (code, name, flag). |
| GET /api/get-banks | Bank list (Shaparak + international). |
| GET /api/get-branches | Bank branches. |
| GET /api/get-card-providers | Card providers (BSI, …). |
| GET /api/get-withdraw-methods | Withdrawal methods. |
| GET /api/get-bill-countries/{type} | Bill services per country/type. |
| GET /api/get-settings / /api/get-settings-v2 | Public site settings (limits, features, branding). |
| GET /api/get-register-fields/{type} | Registration fields per role (user/merchant/agent). |
| GET /api/get-kyc-status | KYC level requirements (public). |
| GET /api/get-passcode-status | Passcode feature flags. |
| GET /api/get-notification-types/{type} | Notification type definitions. |
| GET /api/get-transaction-types-and-statuses | Transaction type & status enums. |
| GET /api/get-languages | Supported languages. |
| GET /api/get-navigation | Site navigation data. |
| GET /api/get-onboarding-screen-images | Onboarding carousel images. |
| GET /api/get-plugins | Enabled platform modules. |
| GET /api/get-notifications | Public announcements. |
| GET /api/mark-as-read-notification | Mark a notification read. |
| GET /api/terms-conditions | Terms & conditions text. |
| GET /api/app-version / /api/version | Latest app version + APK download URL + SHA-256 (used by the mobile client for update checks). |
| GET /api/convert/{from}/{to}/{amount?} | Quick currency conversion (public, cached rates). |
| POST /api/setup-fcm | Register a Firebase device token for push notifications. |
| POST /api/submit-contact-form | Contact form submission. |
| POST /api/subscribe-now | Newsletter subscription. |
| Endpoint | Description |
|---|---|
| GET /api/home-data | Landing page content (hero, features, stats). |
| GET /api/page-data/{code} | Any CMS page by code. |
| GET /api/blogs | Blog list. |
| GET /api/blog-details/{id} | Blog post. |
| GET /api/navigations-data | Header/footer navigation. |
The /pay/{transaction_id} page calls these to let a payer pay with wallet / gift / gateway. They are rate-limited and bound to the transaction.
| Endpoint | Description |
|---|---|
| POST /api/pay/verify-uid | Verify the payer's UID / phone for the transaction. |
| POST /api/pay/verify-wallet | Verify wallet password (or email on first external payment). |
| POST /api/pay/generate-otp | Generate an OTP for the payment. |
| POST /api/pay/request-otp | Request OTP delivery (SMS/email). |
| GET /api/pay/rates | Rates available on the checkout page. |
| GET /api/pay/gateways | Enabled gateways for the transaction's currency. |
| GET /api/pay/qr-status | Poll QR / pending payment status. |
| Endpoint | Description |
|---|---|
| GET /api/epay/overview | ePay dashboard payload. |
| GET /api/epay/cards | ePay cards list. |
| GET /api/epay/cards/{id} | Card detail. |
| POST /api/epay/cards/issue | Issue a new ePay card. |
| POST /api/epay/cards/topup | Top up a card. |
| GET /api/epay/deposit/methods | Deposit methods. |
| GET /api/epay/deposit/wallets | Deposit wallets. |
| POST /api/epay/deposit | Create a deposit. |
International travel services (flights, hotels, SIM). Requires the user token.
| Endpoint | Description |
|---|---|
| GET /api/auth/user/travel/destinations | Destinations. |
| GET /api/auth/user/travel/flights | Flight search. |
| GET /api/auth/user/travel/flights/airports | Airports. |
| GET /api/auth/user/travel/hotels | Hotel search. |
| GET /api/auth/user/travel/hotels/{id} | Hotel detail. |
| GET /api/auth/user/travel/hotels/{id}/rates | Hotel rates. |
| POST /api/auth/user/travel/hotels/book | Book a hotel. |
| GET /api/auth/user/travel/bookings | Your bookings. |
| GET /api/auth/user/travel/bookings/{id}/voucher | Booking voucher. |
| GET /api/auth/user/travel/next-trip | Next trip summary. |
| GET /api/auth/user/travel/travelers | Traveller profiles. |
| POST /api/auth/user/travel/travelers | Add a traveller. |
| DELETE /api/auth/user/travel/travelers/{id} | Delete a traveller. |
| GET /api/auth/user/travel/sim/packages | SIM packages. |
| GET /api/auth/user/travel/sim/my-cards | Your SIM cards. |
| GET /api/auth/user/travel/sim/usage/{iccid} | SIM usage. |
Browser-facing pages and server-to-server callbacks. Merchants only need §4.6 (status check) and §4.5 (their own IPN); the rest is internal plumbing.
| Endpoint | Description |
|---|---|
| GET /pay/{transaction_id} | Classic hosted checkout (Livewire). Wallet / gift / gateway. |
| GET /pro-pay/{transaction_id} | Pro hosted checkout (current default). /sandbox/pay/{id} redirects here. |
| POST /pro-pay/process | Process a gateway selection on the Pro page. |
| GET /pro-pay/result/{tnx} | Return from a gateway (Shaparak / Alipay …) — verifies & shows result. |
| GET /gateway/test-payment | Shaparak sandbox page. |
| GET /gateway/china-payment | China gateway sandbox page. |
| ANY /status/success / /status/cancel | Public success / cancel screens. |
| GET /payment/success/{reftrn} | JSON status of a transaction (see §4.6). |
| GET /non-hosted-gateway/{gateway}/{tnx} | Redirect into a non-hosted gateway (PayPal, …). |
Each gateway calls its own IPN. These are signed / token-verified per gateway; do not call them manually.
| Gateway | IPN path |
|---|---|
| Shaparak — Melli | POST /ipn/melli |
| Shaparak — Saman | GET /ipn/saman |
| Shaparak — Pasargad | GET /ipn/pasargad |
| Shaparak — IPG | GET /ipn/ipg |
| Alipay | POST /ipn/alipay |
| WeChat Pay | POST /ipn/wechatpay |
| UnionPay | POST /ipn/unionpay |
| e-CNY | POST /ipn/ecny |
| Stripe | POST /api/webhooks/gateway/stripe |
| PayPal | GET /ipn/paypal + POST /api/webhooks/gateway/paypal |
| Crypto (CoinPayments, NowPayments, Cryptomus, Coingate, BTCPay, Binance, Blockchain, …) | POST /ipn/{gateway} — see routes/payment.php for the full list |
Generic gateway webhook: POST /api/webhooks/gateway/{gateway} — used by gateways that POST a JSON payload with a shared secret.
| Code | Meaning | Remedy |
|---|---|---|
| 400 | Validation error (amount, currency wallet, transaction_id length…) | Read the errors object in the envelope. |
| 401 | Token missing / invalid / expired / wrong role | Re-login; check the role matches the route prefix. |
| 403 | Account blocked, feature disabled, or KYC level too low | Complete KYC; check account status in the panel. |
| 404 | Unknown route / resource | Check the path & id. |
| 422 | Unprocessable (e.g. idempotent replay with different body) | Keep the same body for the same Idempotency-Key. |
| 429 | Rate limited | Back off; limits in §3. |
| 500 | Internal error | Open a support ticket with the tnx reference. |
Sandbox: POST /api/merchant/sandbox/access-token and POST /api/merchant/sandbox/make-payment behave identically to the live endpoints but create sandbox transactions (no real money, Shaparak test gateway). The hosted page /sandbox/pay/{id} redirects to the Pro checkout.