paytm developer docs logoDeveloperDocumentation
search

POSTSettlement API

Use Case

The Settlement API is used to reconcile the settlement data. This API provides the transaction-level data for all settled transactions. It includes all types of transactions namely, sale (forward) transactions, refunds and chargebacks. This API also gives total bank settled amount and total count of transactions.

Note-

  • This API can be used only on production environment.
  • Paytm Recon system reconciles the transactions even on weekends or day of public holidays, however the payout cannot be released. The payout will be made on next business day. Hence, this API won’t return any response.
  • Date field range can be of maximum 1 day.
  • On a regular business day, settlement processing and payout happens on the same day.

Settlement Cycle Phases

Request Attributes

Attribute Description
MID
string		 Unique Merchant ID provided at the time of integration
Example: INTEGR7769XXXXXX9383
utrProcessedStartTime
string
mandatory		 Date from which merchant wants to check the settlement data. Data will be available for last 6 months of the current date
Example: 2020-04-20		  
utrProcessedEndTime
string
optional		 Date to which merchant wants to check the settlement data. Data will be available for last 6 months of the current date.
Example: 2020-04-20
Note: If not provided, API will pick this value as utrProcessedStartTime + 1
checksumHash
string
mandatory		 Paytm validates the request and ensures that parameters are not tempered by verifying the signature in the request. For creating the checksum (signature) refer to the steps given in Checksum Logic.
Note: Create the signature using the body parameter of the request.
pageNum
integer
mandatory		 Current page number
Example: 1
pageSize
integer
mandatory		 Max entry count in a page, max value is 20
Example: 20

Response Attributes

Attribute Description
status
Enum RestStatus

This parameter indicates the status of API call.
Example: SUCCESS

Possible values: SUCCESS, FAILURE, RECORD_NOT_FOUND
count
integer

Count

Example: 2
resultCode
string		 This is the resultCode corresponding to a particular message and is returned to the merchant. Its maximum length is 64.
Example: 00000000
errorMessage
string		 Error Message
Example: CHECKSUM_VALIDATION_FAILED
totalCount
integer		 Count of transactions/refunds included in the settlement on the chosen day
Example: 1
settlementDetailList
list		 The list of detailed settlements.
paginatorPageNum
integer		 Current page no
Example: 1
paginatorPageSize
integer		 No. of transaction records on the current page
Example: 20
paginatorTotalPage
integer

Total number of pages that contain transaction level data for that date
Example: 1
paginatorTotalCount
integer		 Total count of transactions
Example: 4

 

Settled Transaction Detail Response VO parameters:

Attribute Description
txnId
string		 This is a unique Paytm transaction ID that is issued by Paytm for each transaction.
Example: 20190604111212800110168516600919244
txnType
integer

Transaction type of the payment.
Example: TRANSACTION

Possible values: TRANSACTION, REFUND, ALL, ADDMONEY, M2B, TRANSFER_FOR_SETTLEMENT, ALL_SETTLEMENT, CANCEL, SETTLEMENT, DISPUTE, TOPUP, TOPUP_REFUND, REPAYMENT
txnDate
string		 Transaction Date
Example: 2019-06-04 16:52:48
txnAmount
string		 Payment transaction amount
Example: 2.00
bankName
string		 Issuing bank of the customer
Example: WALLET
custId
string		 Customer ID of the person making the transaction
Example: Test101
paymentMode
string		 Payment mode used by the customer
Example: PPI
mid
string		 Paytm provides MID as a unique identifier to each merchant.
Example: xxxxxxxxxxxxxxxxxxxxx
merchantName
string		 Name of the merchant
Example: AutomationMerchant001
orderId
string		 Unique reference ID for an Order request generated by merchant for payment.
Example: PARCEL51103
mercUnqRefVal
string

Any unique information that the merchant wants to record.
utrProcessedTime
string


The time stamp of UTR update.

Example: 2019-06-06 16:00:00
utr
string		 Unique transaction reference number from bank of the settlement made to merchant’s bank.
Example: 1910535110000023
settleAmount
string		 Total amount settled to the merchant on the chosen day
Example: 2.00
payoutDate
string		 Timestamp when the settlement process starts
Example: 2019-06-05 00:00:00
gst
string		 Tax charged against this transaction
Example: 0.37
commission
string		 Commission charged against this transaction
Example: 1.06

Response Codes & Messages

resultCoderesultStatusresultMsg
00000000SUCCESSSUCCESS
00000010FAILUREException while processing request for query
00000022FAILURECHECKSUM_VALIDATION_FAILED
00000030FAILUREILLEGAL_PARAM
00000031FAILUREFACADE_EXCEPTION
00000074FAILUREToo many requests sent per second. TPS Breached
⇾
Staging
Production
This API is not hosted on staging environment.copy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET

curl -X POST 'https://secure.paytmpayments.com/merchant-settlement-service/settlement/list' \
--header 'Content-Type: application/json' \
--data '{"MID": "xxxxxxxxxxxxxxxxxxxxx", "utrProcessedStartTime": "2019-06-08", "pageNum": 1, "pageSize": 20, " checksumHash ": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"}'
copy icon