paytm developer docs logoDeveloperDocumentation
search

POSTPost Facto Split Settlement API

Use Case

Post-transaction split settlement for orders that are on hold (based on POST_TXN identifier in Initiate Transaction API). User needs to first identify the historical orders that require split settlement based on their preference (Split-type as POST_TXN) at the time of order creation. Once they have identified these orders, they can use this API to initiate the split settlement requests. This will split the settlement amount between the merchant and the relevant parties involved in the transaction.

Request Attributes

Content Type : JSON

Head

AttributeDescription
version
string
optional

Version of the API.

Example: v1

requestTimestamp
string
optional

EPOCH timestamp of the time at which request is being sent.
Example: 1588402269

tokenType
string
mandatory

This parameter identifies whether the API works on checksum authentication. 

Possible Values: CHECKSUM

token
string
mandatory

For tokenType CHECKSUM, It's value to be sent should be the checksum string created by using Paytm checksum library. Authorization string corresponding to the tokenType used.
Example: 16Xm7DXbvNqhaLw+HMj4XB6XTQKCoM=

requestId
string
mandatory

Unique reference ID for a transaction which is generated by merchant and sent in the request

Body

AttributeDescription
mid
string
mandatory

Paytm provides MID as a unique identifier to each merchant. For your staging MID, click here. You get the production MID post the account activation.

Example: INTEGR7769XXXXXX9383

orderId
string
conditional

Main merchantTransId

Note: If acqId is blank then orderId is mandatory
acqId
string
conditional

acqId of main order

Note: if orderId is blank then acqId is mandatory.
splitSettlementInfo
object
mandatory

Split payment details.

splitSettlementInfo
+
AttributeDescription
splitMethod
string
optional

Split method

Possible Values: AMOUNT, PERCENTAGE

splitInfo
object
optional

List for child vendor merchant mid's and their split info

splitInfo
+
AttributeDescription
mid
string
mandatory

Child mid

amount
object
conditional

Share of child vendor in the split by amount base
Use: Only splitMethod is AMOUNT

amount
+
AttributeDescription
value
string
mandatory

This parameter contains the amount to be charged to the customer and can have two places of decimal.
Example: 1.00

currency
string
mandatory

This parameter indicates the currency in which transaction amount is to be deducted.
Possible Values: INR

percentage
string
conditional

Share of child vendor in the split by percentage base
Use: Only splitMethod is PERCENTAGE

partnerId
string
conditional

Optional alternate id created for child MID

goods
object
optional

Split merchant goods info list

goodsInfo
+
AttributeDescription
merchantGoodsId
string
optional

Unique id for the goods item (item no)

merchantShippingId
string
optional

Merchant shipping id

snapshotUrl
string
optional

Product Image URL

description
string
mandatory

Description of product

category
string
optional

Category of Product

quantity
string
mandatory

Quantity ordered

unit
string
optional

Unit of quantity (KG/Litre)

price
object
mandatory

Price of product

Money
+
AttributeDescription
value
string
mandatory

This parameter contains the amount to be charged to the customer and can have two places of decimal.
Example: 1.00

currency
string
mandatory

This parameter indicates the currency in which transaction amount is to be deducted.
Possible Values: INR

extendInfo
object
optional

Extended info of goods

ExtendedInfo
+
AttributeDescription
udf1
string
optional

User define parameter 1. Merchant will receive this parameter in the callback and transaction status API response.

udf2
string
optional

User define parameter 2. Merchant will receive this parameter in the callback and transaction status API response.

udf3
string
optional

User define parameter 3. Merchant will receive this parameter in the callback and transaction status API response.

mercUnqRef
string
optional

Merchant's reference text which comes in final response of Process Transaction API from Paytm

comments
string
optional

Comments

subwalletAmount
string
optional

This parameter is required to limit the maximum amount that could be deducted from a particular subwallet. This parameter is only used for payMode Balance (Paytm Wallet).

Possible Keys: FOOD, GIFT, MULTI_PURPOSE_GIFT, TOLL, CLOSED_LOOP_WALLET, CLOSED_LOOP_SUB_WALLET, FUEL, INTERNATIONAL_FUNDS_TRANSFER, CASHBACK, GIFT_VOUCHER. e.g. "subwalletAmount":{ "FOOD": "2"}

Note:  As per compliance rules, you need to send the Food item amount separately to Paytm.

shippingInfo
object
optional

Split merchant shipping info list

shippingInfo
+
AttributeDescription
merchantShippingId
string
optional

Merchant shipping id

trackingNo
string
optional

Tracking no of shipment

carrier
string
optional

Shipping carrier name

chargeAmount
object
optional

Shipping amount

Money
+
AttributeDescription
value
string
mandatory

This parameter contains the amount to be charged to the customer and can have two places of decimal.
Example: 1.00

currency
string
mandatory

This parameter indicates the currency in which transaction amount is to be deducted.
Possible Values: INR

countryName
string
optional

Shipping country name

stateName
string
optional

Shipping state name

cityName
string
optional

Shipping city name

address1
string
optional

Shipping address 1

address2
string
optional

Shipping address 2

firstName
string
optional

Receiver first name

lastName
string
optional

Receiver last name

mobileNo
string
optional

Receiver mobile no

zipCode
string
optional

Receiver zip code

email
string
optional

Valid email of the user.

Example: vaibhav41094@gmail.com

extendedInfo
object
optional

Extended info of goods.

extendedInfo
+
AttributeDescription
udf1
string
optional

User define parameter 1. Merchant will receive this parameter in the callback and transaction status API response.

udf2
string
optional

User define parameter 2. Merchant will receive this parameter in the callback and transaction status API response.

udf3
string
optional

User define parameter 3. Merchant will receive this parameter in the callback and transaction status API response.

mercUnqRef
string
optional

Merchant's reference text which comes in final response of Process Transaction API from Paytm

comments
string
optional

Comments

subwalletAmount
string
optional

This parameter is required to limit the maximum amount that could be deducted from a particular subwallet. This parameter is only used for payMode Balance (Paytm Wallet).

Possible Keys: FOOD, GIFT, MULTI_PURPOSE_GIFT, TOLL, CLOSED_LOOP_WALLET, CLOSED_LOOP_SUB_WALLET, FUEL, INTERNATIONAL_FUNDS_TRANSFER, CASHBACK, GIFT_VOUCHER. e.g. "subwalletAmount":{ "FOOD": "2"}

Note:  As per compliance rules, you need to send the Food item amount separately to Paytm.

Response Attributes

Content Type : JSON

Head

AttributeDescription
version
string

Version of the API.

Example: v1

responseTimestamp
string

EPOCH timestamp of the time at which response is being sent.
Example: 1588402269

Body

AttributeDescription
mid
string

Main merchant mid

orderId
string

Main merchantTransId

acqId
string

acqId of main order

resultInfo
string

result info object

resultInfo
+
AttributeDescription
resultCode
string

This is the resultCode corresponding to a particular message and is returned to the merchant. It's maximum length is 64. The different result codes corresponding to this API are mentioned below.

resultStatus
string

This parameter indicates the status of API call.

Possible values:
S
For Success
,
F
For Failure
resultMsg
string

This parameter is the result message which contains information about the result. The different result messages corresponding to this API are mentioned below in section " Response Codes and Messages".

Response Codes & Messages

resultCoderesultStatusresultMsg
0000SSuccess
0001FFAILED
0001F

Generic msg: parameter illegal (if mandatory params are not sent in request)

Specific Use Case:

  • splitCommandInfo can't be blank
  • splitCommandInfo illegal
  • split percentage illegal
  • amount sent for PERCENTAGE method
  • split amt illegal
  • amt curr invalid
  • percentage sent for AMOUNT method
  • multi split on main merchant not allowed
  • split percent greater than 100%
  • split amt greater than main order amt
  • post txn split not allowed
  • split and fee amt greater than order amt
0001F

Parent merchant and child merchant relationship illegal

0001FSplitSettlementInfo list size cannot be greater than 50
0001FSplit methods are not equal
309FInvalid Order ID
0001PendingOrder status is not confirmed yet
501USystem error
1007FMissing mandatory element
2005FChecksum provided is invalid
2006FMid is invalid
1001FRequest parameters are not valid
0001FDuplicate request exception
0001FSplit already in progress
⇾
Staging
Production
https://securegw-stage.paytm.in/theia/postTransactionSplit copy icon
REQUEST
RESPONSE
CURL
curl --location ' https://securegw-stage.paytm.in/theia/postTransactionSplit?mid=YOUR_MID' \
--header 'Content-Type: application/json' \--header 'Cookie: JSESSIONID=51853B7D9DCCADA66A7C3B2913E87A86' \--data '{"body": {"mid": "brZxxxxxxxxxxxxxx616","acqId":"20230406011810000850797261947674580","splitSettlementInfo": {"splitMethod": "PERCENTAGE",
"splitInfo": [{"mid": "RSyxxxxxxxxxxx383","percentage": "100"}]}},"head": {"version": "v1","requestTimestamp": "1680789582827","requestId": "9899odmb437jkhkjhgj35959511","tokenType": "CHECKSUM","token":"rdhghvjbkm"}}'
        
        
        
        
        
    




 
copy icon