Additional Features for Investments PG

Investment PG features are available across the following checkout flows across both one time and subscription payments:

Flow	One Time Payments	Subscription Payments
JS Checkout	Click here
All in one SDK	Click here	Click here
Custom UI SDK	Click here
Custom Checkout	Click here	Click here
Standard Checkout		Click here

Depending on the flow of your choice, please refer the below details for additional changes to support Inverstment PG. The following specific features are available for Mutual fund and Stock trade merchants:

Account Verification
Feed file Support

Account Verification

With the Account verification feature, the merchant can ensure that the customer can only pay with his registered bank account with the merchant while paying via Paytm PG. This is required as a compliance requirement for Investment category merchants like Mutual Fund and Stock Trade.

To support Account verification the merchant must share the registered bank account number of the user with Paytm along with the payment request. Paytm will ensure that the payment happens only via the registered bank account only. If the customer chooses a different bank account to pay the transaction is failed and the merchant can accordingly display the failure reason to the user to choose the registered bank account only.

Note: Account Verification is available only to enterprise customers. Get in touch to request access to Account Verification.

Currently Paytm supports Account Verification for the following payment instruments:-

Netbanking- 30 Banks supported. List of Bank Codes
UPI- Supported across UPI push, collect and Intent flows

One time payments- Integration Steps

1. As part of Initiate Transaction request please add the following parameters:

Name

Description

Required

Schema

requestType

This parameter is used to identify the transaction flow
Possible Values: NATIVE_MF, NATIVE_ST

Yes

string

aggMid

Parent Merchant unique Identifier, Unique Id for merchants provided by Paytm

string

validateAccountNumber

The flag to tell whether to match user's registered account number to the one which is being used for the payment
Possible Values: true, false

Yes

string

allowUnverifiedAccount

This flag tells to proceed for the transaction even if account number mismatched
Possible Values: true, false

Yes

string

accountNumber

User account number(s) to validate.
Can also send multiple account numbers(maximum 5) separated by pipe delimiter '|'
E.g. ACC000XXX | ACC000YYY | ACC000ZZZ

Multiple accounts verification will only work if merchant's acquiring bank is ICICI

Yes

string

enablePaymentMode

List of the payment modes which needs to enable. If the value provided then only listed payment modes are available for transaction.
Possible Values: [{"mode" : "NET_BANKING", "channels" : ["HDFC"}}]

array of object

PaymentMode
Name	Description	Required	Schema
mode	Mode of Payment Possible Values: NET_BANKING, UPI	No	string
channels	Channel associated with mode Possible Values: For UPI: UPI, UPIPUSH, UPIPUSHEXPRESS For NET_BANKING: SBI, PNB, HDFC, ICICI. List of Bank Codes	No	string

Request

curl -X POST 'https://securestage.paytmpayments.com/theia/api/v1/initiateTransaction?mid=INTEGR7769XXXXXX9383&orderId=ORDERID_98765' \
--header 'Content-Type: application/json' \
--data '{"body":{"requestType":"NATIVE_MF","mid":"INTEGR7769XXXXXX9383","orderId":"ORDERID_98765","websiteName":"WEBSTAGING","validateAccountNumber":"true","allowUnverifiedAccount":"false","accountNumber":"6298XXXX4220","txnAmount":{"value":"1","currency":"INR"},"userInfo":{"custId":"CUST001"},"callbackUrl":"https://merchant.com/callback"},"head":{"signature":"{signature}"}}'

Response

{
    "head": {
        "responseTimestamp": "1597923613075",
        "version": "v1",
        "signature": "uXJ0IX888MWU2taGAOMxERMiCG6u4Lp+w4fSoIDsxrhucewW2k9TehYBp+FaURz6Ik4+oromvi6s8iXsQUjVRdGBqkUV0QejHX+H1tpcO7s="
    },
    "body": {
        "resultInfo": {
            "resultStatus": "S",
            "resultCode": "0000",
            "resultMsg": "Success"
        },
        "txnToken": "7a6cda2abf82439ba5416e10763551d51597923386883",
        "isPromoCodeValid": false,
        "authenticated": false
    }
}

2. Optional: Now as part of Fetch Payment options API only UPI and registered bank NB would be available for the customers to pay.

3. In case of Custom checkout flow, call the Process Transaction API, after the user has selected the payment option.

Request

curl -X POST 'https://securestage.paytmpayments.com/theia/api/v1/processTransaction?mid=INTEGR7769XXXXXX9383&orderId=ORDERID_98765' \
--header 'Content-Type: application/json' \
--data '{"body":{"orderId":"ORDERID_98765","paymentMode":"NET_BANKING","channelCode":"ICICI","mid":"INTEGR7769XXXXXX9383","authMode":"USRPWD","requestType":"NATIVE_MF"},"head":{"txnToken":"7a6cda2abf82439ba5416e10763551d51597923386883"}}'

Response

{
    "head": {
        "responseTimestamp": "1597924034757",
        "version": "v1"
    },
    "body": {
        "resultInfo": {
            "resultStatus": "S",
            "resultCode": "0000",
            "resultMsg": "Success"
        },
        "bankForm": {
            "pageType": "redirect",
            "isForceResendOtp": false,
            "redirectForm": {
                "actionUrl": "https://shopping.icicibank.com/corp/BANKAWAY?IWQRYTASKOBJNAME=bay_mc_login&BAY_BANKID=ICI",
                "method": "post",
                "type": "redirect",
                "headers": {
                    "Content-Type": "application/x-www-form-urlencoded"
                },
                "content": {
                    "MD": "P",
                    "SBMTTYPE": "POST",
                    "PID": "000000001813",
                    "ES": "OTnIo+Y/D79w8TG7/CYX1dsGLATkGoP5+lU8CqYMobUZTZsTOb/nirWVrgrnXPWJnse4reQz5BCsBZC21GaAUzxrkbCzWktSLXtLGNMIFQnMWXdrWZUiy4j+k54JPlBJm/njq15x3cJ9izjNIOVqP3+1+VkCDXiFLiv2HqElVqI9/tAh4g4sYVornza7SODfiPtJQc7rviMxzUKAV551Xmzp9wY9PvkKNLVX7h42n+ogPdg4yM9HbDKC+RuYspmcaW5rAlIl8m2P3kaisLe37g=="
                }
            }
        }
    }
}

4. In case at the time of payment account validation does not happen the following error code and response would be returned as part of Process Transaction API, Transaction Status API, Payment Status Webhook

Response Attributes

ATTRIBUTE	DESCRIPTION	EXAMPLE
ORDERID	Unique reference ID for a transaction which is generated by merchant and sent in the request	ORDERID_98765
MID	This is a unique identifier provided to every merchant by Paytm	INTEGR7769XXXXXX9383
TXNID	This is a unique Paytm transaction ID that is issued by Paytm for each transaction	20200XXXXXXXX800110168357341774707
TXNAMOUNT	Amount paid by customer in INR	1
PAYMENTMODE	The payment mode used by customer for transaction	NET_BANKING
CURRENCY	Currency in which the transaction has taken place. Currently only "INR" is the supported currency of transaction	INR
TXNDATE	Date and Time of transaction in the format "yyyy-MM-dd HH:mm:ss.S"Example: "2015-11- 02 11:40:46.0"	2020-08-20 19:11:31
STATUS	This contains the transaction status	TXN_SUCCESS
RESPCODE	Codes refer to a particular reason of payment failure/success	01
RESPMSG	Description message is linked with each respcode.	Txn Success
GATEWAYNAME	Gateway used by Paytm to process the transactions. Issuing bank name is passed in this field eg ICICI	ICICI
BANKTXNID	The transaction ID sent by the bank. In case of Paytm proprietary instruments too, there is a unique reference number generated by Paytm's system. In case the transaction does not reach the bank, this will be NULL or empty string. Primary reason for this is user dropping out of the payment flow before the transaction reaches to bank to servers	23309276638
CHECKSUMHASH	Security parameter to avoid tampering. Verified using server side checksum utility provided by Paytm.	2Lvtj3jpbT2jC+iKS/AVPH84/T73siq7mwifcU6jwTptpZAo8mNaQCvFdb4u7crSoIF+RUwc/KOCw0cJPNOV8hbO

Bank Mandates- Account number entered by user to setup mandate is the only bank account allowed by the bank to be used to setup mandate
Authenticate Subscription form post
UPI- Supported across UPI push, collect and Intent flows. Subscription would only be allowed to be actviated using the bank account shared by the merchant

Subscription- Integration Steps

1. As part of Initiate Subscription request please add the following parameters:

Name

Description

Required

Schema

requestType

This parameter is used to identify the transaction flow
Possible Values: NATIVE_MF_SIP

Yes

string

aggMid

Parent Merchant unique Identifier, Unique Id for merchants provided by Paytm

string

validateAccountNumber

The flag to tell whether to match user's registered account number to the one which is being used for the payment
Condition: Use only for UPI
Possible Values: true, false

Conditional

string

allowUnverifiedAccount

This flag tells to proceed for the transaction even if account number mismatched
Condition: Use only for UPI
Possible Values: true, false

Conditional

string

accountNumber

User account number to validate
Condition: Use only for UPI

Conditional

string

subscriptionPaymentMode

The payment mode which user has selected to complete creation and renewal of subscription
Possible Values: BANK_MANDATE, UPI

string

mandateAccountDetails

Mandate Account Detail - For Stardard Checkout (Redirection Flow)

object

MandateAccountDetails
Name	Description	Required	Schema
accountHolderName	Account Holder Name Example: Lalit Chaudhary	No	string
channelCode	Account Holder's Bank Code Examples: SBI, HDFC, ICICI etc.	No	string
accountNumber	Account Number Example: 62980XXXX220	No	string
ifsc	Bank IFSC Example: ICIC00XX298	No	string
accountType	Account Type Pssible values: ISA, CA, OTHERS	No	string

Request

curl -X POST 'https://securestage.paytmpayments.com/subscription/create?mid=INTEGR7769XXXXXX9383&orderId=ORDERID_98765' \
--header 'Content-Type: application/json' \
--data '{"body":{"requestType":"NATIVE_MF_SIP","mid":"INTEGR7769XXXXXX9383","websiteName":"WEBSTAGING","orderId":"ORDERID_98765","subscriptionAmountType":"VARIABLE","subscriptionMaxAmount":"2","subscriptionFrequency":"1","subscriptionFrequencyUnit":"DAY","subscriptionStartDate":"2020-08-21","subscriptionExpiryDate":"2023-10-21","subscriptionEnableRetry":"1","subscriptionGraceDays":"0","validateAccountNumber":"true","allowUnverifiedAccount":"false","accountNumber":"6298XXXX4220","txnAmount":{"value":"1","currency":"INR"},"userInfo":{"custId":"CUST001"},"callbackUrl":"https://merchant.com/callback"},"head":{"signature":"{signature}"}}'

Response

{
    "head": {
        "responseTimestamp": "1597987037048",
        "version": "v1",
        "signature": "q4YgRZwh20L76JYLGPwZIhhqeORenN6NrOpwQP0dOgUMunTQkzIungdWtHYKkJEglqBduXbtBCmyWPk9MUIYadM/b5YubojZbdT/QnOKmhU="
    },
    "body": {
        "resultInfo": {
            "resultStatus": "S",
            "resultCode": "0000",
            "resultMsg": "Success"
        },
        "txnToken": "7a6cda2abf82439ba5416e10763551d51597923386883",
        "subscriptionId": "64665",
        "isPromoCodeValid": false,
        "authenticated": false
    }
}

2. Optional: Now as part of Fetch Payment options API only UPI and List of Bank Mandate supported would be available for the customers to pay.

3. In case of Custom checkout flow, call the Process Transaction API, after the user has selected the payment option.

Request

<html>
    <head>
    <title>Authenticate Subscription</title>
    </head>
    <body>
    <form name="paytm_form" method="POST" action="https://securestage.paytmpayments.com/order/pay?mid=INTEGR776XXXXXX29383&orderId=ORDR_20200429190414">
        <input type="hidden" name="txnToken" value="7a6cda2abf82439ba5416e10763551d51597923386883" /> 
        <input type="hidden" name="SUBSCRIPTION_ID" value="64665" />
        <input type="hidden" name="paymentMode" value="BANK_MANDATE" />
        <input type="hidden" name="AUTH_MODE" value="USRPWD" />
        <input type="hidden" name="ACCOUNT_TYPE" value="ISA" />
        <input type="hidden" name="account_number" value="917777777777" />
        <input type="hidden" name="USER_NAME" value="Lalit" />
        <input type="hidden" name="channelCode" value="PPBL" />
        <input type="hidden" name="mandateAuthMode" value="NET_BANKING" />
        <input type="hidden" name="bankIfsc" value="PYTM0123456" />
    </form>
    <script type="text/javascript">
        document.paytm_form.submit();
    </script>
    </body>
</html>

Response Attributes

ATTRIBUTE	DESCRIPTION	EXAMPLE
ORDERID	Unique reference ID for a transaction which is generated by merchant and sent in the request	ORDERID_98765
MID	This is a unique identifier provided to every merchant by Paytm	INTEGR7769XXXXXX9383
TXNID	This is a unique Paytm transaction ID that is issued by Paytm for each transaction	20200XXXXXXXX800110168357341774707
TXNAMOUNT	Amount paid by customer in INR	1
PAYMENTMODE	The payment mode used by customer for transaction	UPI
CURRENCY	Currency in which the transaction has taken place. Currently only "INR" is the supported currency of transaction	INR
TXNDATE	Date and Time of transaction in the format "yyyy-MM-dd HH:mm:ss.S"Example: "2015-11- 02 11:40:46.0"	2020-08-20 19:11:31
STATUS	This contains the transaction status	TXN_SUCCESS
RESPCODE	Codes refer to a particular reason of payment failure/success	01
RESPMSG	Description message is linked with each respcode.	Txn Success
GATEWAYNAME	Gateway used by Paytm to process the transactions.	PPBLC
BANKTXNID	The transaction ID sent by the bank. In case of Paytm proprietary instruments too, there is a unique reference number generated by Paytm's system. In case the transaction does not reach the bank, this will be NULL or empty string. Primary reason for this is user dropping out of the payment flow before the transaction reaches to bank to servers	23309276638
ACCNUMVERSUCCESS	Indicates whether the account successfully validates or not. Note: This parameter will come only in case of UPI paymode.	TRUE
CHECKSUMHASH	Security parameter to avoid tampering. Verified using server side checksum utility provided by Paytm.	2Lvtj3jpbT2jC+iKS/AVPH84/T73siq7mwifcU6jwTptpZAo8mNaQCvFdb4u7crSoIF+RUwc/KOCw0cJPNOV8hbO

Response Codes and Messages

RESPCODE	STATUS	RESPMSG
01	TXN_SUCCESS	Transaction Successful.
3006	TXN_SUCCESS	SUCCESS (For Bank Mandate)
141	TXN_FAILURE	Transaction cancelled by customer after landing on Payment Gateway Page.
227	TXN_FAILURE	Payment Failed due to a Bank Failure. Please try after some time. Account Details used for Payment do not match with the Account Details registered. Please retry payment or edit your bank account details to complete the payment. Your payment has been declined by your bank. Please try again or use a different method to complete the payment
507	TXN_FAILURE	When user's account number provided by merchant doesn't match with the one used for payment(Account Number Mismatch).
508	TXN_FAILURE	When account Details of the User could not be fetch.(Account Not Exists) (In case of Paytm Payments Bank only).
810	TXN_FAILURE	Page closed by customer after landing on Payment Gateway Page.
8102	TXN_FAILURE	Transaction cancelled by customer post login. Customer had sufficient Wallet balance for completing transaction.
8103	TXN_FAILURE	Transaction cancelled by customer post login. Customer had in-sufficient Wallet balance for completing transaction.
AP05	TXN_FAILURE	No such account (For Bank Mandate)

Feed File

Paytm PG supports payments from Mutual Fund Clients. The Settlement Report for Mutual Fund merchants must include details of the Mutual Fund Purchased. This report is used by their team to allocate mutual funds to the customer. This report is also called as a Feed File. Please reach out to us here

Please click here to download a sample Feed File.

Note: Feed File Support is available only to enterprise customers. Get in touch to request access to Feed file support.

We currently support 12 fields that the merchant can send at the time of payment and the same are included in the Feed file sent to the merchant. These 12 fields can be used by the merchant to specify the details which are needed by them for final fund allocation.

Integration Steps

One time Payments

As part of the Initiate Transaction API, you may pass the following parameters

Name	Description	Required	Schema
additionalInfo	This contains the Map of additional info which need to be send by merchant.(ref1, ref2,...,ref12)	Yes	Map<String,String> Max 4096 Char

Subscription Payments

As part of the Initiate Subscription API, you may pass the following parameters

Name	Description	Required	Schema
additionalInfo	This contains the Map of additional info which need to be send by merchant.(ref1, ref2,...,ref12)	Yes	Map<String,String> Max 4096 Char

As part of the Renewal API, you may pass the following parameters

Name	Description	Required	Schema
requestType	Request Type Value: SUBS_RENEWAL_MF_SIP	Yes	string
feedFileInfo	This contains the Map of additional info which need to be send by merchant.(ref1, ref2,...,ref12)	Yes	Map<String,String> Max 4096 Char

Note: When the payment is done and the feed file shared with the merchant the next day it will include the data as per the Ref 1 - Ref 12 columns