Create Beneficiary API

The Create Beneficiary API is used for creation of beneficiary.

Environment: https://domain/api/onboarding/ v1/beneficiary/create

HTTP Method: POST

Request parameters

Header

ParameterDescriptionExample
x-api-key
mandatory		String This is a unique key.7fe1c0de
clientId
mandatory		String Uniquely identifies the client. During program enrolment each client is provided with a unique client id by Prepaid2000
bankId
mandatory		Numeric Bank Id is provided by Prepaid Aero during program enrolment to uniquely identify the card issuer.7000
entityId
mandatory		Numeric Defaults to parent branch i.e., 100100
secureCode
mandatory		String Uniquely identifies the client on payload level for performing operations.AfYtlO5kqdySIjXyNmGg3F

Body

ParameterDescriptionExample

Encrypted

token
mandatory		String Token is the Encrypted body of the below request AES-192-CBC bits EncryptionPl8F5kDZcvADIiursiA
vvbHNuL9Wv5eaFdorGV
FU6FKfIEnV/YskkzJlA
ov2ZHJWnqGNLOXfBq4S
Qqw8Ep4sK0gCAAkRXAT
Cb1nSY6s=

Decrypted

messageCode
mandatory		Numeric Code to Identify load card request type. Character Limit - 41080
clientTxnId
mandatory		String Unique ID generated by the client for each transaction. Character Limit - 14GOUd789hhhjfscs
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 - 2011001188721
urn
conditional		 NumericA unique reference number for the card(urn). Character Limit - 11
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
beneficiaryName
mandatory		String A unique reference number for the card(urn)Character Limit - 100Ashish
beneficiaryTypeCode
mandatory		Numeric Any of following values are supported :

1 - UPI - Bank account  or IMPS Bank account(Beneficiary Code 1)
2 - UPI - VPA (Beneficiary Code 2)
3 - Wallet to wallet (Beneficiary Code 3)
4 -  IMPS Bank account (Beneficiary Code 4)
Character Limit - 2		1
bankName
conditional		StringName of the Bank on which holding the Benificiary account. To be passed in case of Beneficiary type code – 1 or 4.
Character Limit - 150		HDFC Bank
bankAccountNumber
conditional		StringAccount Number in the beneficiary bank. To be passed in case of Beneficiary type code – 1 or 4.
Character Limit - 20		1234098753
ifscCode
conditional		StringIFSC code of the beneficiary Bank account. To be passed in case of Beneficiary type code – 1 or 4.
Character Limit - 15		HDFC00015
upiVpa
conditional		StringUnique Upi ID of customers. To be passed in case of Beneficiary type code is 2,
Character Limit - 100		anything@payu
beneficiaryMobileNumber
conditional		NumericTo be passed in case of Beneficiary type code is 3
Character Limit - 20
beneficiaryEmailId
conditional		String Email Address of the account holder. Character Limit - 100[email protected]
nameMatchRatio
optional		NumericThis contains the name match ratio of the beneficiary name98
maxTransactionAmountPerTxn
optional		NumericTo capture max. allowed fund transfer per txn to that beneficiary. Cannot exceed global fund transfer limit set at program level.
Character Limit - 10		500
maxTransactionAmountPerDay
optional		NumericTo capture max. allowed fund transfer per day to that beneficiary. Cannot exceed global fund transfer limit set at program level.
Character Limit - 10		500
maxTransactionAmountPerMonth
optional		NumericTo capture max. allowed fund transfer per month to that beneficiary. Cannot exceed global fund transfer limit set at program level.
Character Limit - 10		10000
maxCountTransactionPerDay
optional		NumericTo capture max. allowed no of transactions per day to that beneficiary. Cannot exceed global limit set at program level.
Character Limit - 10		10
maxCountTransactionPerMonth
optional		Numeric To capture max. allowed no of transactions per month to that beneficiary. Cannot exceed global limit set at program level.
Character Limit - 10		30

Sample request

Request packet (Encrypted)

{ 

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

Request packet (Decrypted)

{ 
    "messageCode": "2010", 
    "clientTxnId": "207458URNACC37013134061", 
    "requestDateTime": "20161031214559", 
    "urn": 1435, 
    "beneficiaryName": "New Bene", 
    "beneficiaryTypeCode": "1", 
    "bankName": "AXIS", 
    "bankAccountNumber": "21486224170", 
    "ifscCode": "IDFB0010204", 
    "nameMatchRatio": 97 
}

Response parameters

ParameterDescriptionExample

Encrypted

tokenToken is the Encrypted body of the below request AES-192-CBC bits EncryptionPl8F5kDZcvADIiursiAvvbHNuL9Wv5eaFdorGVFU6FKfIEnV
nYskkzJlAov2ZHJWnqGNLOXfBq4SQqw8Ep4sK0gCAAkRXATCb n1nSY6s=

Decrypted

messageCodeCode to Identity create card response type1011
clientTxnIdValue copied from the request20150701235959xhstiesqfds
responseDateTimeResponse date time in the format YYYYMMDDHHMMSS with time in 24 hr format20161031214559
urnA unique reference number for the card(urn)70000000008
clientIdUniquely ID for the client .9712938648
responseCodeContains the status of the transaction. 201 indicates CREATED. Please refer Appendix for other response codes201
responseMessageResponse message based on response code will be sentCard creation successful
accosaTransactionIdUnique id for a particular transaction generated in Prepaid3591893
beneficiaryIdA unique Beneficiary Id for the beneficiary.874743484374
accountNumberConditional with urn and customerId434532154
beneficiaryTypeCodeCan contain any of following values :

1 - UPI - Bank account  or IMPS Bank account(Beneficiary Code 1)
2 - UPI - VPA (Beneficiary Code 2)
3 - Wallet to wallet (Beneficiary Code 3)
4 -  IMPS Bank account (Beneficiary Code 4)
Character Limit - 2		1
beneficiaryMobileNumberContains the mobile number in case of Beneficiary type code - 3
maxTransactionAmountPerTxnMax. allowed fund transfer per txn to that beneficiary. Cannot exceed global fund transfer limit set at program level.500
maxTransactionAmountPerDayMax. allowed fund transfer per day to that beneficiary. Cannot exceed global fund transfer limit set at program level.500
maxTransactionAmountPerMonthMax. allowed fund transfer per month to that beneficiary. Cannot exceed global fund transfer limit set at program level.10000
maxCountTransactionPerDayMax. allowed no of transactions per day to that beneficiary. Cannot exceed global limit set at program level.10
maxCountTransactionPerMonthMax. allowed no of transactions per month to that beneficiary. Cannot exceed global limit set at program level.30

API error codes

Error CodeDescription
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
1084 URN AND CUSTOMER ID MISMATCH
303135 CREATE BENIFICIARY FAILURE
1281 INVALID BANK NAME
1288 IFSC CODE IS INVALID

Sample response

Packet sample (Encrypted)

{ 

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

Packet sample (Decrypted)

{ 
    "urn": 0, 
    "customerId": "62508sachin2479", 
    "responseCode": "00", 
    "messageCode": 2011, 
    "clientTxnId": "207458URNACC3722134061", 
    "beneficiaryTypeCode": "1", 
    "clientId": "1", 
    "responseDateTime": "2023/10/10 12:54:39", 
    "bankId": 7020, 
    "beneficiaryId": 51465570 
}