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

<WalletHeader />

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

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 - 100

Ashish

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 name

98

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

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

beneficiaryId

A unique Beneficiary Id for the beneficiary.

874743484374

accountNumber

Conditional with urn and customerId

434532154

beneficiaryTypeCode

Can 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

beneficiaryMobileNumber

Contains the mobile number in case of Beneficiary type code - 3

maxTransactionAmountPerTxn

Max. allowed fund transfer per txn to that beneficiary. Cannot exceed global fund transfer limit set at program level.

500

maxTransactionAmountPerDay

Max. allowed fund transfer per day to that beneficiary. Cannot exceed global fund transfer limit set at program level.

500

maxTransactionAmountPerMonth

Max. allowed fund transfer per month to that beneficiary. Cannot exceed global fund transfer limit set at program level.

10000

maxCountTransactionPerDay

Max. allowed no of transactions per day to that beneficiary. Cannot exceed global limit set at program level.

10

maxCountTransactionPerMonth

Max. allowed no of transactions per month to that beneficiary. Cannot exceed global limit set at program level.

30

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