Syriatel Cash API: Accept Payments on Your Site
Customers pay to your Syriatel Cash number and enter the transaction ID on your site. Your backend calls a hosted gateway to look up the transfer, compares amounts as integers, and blocks reused IDs with a unique constraint. Same-day setup, $2 per number per month, and a manual confirm path for odd cases.
If your customers are in Syria, many of them will want to pay with Syriatel Cash. A card checkout often fails them, and a bank transfer can sit for days. What usually breaks afterwards is the wait: someone on your side has to open the wallet, find the incoming amount, and mark the order as paid. I take that confirmation off the merchant's phone with a hosted payment gateway for Syriatel Cash.
I build and run that gateway. It gives your app programmatic access to a Syriatel Cash number you already own: you can look up an incoming transfer, check the balance, and talk to a REST API, reachable from outside Syria with no Syrian proxy. It costs $2 per number per month, and setup is same day. You do not receive source code. Your site calls the ready-made gateway and confirms the payment.
The problem the Syriatel Cash API is for
A typical Syrian checkout still looks like this. The customer places an order, copies your wallet number, pays in the Akrab Ilaik app, then sends a screenshot on WhatsApp or types a transaction ID into a form. You unlock your phone, compare the screenshot with the wallet, and update the order.
That holds for a handful of orders a day. It starts to slip when two customers pay around the same time, or when a payment arrives while you are offline. I have seen shops spend more time answering "did you get it?" than packing the order. Some customers pay twice because nobody confirmed the first transfer. Sometimes the same transaction ID is applied to two orders.
You still use the same Syriatel Cash number, and the customer still pays from their wallet. After the transfer, they enter the transaction ID (رقم العملية) on your site. Your site asks the gateway to look that ID up, checks the amount, and confirms the order if the ID is new and the amount matches. I wrote a shorter overview in How to Automate Payment Confirmation for Syrian Wallets. Here I stay on Syriatel Cash and the matching logic you have to ship.
What you need before you write any code
You need a Syriatel Cash number that can receive the payments. The gateway connects to that existing number. Registering the number, and whatever account limits Syriatel has placed on it, stay with Syriatel. Account types and receiving limits differ, and they can change. If you sell high-value items or expect a busy day of transfers, confirm the current limits for your number with Syriatel.
You also need a place in your system that can hold an unpaid order: an amount, a created-at time, a status, a field for the transaction ID the customer types, and later the sender number the gateway returns. That can be a website checkout, a custom invoice, or a bot order.
Syriatel Cash transfers have no memo or reference field for the payer. Do not ask customers to type an order code into the transfer itself; that field is not there. After they pay, the app or the SMS shows a transaction ID. That ID is what they enter on your site.
Sandbox access is available on request. I would not go live before you have sent test amounts through your own flow and typed the resulting IDs into your form. The service is a hosted gateway for Syriatel Cash and Sham Cash, built and run by me, with same-day setup and no source code handover.
The payment flow
- The customer places an order. Your system stores the amount they must pay and the time the order was created.
- You show your Syriatel Cash number (or merchant code) and that exact amount on the confirmation screen, plus a field for the transaction ID. I repeat the amount in plain numerals. People pay the figure they remember from the product card, and a 50 SYP difference is enough to fail the amount check.
- The customer opens Syriatel Cash, usually inside Akrab Ilaik, and sends the transfer to your number.
- After the transfer succeeds, they copy the transaction ID and enter it on your site. Your backend sends that ID to the gateway at a URL you receive during setup (use a placeholder like
YOUR_GATEWAY_URLuntil then). - If the transfer exists, the gateway returns the amount, the time received, and the sender number. The sender number is always returned. Store it on the order; it helps later in support. Do not use it as the matching key. People often pay from a sibling's or a colleague's wallet.
- If the ID was already used on another order, reject it and leave this order unpaid. If the transfer is not found yet, do not consume the ID; the customer may have mistyped it, or the transfer may still be settling. Ask them to wait a moment and try again. If the transfer is found and the amount does not match, flag the order for review and bind that ID to this order so it cannot be reused elsewhere. If the transfer is found, the amount matches, and the ID is new, mark the order paid, store the transaction ID and sender number, and notify both sides.
The payment window is your shop policy. Some stores give an hour, some keep the order open until the end of the day. Write the rule into the system.
How I match a transaction to an order
I match on the transaction ID the customer enters, then I verify the amount. The sender number is extra information, not a condition.
Compare amounts as integers. Syrian stores often price in whole lira, but your database may store 25000, "25000.00", or a float. Convert both sides with the same rule, then compare.
Each transaction ID is used once. Persist it under a unique constraint before you mark the order paid, and treat a second submit of the same ID as a rejection. Customers resubmit forms, and two tabs can fire the same request. Without this rule, one transfer can close two orders.
If the gateway does not find the ID yet, leave the ID unused so a later retry can succeed. If the amount is wrong, still record the ID against this order (or in the used-ID table) so nobody can apply it to a different order that happens to match the paid amount.
Two open orders with the same total are fine. The ID distinguishes them. The amount is a check after the transfer is found, not a way to guess which open order should close.
How your site talks to the payment gateway
This handler is a pattern for calling the hosted gateway, not an official client. YOUR_GATEWAY_URL and the field names are placeholders; map them to the values you get when the gateway is set up, and keep YOUR_API_KEY out of the repository. In production, replace the in-memory store with a unique database constraint, and run the "lookup then write" step inside a transaction so two requests cannot apply the same ID.
```js import express from "express";
const app = express(); app.use(express.json());
function toIntAmount(value) { return Math.round(Number(value)); }
export async function confirmByTransactionId({ order, transactionId, usedTxIds }) { const id = String(transactionId || "").trim(); if (!id) { return { status: "bad_payload" }; }
if (await usedTxIds.has(id)) { return { status: "rejected", reason: "transaction_already_used" }; }
const response = await fetch("YOUR_GATEWAY_URL", { method: "POST", headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ transactionId: id }), });
const result = await response.json(); // Placeholder response fields: found, amount, receivedAt, senderNumber
if (!result || !result.found) { return { status: "not_found" }; }
const paid = toIntAmount(result.amount); const expected = toIntAmount(order.total);
if (paid !== expected) { await usedTxIds.add(id); return { status: "wrong_amount", orderId: order.id, transactionId: id, paid, expected, senderNumber: result.senderNumber, }; }
await usedTxIds.add(id); return { status: "paid", orderId: order.id, transactionId: id, paid, senderNumber: result.senderNumber, paidAt: result.receivedAt, }; }
app.post("/orders/:id/confirm-payment", async (req, res) => { const order = await loadOpenOrder(req.params.id); const usedTxIds = await loadUsedTransactionIds(); const result = await confirmByTransactionId({ order, transactionId: req.body.transactionId, usedTxIds, });
if (result.status === "paid") { await applyPayment(result); await notifyPaid(result.orderId); return res.status(200).json({ ok: true, orderId: result.orderId }); }
if (result.status === "wrong_amount") { await flagForReview(result); return res.status(409).json({ ok: false, reason: result.status }); }
if (result.status === "not_found") { return res.status(404).json({ ok: false, reason: result.status }); }
const httpStatus = result.status === "bad_payload" ? 400 : 409; return res.status(httpStatus).json({ ok: false, reason: result.reason || result.status }); }); ```
applyPayment should write the transaction ID, the sender number, and the paid status together, and fail if that ID already exists. flagForReview should notify you, bind the ID to the order, and leave the order unpaid. A manual confirm button is not optional; odd cases will show up, and you do not want them stuck until the customer complains. You can also type the ID yourself from a screenshot and run the same check.
If your store runs on WooCommerce, the same rules sit behind a form field and a PHP call to the gateway. I walked through that hook in سيريتل كاش على ووكومرس: يدوي أم تلقائي؟.
Edge cases to decide before you go live
A mistyped or old transaction ID is the case I see most. If the gateway does not find the transfer, do not guess an open order by amount. Tell the customer to check the ID, wait a minute if they just paid, and try again.
Duplicate IDs are usually a second submit, a copied ID, or someone trying to reuse a paid transfer. The second attempt must not mark another order paid. Whoever reviews orders should search by transaction ID before a manual confirm.
Partial payments should not complete an order. A transfer that is 500 SYP short may be a typo, a second transfer still to come, or a different order entirely. Bind the ID to this order, hold it, record the amount that arrived, and notify you. Overpayments get the same hold unless the shop has a written rule that a surplus still completes the order.
Delays work in both directions. The customer may enter the ID before the transfer is visible to the gateway, or they may pay after you already expired the order. Create the order before you ask them to pay, keep it around until your published payment window ends, and allow a retry when the ID is not found yet. If a valid transfer arrives after expiry, keep a path to reopen the order or leave the amount as store credit.
If the customer pays and never comes back to type the ID, the order stays unpaid until you enter it from the dashboard or they return. The gateway can see what landed on your number; it does not mark orders paid on a guess.
Cost, setup, and what I do not do for you
I offer a ready-made payment gateway for Syriatel Cash, and for Sham Cash if you need both. Syriatel Cash API is $2 per number per month. There is no setup fee for a single number. Wiring several numbers into one system is quoted from what you actually need. Setup is same day once the number is ready and you have agreed the flow, and you can ask for sandbox access first.
The service is a hosted API, built and run by me. You keep your wallet account and your site, and you integrate over REST. I do not register the Syriatel Cash number, and I do not set official Syriatel fees or limits; those are between you and Syriatel.
To start, write through the contact form on fayezalshami.com with the wallet type and how many numbers you have, or email fayezalshami.dev@gmail.com.
If customers also pay with Sham Cash
Treat that as a second wallet, not a switch on the same subscription. Sham Cash API is $5 per account per month, billed and managed separately, with the same shape: the customer enters a transaction ID, your site asks the gateway to verify it, and you can also check the balance. Stores that accept both usually subscribe to both, then verify each ID against the wallet that order was waiting on.
A payment bot is a different surface: the customer pays inside Telegram or WhatsApp, sends the transaction ID in the chat, and the bot confirms on top of these gateways. That starts from $120 one-time. For a website checkout, start with the API and the matcher.
Arabic walkthroughs: كيف تربط سيريتل كاش بمتجرك الإلكتروني and كيف تربط شام كاش API بمتجرك.
Go-live checklist
- Your own Syriatel Cash number is connected, and you have looked up test transaction IDs in the sandbox or trial.
- An order exists, with an amount and a created-at time, before the customer is asked to pay.
- The confirmation screen shows the exact payable amount, the destination number, and a field for the transaction ID. The copy does not ask for a transfer memo.
- Amounts are compared as integers after the gateway finds the transfer.
- A transaction ID is stored on the first successful confirm, under a unique constraint, and a reused ID is rejected.
- A wrong amount is flagged, the ID is bound to that order, and the order is not marked paid unless you chose an explicit surplus rule.
- An ID that is not found yet is left unused so the customer can retry.
- The sender number is stored on the order and is not required to match the checkout phone.
- A dashboard button can confirm or reject a transfer by hand, including pasting an ID from a screenshot.
- You get a notification on
wrong_amount,transaction_already_used, and unresolvednot_foundcases that need a person. - You have run four cases before launch: one exact match, one reused ID, one wrong amount, and an ID that is not visible yet.
Frequently asked questions
Do I need my own Syriatel Cash number?
Yes. The gateway connects an existing number and gives your app programmatic access to it. Registering the number is not part of the service.
What does the customer have to enter on my site?
They place the order, transfer the amount you displayed, then enter the transaction ID. There is no memo field on the Syriatel Cash transfer itself.
What if two open orders have the same amount?
That is fine. Matching starts from the transaction ID, and the amount is checked afterwards.
Does this work if my server is outside Syria?
Yes. The gateway works from outside Syria with no Syrian proxy or VPN. That is the usual case when a site is hosted abroad.
Is there a setup fee?
No setup fee for a single number. Several numbers wired into one system are quoted from your needs. The API itself is $2 per number per month.
Can I keep a manual override once matching is automatic?
Yes. I would not launch without one. The gateway closes the clear cases; you confirm the strange ones by hand.