Skip to content
Guide

Sham Cash API: Integrate Payments Into Your App

By Fayez AlshamiPublished: 12 min read
TL;DR

Sham Cash checkout works like Syriatel Cash: create the order, customer transfers and types the transaction ID, your app verifies through a hosted REST API ($5 per account per month). Match on the ID first, store the sender number for support, and bind wrong amounts so one ID cannot close two orders.

A lot of the messages I get about Sham Cash start the same way. The shop already has an account. Customers already transfer to it. Someone on the team still unlocks a phone for every order and hunts for a matching amount. The question is how to let the website, the invoice page, or the bot confirm that transfer without a person in the middle.

I run a hosted payment gateway that gives your app programmatic access to a Sham Cash account you already own. You look up an incoming transfer by the transaction ID the customer types, you can check the balance, and you talk to a REST API that works from outside Syria with no Syrian proxy or VPN. It costs $5 per account per month. Setup is same day. You do not receive source code. A free trial is available on request; use it before you point real customers at the flow.

What this integration actually does

The account stays yours. I do not issue a new Sham Cash wallet in the site's name. The gateway connects to the account you already use, and your backend asks whether a given transaction ID exists, what amount arrived, when it arrived, and which sender number paid.

Sham Cash transfers have no memo or reference field. After the transfer succeeds, the app shows a transaction ID (رقم العملية). That ID is what the customer enters on your confirmation screen. I match on that ID, then I verify the amount. The sender number is always returned with the transfer. Store it on the order for support later. Do not use it as the matching key; people often pay from someone else's wallet.

The general confirmation flow is in How to Automate Payment Confirmation for Syrian Wallets. The price comparison with Syriatel Cash is in Syriatel Cash API vs Sham Cash API. This article stays on Sham Cash: the account, the ID the customer types, and the decisions your code has to make when the amount is wrong or the ID is reused.

What you need before you write any code

You need a Sham Cash account that can receive the payments, and you need to control it. Opening the account, and the receiving limits Sham Cash has placed on it, stay between you and Sham Cash. Limits differ by account and they can change. If you sell high-value items or expect a busy day of transfers, confirm the current limits with Sham Cash. I am keeping that discussion general; I will not invent a ceiling that may already be out of date.

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, and later the sender number. That can be a website checkout, a custom invoice, a WooCommerce order, or a bot order. Create the order before you show the account details. Show the exact amount in plain numerals. A 50 SYP difference is enough to fail the amount check. Give them a field for the transaction ID, and do not ask for a transfer memo.

The payment flow

  1. The customer places an order. Your system stores the amount, the created-at time, and the fact that this order is waiting on Sham Cash.
  2. You show your Sham Cash account details, that exact amount, a field for the transaction ID, and the payment window you chose. An hour is common. Some shops keep the order open until the end of the day. Write the rule into the system.
  3. The customer opens Sham Cash and sends the transfer to your account.
  4. 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 YOUR_GATEWAY_URL until then).
  5. If the transfer exists, the gateway returns the amount, the time received, and the sender number.
  6. Your code then decides: reject a reused ID; leave a missing transfer unused so the customer can retry; flag a wrong amount and bind that ID to this order; or, if the ID is new and the amount matches, mark the order paid, store the ID and sender number, and notify both sides.

Balance and account-status checks are available on the same API. I use those in an internal dashboard, not as a substitute for looking up the transaction ID.

How I match a transaction to an order

I start from the transaction ID the customer enters, then I verify the 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.

Compare amounts as integers. Syrian stores often price in whole lira, but your database may store 62500, "62500.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. 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 it unused so a later retry can succeed. If the amount is wrong, still record the ID against this order so nobody can apply it to a different order that happens to match the paid amount.

Notifications go out after the paid status is saved. If the message fails, retry the message. Do not run the confirm step again in a way that could mark a second order paid.

How your app talks to the payment gateway

This handler is a pattern for calling the hosted gateway, not an official Sham Cash 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 any in-memory set with a unique database constraint, and run the "lookup then write" step inside a transaction so two requests cannot apply the same ID.

```python import os from decimal import Decimal, ROUND_HALF_UP

import httpx from fastapi import FastAPI, HTTPException from pydantic import BaseModel

app = FastAPI() GATEWAY_URL = os.environ["GATEWAY_URL"] API_KEY = os.environ["GATEWAY_API_KEY"]

class ConfirmBody(BaseModel): transaction_id: str

def to_int_amount(value) -> int: return int(Decimal(str(value)).quantize(Decimal("1"), rounding=ROUND_HALF_UP))

async def confirm_by_transaction_id(order: dict, transaction_id: str, used_ids) -> dict: tx_id = (transaction_id or "").strip() if not tx_id: return {"status": "bad_payload"}

if await used_ids.contains(tx_id): return {"status": "rejected", "reason": "transaction_already_used"}

async with httpx.AsyncClient(timeout=15.0) as client: response = await client.post( GATEWAY_URL, headers={ "Authorization": f"Bearer {API_KEY}", "Content-Type": "application/json", }, json={"transactionId": tx_id}, ) response.raise_for_status() result = response.json() # Placeholder response fields: found, amount, receivedAt, senderNumber

if not result or not result.get("found"): return {"status": "not_found"}

paid = to_int_amount(result["amount"]) expected = to_int_amount(order["total"])

if paid != expected: await used_ids.add(tx_id) return { "status": "wrong_amount", "order_id": order["id"], "transaction_id": tx_id, "paid": paid, "expected": expected, "sender_number": result.get("senderNumber"), }

await used_ids.add(tx_id) return { "status": "paid", "order_id": order["id"], "transaction_id": tx_id, "paid": paid, "sender_number": result.get("senderNumber"), "paid_at": result.get("receivedAt"), }

@app.post("/orders/{order_id}/confirm-payment") async def confirm_payment(order_id: str, body: ConfirmBody): order = await load_open_order(order_id) used_ids = await load_used_transaction_ids() result = await confirm_by_transaction_id(order, body.transaction_id, used_ids)

if result["status"] == "paid": await apply_payment(result) await notify_paid(result["order_id"]) return {"ok": True, "orderId": result["order_id"]}

if result["status"] == "wrong_amount": await flag_for_review(result) raise HTTPException(status_code=409, detail=result["status"])

if result["status"] == "not_found": raise HTTPException(status_code=404, detail=result["status"])

status = 400 if result["status"] == "bad_payload" else 409 raise HTTPException(status_code=status, detail=result.get("reason") or result["status"]) ```

apply_payment should write the transaction ID, the sender number, and the paid status together, and fail if that ID already exists. flag_for_review 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 paste the ID yourself from a screenshot and run the same check.

If the store runs on WooCommerce, the same rules sit behind a form field and a PHP call to the gateway. I walked through that hook, for Syriatel Cash, in سيريتل كاش على ووكومرس: يدوي أم تلقائي؟. The Sham Cash version uses the same decision table; you just verify the ID against the Sham Cash account that order was waiting on.

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 a reused paid transfer. The second attempt must not mark another order paid. Search by transaction ID before a manual confirm.

Partial payments should not complete an order. Bind the ID to this order, hold it, record the amount that arrived, and notify you. If a second transfer arrives later with a new ID, you can add the two amounts, or leave the sum to a person at first. I start with a person until I see how this shop's customers actually pay. Overpayments get the same hold unless the shop has a written rule that a surplus still completes the order. Keep a record of the extra; settlement later needs it.

The customer may enter the ID before the transfer is visible, or pay after the order expired. Keep a retry path for not_found. If a valid transfer arrives after expiry, show it next to the expired order and let a person reopen it, treat it as store credit, or handle a refund by the shop's policy. The system should not invent a refund on its own.

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. A transfer sent to a different account will not appear here, including a Syriatel Cash payment while the instructions were for Sham Cash. The manual path is how you audit that, which is why the review button stays after automation is stable.

Cost, setup, and what I do not do for you

The Sham Cash API is $5 per account per month. Setup is same day once the account is ready and you have agreed the flow. 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 Sham Cash account, and I do not set official Sham Cash fees or limits.

To start, write through the contact form on fayezalshami.com with the wallet type and how many accounts you have, or email fayezalshami.dev@gmail.com. Ask for the free trial if this is your first wallet integration.

If customers also pay with Syriatel Cash

Treat that as a second wallet, not a switch on the same subscription. Syriatel Cash API is $2 per number per month, billed and managed separately, with the same shape. Stores that accept both usually subscribe to both, then verify each ID against the wallet that order was waiting on. A Sham Cash transaction ID must not close an order that was waiting on a Syriatel Cash number.

A payment bot is a different surface: the customer sends the transaction ID in Telegram or WhatsApp, 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.

The Arabic walkthrough is كيف تربط شام كاش API بمتجرك. For the wider 2026 checkout picture, see Accepting online payments in Syria in 2026: a developer's guide.

Go-live checklist

  • Your own Sham Cash account is connected, and you have looked up test transaction IDs in the trial.
  • An order exists, with an amount, a created-at time, and an expected wallet, before the customer is asked to pay.
  • The confirmation screen shows the exact amount, the destination account, and a field for the transaction ID, with no request for a transfer memo.
  • Amounts are compared as integers after the gateway finds the transfer.
  • A transaction ID is stored under a unique constraint on the first successful confirm, and a reused ID is rejected.
  • A wrong amount is flagged and bound to that order; an ID that is not found yet is left unused.
  • The sender number is stored 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 unresolved not_found cases.
  • You have run four cases before launch: an exact match, a reused ID, a wrong amount, and an ID that is not visible yet.

If you open the checkout before those points are done, keep someone watching the review queue in the first days.

Frequently asked questions

Do I need my own Sham Cash account?

Yes. The gateway connects an existing account and gives your app programmatic access to it. Registering the account 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 Sham 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.

Can I run Sham Cash and Syriatel Cash together?

Yes. Each is billed and managed on its own. Store the expected wallet on the order so you do not verify a Sham Cash ID against a Syriatel Cash number.

Is there a free trial?

Yes, on request. I recommend it if this is your first wallet checkout. Setup after you agree the flow is same day.

Can I keep a manual override once matching is automatic?

Yes. I would not launch without one.

If you want the hosted Sham Cash gateway, or both wallets on the same shop, write through the form on fayezalshami.com and mention Sham Cash, how many accounts you have, and whether the store is a site, WooCommerce, or a bot. The email is fayezalshami.dev@gmail.com.

Guides & comparisons

Need this built or connected for your business?

See services