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

</td>

<td>
1080
</td>
</tr>

<tr>
<td>
clientTxnId\
**mandatory**
</td>

<td>
`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

</td>

<td>
11001188721
</td>
</tr>

<tr>
<td>
urn\
**conditional**
</td>

<td>
 `Numeric`A unique reference number for the card(urn). `Character Limit - 11`
</td>

<td>
70000000008
</td>
</tr>

<tr>
<td>
customerMobile\
**conditional**
</td>

<td>
`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`
</td>

<td>
919888888888
</td>
</tr>

<tr>
<td>
beneficiaryId\
**conditional**
</td>

<td>
`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

StringIf 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

StringIf 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

StringDenotes 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 CodeDescription
00SUCCESS
1055MALFORMED_REQUEST
1085PRODUCT NOT ALLOWED
1052SYSTEM_ERROR
1032INVALID_CLIENT_CHANNEL
1081OPERATION NOT ALLOWED
1080IP_NOT_ALLOWED
1049INVALID SECURE CODE
1051CHECKSUM FAILURE
1093INVALID CLIENT TXN ID
1320REQUEST_DATETIME_IS_MANDATORY
1031INVALID BANK ID
1264BANK ID NOT PRESENT
1262CLIENT ID NOT PRESENT
1310XCONSUMERKEY NOT PRESENT
1030INVALID MESSAGE
1311SECURE CODE NOT PRESENT
1361INVALID ACCOUNT NUMBER
10079TRANSFER TYPE NOT PRESENT
10074ACTIVATION 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" 
        } 
    ] 
}