ECARDO

ECARDO API Reference

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.

Base URL: https://origin-api.ecardo.ir Version 2.0 Format: JSON Currencies: IRT · USD · CNY · USDT

1. Overview & Architecture

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.

2. Authentication

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.

A. App accounts — Sanctum Bearer tokens

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
EndpointDescription
POST /api/auth/user/registerRegister a new user account (email + password + profile fields). Triggers email verification.
POST /api/auth/user/loginLogin. Returns Sanctum token + user payload. Rate-limited (brute-force protection).
POST /api/auth/user/logoutInvalidate the current token.
POST /api/auth/user/refreshRotate the current token (long-lived sessions).
GET /api/auth/user/getGet the currently authenticated user profile.
POST /api/auth/user/forgot-passwordRequest a password-reset OTP / email.
POST /api/auth/user/reset-verify-otpVerify the reset OTP.
POST /api/auth/user/reset-passwordSet the new password.
POST /api/auth/user/send-verify-emailRe-send email verification link.
POST /api/auth/user/validate-verify-emailValidate the email verification token.
POST /api/auth/user/2fa/verifyVerify Google Authenticator 2FA code when enabled on the account.
POST /api/auth/user/personal-info-updateUpdate 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.

B. Merchant gateway credentials (external websites)

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.

3. Conventions & Security

Common headers

HeaderWherePurpose
Authorization: Bearer <token>All role APIsSanctum token obtained at login.
Accept: application/jsonAll APIsForces JSON error responses instead of HTML redirects.
Content-Type: application/jsonPOST/PUTJSON body (multipart for file uploads).
Idempotency-Key: <uuid>Money-moving POSTsOptional but recommended. Same user + route + key within 24h replays the original result instead of double-charging.

Standard response envelope

// success
{ "status": "success", "data": { ... } }

// validation / business error
{ "status": "error", "message": "Insufficient balance.", "errors": { "amount": ["The amount must be greater than 0."] } }

KYC feature gates

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:

  • Level 1 features: add-money, payment, transfer, cashout, withdraw, exchange, gift, request-money
  • Level 2 features: remittance (store & upload), P2P order release

Currencies

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.

Rate limits

ScopeLimit
Auth endpoints (login/register/forgot)Throttled per IP — brute-force protection
Exchange rate / calculate30 requests / minute
Passcode verify5 attempts / minute
Payment status poll30 requests / minute
Merchant API (all)30 requests / minute per IP

4. Merchant Payment API

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.

4.1 Payment flow

1
Get access token
POST /api/merchant/access-token with public_key + secret_key
2
Create payment
POST /api/merchant/make-payment — returns a hosted payment_url
3
Redirect the user
Send the user (link or iframe) to payment_url. They choose Wallet / Gift / Gateway.
4
User pays
After "SUCCESS – Payment has been completed." an 8-second countdown returns them to your callback_url automatically (or they click Return to Sender Site Now).
5
Verify
IPN hits your server with an HMAC-SHA256 signature; verify before delivering goods.

4.2 Get Access Token POST /api/merchant/access-token

curl -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
}
Tokens are cached and valid for 30 minutes. Re-requesting the same public_key returns the same token until it expires.

4.3 Create Payment POST /api/merchant/make-payment

FieldTypeRequiredDescription
amountnumericYesPayment amount
currencystring (3-4)YesIRR, IRT, USD, CNY … (a wallet of yours in this currency must exist — case-insensitive)
transaction_idstring ≤ 12YesYour unique order reference
descriptionstring ≤ 20YesShown to the payer
callback_urlurlNoPublic HTTPS URL for user return after payment
ipn_urlurlNoServer-to-server webhook URL
customer_namestring ≤ 50NoPayer name
customer_emailstring ≤ 50NoPayer 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"
}
The 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.

4.4 Redirect & Callback

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.

  • If your callback_url already contains a ?, the params are appended with &.
  • The countdown starts only on the SUCCESS page — cancelled payments show a CANCELLED screen without redirect.
  • Refreshing the SUCCESS page restarts the countdown and re-redirects safely.
Important: The callback only tells you the user came back. Trust the IPN (§4.5) or the status endpoint (§4.6) — never the redirect alone.

4.5 IPN — Instant Payment Notification POST to your ipn_url

When 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
Respond with HTTP 200 quickly; we don't retry forever. Verify the signature before any business logic.

4.6 Status Check (backup) GET /payment/success/{TRX…}

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", … }
}
Poll it server-side (e.g. when the user returns to callback_url?tnx=…&status=success) and match data.manual_field_data.transaction_id against your order before delivering goods.

4.7 Gift Payments

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.

  • The payer identifies with UID or verified phone number (09xx… / +989xx… / 989xx… all work).
  • First payment from an external site: the payer must confirm their email and their wallet password (two-step verification).
  • Later payments only need the wallet password.
  • The gift must be in the same currency as your payment request and must cover the full amount; any leftover is returned to the payer's eCardo wallet.
  • The payer cannot redeem their own gift against your payment.

You receive the result exactly like a wallet payment — same callback, same IPN, same status endpoint.

4.8 Embed / iframe

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>
  • The iframe must be served over HTTPS.
  • Never render the iframe on pages with sensitive third-party scripts.
  • Or skip embedding and simply redirect the user — both are fully supported.

4.9 Merchant app endpoints (authenticated)

Merchants also use the app/panel API with their Sanctum token:

EndpointDescription
GET /api/merchant/transactionsMerchant transaction list (payments received, exchange, withdrawals).
GET /api/merchant/activity-chartTime-series activity for dashboard charts.
GET /api/merchant/circle-chartCategory breakdown (pie chart data).
GET /api/merchant/qrcodeMerchant QR payload (UID / phone) for wallet top-ups.
GET /api/merchant/mark-as-read-notificationMark in-app notifications as read.
GET /api/merchant/walletsList merchant wallets (per currency).
POST /api/merchant/walletsOpen a new wallet for a supported currency.
DELETE /api/merchant/wallets/{wallet}Close a wallet (only when balance is zero).
GET /api/merchant/access-keysCurrent public_key / secret_key pair.
POST /api/merchant/access-keys/regenerateRotate credentials — old keys stop working immediately.
GET /api/merchant/exchange/configAvailable exchange pairs & limits.
GET /api/merchant/exchange/rateLive exchange rate (30 req/min).
POST /api/merchant/exchange/calculateQuote: how much you receive for an amount (no execution).
POST /api/merchant/exchangeExecute a currency exchange between your wallets (KYC-gated, idempotent).
GET /api/merchant/exchange/historyExchange history.
GET /api/merchant/exchange/{id}Single exchange detail.
GET /api/merchant/invoices/configInvoice settings (number prefix, etc.).
GET /api/merchant/invoicesList invoices.
POST /api/merchant/invoicesCreate 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/configWithdrawal configuration & limits.
GET /api/merchant/withdraw-accounts/methods/listAvailable payout methods (Shaba, SWIFT, …).
GET /api/merchant/withdraw-accounts/methods/{id}/detailsFields required by a specific payout method.
GET /api/merchant/withdraw-accountsList saved payout accounts.
POST /api/merchant/withdraw-accountsSave 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/withdrawRequest a payout to a saved account (KYC-gated, idempotent, approval-based).
GET /api/merchant/kycCurrent KYC status.
POST /api/merchant/kycSubmit KYC documents.
GET /api/merchant/kyc/historyKYC submission history.
GET /api/merchant/kyc/rejected-dataRejected document details (for resubmission).
GET /api/merchant/kyc-level/levelsAll KYC levels & their requirements.
GET /api/merchant/kyc-level/badgeCurrent level badge payload.
GET /api/merchant/kyc-level/statusCurrent level + next level + required documents.
POST /api/merchant/kyc-level/submitApply for the next KYC level.
POST /api/merchant/settings/profileUpdate profile.
POST /api/merchant/settings/2fa/{type}Enable/disable 2FA (google / email).
POST /api/merchant/settings/change-passwordChange password.
GET /api/merchant/ticket/configSupport-ticket categories.
GET /api/merchant/ticketList support tickets.
POST /api/merchant/ticketOpen 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.

5. User API

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.

5.1 Dashboard & Activity

EndpointDescription
GET /api/user/dashboardHome payload: balances, pending items, quick stats.
GET /api/user/statisticsAggregate statistics (totals, counts by type/status).
GET /api/user/transactionsPaginated transaction list (filter by type, status, date).
GET /api/user/transaction/{tnx}Full detail of one transaction by tnx reference.
GET /api/user/qrcodeUser QR payload (UID / phone) — used for receiving wallet top-ups.
GET /api/user/activity-chartTime-series activity for the dashboard chart.

5.2 Wallets

EndpointDescription
GET /api/user/walletsList all wallets with balances (IRT, USD, CNY, USDT).
POST /api/user/walletsOpen a wallet for a new currency { "currency": "USD" }.
DELETE /api/user/wallets/{wallet}Close a wallet (must be zero balance).

5.3 Add Money (top-up)

EndpointDescription
GET /api/user/add-moneyAvailable top-up methods & limits (Shaparak banks, QR, …).
POST /api/user/add-moneyCreate a top-up request { "amount", "currency", "method" } → returns gateway redirect URL. KYC-gated.

5.4 Payments (in-app)

EndpointDescription
GET /api/user/payment/settingsPayment settings (default currency, limits).
POST /api/user/payment/makePay from wallet to a UID / phone / beneficiary (KYC-gated).
GET /api/user/payment/historyPayment history.
GET /api/user/payment-status/{tnx}Live status of any transaction (30 req/min) — used by the app after a gateway return.

5.5 Pay Bill (utility bills)

EndpointDescription
GET /api/user/pay-bill/services/{country}/{type}Bill services available for a country/type (electricity, water, …).
POST /api/user/pay-billPay a bill { "service", "bill_number", "amount", "currency" }. Idempotent, KYC-gated.
GET /api/user/pay-bill/historyBill payment history.

5.6 Passcode (transaction PIN)

The transaction PIN is not the login password and not 2FA — it protects money movement.

EndpointDescription
GET /api/user/passcode/statushas_passcode + feature flags.
POST /api/user/passcodeSet the PIN the first time { "passcode", "passcode_confirmation" }.
POST /api/user/passcode/changeChange the PIN { "old_passcode", "passcode", "passcode_confirmation" }.
POST /api/user/passcode/disableDisable the PIN (requires the login password).
POST /api/user/passcode/verifyVerify a PIN (5 attempts/min).

5.7 Invoices

EndpointDescription
GET /api/user/invoices/configInvoice configuration.
GET /api/user/invoicesList invoices.
POST /api/user/invoicesCreate 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}/payPay an invoice from wallet (KYC-gated).

5.8 Payment Links (request-to-pay)

EndpointDescription
POST /api/user/payment-links/createCreate a shareable payment link { "amount", "currency", "description" } → returns a public URL anyone can pay. KYC-gated.
GET /api/user/payment-links/historyYour payment links with paid/pending status.

5.9 Request Money

EndpointDescription
GET /api/user/request-money/configFeature config & limits.
POST /api/user/request-moneySend a money request to a UID/phone { "to", "amount", "currency", "note" }. KYC-gated.
GET /api/user/request-money/historyRequests sent & received.
POST /api/user/request-money/{id}/actionAccept / reject a request. Accepting debits the payer immediately. KYC-gated.

5.10 Gifts

EndpointDescription
GET /api/user/gifts/configGift feature config.
POST /api/user/giftsCreate a gift code { "amount", "currency", "to_uid", "message" }. Idempotent, KYC-gated.
POST /api/user/gifts/redeemRedeem a gift code into your wallet { "code" }. Idempotent, KYC-gated.
GET /api/user/gifts/historyGifts you created / received.
GET /api/user/gifts/redeem/historyRedemption history.

5.11 Transfer Money

EndpointDescription
GET /api/user/transfer/configTransfer limits & config.
POST /api/user/transferTransfer between users { "to", "amount", "currency", "passcode" }. Idempotent, KYC-gated.
GET /api/user/transfer/historyTransfer history.

5.12 Beneficiaries

EndpointDescription
GET /api/user/beneficiariesList saved beneficiaries.
POST /api/user/beneficiariesAdd 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.

5.13 Cashout

EndpointDescription
GET /api/user/cashout/configCashout limits & methods.
POST /api/user/cashoutCash out to a beneficiary/agent { "to", "amount", "currency", "passcode" }. Idempotent, KYC-gated.
GET /api/user/cashout/historyCashout history.

5.14 Withdraw (payout to bank)

EndpointDescription
GET /api/user/withdraw-accounts/configWithdrawal configuration & limits.
GET /api/user/withdraw-accounts/methods/listPayout methods (Shaba, SWIFT, …).
GET /api/user/withdraw-accounts/methods/{id}/detailsFields required by a method.
GET /api/user/withdraw-accountsList saved payout accounts.
POST /api/user/withdraw-accountsSave 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/withdrawRequest a payout { "withdraw_account_id", "amount", "currency" }. Idempotent, KYC-gated, approval-based.

5.15 Exchange

EndpointDescription
GET /api/user/exchange/configAvailable pairs & limits.
GET /api/user/exchange/rateLive rate (30 req/min).
POST /api/user/exchange/calculateQuote without executing { "from", "to", "amount" }.
POST /api/user/exchangeExecute exchange between your wallets. Idempotent, KYC-gated.
GET /api/user/exchange/historyExchange history.
GET /api/user/exchange/{id}Single exchange detail.

5.16 Referral

EndpointDescription
GET /api/user/referral/infoYour referral link, code, totals & commission settings.
GET /api/user/referral/directDirect referrals list.
GET /api/user/referral/treeFull referral tree (multi-level).

5.17 Settings & Security

EndpointDescription
POST /api/user/settings/profileUpdate profile fields.
POST /api/user/settings/2fa/{type}Enable/disable 2FA (google / email).
POST /api/user/settings/passcode/verifyVerify transaction PIN (5 attempts/min).
POST /api/user/settings/change-passwordChange login password.
POST /api/user/settings/account-closeRequest account closure (admin review).
GET /api/user/settings/notification-prefsNotification preferences.
POST /api/user/settings/notification-prefsUpdate notification preferences.

5.18 KYC

EndpointDescription
GET /api/user/kycCurrent KYC status.
POST /api/user/kycSubmit KYC documents (multipart: national ID, selfie, …).
GET /api/user/kyc/historySubmission history.
GET /api/user/kyc/rejected-dataRejected document details.
GET /api/user/kyc-level/levelsAll levels & requirements.
GET /api/user/kyc-level/badgeCurrent level badge.
GET /api/user/kyc-level/statusCurrent + next level + required docs.
POST /api/user/kyc-level/submitApply for next level.

5.19 Support Tickets

EndpointDescription
GET /api/user/ticket/configCategories & config.
GET /api/user/ticketList tickets.
POST /api/user/ticketOpen 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.

5.20 Remittance (international transfers)

EndpointDescription
GET /api/user/remittance/methodsAvailable corridors & methods (country, currency, limits).
POST /api/user/remittance/quoteServer-side quote { "from_currency", "to_currency", "amount", "method" } — includes fee & rate snapshot.
POST /api/user/remittance/storeCreate a remittance from a quote { "quote_id", "receiver", "documents" }. KYC level 2, idempotent.
GET /api/user/remittance/historyRemittance history.
GET /api/user/remittance/{uuid}Remittance detail (state machine: pending → approved → settled / refunded).
POST /api/user/remittance/{uuid}/uploadUpload missing documents (multipart). KYC level 2.

5.21 Virtual Cards (BSI)

EndpointDescription
GET /api/user/card-productsAvailable card products.
GET /api/user/card-products/{product}Card product detail.
GET /api/user/cardholdersCardholders.
GET /api/user/cardsList your cards.
POST /api/user/cardsOrder 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-topupTop 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-ordersCard 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).

5.22 Gift Cards (purchase)

EndpointDescription
GET /api/user/gift-cards/categoriesGift card categories.
GET /api/user/gift-cards/countriesAvailable countries.
GET /api/user/gift-cards/productsGift card products (Steam, Amazon, …).
GET /api/user/gift-cards/product-details/{product_id}Product detail & denominations.
POST /api/user/gift-cards/product/orderOrder a gift card { "product_id", "denomination", "quantity" }.
GET /api/user/gift-cards/purchased-historyPurchase history.

5.23 P2P Trading

EndpointDescription
GET /api/user/p2p/marketplaceMarketplace ads (buy/sell).
GET /api/user/p2p/marketplace/configMarketplace config.
GET /api/user/p2p/marketplace/{id}Ad detail.
GET /api/user/p2p/adsYour ads.
POST /api/user/p2p/adsCreate 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/eligibilityCan this user trade? (KYC + flags).
GET /api/user/p2p/ads/highest-order-priceBest (highest) order price on the market.
GET /api/user/p2p/ads/{id}/payment-methodsSeller's payment methods for an ad.
PATCH /api/user/p2p/ads/{id}/status-updateUpdate ad status (active/paused).
GET /api/user/p2p/ordersYour P2P orders.
POST /api/user/p2p/ordersCreate an order against an ad (funds escrowed).
GET /api/user/p2p/orders/{id}Order detail.
POST /api/user/p2p/orders/{id}/cancelCancel an order.
POST /api/user/p2p/orders/{id}/disputeOpen a dispute.
POST /api/user/p2p/orders/{id}/mark-paidBuyer marks bank payment as sent.
POST /api/user/p2p/orders/{id}/releaseSeller releases escrowed funds (KYC level 2).
PATCH /api/user/p2p/orders/{id}/payment-methodSet the payment method for an order.
GET /api/user/p2p/orders/{id}/messagesOrder chat messages.
POST /api/user/p2p/orders/{id}/messagesSend a chat message.
GET /api/user/p2p/payment-accountsYour P2P payment accounts (bank accounts used in P2P).
POST /api/user/p2p/payment-accountsAdd 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-methodsAvailable P2P payment methods.
POST /api/user/p2p/verified-trader-application/applyApply for verified-trader status.
GET /api/user/p2p/verified-trader-application/statusApplication status.

6. Agent API

Agents (exchange offices / cash-in operators) use Authorization: Bearer <agent-token>. Same conventions as the User API (envelope, idempotency, KYC gates).

EndpointDescription
GET /api/agent/dashboardAgent home payload (balances, pending settlements).
GET /api/agent/transactionsAgent transaction list.
GET /api/agent/circle-chartsCategory breakdown.
GET /api/agent/transaction-chartTime-series activity.
GET /api/agent/qrcodeAgent QR payload (for receiving cash-in).
GET /api/agent/mark-as-read-notificationMark notifications read.
GET /api/agent/walletsAgent wallets.
POST /api/agent/walletsOpen a wallet.
DELETE /api/agent/wallets/{wallet}Close a wallet.
GET /api/agent/add-moneyTop-up methods for the agent.
POST /api/agent/add-moneyCreate a top-up request. KYC-gated.
GET /api/agent/cashin/configCash-in config & limits.
POST /api/agent/cashinRecord a cash-in for a user { "user", "amount", "currency", "reference" }. Idempotent, KYC-gated.
GET /api/agent/cashin/historyCash-in history.
GET /api/agent/exchange/configExchange pairs & limits.
GET /api/agent/exchange/rateLive rate (30 req/min).
POST /api/agent/exchange/calculateQuote.
POST /api/agent/exchangeExecute exchange. Idempotent, KYC-gated.
GET /api/agent/exchange/historyExchange history.
GET /api/agent/exchange/{id}Exchange detail.
GET /api/agent/withdraw-accounts/configWithdrawal config.
GET /api/agent/withdraw-accounts/methods/listPayout methods.
GET /api/agent/withdraw-accounts/methods/{id}/detailsMethod fields.
GET /api/agent/withdraw-accountsList payout accounts.
POST /api/agent/withdraw-accountsSave 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/withdrawRequest settlement payout. Idempotent, KYC-gated.
GET /api/agent/kycKYC status.
POST /api/agent/kycSubmit KYC documents.
GET /api/agent/kyc/historyKYC history.
GET /api/agent/kyc/rejected-dataRejected documents.
GET /api/agent/kyc-level/levelsLevels & requirements.
GET /api/agent/kyc-level/badgeCurrent badge.
GET /api/agent/kyc-level/statusCurrent + next level.
POST /api/agent/kyc-level/submitApply for next level.
POST /api/agent/settings/profileUpdate profile.
POST /api/agent/settings/2fa/{type}Enable/disable 2FA.
POST /api/agent/settings/passcode/verifyVerify transaction PIN.
POST /api/agent/settings/account-closeRequest account closure.
POST /api/agent/settings/change-passwordChange password.
GET /api/agent/ticket/configTicket config.
GET /api/agent/ticketList tickets.
POST /api/agent/ticketOpen a ticket.
GET /api/agent/ticket/{ticket}Ticket detail.
POST /api/agent/ticket/reply/{uuid}Reply.
POST /api/agent/ticket/action/{uuid}Close / reopen.

7. Public & Platform APIs

These endpoints need no token (or only the user token where noted). They power the landing page, onboarding, and the hosted checkout.

7.1 Platform data

EndpointDescription
GET /api/get-currenciesAll currencies with symbols & decimal rules.
GET /api/get-countriesCountries (code, name, flag).
GET /api/get-banksBank list (Shaparak + international).
GET /api/get-branchesBank branches.
GET /api/get-card-providersCard providers (BSI, …).
GET /api/get-withdraw-methodsWithdrawal methods.
GET /api/get-bill-countries/{type}Bill services per country/type.
GET /api/get-settings / /api/get-settings-v2Public site settings (limits, features, branding).
GET /api/get-register-fields/{type}Registration fields per role (user/merchant/agent).
GET /api/get-kyc-statusKYC level requirements (public).
GET /api/get-passcode-statusPasscode feature flags.
GET /api/get-notification-types/{type}Notification type definitions.
GET /api/get-transaction-types-and-statusesTransaction type & status enums.
GET /api/get-languagesSupported languages.
GET /api/get-navigationSite navigation data.
GET /api/get-onboarding-screen-imagesOnboarding carousel images.
GET /api/get-pluginsEnabled platform modules.
GET /api/get-notificationsPublic announcements.
GET /api/mark-as-read-notificationMark a notification read.
GET /api/terms-conditionsTerms & conditions text.
GET /api/app-version / /api/versionLatest 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-fcmRegister a Firebase device token for push notifications.
POST /api/submit-contact-formContact form submission.
POST /api/subscribe-nowNewsletter subscription.

7.2 Website content

EndpointDescription
GET /api/home-dataLanding page content (hero, features, stats).
GET /api/page-data/{code}Any CMS page by code.
GET /api/blogsBlog list.
GET /api/blog-details/{id}Blog post.
GET /api/navigations-dataHeader/footer navigation.

7.3 Hosted checkout (Pro-Pay) — used by the payment page itself

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.

EndpointDescription
POST /api/pay/verify-uidVerify the payer's UID / phone for the transaction.
POST /api/pay/verify-walletVerify wallet password (or email on first external payment).
POST /api/pay/generate-otpGenerate an OTP for the payment.
POST /api/pay/request-otpRequest OTP delivery (SMS/email).
GET /api/pay/ratesRates available on the checkout page.
GET /api/pay/gatewaysEnabled gateways for the transaction's currency.
GET /api/pay/qr-statusPoll QR / pending payment status.

7.4 ePay (e-CNY / international cards)

EndpointDescription
GET /api/epay/overviewePay dashboard payload.
GET /api/epay/cardsePay cards list.
GET /api/epay/cards/{id}Card detail.
POST /api/epay/cards/issueIssue a new ePay card.
POST /api/epay/cards/topupTop up a card.
GET /api/epay/deposit/methodsDeposit methods.
GET /api/epay/deposit/walletsDeposit wallets.
POST /api/epay/depositCreate a deposit.

7.5 Travel (user token)

International travel services (flights, hotels, SIM). Requires the user token.

EndpointDescription
GET /api/auth/user/travel/destinationsDestinations.
GET /api/auth/user/travel/flightsFlight search.
GET /api/auth/user/travel/flights/airportsAirports.
GET /api/auth/user/travel/hotelsHotel search.
GET /api/auth/user/travel/hotels/{id}Hotel detail.
GET /api/auth/user/travel/hotels/{id}/ratesHotel rates.
POST /api/auth/user/travel/hotels/bookBook a hotel.
GET /api/auth/user/travel/bookingsYour bookings.
GET /api/auth/user/travel/bookings/{id}/voucherBooking voucher.
GET /api/auth/user/travel/next-tripNext trip summary.
GET /api/auth/user/travel/travelersTraveller profiles.
POST /api/auth/user/travel/travelersAdd a traveller.
DELETE /api/auth/user/travel/travelers/{id}Delete a traveller.
GET /api/auth/user/travel/sim/packagesSIM packages.
GET /api/auth/user/travel/sim/my-cardsYour SIM cards.
GET /api/auth/user/travel/sim/usage/{iccid}SIM usage.

8. Hosted Checkout & Gateway IPN

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.

8.1 Hosted pages

EndpointDescription
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/processProcess a gateway selection on the Pro page.
GET /pro-pay/result/{tnx}Return from a gateway (Shaparak / Alipay …) — verifies & shows result.
GET /gateway/test-paymentShaparak sandbox page.
GET /gateway/china-paymentChina gateway sandbox page.
ANY /status/success / /status/cancelPublic 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, …).

8.2 Gateway IPN endpoints (server-to-server)

Each gateway calls its own IPN. These are signed / token-verified per gateway; do not call them manually.

GatewayIPN path
Shaparak — MelliPOST /ipn/melli
Shaparak — SamanGET /ipn/saman
Shaparak — PasargadGET /ipn/pasargad
Shaparak — IPGGET /ipn/ipg
AlipayPOST /ipn/alipay
WeChat PayPOST /ipn/wechatpay
UnionPayPOST /ipn/unionpay
e-CNYPOST /ipn/ecny
StripePOST /api/webhooks/gateway/stripe
PayPalGET /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.

9. Errors, Limits & Sandbox

CodeMeaningRemedy
400Validation error (amount, currency wallet, transaction_id length…)Read the errors object in the envelope.
401Token missing / invalid / expired / wrong roleRe-login; check the role matches the route prefix.
403Account blocked, feature disabled, or KYC level too lowComplete KYC; check account status in the panel.
404Unknown route / resourceCheck the path & id.
422Unprocessable (e.g. idempotent replay with different body)Keep the same body for the same Idempotency-Key.
429Rate limitedBack off; limits in §3.
500Internal errorOpen 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.