paytm developer docs logoDeveloperDocumentation
search
Your Paytm for business app is working and will keep working beyond March 15th, 2024. Click to know more

POSTCreate Order API

Use Case

To start a payment transaction, merchants first need to call this API, this API will return the transaction token as well as create a new order in the AI router system. This transaction token and the order id will be used in the subsequent APIs for transaction processing. 

Request Attributes

Content Type : JSON

Head

AttributeDescription
requestTimeStamp
string
optional

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

channelId
Enum
optional

The parameter value identifies the Channel for which the API call is initiated.

 

Possible values: APP , WEB , WAP

signature
string
conditional

AI router validates the request and ensures that parameters are not tempered by verifying the signature in the request.

 Note: This is mandatory if “'CHECKSUM_ENABLED” is enabled

Body

AttributeDescription
requestType
Enum
mandatory

This parameter is used to identify the transaction flow.
 

Possible Values: SUBSCRIPTION, PAYMENT

mid
string
mandatory

AI router provides MID as a unique identifier to each merchant.

 

Example: 216820000002516036253

orderId
string
mandatory

The Unique reference ID of the Order. It is alphanumeric and max length is 50 characters.

 

Example: OREDRID_98765

txnAmount
object
mandatory

This parameter is of return type Money and should contain the value of transaction i.e. amount and currency type.

 

Example: {"value" : "1.00", "currency" : "INR"}

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

userInfo
object
mandatory

User information contains user details like customer ID, email, phone number etc.

UserInfo
+
AttributeDescription
custId
string
mandatory

Unique reference ID for every customer which is generated by merchant. Special characters allowed in CustId are @, ! ,=,_ ,$, .
Example: CUST_001

mobile
string
conditional

10-digit mobile number of user.
Example: 9988000000

Mandatory, in case merchant wants to give Debit Card EMI as a payment option to its users.

email
string
optional

Valid email of the user.

Example: vaibhav41094@gmail.com

firstName
string
optional

First name of the user

lastName
string
optional

Last name of the user.

enablePaymentMode
Array of PaymentMode
optional

List of the payment modes which need to be enabled. If the value provided then only listed payment modes are available for transaction

 

Example:[{"mode" : "CREDIT_CARD", "channels" : ["VISA" ,"MASTER"],"banks":[ "ICICI" , "SBI" ]}]

PaymentMode
+
AttributeDescription
mode
string
optional
Mode of Payment
BALANCE,
For Paytm Wallet
PPBL, UPI,
For Paytm Payments Bank
CREDIT_CARD
For Credit Card
DEBIT_CARD
For Debit Card
NET_BANKING
For Net Banking
EMI
For Emi Options
PAYTM_DIGITAL_CREDIT
For paytm postpaid
channels
Array of strings
optional
Channel associated with mode.
Possible Values:
For UPI:
UPI
For UPI Collect
UPIPUSH
For UPI Intent
UPIPUSHEXPRESS
For UPI Push

For CREDIT_CARD/DEBIT_CARD/EMI: VISA, MASTER, AMEX
For NET_BANKING: SBI, PNB, HDFC, ICICI. List of Banks
banks
Array of strings
optional

Different Banks are available
"ICICI", "SBI", "AXIS".  List of banks

disablePaymentMode
Array of PaymentMode
optional

List of the payment modes which need to be disabled. If the value provided then all the listed payment modes are unavailable for transaction.

 

Example: [{"mode" : "CREDIT_CARD", "channels" : ["VISA" ,"MASTER"],"banks":[ "ICICI" , "SBI" ]}]

PaymentMode
+
AttributeDescription
mode
string
optional
Mode of Payment
BALANCE,
For Paytm Wallet
PPBL, UPI,
For Paytm Payments Bank
CREDIT_CARD
For Credit Card
DEBIT_CARD
For Debit Card
NET_BANKING
For Net Banking
EMI
For Emi Options
PAYTM_DIGITAL_CREDIT
For paytm postpaid
channels
Array of strings
optional
Channel associated with mode.
Possible Values:
For UPI:
UPI
For UPI Collect
UPIPUSH
For UPI Intent
UPIPUSHEXPRESS
For UPI Push

For CREDIT_CARD/DEBIT_CARD/EMI: VISA, MASTER, AMEX
For NET_BANKING: SBI, PNB, HDFC, ICICI. List of Banks
banks
Array of strings
optional

Different Banks are available
"ICICI", "SBI", "AXIS".  List of banks

callbackUrl
string
optional

AI router sends the response of the transaction on the URL which comes in the callbackUrl parameter.


Note: Either of websiteName or callbackUrl should be passed in the request.

goodsInfo
Array of GoodsInfo
optional

This contain the goods info for an order

GoodsInfo
+
AttributeDescription
merchantGoodsId
string
optional

Unique Id for the goods item (item no)

merchantShippingId
string
optional

Shipping Id

snapshotUrl
string
optional

Product Image URL

description
string
optional

Description of product

category
string
optional

Category of Product

quantity
string
optional

Quantity ordered

unit
string
optional

Unit of quantity (KG/Litre)

price
string
optional

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
string
optional

Extended info of goods

ExtendInfo
+
AttributeDescription
udf1
string
optional

User define parameter 1.

udf2
string
optional

User define parameter 2.

udf3
string
optional

User define parameter 3.

mercUnqRef
string
optional

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

comments
string
optional

Comments

shippingInfo
Array of ShippingInfo
optional

This contains the shipping info for an order.

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

extendInfo
Map
optional

Merchants can pass any order specific information that is required to be passed here.

ssoToken
object
optional

This is a unique token linked with the user's Paytm wallet and is provided in the response while linking the user's Paytm wallet.

SsoToken
+
AttributeDescription
token
string
optional

Numerical digits

pg
string
optional

It will be of ENUM data-type

integrationType
Enum
optional

Possible value: CUSTOM_CHECKOUT, JS_CHECKOUT ,  SDK,  UNKNOWN 

gatewayInfo
Map
optional

Information related to gateway

websiteName
string
mandatory

websiteName is the key to extract the static callbackUrl defined for merchants at AI router. This is provided by AI router.
 

 Note: Either of websiteName or callbackUrl should be passed in the request.

peonUrl
string
optional

AI router sends the notification of transaction on the URL which comes in the peonUrl parameter.

txnRoutingParams
Map<String,Object>
optional

Routing Configuration Input entered for the Enforced routing rule creation must be passed here for the Routing rule adherence.
 

Note: If this field is received txnRoutingParams in both createOrder And Payment API, then Payment API has a higher priority

Response Attributes

Content Type : JSON

Head

AttributeDescription
responseTimestamp
string

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

signature
string

AI router validates the request and ensures that parameters are not tempered by verifying the signature in the request.

Body

AttributeDescription
txnToken
string

This is the unique transaction token received in the response of Create Order API. It is valid for 15 minutes.

resultInfo
object

This parameter gives the information about the result of the API response

resultInfo
+
AttributeDescription
resultStatus
string

This parameter is the result specific to the phase of the transaction mentioned in the txnType field

resultCode
string

This is the resultCode corresponding to a particular message and is returned to the merchant. It's maximum length is 64.

resultMsg
string

This parameter is the result message which contains information about the result.

extraParamsMap
Map

Map for any extra information (in case of error).

Response Codes & Messages

resultCoderesultStatusresultMsg
0000SSuccess
501FSystem Error
2013FMid in the query param doesn’t match with the Mid sent in the request
2014FOrderId in the query param doesn't match with the orderId sent in the request
1001FRequest parameters are not valid Note: If the value is not valid in the request parameter then the result message should be in the format of "Invalid {field name}" For example: Invalid requestType, Invalid currency, etc
1007FMissing mandatory element
2007FTxn amount is invalid
2006FMid is invalid
324FDuplicate Order Id
1011FParameter illegal Note: If the value is not allowed in request parameters then the result message should be in the format of "Parameter '[field name]' has invalid value '[value]'" For example: If we will send PAYMENT1(invalid value) in requestType in create order request then the result message should be "Parameter '[body->requestType]' has invalid value '[PAYMENT1]'"
2012FOrderId is invalid
2222FInvalid request body
2005FChecksum provided is invalid
1012FParam missing
⇾
Staging
Production
https://stage-router.paytm.in/aoa-acquiring-biz/v2/order?mid={mid}&orderId={orderId} copy icon
REQUEST
RESPONSE
CURL
JAVA
NODE
PHP
PYTHON
DOTNET

curl --location --request POST 'https://stage-router.paytm.in/aoa-acquiring-biz/v2/order?mid=YOUR_MID_HERE&orderId=Ravi1366' \
--header 'Content-Type: application/json' \
--data-raw '{"body": {"requestType": "PAYMENT","websiteName":"retail","peonUrl":"/paytm","mid": "YOUR_MID_HERE","orderId": "Ravi1366","txnAmount": {"value": "1","currency": "INR"},"userInfo": {"custId": "cus0012","mobile": "7000000003","email": "abc@gmail.com","firstName": "Ravi","lastName": "Ranjan"},"callbackUrl": "https://pgp-automation.paytm.in/mockbank/MerchantSite/bankResponse","goodsInfo": [{"merchantGoodsId": "24525635625623","merchantShippingId": "564314314574327545","snapshotUrl": "[http://snap.url.com ]","description": "description","category": "travelling/subway","quantity": "3.2","unit": "Kg","price": {"currency": "INR","value": "199"},"extendInfo": {"udf1": "","udf2": "","udf3": "","udf4": "","udf5": ""}}],"shippingInfo": [{"merchantShippingId": "564314314574327545","trackingNo": "646431431322332133","carrier": "Federal Express","chargeAmount": {"currency": "INR","value": "1"},"countryName": "JP","stateName": "GA","cityName": "Atlanta","address1": "137 W San Bernardino","address2": "4114 Sepulveda","firstName": "Jim","lastName": "Li","mobileNo": "13765443223","zipCode": "310001","email": "abc@gmail.com"}],"extendInfo": {"udf1": "abc","udf2": "def","udf3": "xyz","mercUnqRef": "","comments": ""},"integrationType":"JS_CHECKOUT"}}'




 
copy icon