EXPRESS UPI S2S API’s

API SPECIFICATION DOCUMENT

Mindgate Solutions Pvt. Ltd.

December 21, 2023

1|Page
REVISION & SIGNOFF SHEET

Record Changes

Date Author Version Change reference

18-12-2023 Jayesh C V.1.0 Draft Version

Reviewers

Date Approver Version Change reference

21-12-2023 Nikhil M V.1.0

2|Page
TABLE OF CONTENTS

1. INTRODUCTION .......................................................................................................................... 5
1.1 Objectives ............................................................................................................................. 5
1.2 Purpose ................................................................................................................................. 5
1.3 Abbreviations ...................................................................................................................... 5
2. API REQUEST FORMATION .................................................................................................. 6
2.1 Request ................................................................................................................................. 6

Sample Message............................................................................................................... 6
Field Description ............................................................................................................... 6
3. BANK LIST .................................................................................................................................... 9
3.1 Request ................................................................................................................................. 9
Sample Message............................................................................................................... 9
Field Description ............................................................................................................... 9
3.2 Response.......................................................................................................................
10

Sample Message............................................................................................................. 10
Field Description ............................................................................................................. 10
4. TRANSACTION STATUS .......................................................................................................... 13
4.1 Request ............................................................................................................................... 13

Sample Message............................................................................................................. 13
Field Description ............................................................................................................. 14
4.2 Response ............................................................................................................................. 16
4.2.1 Transaction Status Response Sample ...................................................................... 16

Sample Message............................................................................................................. 16
Field Description ............................................................................................................. 16
4.2.2 Transaction Dispute Status Response...................................................................... 18
Sample Message............................................................................................................. 18
Field Description ............................................................................................................. 18
4.2.3 Dispute Status Response............................................................................................. 20
Sample Message............................................................................................................. 20
Field Description ............................................................................................................. 21
5. NOTIFICATION – CALL BACK ................................................................................................. 23

3|Page
 5.1 Mandate Creation ............................................................................................................. 23

Sample Payload .............................................................................................................. 23

Field Description ............................................................................................................. 24
5.2 Collect Initiate ................................................................................................................... 29

Sample Message............................................................................................................. 29
Field Description ............................................................................................................. 29
5.3 Credit Confirmation ......................................................................................................... 31
Sample Message............................................................................................................. 31
Field Description ............................................................................................................. 31
5.4 Dispute Call Back .............................................................................................................. 33
Sample Payload .............................................................................................................. 33
Field Description ............................................................................................................. 33

4|Page
1. INTRODUCTION

1.1 Objectives

The primary objective of this document is to deliver the Server to Server API specification
including the encryption standards to understand the fundamental purpose and capabilities
of the below services:
• Bank List
• Transaction Status
• Notification – Call Back

1.2 Purpose

This document serves the purpose of providing clear and concise specification on the API
services as well as the encryption logic over a payload.

1.3 Abbreviations

Sr No Abbreviation Full Forms

1 API Application Programming Interface

2 AES Advanced Encryption Standard

3 AES GCM AES with Galois/Counter Mode

4 PSP Payment Service Provider

5|Page
2. API REQUEST FORMATION

For all API covered in this document, the payload request message will be in JSON format and
encrypted with key’s.
Below section provides the sample structure and parameters.

Pre-Requisites : PSP/Merchant has to share the URL to whitelist to receive the callbacks.

Note: Encryption logic used here is AES (AES/GCM/NoPadding)

2.1 Request

Sample Message

{
"pspId/pgMerchantId": "1",
"requestMsg":
"F012522d1d4d2cd5c2d4c2d457117HD012522d1d4d2cd5c2d4c2d457117MYBANK012522
d1d4d2cd5c2d4c2d457117",
"key_data": {
"ivToken": "254012522d1d4d2cd5c2d4c2d457117",
"keyId": 0
},
"encVer": "3.0"
}

Field Description

Sr. Data Condi

Fields Description Length Sample Data
No Type tion
1. pspId pspId is the String 20(Max) M MYBANK000000000
unique identifier 0001
for each PSP Expected: Alpha
Numeric
2. payload/req Encrypted json String 2000(Ma M 88EC24F7C1B8FF2B0
uestMsg payload should x) 46C5C5F3F4FDD39C
be populated in DE2CC457A3025315
this field. 457D5C53CC61C39E
FCC03CFDE3D51650
9C6F2A44B2AC1352
A10099ED961F50AA
188746CC3932351B
CC3BDBDA58A1EA7
8B69D942B92E753A

6|Page
 A52C797E0D37810E
0AA3929FFF3B72E5
A88FDE2D249A61CC
D956C79FF7FF6A644
529DC0EBF506AF99
39803EADC561AAFE
A0FDDD59F0E89A3E
23AB219C50E707B6
1C2887C765315DFC
95
3. key_data Key data block for Object NA M "key_data": {
ivToken "ivToken":
parameter and "254012522d1d4d2c
key id in case of d5c2d4c2d457117",
multiple key "keyId": 0
}
4. ivToken Initialization String 35(Max) Optio 254012522d1d4d2cd
Vector for AES nal 5c2d4c2d457117
encrypted with
AES/GCM/NoPad
ding,
Note: If keyID
value is other that
0, ivToken field
becomes
mandatory

5. keyId Key id index in Numeri 5(Max) Optio Default value = 0

case of multiple c nal
key.
Default value =
0
6. encVer Encrypted Version Numeri 5(Max) Optio By default AES
c nal Encryption logic is
used, but if the
In Encrypted Logic is
case either (ECB, CBC or
of GCM), encVer field
ECB(" becomes
1.0"), mandatory.
CBC("
2.0"), ECB("1.0"),
GCM( CBC("2.0"),
"3.0"), GCM("3.0")

7|Page
8|Page
3. BANK LIST

The Bank List API serves the purpose of offering users / PSP App to listing of banks in
the UPI Platform. This API includes the Name of the Bank, Bank ID, Bank Code, IFSC and
any additional relevant details.

Endpoint:- /getBankList

3.1 Request

Sample Message

{
"requestInfo" : {
"pspId" : "1",
"pspRefNo" : "MYBANK30fa622877f7fb45ed41c0ae20"
}
}

Field Description

Sr Type
Fields Description Data Type Length Condition
No.
requestInfo This block represents below fields for the Request Information.
1. pspId PSP id of the Configured Numeric 16(Max) M
application This is Value
a unique value for
each PSP
2. pspRefNo pspRefNo This is Configured Alphanumeric 35(Fixed) M
unique reference Value
number which is
generated by the
PSP/TPAP for
every request,
cannot be
duplicate

9|Page
3.2 Response

Sample Message

{
"status":"S",
"statusDesc":"Bank data exists",
"bankMasterList":[
{
"bankId":393,
"bankName":"Punjab National Bank",
"ifsc":"MYBANK",
"bankCode":"MYBANK",
"iin":"607093",
"formatType":"FORMAT2",
"versionList": "[{\"no\":\"2.0\",\"description\":\"ITS A 2.0 BASE
VERSION\",\"mandatory\":\"false\"},{\"no\":\"2.5\",\"description\":\"I18N_FULLY_COMPATIB
ILE\",\"mandatory\":\"false\"},{\"no\":\"2.99\",\"description\":\"Credt
card\",\"mandatory\":\"false\"},{\"no\":\"2.98\",\"description\":\"LITE_VERSION\",\"mandato
ry\":\"false\"},{\"no\":\"2.96\",\"description\":\"Aadhaar OTP\",\"mandatory\":\"true\"}]",
"ccEnable": "Y"
}
}],
"requestInfo":{
"pspId":"1",
"pspRefNo":"MYBANK30fa622877f7fb45ed41c0ae20"
}
}

Field Description

Sr Max.
Fields Description Data Type Condition
No. Length
1. status Status (S: Success, F: Character 1(Fixed) M
Failure, V: Validation[in
case of validation Error])

2. statusDesc Status description Alphabet 100(Max) M

bankMasterList This block represents below fields for the Bank Master List,
Elements under this list may repeat and have multiple values
3. bankId Bank ID Numeric 10(Max) M

4. bankName Bank Name Character 50(Max) M

10 | P a g e
 5. ifsc IFSC of the bank Character 11(Max) M

6. bankCode Code of the Bank Character 11(Max) M

7. iin Unique number Numeric 10(Max) M

8. formatType This field provides the Alphanumeric 10(Max) M

information of the
supported format type,
“FORMAT1” = This
Supports last 6 digit of
debit card and expiry
date in the set MPIN
flow.
“FORMAT2” = This
supports Last 6 digit of
debit card in the set
MPIN flow.
“FORMAT3” = This
supports Aadhar otp
verification or last 6
digit of debit card in set
MPIN flow.
versionList Elements under the Version Information Block may repeat and can
have multiple values

9. no Version Number Numeric 3(Max) M

provides the
information on the
supported version of
the features
i.e. ‘2.98’ = LITE
VERSION
10. description Version Description Character 50(Max M
Provides the detail of
the version code
i.e LITE VERSION
11. mandatory Mandatory flag Boolean NA(Max) O

12. ccEnable This flag represents, If Character 2(Max) M

the bank is credit card
enabled
requestInfo This block represents below fields for the Request Information.
13. pspId PSP id of the application Numeric 16(Max) M
This is a unique value
for each PSP
14. pspRefNo pspRefNo This is unique Alphanumeric 35(Max) M
reference number which

11 | P a g e
 is generated by the
PSP/TPAP for every
request, cannot be
duplicate

12 | P a g e
4. TRANSACTION STATUS

This API is used to fetch the status of a transaction at various stages as below:
• Transaction Status
• Transaction Dispute Status
• Dispute Status

Endpoint :- /checkTransactionStatus

4.1 Request

Sample Message

{
"action_type": "TRANSACTION_STATUS",
"deviceInfo": {
"androidId": "d90ce5a040828d38",
"appGenId": "HDCFA0D6A02A268A451EA7101C2F2377257",
"appName": "com.mgs.bank.qa",
"appVersionCode": "5",
"appVersionName": "0.5",
"capability": "5200000200010004000639292929292",
"deviceId": "d90ce5a040828d38",
"deviceType": "MOB",
"fcmToken": "",
"geoCode": "0.0 ,0.0",
"ip": "127.0.0.1",
"location": "Mumbai",
"mobileNo": "918976764613",
"os": "Android13",
"regId": "NA",
"relayButton": "BmiT0ixZCMFRIR9sJSoACfHKImt0uEHEcWfbcgo8i4Y=",
"selectedSimSlot": 0,
"simId": "d90ce5a040828d385",
"wifiMac": "02:00:00:00:00:00"
},
"onBehalf_Of": "PAYER",
"org_txn_date": "30-11-23",
"org_txn_id": "HDCFB9F45D627EA34401B06FE9B947AF7A3",
"requestInfo": {
"pspId": "11",
"pspRefNo": "HDCF18B144AF79DD4B24A9DD278710"
}
}

13 | P a g e
Note: Device information block should have a static value if the API calling is Server to Server.

Field Description

Sr Type
Data Lengt Conditi
N Fields Description
Type h on
o.
1. action_type Action Type Configu Character 20(Ma M
“TRANSATION_STATUS” red x)
“TXN_DISPUTE_STATUS” Value
"DISPUTE_STATUS"

deviceInfo This block represents below fields for the Request Information.
2. androidId Android id of the user System Alphanum 50(Ma M (for
device Defined eric x) Androi
d)
3. appGenId Unique device specific System Alphanum 32(ma M
identification Defined eric x)
4. appName Application package name, System Alphanum 50(Ma M
recommendation is to Defined eric x)
provide different values for
android and iOS
5. appVersionC Application Version Code System Alphanum 50(Ma M
ode Defined eric x)
6. appVersion Application Version Name System Alphanum 50(Ma
Name Defined eric x)
7. capability It is a mandatory field for System Alphanum 50(Ma M
NPCI during registration Defined eric x)
and transaction. For
integration purpose sample
value can be passed as
below,
52000002000100040006392
92929292
8. deviceId Device id of the user mobile System Alphanum 50(Ma M
Defined eric x)
9. deviceType Device type of the user System Alphanum 50(ma M
Defined eric x)
10. fcmToken Firebase token This is not System Alphanum 150(M O
supported for Server to Defined eric ax)
Server integration
11. geoCode Geo coordinates of the System Alphanum 50(Ma M
user, i.e. longitude and Defined eric x)
latitude value
12. ip ip address of the user System Alphanum 50(Ma M
Defined eric x)

14 | P a g e
 13. location Location of the user System Alphanum 50(Ma M
contains complete address. Defined eric x)
14. mobileNo Mobile number of the user Input Numeric 12(Ma M
Paramet x)
er
15. os OS of the user device System Alphanum 50(Ma M
Defined eric x)
16. regId Registration ID, "regid" is System Alphanum 20(Ma O
not required can be passed Defined eric x)
as NA.
17. relayButton It is PSP level constant System Alphanum 50(Ma O
value. Defined eric x)

18. selectedSim The sim slot number System Numeric 2(Max) O

Slot Defined
19. simId Sim No of the user device System Alphanum 20(Ma M
Defined eric x)
20. wifiMac Wifi address of user phone System Alphanum 50(ma O
Defined eric x)
21. onBehalfOf This is on behalf of payer or Configu Code 5(Max) M
payee red
Value
22. org_txn_id Original Transaction id Configu Alphanu 35(Ma M
red meric x)
Value
23. org_txn_date Original Transaction Date Configu String 10(Ma O
red x)
Value
requestInfo This block represents below fields for the Request Information.
24. pspId PSP id of the application Configu Numeric 16(Ma M
This is a unique value for red x)
each PSP Value
25. pspRefNo pspRefNo This is unique Configu Alphanum 35(Ma M
reference number which is red eric x)
generated by the PSP/TPAP Value
for every request, cannot be
duplicate

15 | P a g e
4.2 Response

The response fields chage based on the request type.

4.2.1 Transaction Status Response Sample

In the “action_type” Parameter, passing the type as TRANSATION_STATUS will provide you
the below response.

Sample Message

{
"requestInfo": {
"pspId": "1",
"pspRefNo": "HDFC18B144AF79DD4B24A9DD278710"
},
"status": "S",
"statusDesc": " API request processed successfully",
"txn_status_details": {
"result": "DEEMED",
"error_code": "",
"txn_id": "HDFA6B4ABA91A404AA8A21960FF6A176C78",
"adjFlag": "",
"adjCode": "",
"resp_code": "RB"
},
"action_type": "TRANSACTION_STATUS"
}

Field Description

Sr
Fields Description Data Type Length Condition
No.
requestInfo This block represents below fields for the Request Information.
1. pspId PSP id of the Alphanumeric 16Max) M
application
This is a
unique value
for each PSP
2. pspRefNo PSP Numeric 35(Fixed) M
Reference
Number This
is unique
reference
number

16 | P a g e
 which is
generated
by the
PSP/TPAP
for every
request,
cannot be
duplicate
3. status Status (S: Numeric 1(Fixed) M
Success, F:
Failure, V:
Validation[in
case of
validation
Error])
4. statusDesc Status Alphabet 100(Max) O
description
txn_status_details This block represents below fields for the Transaction Status
Details.
5. result Transaction Alphabet 8(Max) M
Result
6. error_code UPI Alphanumeric 6(Max) M
Switch/NPCI
error code
7. txn_id Transaction Alphanumeric 35(Fixed) M
Identifier
8. adjFlag adjustment Alphabet 3(Max) O
Flag
9. adjCode adjustment CODE 3(Max) O
Code
10. resp_code Response Numeric 2(Max) M
Code
11. action_type Type of the CODE 20(Max) M
check txn

17 | P a g e
4.2.2 Transaction Dispute Status Response

In the “action_type” Parameter, passing the type as TXN_DISPUTE_STATUS will provide you
the Transaction status including the Dispute status of the transaction against the original
transaction Id.

Sample Message

{
"requestInfo": {
"pspId": "202",
"pspRefNo": "MYBANK1A59278C53994F10BB1F120E17F200205"
},
"status": "S",
"statusDesc": " API request processed successfully",
"action_type": "TXN_DISPUTE_STATUS",
"txn_status_details": {
"result": "DEEMED",
"error_code": "RB",
"adjFlag": "TCC",
"adjCode": "102",
"adjRefId": "XYA/PTM/Complaint Raise/923197440/SYSTEM",
"resp_code": "RB",
"txn_id": "MYBANK03B38DB344DD4FA5AAD98EBC1A583D14",
"adjTs": "2019-09-24 14:21:05",
"org_rrn": "876543211234",
"crn": "UPI2005138765432",
"adjAmt": 500,
"prRespcode": "UT1",
"prRevRespcode": "U97",
"pyRespcode": "RB",
"pyRevRespcode": "RB"
}
}

Field Description

Sr
Fields Description Data Type Length Condition
No.
requestInfo This block represents below fields for the Request Information.
1. pspId PSP id of the Alphanumeric 16Max) M
application
This is a
unique value
for each PSP

18 | P a g e
 2. pspRefNo PSP Numeric 35(Fixed) M
Reference
Number This
is unique
reference
number
which is
generated
by the
PSP/TPAP
for every
request,
cannot be
duplicate
3. status Status (S: Numeric 1(Fixed) M
Success, F:
Failure, V:
Validation[in
case of
validation
Error])
4. statusDesc Status Alphabet 100(Max) O
description
5. action_type Type of the CODE 20(Max) M
check txn
txn_status_details This block represents below fields for the Transaction Status
Details.
6. result Transaction Alphabet 8(Max) M
Result
7. error_code UPI Alphanumeric 6(Max) M
Switch/NPCI
error code
8. adjFlag adjustment Alphabet 3(Max) M
Flag
9. adjCode adjustment CODE 3(Max) M
Code
10. adjRefId adj Alphanumeric 15(Max) M
Reference Id
11. resp_code Response Numeric 2(Max) M
Code
12. txn_id Transaction Alphanumeric 35(Fixed) M
Identifier
13. adjTs Adj Time Date 8(Max) O
Stamp
14. org_rrn Original Alphanumeric 35(Max) O

19 | P a g e
 15. crn Complaint Alphanumeric 16(Max) O
Reference
Number
16. adjAmt Transaction Numeric 10(Max) C
Amount If the disputed amount
is being adjusted, this
field contains the
adjustment amount
17. prRespcode Payer Code 3(max) C
Response Any one of the given
Code field will be
populated based on
18. prRevRespcode Payer Code 3(max) the Transaction
Reversal response code
Response
Code
19. pyRespcode Payee Code 3(max)
Response
Code
20. pyRevRespcode Payer Code 3(max)
Reversal
Response
Code

4.2.3 Dispute Status Response

In the “action_type” Parameter, passing the type as DISPUTE_STATUS will provide you the
dispute status against the original Transaction Id.

Sample Message

{
"requestInfo": {
"pspId": 202,
"pspRefNo": "TXNF93A7A40FBE14C5ABEEFCFFDC9F",
"time_stamp": "2019-09-24 14:21:05"
},
"status": "S",
"statusDesc": "API request processed successfully/API request Failed ",
"action_type": "DISPUTE_STATUS",
"txn_status_details": {
"adjFlag": "DRC",
"adjCode": "102",
"adjRefId": "P1705110000338829745321",
"result": "SUCCESS",

20 | P a g e
 "result_desc": "Transaction success",
"error_code": "",
"resp_code": "00",
"txn_id": "TXN123A7A40FBE14C5ABEEFCFFDC92",
"crn": "UPI2005138765432",
"adjAmt": 500
}
}

Field Description

Sr
Fields Description Data Type Length Condition
No.
requestInfo This block represents below fields for the Request Information.
1. pspId PSP id of the Alphanumeric 16Max) M
application
This is a
unique value
for each PSP
2. pspRefNo PSP Numeric 35(Fixed) M
Reference
Number This
is unique
reference
number
which is
generated
by the
PSP/TPAP
for every
request,
cannot be
duplicate
3. time_stamp Request Numeric 30(Max) M
creation
time stamp
4. status Status (S: Numeric 1(Fixed) M
Success, F:
Failure, V:
Validation[in
case of
validation
Error])
5. statusDesc Status Alphabet 100(Max) O
description

21 | P a g e
 6. action_type Type of the CODE 20(Max) M
check txn
txn_status_details This block represents below fields for the Transaction Status
Details.
7. result Transaction Alphabet 8(Max) M
Result
8. error_code UPI Alphanumeric 6(Max) M
Switch/NPCI
error code
9. txn_id Transaction Alphanumeric 35(Fixed) M
Identifier
10. crn Complaint Alphanumeric 16(Max) O
Reference
Number
11. adjFlag adjustment Alphabet 3(Max) M
Flag
12. adjCode adjustment CODE 3(Max) M
Code
13. adjRefId adj Alphanumeric 15(Max) M
Reference Id
14. resp_code Response Numeric 2(Max) M
Code
15. adjAmt Adjustment Numeric 16(Max) C
Amount If the disputed amount
is being adjusted, this
field contains the
adjustment amount

22 | P a g e
5. NOTIFICATION – CALL BACK

This section covers the Call back API applicable for various process, based on the
requirement, PSP will receive the call backs.

5.1 Mandate Creation

This Call-back is provided against the mandate creation use to notify the payer regarding the
initiation of the mandate.

Sample Payload

{
"statusDesc": "Mandate Approval Request Received from NPCI",
"errCodeDesc": "Mandate Approval Request Received from NPCI",
"mandateDtls": [
{
"custRefNo": "333501719915",
"requestDate": "01 Dec 2023 04:21 PM",
"txnId": "HDF0B713C4322383442E06310B2E20A2D67",
"remarks": "UPI Mandate",
"name": "test KP",
"mandateType": "CREATE",
"frequency": "MONTHLY",
"amount": "26.00",
"startDate": "01 Dec 2023",
"endDate": "01 Dec 2025",
"isRevokeable": "Y",
"payerVPA": "7208960131@hdfcbank",
"payerName": "prashant",
"payeeVPA": "kpstore@hdfcbank",
"payeeName": "KPStore",
"status": "PENDING",
"creditIfsc": "HDFC0000273",
"crediAccount": "50100101674310",
"noOfDebit": 25,
"onBehalf_Of": "PAYER",
"amt_rule": "MAX",
"ruleType": "ON",
"ruleValue": "1",
"has_update_authority": "N",
"create_date_time": "01 Dec 2023 04:21 PM",
"ref_url": "https://www.hdfc.co.in",
"payType": "P2M",
"show_QR": "N",

23 | P a g e
 "callback_type": "MANDATE_COLLECT",
"purpose_code": "14",
"expire_time": "250",
"mcc": "5411",
"expiry_date_time": "01 Dec 2023 08:31 PM",
"message": "Mandate Approval Request Received from NPCI",
"is_verified": false,
"blockFund": "N",
"initiatedBy": "PAYEE",
"nextRecurDate": "Dec 1, 2023",
"remRecuCount": 25,
"pauseStartDate": "",
"pauseEndDate": "",
"prdMobile": "917208960131",
"initiationMode": "00",
"refId": "HDFCBANK862410968085"
}
]
}

Field Description

Sr. No Field Description Data Type Length Condition

1. status API Status: - String 1(Max) M
S: - Success
F: - Failure
V:- Validation Error
2. statusDesc API Status Alphabet 100(Max) M
description
3. errCodeDesc Error Code Alphabet 100(Max) O
Description
mandateDtls Mandate Details in Response: If API status =”V” validation
error then this block will not be populated
4. custRefNo Customer Reference String 12(Fixed) M
number is the
Retrieval reference
number for the
customer
5. requestDate Mandate Request String 50(Max) M
Date and Time
6. txnId Transaction Id String 35(Max) M

7. remarks Remarks if any String 50(Max) O

8. name Mandate Name String 20(Max) M

24 | P a g e
 9. mandateType Mandaten Action String Fixed M
Type
10. frequency Frequency of the String Fixed M
mandate
11. amount Mandate Amount String 19(Max) M

12. startDate Madate Start Date String 11(Max) M

13. endDate Mandate End Date String 11(Max) M

14. isRevokeable Whether mandate String 1(Fixed) M

can be revoked by
payer for
payee(Merchant)
initiated mandate:
Y/N
15. payerVPA Payer VPA/UPI ID String 255(Max) M

16. payerName Name of the payer String 100(Max) M

17. payeeVPA Payee VPA/UPI ID String 255(Max) M

18. payeeName Name of the Payee String 100(Max) M

19. status Mandate Status :- String 20(Max) M

ACTIVE
REVOKED
SUSPEND
PENDING
EXPIRED
COMPLETED
REJECTED
EXPIRED
20. creditIfsc Beneficiary IFSC String 11(Max) M

21. crediAccount Beneficiary Account String 30(Max) M

number
22. noOfDebit No of Debit Done String 10(Max) M

23. onBehalf_Of Mandate Initiated String Fixed M

By
“PAYEE”
“PAYER”
24. amt_rule Mandate amount String Fixed M
rule:
MAX: Maximum
amount
EXACT: Exact
amount

25 | P a g e
 25. ruleType Recurrence Rule String 20(Max) C
(ON/BEFORE/AFTER)

If Pattern is other
than ONETIME/AS
PRESENTED/DAILY,
then ruleType is
mandatory
26. ruleValue Recurrence Rule String 2(Max) C
(Defines the
date/day on which
the mandate
amount will be
debited)

For WEEKLY,
If the start date
(day) = Monday,
Rule Value = 1, for
Tuesday it is
2………for Sunday it
is 7.

For FORTNIGHTLY

For Start Date (1st –

15th)
Rule Value = Start
Date

For Start Date (16th

– 31th)
Rule Value = Start
Date – 15

For MONTHLY and

greater than
Monthly frequencies

Rule Value = Start

Date
27. has_update_authority Update authority String 1(Fixed) M
flag
28. create_date_time Mandate Request String 50(Max) M
Date and time

26 | P a g e
 29. ref_url Ref URL for invoice String 35(Max) O
details for mandate
which will be shown
to Payer
30. payType Pay Type String 3(Max) O
“P2M” = Person to
Merchant
31. show_QR Flag for PSP to show String 1(Fixed) O
QR
32. callback_type Call back type String 20(Max) M

33. purpose_code Type of mandate String 2(Max) O

Should be always
‘14’ for Recurring
Mandate

00-Default
01-SEBI
02- AMC
03- Travel
04- Hospitality
05- Hospital
06- Telecom
07- Insurance
08- Education
09- Gifting
10- Others
14- Recurring
Mandate
34. expire_time Mandate Expiry String 30(Max) M
Time
35. mcc Merchant Category String 4(Fixed) O
Code
36. expiry_date_time Expiry date of the String 30(Max) M
mandte
37. message Message String 100(Max) O
descriptions against
errCode
38. is_verified Merchant is verified Boolean Fixed O
at NPCI end
39. blockFund Should always be String 2(Max) O
‘N’ for recurring
mandate
40. initiatedBy Initiated By String 2(Max) O

27 | P a g e
 41. nextRecurDate Mandate next debit String 50(Max) O
date
42. remRecuCount Remaining number String 5(Max) O
of debits for the
given mandate
43. pauseStartDate Pause mandate start String 11(Max) O
date
44. pauseEndDate Pause mandate end String 11(Max) O
date
45. prdMobile Payer Mobile String 12(Max) M
Number
46. initiationMode Initiation Mode String 2(Max) O

47. refId Reference number String 35(Max) M

of the Mandate
which was passed in
request parameter
ref_id, If ref_id is
not passed in the
request then
pspRefNo will be
returned

28 | P a g e
5.2 Collect Initiate

This call back is used for collect request notification. Merchant/psp will share the call-back
URL with bank for whitelisting and bank will post this call-back data on the same url
configured against the merchant/psp.
Also, the call back will be in encrypted format.

Sample Message

{
"upiTransRefNo": "7845907",
"custRefNo": "334801713590",
"npciTranId": "HDF60E538B520EA44329F0BC9B707396BE9",
"payeeVPA": "mrita66@mybank",
"payeeAccNo": "XXXXXX6027",
"payeeIfsc": "HDFC0002373",
"payeeBankCode": "HDFC",
"PayeeName": "Williams",
"expiryTime": "1440",
"amount": "25.00",
"payerVPA": "prashant24@mybank",
"txnNote": "Collect",
"payType": "P2P"
}

Field Description

Sr. No. Field Description Data Type Length Condition

1. upiTransRefNo UPI Transaction Numeric 12(Max) M
Reference Number
2. custRefNo Customer Reference Character 12(Max) M
Number
3. npciTranId NPCI Transaction Character 35(Max) M
Identifier
4. payeeVPA Payee Virtual Character 255(Max) M
Payment Address
5. payeeAccNo Payee Account Character 50(Max) M
Number
6. payeeIfsc Payee IFSC Character 20(Max) M

7. payeeBankCode Payee Bank Code Character 20(Max) M

8. payeeName Payee Name Character 100(Max) M

9. expiryTime Expiry Time in Numeric 5(Max) M

29 | P a g e
 10. amount Amount Numeric 16(Max) M

11. payerVPA Payer Virtual Character 255(Max) M

Payment Address
12. txnNote Transaction Note Character 100(Max) M

13. payType Pay Type Character 100(Max) M

30 | P a g e
5.3 Credit Confirmation

After successful credit this call back is provided to the payee to notify about the transaction.

Sample Message

{
"upitrnRefNo": "6206530",
"custRefNo": "335401715366",
"txnId": "HDFAB0D6920FE4C4EF292D8D30AB9752F34",
"prfvaddr": "muthootexim@hdfcbank",
"pyFvaddr": "rockstar@hdfcbank",
"status": "S",
"statusDesc": "00",
"txnAmt": "200000.00",
"transactionAuthDate": "20/12/2023 19:13:59",
"respcode": "00",
"approvalNum": "null",
"txnType": "CREDIT",
"txnNote": "Cashback Testing"
}

Field Description

Sr. No. Field Description Data Type Length Condition

1. upiTransRefNo UPI Numeric 16(Max) M
Transaction
Reference
Number
2. custRefNo Customer Character 12(Max) M
Reference
Number
3. txnId NPCI Character 35(Max) M
Transaction
Identifier
4. prfvaddr Payer Virtual Character 255(Max) M
Address
5. pyFvaddr Payee Virtual Character 255(Max) M
Address
6. status Status (S: Character 1(Fixed) M
Success, F:
Failure,
V:Validation}
7. statusDesc API Status Alphabet 100(Max) M
description

31 | P a g e
 8. txnAmt Transaction Numeric 10(Max) M
Amount
9. transactionAuthDate Transaction Numeric 30(Max) M
Authentication
Date
10. respcode Response Character 3(Max) M
Code
11. approvalNum Approval Character 6(Max) O
Number
12. txnType Transaction Character 10(Max) M
Type
13. txnNote Tranasaction Character 100(Max) M
Note

32 | P a g e
5.4 Dispute Call Back

This Call-back provides the update on the dispute status against the transaction.

Sample Payload

{
"requestInfo": {
"pspId": "1",
"pspRefNo": "MGA6FA28F46209D4500BB6061B89B5E8A03"
},
"complaint_info": {
"org_txn_id": "MGA892A3EE10F764918855BA8B5F5FEFE95",
"action_type": "COMPLAINT_STATUS",
"txn_remarks": "Customer Account has been Credited",
"crn": "UPI2005138765432",
"adj_flag": "TCC/RET/DRC/DUU/RUU/PUU",
"adj_code": "103/102/115/120/UT1/U6",
"txn_Id": "MGA1B94E75832B44996AB21F3E740B71FC6",
"onBehalf_Of": "PAYER ",
"req_adj_code": "U010",
"req_adj_flag": "PBRB",
"int_adj_flag": "RET",
"int_adj_code": "115"
},
"txn_status_details": {
"result": "SUCCESS",
"result_desc": "Transaction success",
" error_code ": "BT/RB",
"resp_code": "BT/RB",
"org_txn_id": "MGA892A3EE10F764918855BA8B5F5FEFE95"
}
}

Field Description

Data Type /
Sr No. Fields Description Length Condition
Value
requestInfo This block represents below fields for the Request Information.
1. pspId PSP id of the Numeric 16(Max) C
application This
is a unique value
for each PSP

33 | P a g e
 2. pspRefNo PSP Reference Alphanumeric 35(Max) M
Number This is
unique reference
number which is
generated by
the PSP/TPAP
for every
request, cannot
be duplicate
complaint_info This block represents below fields for the Complaint
Information
3. org_txn_id Original Alphanumeric 35(Max) M
Transaction id
4. action_type Type of the Code 20(Max) M
check txn
5. txn_remarks Transaction Alphanumeric 20(Max) M
Remarks
6. crn Complaint Alphanumeric 16(Max) M
Reference
Number
7. adj_flag adj Flag Alphabet 3(Max) M

8. adj_code adj Code Code 3(Max) M

9. txn_Id Transaction Id Alphanumeric 35(Max) M

10. onBehalf_Of This is on behalf Code 5(Max) O

of payer or
payee
11. req_adj_code adj Flag Code 4(Max) O

12. req_adj_flag adj Code Alphabet 4(Max) O

13. int_adj_flag adj Flag Alphabet 3(Max) O

14. int_adj_code adj Code Numeric 3(Max) O

txn_status_details This block represents below fields for the transaction Status

15. result Result Alphanumeric 8(Max) O

16. result_desc Result Alphabetic 20(Max) O

Description
17. error_code UPI Switch/NPCI Alphanumeric 2(Max) O
error code
18. resp_code Response Code Alphanumeric 2(Max) O

34 | P a g e
 19. org_txn_id Original Alphanumeric 35(Max) M
Transaction id

------------------End of the Document--------------

35 | P a g e