On this page
Overview
Every time MFS Tool captures an SMS from an approved sender, it sends one JSON POST to the Webhook URL you set in Onboarding (or later in Settings → Webhook).
- Built-in senders: the SMS is parsed on your phone and only the transaction fields are sent. The raw SMS text is never sent.
- Custom senders you add yourself: the raw message is forwarded as-is.
Your receiver decides what to do with the data and tells the app whether it was accepted.
Request
POST <your Webhook URL>
Content-Type: application/json
X-BT4-Key: <the Key you configured in the app>- Method: always
POST. - Auth: one shared-secret header,
X-BT4-Key, set to the Key you entered in the app. Treat it as a bearer token and reject anything that doesn't match. - Body: JSON, UTF-8, one message per request (never batched).
- Timeout: the app waits 20 seconds for a response before treating the attempt as failed and retrying later.
Built-in senders
The message is parsed on the device and only these fields are sent. Every field is always present.
| Field | Type | Notes |
|---|---|---|
sender | string | Provider display name, exactly as listed under Supported providers (e.g. bKash, BRAC Bank). Route on this. |
type | string | Personal, Agent, Merchant or Bank. |
amount | string | Transaction amount, thousands separators removed (e.g. 1030.00). "0" if the SMS format doesn't include it. |
phone_number | string | Counterparty number, card or account as printed in the SMS (may be masked, or a name such as a bank). If the SMS has none (common for bank credit alerts), a random 8-character token. |
ref | string | null | Reference or note, or null when the SMS carried none. Optional, safe to ignore. |
balance | string | Resulting balance, separators removed. "0" if the SMS format doesn't include it. |
transaction_id | string | Provider transaction ID (TrxID / TxnID / TxID / Ref). If the SMS has none (common for bank credit alerts), a random 8-character token, generated once at capture so every retry carries the same value. |
received_at | string (ISO-8601) | When the device received the SMS. Local time, millisecond precision, no offset. |
Example: a bKash transfer
{
"sender": "bKash",
"received_at": "2026-09-04T19:22:03.412",
"type": "Personal",
"amount": "30.00",
"phone_number": "01946664890",
"ref": null,
"balance": "39.59",
"transaction_id": "DHI9JYQ9DD"
}Example: a bank credit alert with no ID or counterparty
{
"sender": "EBL Bank",
"received_at": "2026-10-21T11:05:47.090",
"type": "Bank",
"amount": "1700.00",
"phone_number": "Q7K2M9XA",
"ref": null,
"balance": "30000.00",
"transaction_id": "4HZP0C1T"
}A built-in-sender SMS that matches no known transaction format (an OTP or a promo, for example) is ignored. Nothing is stored or sent, because the raw text must not leave the device.
Supported providers
The value in the first column is sent as sender. The second column lists the type values that provider can produce.
sender | type values |
|---|---|
| Mobile financial services | |
| bKash | Personal, Merchant, Agent |
| Nagad | Personal, Merchant, Agent |
| Rocket | Personal, Merchant, Agent, Bank |
| Upay | Personal, Merchant, Agent |
| Tap | Personal |
| Cellfin | Personal, Merchant, Bank |
| OkWallet | Personal |
| mCash | Personal, Merchant, Agent |
| PathaoPay | Personal, Merchant |
| TallyPay | Merchant |
| DgePay | Merchant |
| Banks | |
| AB Bank | Merchant |
| Al-Arafah Bank | Merchant, Bank |
| Bank Asia | Merchant |
| BRAC Bank | Merchant, Bank |
| City Bank | Merchant, Bank |
| Dhaka Bank | Merchant |
| EBL Bank | Bank |
| IFIC Bank | Bank |
| Janata Bank | Merchant |
| Midland Bank | Bank |
| Mutual Trust Bank | Bank |
| Prime Bank | Bank |
| Pubali Bank | Merchant, Bank |
| UCB Bank | Merchant, Bank |
Custom senders
Senders you add yourself have no parsing rules, so the raw message is forwarded as-is.
| Field | Type | Notes |
|---|---|---|
sender | string | The custom sender's display name. |
address | string | Raw originating address. For a manual entry it is manual:<Provider>. |
message | string | Full SMS text (whitespace collapsed to single spaces). |
received_at | string (ISO-8601) | When the device received the SMS. |
{
"sender": "MyBank",
"received_at": "2026-09-04T19:22:03.412",
"address": "MYBANK",
"message": "Your account was credited BDT 500 ..."
}Expected response
The app marks a message Succeed only when the response body explicitly reports success. Your receiver must return a JSON body with a status:
HTTP 200
Content-Type: application/json
{ "status": "success" }| Response body | App behaviour |
|---|---|
{"status":"success"} (or {"success":true}) | Marked Succeed. |
{"status":"failed"}, or any other status value | Marked Failed and retried. |
No status, a non-JSON body, a timeout, or no response | Marked Failed and retried. |
- Pending vs Failed: if the app reaches your webhook and the response is not success, the message is marked Failed immediately. Only when your webhook can't be reached at all (timeout or no network) does it stay Pending and keep retrying.
- A missing or empty body counts as Failed. You must return
{"status":"success"}, even onHTTP 200. - The HTTP status code is not used on its own; the
statusfield is what matters. Still, return2xxwith{"status":"success"}. - For a duplicate you already have, return
{"status":"success"}so the app stops retrying it.
Retry schedule
If a message isn't accepted, the app retries with exponential backoff:
5s → 15s → 60s → 5m → 30m (capped, repeats at 30m)After 10 attempts a message is marked Failed. It is not dropped:
- it keeps retrying automatically on the capped ~30-minute cadence, and
- tapping Sync in the app retries every undelivered message (pending and failed) immediately.
There is also a background sweep of undelivered messages roughly every 15 minutes, and a flush as soon as connectivity returns while the app is open.
Duplicates
The app can send the same message more than once: its own retries and a periodic catch-up re-read of the SMS inbox can both attempt the same row.
- Treat
transaction_idas the unique key for built-in senders, and(address, message)for custom senders. - Accept a duplicate silently with
{"status":"success"}(or return409). - The app also de-duplicates on
(address, message)locally, so repeats are rare.
When transaction_id is a generated token (the SMS printed none), it stays the same across every retry of that message, but it is not the provider's own ID. The app never re-imports inbox history from before it was installed, so an old SMS is not captured a second time with a new token.
Example receiver (PHP)
A minimal endpoint that checks the Key, accepts both payload shapes and replies in the format the app expects.
<?php
header('Content-Type: application/json');
$expected = 'YOUR_KEY'; // the Key you entered in the app
$key = $_SERVER['HTTP_X_BT4_KEY'] ?? '';
if (!hash_equals($expected, $key)) {
http_response_code(401);
echo json_encode(['status' => 'failed']);
exit;
}
$data = json_decode(file_get_contents('php://input'), true);
if (!is_array($data) || !isset($data['sender'])) {
http_response_code(400);
echo json_encode(['status' => 'failed']);
exit;
}
if (isset($data['transaction_id'])) {
// Built-in sender: sender, type, amount, phone_number, ref, balance,
// transaction_id, received_at. Store it, ignoring a duplicate transaction_id.
} else {
// Custom sender: sender, address, message, received_at.
}
echo json_encode(['status' => 'success']);What is not sent
Sender and pattern configuration (which senders the app listens to, and the rules that parse built-in senders) stays on the device and never leaves the phone. For built-in senders your receiver never sees the raw SMS text, only the parsed fields above. The parsing patterns are stored encoded inside the app, not in plaintext. See the Privacy Policy for the full picture.