Fetch Beneficiary API

The Fetch Beneficiary API is used for fetching beneficiary details.

URL: https://domain/api/onboarding/ v1/beneficiary/fetch

HTTP Method: GET

Request parameters

Body

Parameter	Description	Example
Encrypted
token mandatory	`String` Token is the Encrypted body of the below request AES-192-CBC bits Encryption	Pl8F5kDZcvADIiursiA vvbHNuL9Wv5eaFdorGV FU6FKfIEnV/YskkzJlA ov2ZHJWnqGNLOXfBq4S Qqw8Ep4sK0gCAAkRXAT Cb1nSY6s=
Decrypted
messageCode mandatory	`Numeric` Code to Identify load card request type. `Character Limit - 4`	1080
clientTxnId mandatory	`String` Unique ID generated by the client for each transaction. `Character Limit - 14`	GOUd789hhhjfscs
requestDateTime mandatory	`Numeric` Local Date and time stamp when the transaction originated from the client in YYYYMMDDHHMMSS with time in 24 hr format. `Character Limit - 4`
customerId conditional	`String` Customer Id (entityCIF), which uniquely identifies the cardholder in the client system. It is conditional with mobile number and URN, i.e., either one of them should be present. `Character Limit - 20`	11001188721
urn conditional	`Numeric`A unique reference number for the card(urn). `Character Limit - 11`	70000000008
customerMobile conditional	`Numeric` Mobile number of the cardholder. Conditional with customer id and Urn i.e either one of them should be present. Please append 91 at the beginning of this field for India international code. `Character Limit - 20`	919888888888
beneficiaryId conditional	`String` A unique Beneficiary Id for the beneficiary. If value is passed in Beneficiary ID, then only beneficiary details of that specific beneficiary is to be provided in API response. conditional with urn, customer id and mobile. `Character Limit - 100`	874743484374
activationStatus conditional	`String`If no value is passed in Beneficiary ID, any of the folloinw value needs to be passed in activation status.  There are three types of status: - IN - List of all inactive beneficiaries - AC - List of all active beneficiaries - ALL - List of all beneficiaries	IN
accountNumber conditional	`String`If value is passed, all beneficiary details of that specific wallet need to be provided in API response. Conditional - with urn, customer id and mobile `Character Limit - 15`	4321555
transferType mandatory	`String`Denotes whether transaction is fund transfer or wallet closure `Character Limit - 100`	FT/WC

Sample request

Request packet (Encrypted)

{ 

   “token”: “h/0YSUdGzgNsMcmfYAvIIPgF3Z80/kMJkW/7l9wG9L+bXt//P/HBG0NsuoPtbn6ugjzNOLl/wQPJFbCKMqQJtSSQs4JVYBohia1TPP1yJULHN+TLIVKFRZsg0GokTPI+ZKpNPcrKrQSa70qV/RtVWMv6CmqRHaG1gQvgAYKjNyOpip7G3Io5IDEF4b2cXOlH4G1hbOtjAHQ/7ZS9KrkmJA==”}

Request packet (Decrypted)

{ 
    "messageCode": "2020", 
    "clientTxnId": "20771458URNFETCH131331u19", 
    "requestDateTime": "20161031214559", 
    "urn": 1435, 
    "activationStatus": "ALL", 
    "transferType": "FT" 
}

Response parameters

Parameter	Description	Example
Encrypted
token	Token is the Encrypted body of the below request AES-192-CBC bits Encryption	Pl8F5kDZcvADIiursiAvvbHNuL9Wv5eaFdorGVFU6FKfIEnV/ nYskkzJlAov2ZHJWnqGNLOXfBq4SQqw8Ep4sK0gCAAkRXATCb n1nSY6s=
Decrypted
messageCode	Code to Identity create card response type	1011
clientTxnId	Value copied from the request	20150701235959xhstiesqfds
responseDateTime	Response date time in the format YYYYMMDDHHMMSS with time in 24 hr format	20161031214559
urn	A unique reference number for the card(urn)	70000000008
clientId	Uniquely ID for the client .	9712938648
responseCode	Contains the status of the transaction. 201 indicates CREATED. Please refer Appendix for other response codes	201
responseMessage	Response message based on response code will be sent	Card creation successful
accosaTransactionId	Unique id for a particular transaction generated in Prepaid	3591893
beneficiaryDataList	If beneficiary ID is passed (conditional parameter), share beneficiary data list only for that beneficiary. If Beneficiary ID is not passed and instead activation status is passed, share beneficiary data list for all the beneficiaries under that customer (as per activation status). This list contains the details of all the beneficiaries under that customer. Details like private long beneficiaryId, beneficiaryName, bankName, bankAccountNumber, ifscCode, upiVpa, mobileNumber, emailId are sent in the response if present in the DB.

The format of the beneficiaryDataList is:

beneficiaryId Numeric(15)
benifiaryName String (100)
bankName String (150)
bankAccountNumber String (150)
ifscCode String (50)
upiVpa String (100)
emailId String (100)
status (0: Inactive | 1: Active)
beneficiaryType (0: OTHER | 1: SELF)
coolingOff (0: beneficiary in cooldown | 1: not in cooldown)
createdTime (yyyy-mm-dd HH:MM:SS)
modifiedTime (yyyy-mm-dd HH:MM:SS)
beneficiaryTypeCode numeric(2)
accountNumber String(15)
beneficiaryMobileNumber numeric(20)
beneficiaryLimitPerTxn numeric(10)
beneficiaryLimitOutstandingDailyLimit numeric(10)
beneficiaryLimitOutstandingMonthlyLimit numeric(10)
beneficiaryMaxCountTransactionsPerDayOutstandingLimit numeric(10)
beneficiaryMaxCountTransactionsPerMonthOutstandingLimit numeric(10)

API error codes

Error Code	Description
00	SUCCESS
1055	MALFORMED_REQUEST
1085	PRODUCT NOT ALLOWED
1052	SYSTEM_ERROR
1032	INVALID_CLIENT_CHANNEL
1081	OPERATION NOT ALLOWED
1080	IP_NOT_ALLOWED
1049	INVALID SECURE CODE
1051	CHECKSUM FAILURE
1093	INVALID CLIENT TXN ID
1320	REQUEST_DATETIME_IS_MANDATORY
1031	INVALID BANK ID
1264	BANK ID NOT PRESENT
1262	CLIENT ID NOT PRESENT
1310	XCONSUMERKEY NOT PRESENT
1030	INVALID MESSAGE
1311	SECURE CODE NOT PRESENT
1361	INVALID ACCOUNT NUMBER
10079	TRANSFER TYPE NOT PRESENT
10074	ACTIVATION STATUS NOT PRESENT

Sample response

Packet sample (Encrypted)

{ 

   “token”: “h/0YSUdGzgNsMcmfYAvIIPgF3Z80/kMJkW/7l9wG9L+bXt//P/HBG0NsuoPtbn6ugjzNOLl/wQPJFbCKMqQJtSSQs4JVYBohia1TPP1yJULHN+TLIVKFRZsg0GokTPI+ZKpNPcrKrQSa70qV/RtVWMv6CmqRHaG1gQvgAYKjNyOpip7G3Io5IDEF4b2cXOlH4G1hbOtjAHQ/7ZS9KrkmJA==”}

Packet sample (Decrypted)

{ 

    "customerId": "62508sachin2479", 
    "responseCode": "00", 
    "messageCode": 2021, 
    "responseMessage": "SUCCESS", 
    "bankId": 7020, 
    "clientTxnId": "207458URNACC3722134061", 
    "responseDateTime": "2023/10/10 12:54:39", 
    "clientId": "1", 
    "beneficiaryDataList": [ 
        { 
            "beneficiaryId": 51465570, 
            "beneficiaryName": "New Bene", 
            "bankName": "AXIS", 
            "bankAccountNumber": "21486224170", \
            "ifscCode": "IDFB0010204", \
            "upiVpa": "null", 
            "mobileNumber": "null", 
            "emailId": "null", 
            "walletProgram": "null", 
            "status": 0, 
            "coolingOff": 1, 
            "beneficiaryType": 1, 
            "beneficiaryTypeCode":1, 
            "accountNumber":244543443, 
            "beneficiaryMobileNumber":"919855993322", 
            "beneficiaryLimitPerTxn":2000, 
            "beneficiaryLimitOutstandingDailyLimit":300, 
            "beneficiaryLimitOutstandingMonthlyLimit":2000, 
            "beneficiaryMaxCountTransactionsPerDayOutstandingLimit":4, 
            "beneficiaryMaxCountTransactionsPerMonthOutstandingLimit":5, 
            "createdTime": "2023-10-03 19:11:09.0", 
            "modifiedTime": "2023-10-03 19:11:09.0" 
        } 
    ] 
}