JioPay Non PCI DSS Integration Handbook v1.4.3

JioPay Non-PCI DSS
Integration Handbook v1.4.3

Contents
JioPay Direct............................................................................................................................................................ 4
Getting started ..................................................................................................................................................... 4
Integrating JioPay Direct services ......................................................................................................................... 5
Generate Authentication Tokens ............................................................................................................................. 6
Authenticate API................................................................................................................................................... 6
Sample Request ................................................................................................................................................ 6
Sample Response.............................................................................................................................................. 7
Parameter Description ..................................................................................................................................... 7
Create Intent for a transaction ................................................................................................................................. 8
Intent API .............................................................................................................................................................. 8
Sample Request ................................................................................................................................................ 9
Sample Response............................................................................................................................................ 10
Parameter Description ................................................................................................................................... 12
Pass details to the checkout page .......................................................................................................................... 15
Sample Form POST ......................................................................................................................................... 16
Handle the response & get the status .................................................................................................................... 18
S2S Callback ........................................................................................................................................................ 18
Sample Callback .............................................................................................................................................. 19
Browser based response .................................................................................................................................... 24
Status API............................................................................................................................................................ 24
Sample Request .............................................................................................................................................. 24
Sample Response............................................................................................................................................ 25
Initiate a refund for a transaction .......................................................................................................................... 26
Refund API .......................................................................................................................................................... 26
Sample Request .............................................................................................................................................. 26
Sample Response............................................................................................................................................ 27
Check status of dropped transaction ..................................................................................................................... 31
IntentStatus API .................................................................................................................................................. 31
Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 2 of 36

Sample Request .............................................................................................................................................. 31
Sample Response............................................................................................................................................ 31
Error Codes ............................................................................................................................................................. 33
Support ................................................................................................................................................................... 35
Production endpoints ............................................................................................................................................. 35

JioPay Direct
Integrate JioPay Direct and get paid by your users anytime and anywhere. Integrate once to solve your payment
acceptance problems and increase your online business.
JioPay Direct is a quick, easy and secure web-based integration to start accepting online payments from your
customers. We provide a seamless experience to your customers to complete payments using credit & debit
cards, UPI, net-banking and wallets.
Getting started
Well, the good news is that if you are reading this, you have already started!
This document will give you a quick understanding of the easy steps in which you can start accepting payment
online. The steps are broadly as follow:
1. Creation of your account with us

The process of creating your account with us has already started. This will require you to provide some basic
documentation about your business. You should have already been informed about the required documents
by your relationship manager. If not, please feel free to reach out.
Completion of this step is critical for you to start accepting payments online.
2. Release of test credentials & integration support

Our integration team will share test credentials (Client ID, Client Secret & MID) with you so that you
can use the same while you integrate with us. This document will guide your tech team with the details of
APIs to be used, their correct sequence as well as the triggers for the same.
You need to provide the JioPay integration team with a HTTPS URL which will be configured as the Callback
URL at JioPay. This is required so that you can consume our Server To Server (S2S) responses. We will need
to provide a URL for test environment as well as one for your live environment.
3. Review of your integration

Our integration team will support you through each step of your integration with us. Once you are confident
that your integration is complete, our integration team will validate your integration by asking you to execute
certain test cases.
4. Release of Live credentials

You shall receive your live credentials on your registered email address once Step 1 & Step 3 have both been
completed successfully. As soon as you receive your live credentials, you should be able to configure the
same at your end and point your application to our production end-points.
Please ensure that you have shared your Callback URL for the live environment and that you are getting
the callback as expected.
With that background, let us take a quick look at the steps involved in integrations.

Integrating JioPay Direct services
The following are the broad steps for integrating JioPay Direct services:
1. Generate Authentication Tokens

2. Create Intent for a transaction
3. Pass details to the checkout page
4. Handle the response & get the status
5. Initiate a refund for a transaction
6. Check Status of dropped transaction
IMPORTANT NOTE:
Please do not hardcode the parameters. We might add few extra parameters to the response
as a part of our enhancements. However, the addition of parameters will not break the
existing functionality.
Also note that this document is intended only for the purpose of merchant integrations with
JioPay PG and is meant for merchant use only.

Generate Authentication Tokens
Authenticate API
The Authenticate API is used to authenticate Application and get tokens which can be used for subsequent calls.
You will need to use the Client ID (clientId) & Client Secret (authenticateList.value) received from JioPay
(on your registered email address) in this call to get the App Access & App Identifier tokens which will be required
for calling all other services
You need to use the following end point for Authenticate API
POST https://pp-apig.jiomoney.com/jfs/v1/app/authenticate
Sample Request
Headers:
x-trace-id: 01c570cf-2bdf-49d0-a126-baec7038bbd1
Request Body:
{
"application": {
"clientId": "677e5aabb4180f4d9cf834c9d12b0b07"
},
"authenticateList": [
{
"mode": 22,
"value": "2656e2edd14e87v0b960fcf61d7a95df410e0a0b45700f38c49d9d81e71f55a4"
}
],
"scope": "SESSION",
"purpose": 2
}

Sample Response
Success response:
{
"status":"SUCCESS",
"session":{
"accessToken":{
"tokenValue":"83b07698-e818-4026-80bb-1e6caefe08baAPPACCESS",
"expiresIn":1800
},
"refreshToken":{
"tokenValue":"5a8f93bd-4989-4264-bbd2-bd60cd01b773APPREFRESH",
"expiresIn":608400
},
"appIdentifierToken":"z1l1lsLVftzrXdNmh"
}
}
Failure response:
{
"status":"FAILURE",
"error":{
"code":"30010",
"message":"Client Id is Inactive."
}
}
Failure response (400 Bad request):

{
"error":{
"message":"Invalid request received"
}
}
Failure response (500 Internal Server Error):

{
"error":{
"message":"Some technical error occurred. Please try after sometime!",
"code":6011
}
}
Parameter Description
Request Headers
x-trace- string You need to pass a unique identifier which can used for tracing the request. It can
id* be generated as UUID.

Request Body
application object
clientId* string This is Client ID which will be shared by JioPay. Client ID uniquely
identifies your merchant account.
authenticateList object list of authentication details
mode* number You need to pass a static value (22) here. This is used to identify the mode
of authentication
value* string you need to pass the Client Secret which will be shared by JioPay
scope* string You need to pass a static value (SESSION) for all your requests
purpose* number You need to pass a static value (2) for all your requests
Response body
status string Status of the Authenticate call
error object Error details. (this will come up only in case of any error)
code* number Error code.
message string Error message.
session object Session object.
accessToken object Details of access token
tokenValue string This is the x-app-access-token which needs to be used in the rest of
the API calls (Intent, Status, IntentStatus, Refund)
expiresIn number Expiry time of access token (in seconds)
refreshToken object Details of refresh token
tokenValue string Refresh token value.
expiresIn number Expiry time of refresh token (in seconds)
appIdentifierToken string This is the x-appid-token which needs to be used in the rest of the
API calls (Intent, Status, IntentStatus, Refund)
Create Intent for a transaction

Intent API
The Intent API is used to create an intent before initiating a transaction. The details related to the transaction
are securely exchanged over server calls to ensure security. This is equivalent to creating an order.
Each transaction needs to be preceded with an intent to initiate the transaction. The Intent call will ensure that
details of the transaction like your order reference number (invoice) are securely exchanged over S2S calls and
that these details need not be exposed on browser based calls.
You need to use the following end point for Intent API

POST https://pp-apig.jiomoney.com/payments/jfs/v1/payments/intent
Sample Request
Headers:
x-trace-id: 01c570cf-2bdf-49d0-a126-baec7038bbd1,
x-app-access-token: 42385fb1-9039-4574-8d00-79ccd7f72935APPACCESS,
x-appid-token: wJdsd+2uKRDJRt8V+w0P6Y9n966FngiO0dLJ17ynuORnpubrPGuJk92y2RQkTlf7Py
Request Body:
{
"transaction": {
"idempotentKey": "$randomAlphaNum03",
"invoice": "JIO000$timestamp01",
"initiatingEntityTimestamp": "2023-04-20T18:17:32.324Z",
"initiatingEntity": {
"returnUrl": "https://psp-mandate-merchant-
sit.jiomoney.com:3003/merchantsimulator/pp/merchantstatus"
}
},
"amount": {
"netAmount": "1.23"
},
"payer": {
"externalId": "JIO1234",
"name": "test",
"email": "[email protected]",
"mobile": {
"number": "1234567890",
"countryCode": "91"
}
},
"payee": {
"merchantId": "100001000217999"
},
"checkout": {
"template": {
"id": "101"
},
"allowed": [
{
"rank": "1",
"methodType": "110",
"methodSubType": "582",
"cardType": [110,130,131]

},
{
"rank": "2",
"methodSubType": "580"
},
{
"rank": "3",
},
{
"rank": "4",
}
]
}
}
Instead of “allowed” array, “notAllowed” array can be used inside “checkout” object, to restrict payments
modes:
"notAllowed": [
{
"cardType": [
110,
130,
131
]
}
]
Sample Response
Response body:
{
"transaction": {
"id": "10032311066145289000",
"originalId": "10032311066145289000",
"idempotentKey": "$randomAlphaNum03",
"created": "2023-04-20T18:22:25.289Z",
"currency": 356,
"metadata": {
"x-appid-token": "AW6nGuFtestdummy9bOsm+nkonMckj1FPImL2pn8iUv9Mn7l8Mzu=",

"x-app-access-token": "23259ab6-4988-4112-9111-95c42fd2e0efAPPACCESS"
},
"mode": 1,
"method": {
"type": 300
},
"status": "INITIATED",
"application": 8000,
"livemode": true,
"entityId": 2103,
"callbackUrl": "https://rep.jfh.jio.com/TransactionCallback",
"returnUrl": "https://psp-mandate-merchant-
},
"invoice": "JIO000$timestamp01",
"responseTime": "2023-04-20T18:23:25.289Z",
"intentId": "10032311066145289000",
"referenceNumber": "190015209958",
"description": "Payment"
},
"amount": {
"netAmount": 1.23,
"grossAmount": 1.23
},
"payer": {
"externalId": "JIO1234",
"name": "test",
"mobile": {
"countryCode": "91",
"number": "1234567890"
},
"type": 11
},
"payee": {
"merchantId": "100001000217999",
"name": "AutoBusiness",
"mobile": {
"countryCode": "+91",
"number": "9790425436"
},
"vpa": "pktest-3@jiopay",
"type": 16
},
"checkout": {
"template": {
"id": "101"

},
"allowed": [
{
"rank": "1",
"cardType": [110,130,131]
},
{
"rank": "2",
},
{
"rank": "3",
},
{
"rank": "4",
}
]
}
}
Request Headers
x-trace-id* string You need to pass a unique identifier which can used
for tracing the request. It can be generated as UUID.
x-app-access-token* string This is the (session.accessToken.tokenValue)
received in the response of the Authenticate call.
x-appid-token* string This is the (session.appIdentifierToken) received
in the response of the Authenticate call.
Request Body
transaction object
idempotentKey* number max length 36. This is a unique ID which you need
to generate to uniquely identify each request.

invoice* string the Order Id for the transaction. This can be same
across more than one transaction requests if the purchase
is intended for the same order/cart.
initiatingEntityTimestamp* number pass the timestamp in ISO format.
initiatingEntity* object
returnUrl* string the URL to which the user will be redirected after
completion of the transaction
amount object
netAmount* number pass the Net Amount in rupees. This will accept
values up to 2 decimal places
This is the amount to be charged to the customer during
mandate creation.
In-line mandate - It will be equal to first payment.
Standalone mandate – Please pass the value as ‘2’.
payer object details of the payer
externalId* string a unique identifier for each customer. This
is mandatory parameter for setting up a mandate
so that the mandate can be setup against a unique
customer.
name string name of the customer
email string email address of the customer
vpa string vpa of the customer
mobile object
number string mobile number of the customer
countryCode string country code for customer’s mobile number
payee object details of the payee
merchantId* string pass the Merchant id (MID) provided by JioPay. This
is a unique identifier for your merchant account.
checkout object
template object template details available to the merchant
id string Blank / ”0” – Template 1 (Default)
“100” – Template 2 (No merchant name/logo)
“101” – Template 3 (New Template)
allowed Array
rank string Determines the order of the MoPs (“1”=topmost,
“2” = second and so on)
methodType string 110 - Purchase,
212 – UPI Intent (use with methodSubType 580)
methodSubType string this defines the payment method used
566 – UPI collect,

579 – Wallets,
580 – UPI Intent
581 – Netbanking,
582 – Cards,
601 – Paylater,
620 – Corporate Netbanking
cardType string defines the type of card used
110 – Debit Card
130 – Credit Card
131 – Prepaid Card
Response body
transaction object
id number This is unique Intent ID provided to you by JioPay for each
unique Intent API request. You will have to store this in your records to
fetch the details of transactions initiated using the Intent ID in case
of those transactions where the response is not received within the
expected timelines.
originalId number In case of Intent API, this value will be same as the Intent ID.
idempotentKey number the transaction.idempotentKey provided by you in the
request of Intent API
initiatingEntityTimestamp number timestamp as provided by you in the request of Intent API
created string Time (in ISO format) at which the intent was initiated
currency number ISO Currency Code
mode number defines the mode of the payment. The value will be 1 for online
payments.
1 – online / card not present
2 – card present
method object this is the object for type of transaction
type number defines the type of transaction
110 – PURCHASE
211 – REFUND
212 – UPI Intent
300 – INTENT
metadata object
x-appid-token string This is the token to pass in checkout page request which is
received in the response.
x-app-access-token string This is the token to pass in checkout page request which is
received in the response.
status string This provides the status of the intent.
INITIATED –Intent is initiated successfully.

SUCCESS – Intent success (Success is sent via S2S or status API)
FAILED – Intent failed
*status will be sent via S2S URL.
application number this is for future use

livemode boolean The value for this will be set to true for all
intents/transactions for now
initiatingEntity object the object containing details of the initiating entity
entityId number this is for future use
callbackUrl string the URL where you will receive the S2S callback
returnUrl string the returnUrl provided by you in the request of Intent API
invoice string the invoice provided by you in the request of Intent API
responseTime string this is for future use
intentId number intent id associated with the transaction
referenceNumber number 12 digit internal reference number generated by JioPay
amount object
netAmount number the netAmount provided by you in the request of Intent API
payer object the object will return back the details of the customer which
have been provided in the request of Intent API
payee object the object will return the details of the merchant
checkout object the object will return the details of the merchant
Pass details to the checkout page

Once you have received a response to the Intent API, please pass the MID, Intent ID, appidtoken (x-
appid-token received in Intent response) and appaccesstoken (x-app-access-token received in Intent
response) to the JioPay payment gateway page.
You need to use the following end point for invoking the Checkout Page
POST https://pp-checkout.jiopay.com:8443

Sample Form POST
<form name="payment" method="POST" action="https://pp-checkout.jiopay.com:8443"
enctype="application/x-www-form-urlencoded">
<input type='hidden' name="mid" value="100001000014146"/>
<input type='hidden' name="appidtoken" value="42385fb1-9039-4574-8d00-
79ccd7f72935APPACCESS"/>
<input type='hidden' name="appaccesstoken" value="42385fb1-9039-4574-8d00-
79ccd7f72935"/>
<input type='hidden' name="intentid" value="102425102452"/>
<input type='hidden' id='brandColor' name='brandColor' value='#24fd24'/>
<input type='hidden' id='bodyBgColor' name='bodyBgColor' value='#ffeede'/>
<input type='hidden' id='bodyTextColor' name='bodyTextColor' value='#a15814'/>
<input type='hidden' id='headingText' name='headingText' value='#a15814'/>
<input type="submit" value="Jio Pay"/>
</form>
string Pass the Merchant id (MID) provided by JioPay. This is a unique
mid*
identifier for your account.
appidtoken* string Pass the x-appid-token received in Intent response here.
appaccesstoken* string Pass the x-app-access-token received in Intent response here.
intentid* string Pass the id received in Intent response.
brandColor string Controls the header background colour.
bodyBgColor string Controls the body background colour,
bodyTextColor string Controls the body text colour.
headingText string Controls the header text colour.

Default Template:
Sample alternative color combinations:

New Template (101):
Handle the response & get the status

Once the transaction is successful, we will send you S2S Callback (to the URL which you have already
configured at our end) as well as a browser-based response to the returnUrl specified in the Intent API
request.
S2S Callback
The S2S Callback will be sent to you once the transaction is successful or at the pre-defined closure time
for the intent. The default closure time for an intent is around 35 minutes.
If there is no successful transaction for the intent within the defined closure time, you will receive a failed
response in S2S.

If the transaction is successful or failed, we will send you the S2S response at least once. Just provide 200
OK response for S2S Call.
You need to store the transaction ID (transactionList.transaction.id) received in the S2S Callback
in your records. You will need this to check the validate the browser response as well.
The response will contain an array (transactionList) of all transactions attempted for the Intent ID
(intentDetails.id). You will have to consider the transaction where the
transactionList.transaction.status is SUCCESS.
Sample Callback
Body:
{
"transactionList": [
{
"transaction": {
"id": "10232104375554549000",
"originalId": "10232104375554549000",
"idempotentKey": "iytfTDLj",
"created": "2021-02-12T20:59:14.549Z",
"currency": 356,
"mode": 1,
"method": {
"type": 110,
"subType": 581
},
"status": "SUCCESS",
"livemode": true,
"entityId": 2103,
"callbackUrl": "http://psp-mandate-merchant-
sit.jiomoney.com:3003/merchantsimulator",
"returnUrl": "http://psp-mandate-merchant-
},
"invoice": "JIO0000001",
"responseTime": "2021-02-12T21:00:14.549Z",
"processorTransactionId": "U1230001833389",
"intentId": "10202104375530484000",
"referenceNumber": "190000028212"
},
"amount": {
"netAmount": 1.0,
"grossAmount": 1.0
},
"payer": {
"externalId": "test123",
"name": "test",
"bankId": "1016",
"bankName": "Canara Bank",

"type": 11
},
"payee": {
"terminalId": "10233349",
"merchantId": "100001000217999",
"name": "AutoBusinessDisplayName",
"mobile": {
"number": "9790425436"
},
"type": 12
}
}
],
"intentDetails": {
"id": "10202104375530484000",
"idempotentKey": "txTD09ls",
"created": "2021-02-12T20:58:50.484Z",
"currency": 356,
"responseTime": "2021-02-12T20:59:50.484Z",
"amount": {
"netAmount": 1.0,
"grossAmount": 1.0
}
}
}
Payer block – different scenarios

UPI Transaction
"payer":{
"externalId":"test123",
"name":"test",
"email":"[email protected]",
"vpa":"6361753693@jio",
"type":11
}
Card Transaction
"payer":{

"name":"test",
"card":{
"type":130,
"scheme":104,
"maskedNumber":"424242XXXXXX8007",
"name":"seedfrgt"
},
"type":11
}
transactionList object an array containing transaction list
transaction object the transaction object
id number unique transaction ID
originalId number same as the unique transaction ID
idempotentKey number idempotent key which has been generated by the checkout
page for each transaction
initiatingEntityTimestamp number the value which was provided in the request of Intent API
created string Time (in ISO format) at which the transaction was initiated.
failureCode string it will contain a code for the failure and will be present in
case the status is FAILED
failureMessage string it will contain the failure reason and will be present in case
the status is FAILED
mode number defines the mode of the payment. The value will be 1 for
online payments.
2 – card present
method object This is the object for type of transaction and details of
payment method
110 – PURCHASE
211 – REFUND
212 – UPI Intent (use with subtype 580)
300 – INTENT

subtype number this defines the payment method used
579 – Wallets/Prepaid Instruments
566 – UPI Collect
580 – UPI Intent
581 – Net-banking
582 – Cards
601 – PayLater
status string this provides the status of the transaction
livemode boolean the value for this will be set to true for all
intents/transactions for now
returnUrl string the returnUrl provided by you in the request of Intent API
invoice string the invoice provided by you in the request of Intent API
processorTransactionId string transaction id of the processors/banks
intentId number intent id associated with the transaction
amount object
grossAmount number this is for future use
payer object the object will return back the details of the customer which
have been provided in the request of Intent API as well as the details
of the payment method used by the payer
Details of the payer block have been separately
payee object the object will return the details of the merchant
intentDetails object
id number the transaction.id received in response of Intent API
idempotentKey number the transaction.idempotentKey provided by you in the
request of Intent API
initiatingEntityTimestamp number timestamp as provided by you in the request of Intent API
created string Time (in ISO format) at which the intent was initiated

status String This provides the status of the intent.
INITIATED –Intent is initiated successfully.
SUCCESS – Intent success (Success is sent via S2S or status
API)
FAILED – Intent failed
*status will be sent via S2S URL or you can manually call status API
to get the latest status of the intent
invoice string This the same invoice value provided by you in the request
of Intent API
amount object
Payer block details

payer object the object will return back the details of the customer which have been
provided in the request of Intent API. This will also contain payment method details.
externalId string a unique identifier for each customer. This will return the same value which
was provided by you in the request of Intent API
name string name of the customer as provided in the request of Intent API
email string email address of the customer as provided in the request of Intent API
mobile object
number string mobile number of the customer as provided in the request of Intent API
countryCode string country code for customer’s mobile number as provided in the request of
Intent API
vpa string vpa of the payer if UPI was used for the transaction
bankId string 4 digit unique bank/wallet ID provided by JioPay. This will be present in the
response only if the transaction was done using a bank/wallet
bankName string name of the bank/wallet. This will be present in the response only if the
transaction was done using a bank/wallet
card object the object will be present only if the transaction was done using a card
type number defines the type of card used
110 – Debit card
130 – Credit card
131 – Prepaid card

scheme number defines the scheme of card used
104 – Visa
105 – Master
199 – Rupay
107 – Diners
103 – Amex
133 – CUP
108 – Discover
109 – JCB
maskedNumber string card number used by the customer. The number will be masked.
name string name of the cardholder as provided by the customer
type number type will always be 11 for payer
Browser based response

As suggested above, you will also receive a browser-based response for a transaction. The response will be a GET
call and will contain the transaction ID in the query parameter tid. You will have to check your backend system
to verify that you have received the S2S Callback for the transaction already. You should show the response page
to your customers based on the transaction status in your backend.
You will get a sample GET call as mentioned below:
GET returnUrl?tid={transactionID}
If you have received the browser based response, however the record for the same is not available in your
backend, you will have to call the Status API using the tid (received in query parameter) to get the status of a
transaction.
Status API
This API is used to check the status of a transaction using the transaction ID (tid) received as a query parameter
in the browser response from the JioPay payment page after completion of a transaction.
Please use intentId from the response to match the same with your backend. The intentId is the
transaction.id which you would have received in the response of the Intent API.
You need to use the following end point for Status API
POST https://pp-apig.jiomoney.com/payments/jfs/v2/payments/status
Sample Request
Headers:
x-trace-id:01c570cf-2bdf-49d0-a126-baec7038bbd1,
x-appid-token: wJdsd+2uKRDJRt8V+w0P6Y9n966FngiO0dLJ17ynuORnpubrPGuJk92y2RQkTlf7Py

Request Body:
{
"transactionId":"10592102958465711000"
}
Sample Response
Response body:
{
"transactionList": [
{
"transaction": {
"id": "10592102958465711000",
"originalId": "10592102958465711000",
"idempotentKey": "lvcFpTnr",
"created": "2021-01-29T16:14:25.711Z",
"currency": 356,
"mode": 1,
"livemode": true,
"returnUrl": "http://sit.jiomoney.com:3003/sit/merchantstatus"
},
"responseTime": "2021-01-29T16:15:25.711Z",
"processorTransactionId": "U1230001814107",
"intentId": "10592102958413022000",
},
"amount": {
"netAmount": 1
},
"payer": {
"externalId": "test123",
"name": "test",
"bankId": "2006",
"bankName": "Mobikwik"
},
"payee": {
"terminalId": "10232760",
"merchantId": "100001000217423",
"mobile": {
"number": "8169619527"
}
}
}
]
}

Request Headers
x-trace-id* string You need to pass a unique identifier which can used for tracing the request. It
can be generated as UUID.
x-app-access- string the session.accessToken.tokenValue received in the response of the
token* Authenticate API.
x-appid-token* string the session.appIdentifierToken received in the response of the
Authenticate API.
Request Body
transactionId* string the transaction ID of the transaction for which you need to check the status
Response Body
The response body for Status API follows the same structure as the S2S Callback, except for the fact that it doesn’t
contain the intentDetails object. Please refer the S2S Callback parameter description.
Initiate a refund for a transaction

Refund API
You need to use this API to refund a transaction. Complete and multiple partial refunds are supported, however
the total amount being refunded cannot exceed the transaction amount.
You need to use the following end point for Refund API
POST https://pp-apig.jiomoney.com/payments/jfs/v1/refunds
Sample Request
Headers:
x-appid-token: wJdsd+2uKRDJRt8V+w0P6Y9n966FngiO0dLJ17ynuORnpubrPGuJk92y2
Request Body:
{
"transaction":{
"originalId":"10712031500413657000",
"idempotentKey":"1Bhtn6fxjW",
"invoice":"test",
"initiatingEntityTimestamp":"2020-11-10T02:13:56.604Z"
},

"amount":{
"netAmount":0.12
}
}
Sample Response
Response Body:
{
"transaction":{
"id":"10202104632378846000",
"originalId":"10712031500413657000",
"idempotentKey":"z4SGzjomw6",
"object":"refund",
"arrivalDate":"2021-02-15T09:00:08.846Z",
"initiatingEntityTimestamp":"2021-02-15T08:59:37.960Z",
"created":"2021-02-15T08:59:38.846Z",
"currency":356,
"livemode":true,
"mode":1,
"method":{
"type":211,
"subType":581
},
"captureMethod":1,
"status":"ACCEPTED",
"application":2103,
"initiatingEntity":{
"entityId":2103,
"callbackUrl":"http://localhost:9002/jfs/v1/plan"
},
"processingEntity":5151,
"invoice":"test",
"responseTime":"2021-02-15T09:00:38.846Z",
"processorTransactionId":"U1230001627396",
"referenceNumber":"190000004149"
},
"amount":{
"netAmount":0.02,
"grossAmount":0.02
}
}
Request Headers
x-trace-id* string You need to pass a unique identifier which can used for tracing the request. It
can be generated as UUID.

x-app-access- string the session.accessToken.tokenValue received in the response of the
token* Authenticate API.
x-appid-token* string the session.appIdentifierToken received in the response of the
Authenticate API.
Request Body
transaction Object
originalId* number transaction ID of the transaction to be refunded
idempotentKey* number max length 36. This is a unique ID which you need to generate
to uniquely identify each request.
invoice string the Order Id for the transaction. This can be same across more
than 1 transaction requests if the purchase is intended for the same
order/cart.
initiatingEntityTimestamp* number pass the timestamp in ISO format.
amount object
netAmount* number the amount to be refunded
}
Response Body
transaction object
id number transaction ID generated for the refund request
originalId number transaction ID which is to be refunded as provided by you in
the request of Refund API
idempotentKey number idempotent key which has been generated by JioPay for the
refund request
object string defines type of object. The value will be refund for this API.
arrivalDate string this is for future use
initiatingEntityTimestamp number the value which was provided in the request of Refund API
created string Time (in ISO format) at which the refund was initiated
livemode boolean the value for this will be set to true for all
intents/transactions/refund for now
mode number defines the mode of the payment. The value will be 1 for online
payments.
2 – card present
method object This is the object for type of transaction and details of payment
method

110 – PURCHASE
211 – REFUND
212 – UPI Intent (use with subtype 580)
300 – INTENT
subType number this defines the payment method used
566 – UPI Collect
579 – Wallets/Prepaid Instruments
580 – UPI Intent
581 – Net-banking
582 – Cards
601 – PayLater
captureMethod number defines whether a transaction is Captured Automatically (1) or
Captured Manually (2). For this integration, the value will always be 1
status string this provides the status of the refund request. Refund flow and
status actions are represented below using flow diagram.
ACCEPTED
ACCEPTED_NT
SUCCESS
PENDING
PROCESSED
FAILED
processingEntity string this is for future use
invoice string the invoice provided by you in the request of Refund API
processorTransactionId string transaction id of the processors/banks of the original
transaction
amount object
netAmount number the netAmount provided by you in the request of Refund API

Flow Diagram for refund status:

Check status of dropped transaction
IntentStatus API
This API is to be used when you have initiated a transaction, however you have not received a response for the
transaction within the stipulated time.
This API can be called by using the Intent ID.
You need to use the following end point for Refund API
POST https://pp-apig.jiomoney.com/payments/jfs/v1/payments/intentStatus
Sample Request
Headers:
x-appid-token: wJdsd+2uKRDJRt8V+w0P6Y9n966FngiO0dLJ17ynuORnpubrPGuJk92y2
Request Body:
{
"transactionId":"10202104375530484000"
}
Sample Response
Response Body:
{
"transactionList":[
{
"transaction":{
"id":"10232104375554549000",
"originalId":"10232104375554549000",
"idempotentKey":"iytfTDLj",
"created":"2021-02-12T20:59:14.549Z",
"currency":356,
"mode":1,
"method":{
"type":110,
"subType":581
},
"status":"SUCCESS",
"application":8006,
"livemode":true,
"initiatingEntity":{
"entityId":2103,
"callbackUrl":"http://psp-mandate-merchant-
sit.jiomoney.com:3003/merchantsimulator",

"returnUrl":"http://psp-mandate-merchant-
},
"invoice":"JIO0000001",
"responseTime":"2021-02-12T21:00:14.549Z",
"processorTransactionId":"U1230001833389",
"intentId":"10202104375530484000",
"referenceNumber":"190000028212"
},
"amount":{
"netAmount":1.0,
"grossAmount":1.0
},
"payer":{
"name":"test",
"bankId":"1016",
"bankName":"Canara Bank",
"type":11
},
"payee":{
"terminalId":"10233349",
"merchantId":"100001000217999",
"name":"AutoBusinessDisplayName",
"mobile":{
"countryCode":"+91",
"number":"9790425436"
},
"type":12
}
}
],
"intentDetails":{
"id":"10202104375530484000",
"idempotentKey":"txTD09ls",
"created":"2021-02-12T20:58:50.484Z",
"currency":356,
"status":"SUCCESS",
"invoice":"JIO0000001",
"responseTime":"2021-02-12T20:59:50.484Z",
"amount":{
"netAmount":1.0,
"grossAmount":1.0
}
}
}

Request Headers
x-trace-id* string You need to pass a unique identifier which can used for tracing
the request. It can be generated as UUID.
x-app-access-token* string the session.accessToken.tokenValue received in the
response of the Authenticate API.
x-appid-token* string the session.appIdentifierToken received in the response
of the Authenticate API.
Request Body
transactionId* string the Intent ID for which you need to check the status
Response Body
The response body for IntentStatus API follows the same structure as the S2S Callback. Please refer the S2S
Callback parameter description.
Error Codes
Error codes are captured in two ways for all the APIs.
1. HTTP 200 response with status = “FAILED”

- This means request is processed to bank and failed due to business error. In this case look for
“FailureMessage” and “FailureCode” in the response
2. HTTP 400 and 500 are sent on Error Object
Sample errors shown below.
Sample Error response for HTTP 200

Body:
{
"transaction": {
"id": "10862136337856047000",
"originalId": "10862136337856047000",
"idempotentKey": "autopay_card_preprocess_1640754056",
"object": "payment",
"arrivalDate": "2021-12-29T10:31:26.047Z",
"standingInstruction": {
"scheduledAt": "2021-12-29T10:30:55.837Z",
"uniqueMandateNumber": "1771787178074593792"
},
"created": "2021-12-29T10:30:56.047Z",
"currency": 356,

"failureCode": "29999",
"failureMessage":
"TRAIE0060-
Validate date should be within allowed range from debit date",
"livemode": true,
"metadata": {
"request": {
"PROCESSOR_MANDATE_REFERENCE": "MA0F9F00077804",
"dueDate": "2021-12-29T10:30:55.837Z",
"invoiceDate": "2021-12-29T10:30:55.837Z"
}
},
"method": {
"type": 306,
"subType": 590
},
"status": "FAILED",
"entityId": 8008
},
"invoice": "Invoice_1640754056",
"responseTime": "2021-12-29T10:31:56.047Z",
"processorTransactionId": "IA16E600009644",
},
"amount": {
"netAmount": 1.0,
"grossAmount": 1.0
},
"payer": {
"userId": "1234567890",
"type": 11,
"name": "Payer name"
},
"payee": {
"type": 12,
"merchantId": "100002000003382"
}
}
Failure response (400 Bad request):

{
"error":{
"message":"Invalid request received"
}
}

Failure response (500 Internal Server Error):
{
"error":{
"message":"Some technical error occurred. Please try after sometime!",
"code":6011
}
}
The comprehensive list of error codes shall be shared as a separate file. The error codes follow the logic as
specified below:
50XXX JioPay Technical Errors

500XX JioPay generic Errors
4XXXX External Technical Errors
3XXXX JioPay Business declines
2XXXX External Business declines
Support
If you have any queries regarding the integration, raise a concern to [email protected]. For any kind of
merchant queries or complaints in production, please raise a concern to [email protected]
. Below is the escalation matrix for production support.
Escalation Levels Email ID POC Contact No.

Level 1 [email protected] Merchant Support -
Level 2 [email protected] Kausar Hasan +91 9321825979
[email protected] Vaibhav Dolas +91 8850589048
Level 3 [email protected] Yezaaz Ahmed +91 77188 99123
Production endpoints
Authenticate https://apig.jiomoney.com/jfs/v1/app/authenticate
Intent https://apig.jiomoney.com/payments/jfs/v1/payments/intent
Pre-process https://apig.jiomoney.com/payments/jfs/v1/mandate/preprocess
Execute https://apig.jiomoney.com/payments/jfs/v1/mandate/execute
Checkout Page https://checkout.jiopay.com/
PaymentStatus https://apig.jiomoney.com/payments/jfs/v2/payments/status
Refund https://apig.jiomoney.com/payments/jfs/v1/refunds
IntentStatus https://apig.jiomoney.com/payments/jfs/v1/payments/intentStatus


JioPay Non PCI DSS Integration Handbook v1.4.3

Uploaded by

Copyright:

Available Formats

JioPay Non PCI DSS Integration Handbook v1.4.3

Uploaded by

Document Information

Original Title

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

JioPay Non PCI DSS Integration Handbook v1.4.3

Uploaded by

Copyright:

Available Formats

JioPay Non-PCI DSS

Integration Handbook v1.4.3

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 2 of 36

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 3 of 36

1. Creation of your account with us

2. Release of test credentials & integration support

3. Review of your integration

4. Release of Live credentials

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 4 of 36

1. Generate Authentication Tokens

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 5 of 36

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 6 of 36

Failure response (400 Bad request):

Failure response (500 Internal Server Error):

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 7 of 36

Create Intent for a transaction

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 8 of 36

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 9 of 36

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 10 of 36

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 11 of 36

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 12 of 36

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 13 of 36

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 14 of 36

application number this is for future use

Pass details to the checkout page

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 15 of 36

appidtoken* string Pass the x-appid-token received in Intent response here.

appaccesstoken* string Pass the x-app-access-token received in Intent response here.

intentid* string Pass the id received in Intent response.

brandColor string Controls the header background colour.

bodyBgColor string Controls the body background colour,

bodyTextColor string Controls the body text colour.

headingText string Controls the header text colour.

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 16 of 36

Sample alternative color combinations:

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 17 of 36

Handle the response & get the status

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 18 of 36

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 19 of 36

Payer block – different scenarios

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 20 of 36

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 21 of 36

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 22 of 36

Payer block details

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 23 of 36

Browser based response

You will get a sample GET call as mentioned below:

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 24 of 36

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 25 of 36

Initiate a refund for a transaction

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 26 of 36

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 27 of 36

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 28 of 36

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 29 of 36

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 30 of 36

This API can be called by using the Intent ID.

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 31 of 36

Confidential JioPay Non-PCI DSS - Integration Handbook v1.4.3 Page 32 of 36

1. HTTP 200 response with status = “FAILED”