YallaPay Staging - Documentation

Verify Payment via API

Confirm a transaction's status server-side using its transaction ID. Use this endpoint to validate a payment before fulfilling an order.

Endpoint

POST Verify payment

https://staging.yallapay.net/api/transaction/verify

Headers

Accept	application/json
Content-Type	application/json

Request Body

BODY formdata

private_key	Merchant Private Key (From merchant Dashboard)
trx_id	Transaction ID, e.g "123456789"

In body add private_key and trx_id with their values from the merchant profile credentials and transactions page.

cURL Example

curl -X POST "https://staging.yallapay.net/api/transaction/verify" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "private_key": "YOUR_PRIVATE_KEY",
    "trx_id": "123456789"
  }'

Always verify before fulfilling

Even if the customer is redirected back to your success page, call this endpoint server-side to confirm the payment is genuinely completed.

Response

A found transaction comes back as a single-element array. Amounts are strings with two decimals; the currency is AED.

[
  {
    "trx_id": "07071234567890123456",
    "amount": "250.00",
    "fees": "7.25",
    "net_amount": "242.75",
    "currency": "AED",
    "status": "Paid",
    "external_id": "12345",
    "gateway_name": "…"
  }
]

Fields

trx_id	The transaction id you asked about.
amount	What the customer was charged.
fees	Processing fee deducted from this payment.
net_amount	What settles to you — the amount to reconcile against your payout.
currency	AED.
status	`Paid`, `Failed`, `Refunded`, `Disputed` or `Initiated`. Fulfil only on `Paid`.
external_id	The id you sent when you created the link, so you can match it to your order.
gateway_name	Internal routing detail. Ignore it — never build logic on this value.

Errors

An unknown transaction id returns 404, and a key belonging to an account that is not approved returns 401. Neither is a payment failure — treat them as "unknown", retry, and never mark an order as failed on their basis.

404 {
  "error": "Transaction not found."
}

401 {
  "error": "Your account is not approved for transactions.
            Please check your KYC status."
}

Where to find a transaction id

In your dashboard under Payment Report — the Trx Id column, which you can also search on.
In the trxid parameter on the return URL the customer comes back to.
In the webhook payload — the reliable one, because it reaches you even if the customer closes the tab.

Webhook