intelligent.pageDocs

Paytm

Paytm has a documented payments and settlement API with checksum signed requests, but its marketplace seller side is a panel with no public API.

Paytm is two very different things to a seller, and a connector has to pick one. As a payment gateway it has a real, public, well documented developer platform: self serve account creation, versioned REST APIs, staging endpoints, server SDKs, a Postman collection, webhooks and a settlement API that returns bank UTRs. As a marketplace, Paytm Marketplace, formerly Paytm Mall, it has a login only seller panel at seller.paytm.com and publishes nothing programmatic at all. This page covers both, with the payments side documented in detail because that is where the verifiable surface is, and where the settlement data a commerce database actually needs lives.

At a glance

What it is

Paytm began as a mobile wallet and became India's most visible consumer payments brand, then spread into a payment gateway for merchants, point of sale hardware, a lending distribution business and, for several years, a marketplace. The marketplace, Paytm Mall, was spun into a separate entity and wound down commercially. Its remains are still online: paytmmall.com serves a bare storefront shell with a 2026 copyright, and seller.paytm.com still serves a working "Paytm Marketplace" sign up flow. Neither should be treated as a growing channel without confirming with Paytm that it is open for business.

The payments business is very much alive and is the part worth integrating.

Note

The seller sign up page at seller.paytm.com contains an error state reading "Your account has been delisted due to" followed by a reason list, with an instruction to raise a ticket for review. A sign up screen that leads with delisting handling is a signal about the state of that marketplace. Confirm channel viability before you scope it.

API access

For payments, self serve. Create an account from the developer site, get a Merchant ID, called MID, and a merchant key. Staging credentials are available immediately; production credentials follow account activation. The documentation set covers Payment Gateway, QR Code, Payment Links, Payment Invoice, Subscriptions, International Merchants, split settlements, disputes, tokenisation, EMI and no cost EMI, guest checkout and a point of sale stack. Paytm publishes server SDKs, e-commerce platform plugins, a Postman setup guide, a checkout playground and an API playground.

For the marketplace, onboarding is documented on the sign up page itself as five steps: have your Paytm credentials ready, log in with them, give the name and email you want to register with, submit the requested documents, and go live after document verification. No API, no credential console, no developer documentation.

Authentication

Paytm does not use OAuth. It uses a checksum signature over the request, and the same mechanism in reverse to verify responses.

  1. Obtain your MID and merchant key from the Paytm dashboard. The merchant key is a secret and never leaves your server.
  2. Build the request. Most modern APIs take a JSON object with a head object and a body object.
  3. Compute the checksum over the request body using your merchant key. Paytm's own description: checksums use "SHA256 hashing and AES128 encryption", calculated over parameters in name value pair format for the legacy surfaces.
  4. Put the result in head.signature.
  5. On the response, recompute the checksum over the response body and compare it to the head.signature Paytm returned. A mismatch means the response was altered and must be rejected.

Paytm ships checksum utilities in its server SDKs so that you do not implement the hashing yourself. Use them.

There is no access token and therefore no refresh job. The credential store needs to hold, per merchant account, a MID and a merchant key, and nothing expires on a timer. Multi account handling is simply one MID and key pair per merchant entity, with the MID carried in both the query string and the request body on most calls.

A transaction initiation looks like this. Staging host shown, because that is the one Paytm publishes:

POST /theia/api/v1/initiateTransaction?mid={mid}&orderId={order-id} HTTP/1.1
Host: securestage.paytmpayments.com
Content-Type: application/json

{
  "head": {
    "signature": "{checksum}",
    "version": "v1",
    "channelId": "WEB",
    "requestTimestamp": "1588402333"
  },
  "body": {
    "requestType": "Payment",
    "mid": "{mid}",
    "orderId": "{order-id}",
    "websiteName": "WEBSTAGING",
    "callbackUrl": "https://{your-domain}/paytm-callback",
    "txnAmount": { "value": "1.00", "currency": "INR" },
    "userInfo": { "custId": "{customer-id}" }
  }
}

The response carries a txnToken valid for fifteen minutes:

{
  "head": {
    "signature": "{signature}",
    "version": "v1",
    "responseTimestamp": "1588402333"
  },
  "body": {
    "resultInfo": {
      "resultCode": "0000",
      "resultStatus": "S",
      "resultMsg": "Success"
    },
    "txnToken": "f0bed899539742309eebd8XXXX7edcf61588842333227"
  }
}

Result codes worth handling up front: 0000 success, 2005 invalid checksum, 1006 session expired, 1007 missing mandatory element.

Objects we can read

Payments and settlements

This is the object that matters for a commerce database, because it is the only place in a multi channel stack where money actually lands with a bank reference.

POST /merchant-settlement-service/settlement/list HTTP/1.1
Host: secure.paytmpayments.com
Content-Type: application/json

Request body fields, per Paytm's reference: MID mandatory, utrProcessedStartTime mandatory in YYYY-MM-DD form, utrProcessedEndTime optional and defaulting to start plus one day, pageNum mandatory, pageSize mandatory with a maximum of 20, and checksumHash mandatory.

Response fields: status with values SUCCESS, FAILURE or RECORD_NOT_FOUND, resultCode where 00000000 is success, errorMessage, totalCount, paginatorPageNum, paginatorPageSize, paginatorTotalPage, paginatorTotalCount, and settlementDetailList, an array of transaction level detail carrying txnId, amount, utr and settleAmount.

Three constraints shape any sync job you write against it:

  • Production only. There is no staging settlement data.
  • Maximum one day date range per call. So the pagination model is a date window loop with a page loop nested inside it.
  • Six months of history. Backfill early and keep your own copy, because the window rolls.

Paytm documents a family of related calls beyond the list endpoint: Split Settlement, Settlement Summary, Settlement Detail, Settlement Order Detail and Settlement Transaction Detail. Settlement timing, per Paytm's own introduction, "typically is done on a T+1/T+2 basis excluding the Public/banking holidays (All Sunday, 2nd and 4th Saturdays)".

Refunds

POST /refund/apply HTTP/1.1
Host: securestage.paytmpayments.com
Content-Type: application/json

Head fields: signature mandatory, plus optional version, channelId, requestTimestamp and clientId. Body fields: mid, orderId, refId, txnId, txnType with the value REFUND, and refundAmount, all mandatory, plus optional preferredDestination, comments, disableMerchantDebitRetry, agentInfo, and conditional refundItems. The response carries resultInfo, mid, orderId, refId, refundId, txnId, txnTimestamp and refundAmount.

Note that refId is yours and refundId is Paytm's. Store both, and make refId idempotent, because a retried refund with a fresh refId is a second refund.

Orders, listings, inventory, shipments, returns, customers, locations

Not available. Paytm's APIs are payment APIs. A payment transaction is not an order: it has an orderId that you supplied, so it joins back to your own order record, but it carries no line items, no SKU, no shipping address and no fulfilment state. The marketplace side, which would have had those objects, publishes nothing.

Writing back: listings, price and stock

Not available through any Paytm API. Marketplace catalogue, pricing and stock are managed in the seller panel at seller.paytm.com after document verification. No bulk feed format, no processing report and no job status endpoint is published.

Webhooks and notifications

Paytm distinguishes a callback URL, which receives the transaction status at the end of a checkout, from webhooks, which are server to server event notifications.

Documented webhook events: payment status for one time payments, subscription status, link payment status, accept refund, which fires when the amount is deducted, success refund, which fires when the refund is submitted to the bank, subscription pre notify, dispute and chargeback status, card expiry notification, and downtime notification.

Subscription mechanism: most webhook URLs are configured in the merchant dashboard. Paytm states that subscription status, link payment status, card expiry and downtime notification webhooks require you to "get in touch with us to configure".

One hard constraint worth knowing before you design your endpoint: webhooks "only allow port number 443". Your receiver must be on standard HTTPS.

Verification: the documentation page we read does not state the signature verification procedure for webhooks or the retry policy. Given that every other Paytm surface is checksum signed, verify the checksum on the received body using the same merchant key before acting on it, and confirm the exact procedure with Paytm support. Do not assume an unsigned webhook is safe to trust.

Default callback URLs, used by the SDK integrations: https://securestage.paytmpayments.com/theia/paytmCallback?ORDER_ID=<order_id> on staging and https://secure.paytmpayments.com/theia/paytmCallback?ORDER_ID=<order_id> on production.

Rate limits and pagination

No rate limit numbers and no quota headers are published on the API pages we read. The concrete pagination constraints are on the Settlement API: pageSize capped at 20, a maximum one day date range, and six months of retained history. A daily settlement sync therefore costs one date window and as many pages as the day's transaction count divided by twenty, which for most merchants is a handful of calls.

Mapping to the unified model

Paytm populates the money side of the model and nothing else. Do not create a paytm value in orders.channel for payment gateway data, because a Paytm transaction is a payment against an order you already have from another channel.

Gaps and open questions

  • Webhook signature verification and retry policy are not stated on the callback and webhook page. Confirm with Paytm before you go live.
  • The production host for the Refund API is not listed on the page we read, only the staging host. The settlement endpoint's production host is secure.paytmpayments.com, and the pattern is consistent, but confirm rather than assume.
  • Whether Paytm Marketplace is open to new sellers is unverified. The sign up flow is live, the storefront is a shell, and no aggregator we could check lists it as a supported channel.
  • Per transaction fee schedules drift and are on the pricing page rather than in the API reference. Quote them with a date when you use them.
  • No rate limits are published anywhere we read. Ask for them if you plan a heavy backfill of the six month settlement window.

Sources