MASTER PAY Integration Guide

MASTER PAY verifies wallet, bank, and UPI payments by matching the customer's transaction ID against the actual SMS your bound Android device receives. We don't process payments — we only confirm them.

This guide walks you through the full integration: from creating your merchant account to having verified transactions land in your dashboard.

1. 1. Sign up at /register — pick your country (currency auto-set)
2. 2. Note your API Key and Device Auth Key — both shown under Integration credentials on your dashboard overview
3. 3. Add a Gateway — your wallet/bank account number (or last 4 of bank acct)
4. 4. Install the APK on your shop's phone, paste the Device Auth Key
5. 5. Test with a checkout session (see below)

curl -X POST https://checkout.masterpay.it.com/api/payment/sessions \
  -H "X-API-Key: pk_live_xxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "order_id": "TEST-001",
    "redirect_url": "https://example.com/done"
  }'

The response gives you a checkout_url — open it in a browser, pick a gateway, paste a TxnID, click Verify. That's the whole flow.

MASTER PAY sits between the merchant's e-commerce backend, the customer's browser, and the bound Android phone receiving wallet SMS.

┌─────────────────────┐                                  ┌─────────────────────┐
│  Customer's browser │                                  │  Vendor's bound     │
│  on yourstore.com   │                                  │  phone (MASTER PAY) │
└──────────┬──────────┘                                  └─────────────────────┘
           │   1) POST /api/payment/sessions  (+ vendor_id)        │
           │   ◄──────── checkout_url ────────                     │
           ▼                                                       │
┌─────────────────────┐  2) redirect to checkout_url              │
│  MASTER PAY hosted   │ ◄─────────────────────────────────        │
│  /pay/<sessionId>   │                                            │
└──────────┬──────────┘                                            │
           │   3) customer pays, submits                           │
           │      TxnID + sender number + screenshot               │
           ▼                                                       ▼
       transaction.status = pending          ◄────── wallet SMS arrives
           │                                          │
           ├──── 4a) auto-match SMS vs TxnID ◄────────┘
           │                                          │
           └──── 4b) no match → notify ONLY this      │
           │          vendor's phone → Approve/Reject ◄┘
           ▼
       transaction.status = success  (or failed)
           │   5) redirect customer back to merchant
           ▼
┌─────────────────────┐
│ yourstore.com/done  │
│ ?status=success     │
└─────────────────────┘

• 1. Customer hits your checkout — your backend calls POST /api/payment/sessions
• 2. We return a hosted checkout_url — you redirect the customer
• 3. Customer pays from their wallet app, then submits the TxnID + sender number + a payment screenshot on the checkout and clicks Verify — a pending transaction is created
• 4. Your bound APK forwards the incoming wallet SMS to our backend (pure staging — nothing is auto-created from random SMS)
• 5. The pending transaction resolves one of two ways: (a) the TxnID auto-matches a staged SMS, or (b) no match — so we notify only that vendor's phone to Approve / Reject (you can also Mark Paid / Failed from the dashboard)
• 6. Once resolved as success (or failed), the customer is redirected back to you with the status

MASTER PAY uses three credentials, each for a different actor:

A gateway is one wallet/bank account where you receive customer payments — e.g. bKash Personal · 01711111111, or UPI · last-4-of-bank XX6788. Each gateway has an account_number that gets matched against incoming SMS.

The MASTER PAY Android app runs on the phone you use to receive wallet SMS. It does one job: read incoming wallet SMS and forward them to our backend as data staging. The SMS only becomes a verification when a customer submits a matching TxnID through your checkout — random unrelated SMS sit unused and never become orphan transactions.

The APK also receives verify requests for any pending row a customer submits that hasn't auto-matched yet, so the merchant can Approve / Reject from the phone (mirror of the dashboard's Mark Paid / Mark Failed).

The vendor installs the APK on the phone holding their SIM, opens it, and pastes the Device Auth Key you gave them (PV-…, ~350 characters — copy it, never retype). A marketplace binds no phone of its own.

For Android developers building/extending the APK, see the full contract at docs/APK_API.md in the repo.

Visit /register. Fill in your business details. Your country choice determines your default currency (India → INR, Bangladesh → BDT, US → USD, etc.) — you can override per-session later.

On successful registration, three things are generated for you:

• api_key (pk_live_...) — for your backend
• secret_key (sk_live_...) — for webhook signatures (future)
• A default brand matching your domain

You get no device auth key. That belongs to each vendor — POST /api/vendors returns one per seller.

You never hold a payment number — your vendors do. Create one per seller with POST /api/vendors, hand them the device_auth_key (PV-XXXXXX) it returns, and they register at /vendor/register and add their own bKash / Nagad number in their own panel.

The vendor's Account Number must contain what the wallet's SMS will mention — for UPI/bank deposits, that's the bank account suffix (e.g. XX6788), not the GPay phone (the bank SMS doesn't echo it).

Only some of your sellers will ever do this, and that's expected. Call GET /api/vendors/availability before rendering a Pay button to find out which ones can take money — the rest come back payable: false with a ready-to-render message.

The vendor installs MASTER PAY on the Android phone that receives their wallet SMS, and pastes the device_auth_key you gave them. The phone shows up in their panel at /vendor/dashboard/device as Online. A marketplace binds no phone of its own.

From this moment, every wallet SMS that arrives on the phone gets forwarded to MASTER PAY automatically.

When a customer reaches your checkout, your backend creates a payment session and redirects them to the MASTER PAY checkout URL.

// Node.js (Express)
app.post('/checkout', async (req, res) => {
  const r = await fetch('https://checkout.masterpay.it.com/api/payment/sessions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-Key':     process.env.PAYVERIFY_API_KEY,
    },
    body: JSON.stringify({
      amount:        req.body.amount,
      order_id:      req.body.order_id,
      redirect_url:  'https://yourstore.com/payment/result',
      customer_phone: req.body.customer_phone,
    }),
  });
  const { checkout_url } = await r.json();
  res.redirect(checkout_url);
});

After payment, the customer is redirected back to your redirect_url with query params:

https://yourstore.com/payment/result?session_id=eNOuUpsg2IGX4ko4HbFL&status=success

app.get('/payment/result', async (req, res) => {
  const r = await fetch(
    `https://checkout.masterpay.it.com/api/payment/sessions/${req.query.session_id}`,
    { headers: { 'X-API-Key': process.env.PAYVERIFY_API_KEY } }
  );
  const { session } = await r.json();
  if (session.status === 'success') {
    await markOrderPaid(session.order_id);
    return res.render('order-confirmed', { session });
  }
  if (session.status === 'pending') {
    // Verification didn't finish before redirect. Show a "processing" page;
    // keep polling GET /sessions/:id server-side until it resolves or expires.
    return res.render('payment-processing', { session });
  }
  res.render('payment-failed', { reason: session.status });
});

Hosting many independent sellers under one site? Give each seller their own phone to confirm payments — a payment for Seller A only buzzes Seller A's phone, never Seller B's. You create one vendor per seller; each gets its own device_auth_key and its own payment numbers.

1. 1. A seller signs up on your site → you call POST /api/vendors → we return a vendor_id and a device_auth_key.
2. 2. The seller installs the APK and pastes that device_auth_key → their phone is bound to that vendor.
3. 3. You add the seller's wallet number → POST /api/vendors/:id/gateways.
4. 4. A customer buys from that seller → create the session with "vendor_id": "…". The checkout shows only that vendor's numbers, and only that vendor's phone is notified.

{
  "label":       "Riya's Sarees",   // optional
  "external_id": "seller_4821"       // optional, YOUR seller id (idempotent)
}

// 201 Created (or 200 with "existed": true if external_id already mapped)
{
  "vendor": {
    "vendor_id":       "0f4c…-uuid",
    "label":           "Riya's Sarees",
    "external_id":     "seller_4821",
    "device_auth_key": "PV-7K2QF9",   // give this to the seller for the APK
    "is_default":      false,
    "created_at":      "2026-06-20T10:00:00Z"
  }
}

{
  "vendors": [
    {
      "vendor_id":       "0f4c…-uuid",
      "label":           "Riya's Sarees",
      "external_id":     "seller_4821",
      "device_auth_key": "PV-7K2QF9",
      "is_default":      false,
      "created_at":      "2026-06-20T10:00:00Z"
    }
  ]
}

{
  "vendor": {
    "vendor_id":       "0f4c…-uuid",
    "label":           "Riya's Sarees",
    "external_id":     "seller_4821",
    "device_auth_key": "PV-7K2QF9",
    "is_default":      false,
    "created_at":      "2026-06-20T10:00:00Z",
    "bound_devices":   1,
    "gateways": [
      {
        "id":             "9a1b…-uuid",
        "provider":       "bkash",
        "variant":        "personal",
        "account_number": "01711111111",
        "label":          null,
        "is_enabled":     true,
        "created_at":     "2026-06-20T10:05:00Z"
      }
    ]
  }
}

// 404 — not your vendor
{ "error": "Vendor not found" }

{
  "provider":       "bkash",          // a provider your platform admin enabled
  "variant":        "personal",
  "account_number": "01711111111",    // what the wallet SMS will mention
  "label":          "Riya bKash",     // optional
  "charge_value":   0,                 // optional, fee added to the bill
  "charge_type":    "fixed",           // "fixed" | "percent"
  "discount_value": 0,                 // optional
  "discount_type":  "fixed"
}

// 201 Created
{
  "gateway": {
    "id":             "9a1b…-uuid",
    "account_id":     "0f4c…-uuid",   // = vendor_id
    "provider":       "bkash",
    "variant":        "personal",
    "account_number": "01711111111",
    "label":          "Riya bKash",
    "is_enabled":     true,
    "created_at":     "2026-06-20T10:05:00Z"
  },
  "retroactively_matched": 0
}

// 400 — unknown provider/variant, or missing account_number
{ "error": "Provider \"bkash\" not found or disabled" }

// 409 — vendor already has a gateway for this provider+variant
{ "error": "This account already has a gateway for this provider and type. Each account allows one per provider+variant." }

{
  "gateways": [
    {
      "id":             "9a1b…-uuid",
      "account_id":     "0f4c…-uuid",
      "provider":       "bkash",
      "variant":        "personal",
      "account_number": "01711111111",
      "label":          "Riya bKash",
      "min_amount":     null,
      "max_amount":     null,
      "charge_value":   "0",
      "charge_type":    null,
      "discount_value": "0",
      "discount_type":  null,
      "balance_check":  false,
      "is_enabled":     true,
      "created_at":     "2026-06-20T10:05:00Z",
      "updated_at":     "2026-06-20T10:05:00Z"
    }
  ]
}

{
  "account_number": "01722222222",
  "label":          "Riya bKash (new)"
}

{
  "gateway": {
    "id":             "9a1b…-uuid",
    "account_id":     "0f4c…-uuid",
    "provider":       "bkash",
    "variant":        "personal",
    "account_number": "01722222222",
    "label":          "Riya bKash (new)",
    "is_enabled":     true,
    "updated_at":     "2026-06-20T11:00:00Z"
  },
  "retroactively_matched": 0
}

// 404 — gateway not found / not yours
{ "error": "Gateway not found" }

// 200 OK
{ "ok": true }

// 404 — gateway not found / not yours
{ "error": "Gateway not found" }

These endpoints are called by your Android APK, authenticated by device_auth_key in the body. Never call from a server or browser.

{
  "auth_key":     "PV-XXXXXX",
  "device_id":    "android-stable-id",
  "model":        "CPH1937",
  "manufacturer": "OPPO",
  "os_version":   "11"
}

{ "auth_key": "PV-XXXXXX", "device_id": "android-stable-id" }

{
  "auth_key":  "PV-XXXXXX",
  "device_id": "android-stable-id",
  "messages": [{
    "sender":      "bKash",
    "body":        "Cash In Tk 500.00 successful. TrxID: BKX92H1 from 01712345678",
    "received_at": "2026-05-12T11:25:30Z"
  }]
}

{ "auth_key": "PV-XXXXXX", "device_id": "android-stable-id" }

{
  "verifications": [{
    "verification_id": 421,
    "txnid_submitted": "BKX92H1",
    "amount":          500.00,
    "currency":        "BDT",
    "customer_phone":  "01712345678",
    "customer_name":   "Customer Name",
    "order_id":        "ORD-9911",
    "provider":        "bkash",
    "variant":         "personal",
    "account_number":  "01799999999",
    "created_at":      "2026-05-12T11:25:30Z"
  }]
}

{
  "auth_key":        "PV-XXXXXX",
  "device_id":       "android-stable-id",
  "verification_id": 421,
  "result":          "success",
  "matched_sms":     "Cash In Tk 500.00 successful. TrxID: BKX92H1...",
  "failure_reason":  null
}

{
  "ok":              true,
  "verification_id": 421,
  "status":          "success",
  "session_id":      "Y_giE7l9...",
  "transaction": {
    "id":            421,
    "status":        "success",
    "result_source": "apk"
  }
}

{
  "auth_key":  "PV-XXXXXX",
  "device_id": "android-stable-id",
  "status":    "pending",
  "q":         "BKX92",
  "limit":     50
}

{
  "transactions": [{
    "id":              421,
    "txnid_submitted": "BKX92H1",
    "amount":          500.00,
    "status":          "pending",
    "result_source":   null,
    "verified_at":     null,
    "failure_reason":  null,
    "provider":        "bkash",
    "account_number":  "01799999999",
    "order_id":        "ORD-9911",
    "customer_name":   "Customer Name",
    "created_at":      "2026-05-12T11:25:30Z"
  }]
}

{
  "auth_key":  "PV-XXXXXX",
  "device_id": "android-stable-id",
  "txnid":     "BKX92H1"
}

{
  "matched": true,
  "already_existed": false,
  "transaction": {
    "id": 422, "txnid_submitted": "BKX92H1", "amount": 500.00,
    "status": "success", "result_source": "manual_verify",
    "provider": "bkash", "account_number": "01799999999"
  },
  "sms": { "id": 7711, "sender": "bKash", "body": "...", "received_at": "..." }
}

Full APK contract (poll/report patterns, SMS matching rules, permissions) lives in docs/APK_API.md.

Error response shape

Customer-facing endpoints (/api/payment/sessions, /api/checkout/:id/submit) split every error into two tiers so you can safely route the right text to each audience:

{
  "error":            "Services currently unavailable.",
  "merchant_message": "Merchant wallet has insufficient balance to cover the per-verification fee. Top up at the dashboard.",
  "insufficient_balance": true,
  "code":             "merchant_wallet_empty"
}

• error — safe to display to your customer. Neutral, no MASTER PAY-specific language, no numeric leaks.
• merchant_message — for your server logs / admin alerts only. Tells you exactly what to fix. Never render this to the end customer.
• code — stable machine-readable identifier (e.g. merchant_wallet_empty, order_already_paid). Use this for programmatic branching.
• Other fields like insufficient_balance or existing_session_id are programmatic hints — safe but uninformative if shown.

Reference handler (Node):

const r = await fetch(...);
const body = await r.json();
if (!r.ok) {
  // Log the technical detail for ops
  console.warn('[masterpay]', body.merchant_message || body.error, '— code:', body.code);
  // Show ONLY the safe text to the customer
  return res.status(503).json({ error: body.error });
}

MASTER PAY throttles every public endpoint to protect against brute force, TxnID mining, and runaway integrations. When you exceed a limit you get HTTP 429 instead of the normal response — the request did not run.

Per-endpoint limits

429 response shape

Every throttled response carries a body explaining the retry window and headers a polite client can read.

HTTP/1.1 429 Too Many Requests
X-RateLimit-Limit:     60
X-RateLimit-Remaining: 0
X-RateLimit-Reset:     1716210000
Retry-After:           37

{
  "error":               "API rate limit exceeded. Slow down session creation.",
  "retry_after_seconds": 37
}

• X-RateLimit-Limit — the cap for this endpoint.
• X-RateLimit-Remaining — how many calls you have left in the current window.
• X-RateLimit-Reset — Unix timestamp when the counter resets.
• Retry-After — seconds to wait before retrying (also in the body as retry_after_seconds).

Polite retry pattern (Node)

async function callWithBackoff(url, init, maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const r = await fetch(url, init);
    if (r.status !== 429) return r;

    // Server told us how long to wait; honour it (cap at 60s).
    const ra = Number(r.headers.get('Retry-After')) ||
               (await r.clone().json().then(b => b.retry_after_seconds).catch(() => 1));
    const waitMs = Math.min(60, Math.max(1, ra)) * 1000;
    if (attempt === maxAttempts) return r; // give up after last attempt
    await new Promise((res) => setTimeout(res, waitMs));
  }
}

Issues integrators hit most often, with the fix.

PHP cURL: SSL routines:ssl3_read_bytes:tlsv1 unrecognized name

TLS handshake error. The client didn't send a Server Name Indication (SNI) the cert recognizes, and old OpenSSL (≤ 1.0.x, common in PHP 5.x / 7.0–7.3) treats it as fatal instead of a warning. Three checks, in order:

1. Hostname must be exact. Use https://checkout.masterpay.it.com — not an IP, not www., not a CDN alias. Calling by IP doesn't send SNI at all.
2. Don't bypass DNS. Do NOT set CURLOPT_RESOLVE or pass --resolve on the CLI — both can send the wrong SNI name.
3. Force TLS 1.2 and keep verification on. Don't disable CURLOPT_SSL_VERIFYPEER or CURLOPT_SSL_VERIFYHOST — that often makes the problem worse, not better.

Working PHP example:

<?php
$ch = curl_init('https://checkout.masterpay.it.com/api/payment/sessions');
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => [
        'Content-Type: application/json',
        'X-API-Key: pk_live_...',
    ],
    CURLOPT_POSTFIELDS     => json_encode([
        'amount'         => 1.00,
        'order_id'       => 'ORD-1',
        'redirect_url'   => 'https://yoursite.com/payment/result',
        'customer_phone' => '7557012345',
        'customer_name'  => 'Customer Name',
    ]),
    CURLOPT_SSLVERSION     => CURL_SSLVERSION_TLSv1_2,
    CURLOPT_SSL_VERIFYPEER => true,
    CURLOPT_SSL_VERIFYHOST => 2,
]);
$response = curl_exec($ch);
if (curl_errno($ch)) {
    error_log('MASTER PAY cURL error: ' . curl_error($ch));
}
curl_close($ch);
$body = json_decode($response, true);
header('Location: ' . $body['checkout_url']);

Still failing? Test from the shell first:

curl -v https://checkout.masterpay.it.com/api/providers

• curl works, PHP fails → upgrade PHP/OpenSSL (PHP ≥ 7.4 with OpenSSL ≥ 1.1.1 fixes it permanently).
• Both fail with the same SNI error → you're on the wrong hostname, or behind a corporate proxy mangling SNI.
• Both succeed but your code still errors → it's your request body, not TLS. Check the response status & body.

404 from /api/payment/sessions

You're hitting the wrong host. MASTER PAY has two services — the dashboard UI and the API — on different domains. The API base URL is https://checkout.masterpay.it.com. Pointing your backend at the dashboard URL returns 404 because the dashboard doesn't serve the API.

Sanity check: curl https://checkout.masterpay.it.com/api/providers should return JSON with the provider list (no auth needed). If it does, the URL is correct; if it doesn't, fix the base URL first.

401 Invalid or expired token

You sent the wrong header for the wrong endpoint:

• Backend-to-MASTER PAY (/api/payment/...): use X-API-Key: pk_live_...
• Merchant dashboard / your own JWT calls (/api/merchant/...): use Authorization: Bearer <jwt>
• APK calls (/api/device/...): use the auth_key field in the JSON body.

Trailing-slash double-slash //api/...

If your config stores the base URL with a trailing slash and your code appends /api/payment/..., you'll request https://checkout.masterpay.it.com//api/payment/sessions. Some nginx setups normalize this; others 404. Strip the trailing slash from your base URL.

402 insufficient_balance

MASTER PAY charges merchants a small per-verification fee, debited from the merchant's wallet on every successful verification. When the wallet drops below that fee, the merchant's operations are paused:

• New POST /api/payment/sessions calls return 402 — xyz.com can't create new checkouts.
• APK endpoints (poll/sms/report/verify/heartbeat) return 402 — the phone shows a "Wallet empty" screen.
• /bind and /unbind stay available so the phone can disconnect/reconnect.

Fix: log into the merchant dashboard → Wallet → Add Balance → pay via wallet. Operations resume on the next request after the recharge confirms.

409 "This order has already been paid"

You called POST /sessions with an order_id that already has a successful session. Don't retry — fetch the existing session via existing_session_id in the error body and treat the order as fulfilled.

Transactions stuck on Pending

The customer submitted a TxnID but no matching SMS has reached the backend. Two common causes:

• No bound device. Check Dashboard → Devices. An "Online" row means the APK is heartbeating; it does NOT guarantee SMS is being forwarded. If the SMS log (Dashboard → SMS) is empty, the APK isn't uploading.
• Gateway identifier mismatch. The number you set on the gateway must appear in the SMS body. For SMS that show only a masked bank suffix (e.g. XX6788), store multiple identifiers comma-separated.

As a fallback, the merchant can resolve any pending row from Dashboard → Transactions (Mark Paid / Mark Failed). Customers still on the checkout page (within ~15s of submitting) see the decision and are redirected; customers who've already returned to your site with status=pending pick up the new state through your backend's polling of GET /sessions/:id.

• 1. Always verify server-side. Don't trust query params on return — call GET /sessions/:id from your backend before fulfilling.
• 2. Keep keys out of git + browser. Store api_key in env vars; never log it.
• 3. Set customer_phone on the session. Tightens SMS matching, reduces false positives dramatically.
• 4. Use HTTPS for redirect_url. No exceptions in production.
• 5. Configure multiple identifiers per gateway. Mobile + bank suffix (comma-separated) means new banks rolling out won't silently stop working.
• 6. Tell vendors to watch /vendor/dashboard/device. If a vendor's bound phone goes offline, their verifications queue but don't complete. You can't see or fix their phone — only they can.
• 7. Keep your wallet topped up. Each successful verification debits a small fee from your wallet balance. Below the per-verification fee, all your endpoints return 402 and your APK is paused. The dashboard shows an amber warning before you hit empty — top up then. Wallet →
• 8. Handle the order_id idempotency response. POST /sessions can return 200 (with existed:true) when the same order_id has a live pending session — use the URL it returns, don't create a parallel checkout.

Today, you confirm payments by polling GET /sessions/:id after the customer returns.

Webhooks are on the roadmap. When live, MASTER PAY will POST to a URL on your domain whenever a session resolves, signed with HMAC-SHA256 of the body using your brand's secret_key:

POST https://yourstore.com/masterpay/webhook
X-MASTER PAY-Signature: t=1683900000,v1=<hmac-sha256-hex>

{ "event": "session.success", "session": { ... } }

Until then, polling on customer return is the recommended pattern.

Questions? Run into something the docs don't cover?

• 📧 Email: support@masterpay.it.com
• 🐛 Bugs / API issues: open a ticket from your dashboard
• 📖 APK developer reference: docs/APK_API.md
• 📖 Integration deep-dive: docs/INTEGRATION.md