IQIraQPayAPI Reference

Notices & Limitations

Please review these rules before going live. Ignoring them is the most common source of production incidents.

Amounts

  • Currency is always IQD; send plain numbers (25000), no separators, no currency symbol.
  • Deposits must be a multiple of your site's step (default 250 IQD) and within min/max of both your site and the method.
  • Credit the user with the callback's amount, never with the amount you requested.

Idempotency

  • processId must be unique per transaction in your system; re-sending it returns the original transaction.
  • A user with a pending deposit gets the same deposit back (alreadyPending: true) — do not create a parallel request for the same user.
  • Process each callback once per (transactionId, status).

Expiry

  • Deposits expire after the window configured for your site (default 30 minutes) → callback unsuccessful / expired. A transfer that arrives late can still be approved by operators, in which case you will receive a second callback with successful. Handle this as a correction.

Security

  • Keep appSecret on your backend only. Rotate it from the panel if exposed; the old secret stops working immediately.
  • Verify X-IraQPay-Signature on every callback; do not rely on IP filtering for callbacks.
  • Enable the IP allowlist for your servers so withdrawals can only be created from them.

Rate limits

  • 600 requests/minute per appKey (all your servers share one quota). Exceeding it returns HTTP 429 with errMessage: "rate_limited" and a Retry-After header — back off, do not retry in a tight loop.
  • Edge protection additionally caps 300 requests per 10 seconds per source IP; bursts above that are blocked for 10 seconds.
  • Status polling: no more than once per 10 seconds per transaction — callbacks are the primary channel.

Support

Include transactionId, processId, timestamp and the exact error body when contacting integrations@deuspay.co. Never send your secret.