Paytm Payment Gateway

Yellow.ai Integration with Paytm Payment Gateway enables the end user to do the following:

Generate a payment link and receive an intimation regarding the status of the payment as to whether it was a success or failure.
Initiate the process of refund.
Check the status of the refund that was initiated.

1. Use cases

Following are the use cases that are currently accommodated in the Integration:

1.1 Generate Payment Link

In the studio flow builder, you need to choose the node type Integrations from the dialog box and then you will see an option to select Paytm from the list of Integrations that have been enabled for that particular bot.

After clicking on Paytm, you will see that an Integration Action Node is added to the flow builder. On clicking the Integration Action Node, you will see the dropdown of available use cases for this integration and you need to choose Generate Payment Link from that dropdown.

The set of mandatory fields required for the successful execution of this use case (Generate Payment Link in this case), will be displayed. The below-mentioned table consists of the sample value, data type, and description for each field present in the above screenshot:

Field name	Sample value	Data type	Description
Timestamp	1588402269	String	EPOCH timestamp of the time at which the request is being sent
Amount	3500	String	Transaction amount
LinkName	Test	String	Name of the link that you want to display to the customer, link name is used to generate a long URL
LinkType	FIXED	String	Type of link
LinkDescription	Test	String	Description of the link that you want to display to the customer
SendSms	true/false	Boolean	Flag whether SMS is to be sent to the customer by Paytm
SendEmail	true/false	Boolean	Flag whether Email is to be sent to the customer by Paytm
CustomerName	Mahesh	String	Name of the customer
CustomerEmail	[email protected]	String	Email ID of the customer
CustomerMobile	9876543210	String	Mobile number of the customer
LinkNotes	Reference details	String	Add additional notes to your link. This won’t be shown to the customers

The Generate Payment Link Integration Action Node has two possible outcomes, success or failure which are depicted by the success and fallback branches. Based on whether the execution of the Integration Action Node was successful or not, the flow will proceed to the success or fallback branches respectively.

note

The easiest way to identify success/failure is by looking at the key tokenType in the head object. If its value is AES, the response is a success.

Sample response for success

In case of success, you must extract the key shortUrl present in the body object and display it to the end user with an appropriate message with the help of any of the Message type nodes.

{
    "head": {
        "version": null,
        "timestamp": "1566994462639",
        "channelId": null,
        "tokenType": "AES",
        "clientId": null
    },
    "body": {
        "linkId": 5861,
        "linkType": "GENERIC",
        "longUrl": "https://securegw-stage.paytm.in/link/PAYMENTLINKNAME/LL_5861",
        "shortUrl": "https://paytm.me/ID-PBo7",
        "expiryDate": "27/08/2020 17:44:22",
        "isActive": true,
        "merchantHtml": "",
        "createdDate": "28/08/2019 17:44:22",
        "notificationDetails": [],
        "resultInfo": {
            "resultStatus": "SUCCESS",
            "resultCode": "200",
            "resultMessage": "Payment link is created successfully"
 }
}
} 

Sample response for fallback

{
    "head": {
        "version": "v2",
        "timestamp": "28/08/2019 17:47:22",
        "channelId": null,
        "tokenType": null,
        "clientId": null
    },
    "body": {
        "resultInfo": {
            "resultStatus": "FAILED",
            "resultCode": "302",
            "resultMessage": "link name contains sepcial character."
        }
    }
}

To use this Integration Action Node in an app.yellow.ai bot, refer to the below-mentioned example:

 app.executeIntegrationAction({
            "integrationName": "paytm",
            "action": "Generate Payment Link",
"dynamicParams": {
    "amount": "5",
    "timestamp": "1658203708983",
    "linkName": "Test",
               "linkType": "FIXED",
               "linkDescription": "Test Description",
                          "sendSms": false,
                          "sendEmail": false,
                          "customerName": "John Doe",
                          "customerEmail":"[email protected]",
                          "customerMobile":"9955995500",
                          "linkNotes":"test note"
}
}).then((res)=>{
    console.log("response from action node", res);
    app.log(res, '||Response from action node||')
}).catch((err)=>{
    console.log("Error in action node",err);
    app.log(err, '||Error in action node||')
})

1.2 Initiate Refund

In the studio flow builder, choose the node type as Integrations from the dialog box. You will see an option to select Paytm from the list of Integrations that have been enabled for that particular bot.

After clicking on Paytm, you will see that an Integration Action Node is added to the flow builder. Upon clicking on the Integration Action Node, you will see the dropdown of available use cases for this integration and you need to choose Initiate Refund from that dropdown.

The set of mandatory fields required for the successful execution of this use case (Initiate Refund in this case), will be displayed. The below-mentioned table consists of the sample value, data type, and description for each field present in the above screenshot:

Field name	Data type	Description	Sample value
RequestTimestamp	String	POCH timestamp of the time at which the request is being sent	1588402269
OrderId	String	It is a unique reference ID for a transaction passed in the transaction request. Order ID should be passed to raise the refund	OREDRID_98765
ReferenceId	String	Unique Reference ID for refund transaction which is generated by merchant. Duplicate REFID will be rejected by the Paytm gateway	REFUNDID_98765
TransactionId	String	TXNID is the Paytm payment Transaction ID against which the refund transaction is being placed.TXNID is provided in response payload for every payment transaction	202005081112128XXXXXX68470101509706
RefundAmount	String	Amount for which the refund is to be made. It can be equal to or less than the transaction amount and should be up to two decimal places. The only special character allowed is (".")	30.00

The Initiate Refund Integration Action Node has two possible outcomes, success or failure which are depicted by the success and fallback branches. Based on whether the execution of the Integration Action Node was successful or not, the flow will proceed to the success or fallback branches respectively.

note

The easiest way to identify success/failure is by looking at the key resultStatus in the resultInfo object. If its value is not TXN_FAILURE, the response is a success.

Sample response for success

In case of success, you need to extract the key resultStatus, and resultMsg in the resultInfo object and display them to the end user with an appropriate message with the help of any of the Message type nodes.

{
    "head": {
        "responseTimestamp": "1567421120859",
        "signature": "WaFdplm36GmfBtZ6jPIFClLSEffhAk9fTpJ6i8WpgqiZvtUNl53mLL7mu4JWwxPpfSa5pdexyxK/68WtoTmd53TI+R9GffjGc3USoLgWcKI=",
        "version": "v1"
    },
    "body": {
        "txnTimestamp": "2019-09-02 12:31:49.0",
        "orderId": "YOUR_ORDER_ID",
        "mid": "YOUR_MID_HERE",
        "refId": "UNIQUE_REFUND_ID",
        "resultInfo": {
            "resultStatus": "PENDING",
            "resultCode": "601",
            "resultMsg": "Refund request was raised for this transaction. But it is pending state"
        },
        "refundId": "PAYTM_REFUND_ID",
        "txnId": "PAYTM_TRANSACTION_ID",
        "refundAmount": "1.00"
    }
}    

Sample response for fallback

{
    "head": {
        "responseTimestamp": "1567421388384",
        "signature": "ry2bNQ+iq+geNezbFNBfIkXXWTFPUnavG6XkxciEJUNLmL7Op9S7qWP8V1TGHNYvggw2IsIt1OmprSfq92pODO5xiNJ+6pFyVtBUxnRrdL8=",
        "version": "v1"
    },
    "body": {
        "orderId": "YOUR_ORDER_ID",
        "mid": "YOUR_MID_HERE",
        "resultInfo": {
            "resultStatus": "TXN_FAILURE",
            "resultCode": "607",
            "resultMsg": "Refund can not be initiated for acanceledd transaction."
        },
        "txnId": "PAYTM_TRANSACTION_ID",
        "refundAmount": "1.00"
    }
}

To use this Integration Action Node in an app.yellow.ai bot, refer to the below-mentioned example:

app.executeIntegrationAction({
            "integrationName": "paytm",
            "action": "Initiate Refund",
"dynamicParams": {
    "requestTimestamp": "1658203708983",
    "orderId": "OREDRID_98765",
    "referenceId": "REFUNDID_98765",
               "transactionId": "202005081112128XXXXXX68470101509706",
               "refundAmount": "30.00"
}
}).then((res)=>{
    console.log("response from action node", res);
    app.log(res, '||Response from action node||')
}).catch((err)=>{
    console.log("Error in action node",err);
    app.log(err, '||Error in action node||')
})

1.3 Check Refund Status

In the studio flow builder, choose the node type Integrations from the dialog box, and then you will see an option to select Paytm from the list of Integrations that have been enabled for that particular bot.

The set of mandatory fields required for the successful execution of this use case (Check Refund Status in this case), will be displayed. The below-mentioned table consists of the sample value, data type, and description for each field present in the above screenshot:

Field name	Sample value	Data type	Description
RequestTimestamp	1588402269	String	EPOCH timestamp of the time at which the request is being sent
OrderId	OREDRID_98765	String	It is a unique reference ID for a transaction passed in the transaction request and the Initiate Refund Integration Action Node. Order ID should be passed to check the actual status of the refund
ReferenceId	REFUNDID_98765	String	Merchant's Reference ID unique for every refund transaction. This is REFID for which refund status is being inquired

The Check Refund Status Integration Action Node has two possible outcomes, success or failure which are depicted by the success and fallback branches. Based on whether the execution of the Integration Action Node was successful or not, the flow will proceed to the success or fallback branches respectively.

note

The easiest way to identify success/failure is by looking at the key resultStatus in the resultInfo object. If its value is TXN_SUCCESS, the response is a success.

Sample response for success

In case of success, extract the key(s) and display to the end user an appropriate message with the help of any of the Message type nodes.

{
    "head": {
        "clientId": "C11",
        "responseTimestamp": "1556719120393",
        "signature": "Stx6P9HpnEG3GADkMuOcj50dm7ZHmvMPd29b8K5rxi4aVzRcJ5hklZo//RZdtTA+zcll8sdelyAYsxqPxFs66RVE0F2b9RElTMqYSfBj89I=",
        "version": "v1"
    },
    "body": {
        "orderId": "YOUR_ORDER_ID",
        "userCreditInitiateStatus": "SUCCESS",
        "mid": "YOUR_MID_HERE",
        "merchantRefundRequestTimestamp": "2019-05-01 19:27:25.0",
        "resultInfo": {
            "resultStatus": "TXN_SUCCESS",
            "resultCode": "10",
            "resultMsg": "Refund Successfull"
        },
        "txnTimestamp": "2019-05-01 19:25:41.0",
        "acceptRefundTimestamp": "2019-05-01 19:27:25.0",
        "acceptRefundStatus": "SUCCESS",
        "refundDetailInfoList": [{
            "refundType": "TO_SOURCE",
            "payMethod": "BALANCE",
            "userCreditExpectedDate": "2019-05-02",
            "userMobileNo": "91-******7777",
            "refundAmount": "1.00"
        }],
        "userCreditInitiateTimestamp": "2019-05-01 19:27:26.0",
"totalRefundAmount": "1.00",
        "refId": "UNIQUE_REFUND_ID",
        "txnAmount": "10.00",
        "refundId": "PAYTM_REFUND_ID",
        "txnId": "PAYTM_TRANSACTION_ID",
        "refundAmount": "1.00",
        "refundReason": "Testing refund reason",
        "agentInfo": {
            "name": "Lalit",
            "employeeId": "Em1-00`",
            "phoneNo": "7777777777",
            "email": "[email protected]"
        }
    }
}  

Sample response for fallback

{
    "head": {
        "clientId": "C11",
        "responseTimestamp": "1556719175104",
        "signature": "gJD0EM+p9rGekkXKRt1M0aTUTaqZ6SVcmWfysIO9s9tJKhjrfpySlCEG8Tb97G1h4iYyJuhCglTr1obhO7xX+TIFwlaIgrundaj7dyt2SdA=",
        "version": "v1"
    },
    "body": {
        "orderId": "YOUR_ORDER_ID",
        "mid": "YOUR_MID_HERE",
        "refId": "UNIQUE_REFUND_ID",
        "resultInfo": {
            "resultStatus": "PENDING",
            "resultCode": "501",
            "resultMsg": "System Error."
        }
    }
}

To use this Integration Action Node in an app.yellow.ai bot, refer to the below-mentioned example:

  app.executeIntegrationAction({
            "integrationName": "paytm",
            "action": "Check Refund Status",
"dynamicParams": {
    "requestTimestamp": "1658203708983",
    "orderId": "OREDRID_98765",
    "referenceId": "REFUNDID_98765"
}
}).then((res)=>{
    console.log("response from action node", res);
    app.log(res, '||Response from action node||')
}).catch((err)=>{
    console.log("Error in action node",err);
    app.log(err, '||Error in action node||')
})

2. Configuration

You can configure the Paytm payment gateway by following the below steps:

Enabling the Integration in the yellow.ai Integrations Module.
- Login to cloud.yellow.ai and click the Integrations Module from the top left corner of your screen.
- Then search the integration named Paytm or choose the category named Payment from the left navigation bar and then click Paytm.
- This will now open a section where we have to type in the required details to enable this integration. The required values are Merchant ID (To be provided by the client/Paytm spoc of the client), Merchant Key (To be provided by the client/Paytm spoc of the client) , API Domain (In case you want to use the staging domain of Paytm please use https://securegw-stage.paytm.in otherwise please use https://securegw.paytm.in) , Channel ID (To be provided by the client/Paytm spoc of the client), Industry Type (To be provided by the client/Paytm spoc of the client).
- After entering these values, you need to click Connect and the Integration will be enabled at yellow.ai’s end.

Configure the webhook URL in the Paytm dashboard.
- Copy the webhook URL mentioned in the Instructions section of the Paytm Integration Card. Please note that based on the region of your bot i.e r1/r2/r3/r4/r5, you need to append that to the domain of the webhook URL. For example, if the domain is https://cloud.yellow.ai, you need to change it to https://r1.cloud.yellow.ai if the region of the bot is r1. If the bot belongs to the Indian region, you can use the origin domain itself.

The client needs to log in to the Paytm dashboard and navigate to the Webhook URL Configuration section and add the provided webhook URL.

Receiving event in yellow.ai Bot.
- Login to cloud.yellow.ai and click the Studio Module from the top left corner of your screen.
- Click the Event, from the left navigation bar and then choose Integrations.
- You will find an event named Paytm Payment Status that needs to be activated by clicking on the three dots next to the name of the event.
- After activating the event, a flow needs to be created in the Studio module whose trigger point is this event. Now based on the event data received, an appropriate message is displayed to the end user.

Sample webhook event data sent by Paytm

{
 "PAYMENTEMAILID": "[email protected]",
 "PAYMENTMOBILENUMBER": "7777777777",
 "GATEWAYNAME": "WALLET",
 "RESPMSG": "Txn Success",
 "BANKNAME": "WALLET",
 "PAYMENTMODE": "PPI",
 "CUSTID": "CUST_001",
 "MID": "INTEGR7769XXXXXX9383",
 "MERC_UNQ_REF": "LI_12345",
 "RESPCODE": "01",
 "TXNID": "202005081112128XXXXXX68470101509706",
 "TXNAMOUNT": "1.00",
 "ORDERID": "ORDERID_98765",
 "STATUS": "TXN_SUCCESS",
 "BANKTXNID": "63240520",
 "TXNDATETIME": "2020-09-10 13:03:05.0",
 "TXNDATE": "2020-09-10",
 "CHECKSUMHASH": "PMXJocjUUKGq7MXGwHO0LNOV+YxwuYi4gKjRgFOIZVGVqyxqfFuec+A8boUq5Q3c87yYM9DOeCmjIj5mH20SfIiDjOJiU4eFzNxu0J1qKdc=",
 "LINKNOTES": "Link Note Description"
}

1. Use cases​

1.1 Generate Payment Link​

1.2 Initiate Refund​

1.3 Check Refund Status​

2. Configuration​

1. Use cases

1.1 Generate Payment Link

1.2 Initiate Refund

1.3 Check Refund Status

2. Configuration