The Register Customer API allows you to register a new customer and facilitates the creation of a digital wallet. This API performs onboarding checks when opted by the issuer.
Environment
Environment | URL |
---|---|
Test | http://apitest.payu.in/loyalty-points/v1/wallet/enroll |
HTTP Method: POST
Authentication
This API uses HMAC-SHA512 authentication on the header.
Parameter | Description |
---|---|
walletIdentifier mandatory |
String Program Type (e.g., CLW)
|
date mandatory |
String GMT formatted date (e.g., Thu, 17 Feb 2022 08:17:59 GMT)
|
Authorization mandatory |
String HMAC-SHA512-based authentication token
|
Content-Type mandatory |
String application/json
|
If you do not post the authentication, you will get error in response. For the list of error codes, refer to Status Codes
hmac authentication logic
hmac username="smsplus", algorithm="sha512", headers="date", signature="7ff938849aa79265a3de63fe241dfecb1c680f58c6d11e9f9ca08512afea374705eb9f8995ef6c4584e16eca2e1dc688262bb0937a36cc0f75ec22a9eea33523"
Where, the fields in this example are:
- username: The merchant key of the merchant.
- algorithm: This must have the value as hmac-sha512 that is used for this API.
- headers: This must have the value as date digest.
- signature: This must contain the hmacsha512 of (signing_string, merchant_secret), where:
- signing_string: It must be in the "date: {dateValue}"format. Here, the dateValue is the same values in the fields listed in this table For example, "date: Thu, 17 Feb 2022 08:17:59 GMT"
- merchant_secret: The merchant Salt of the merchant. For more information on getting the merchant Salt, refer to Generate Merchant Key and Salt.
Request Parameters
Body Parameters
The request body contains both encrypted and decrypted parameters.
Encrypted
Parameter | Description |
---|---|
tokenmandatory | String AES-192-CBC encrypted request body containing all the decrypted parameters |
Decrypted
Parameter | Description | Example |
---|---|---|
messageCode mandatory |
A unique API code to identify the API request for registering customers. Data type: Numeric(4) |
3510 |
clientTxnId mandatory |
The unique transaction ID generated by the calling application for every transaction. This ID must be unique across all API requests. Data type: AlphaNumeric(100) |
20150701235959xhstiesqfds |
requestDateTime mandatory |
Local date and time when the transaction originated from the calling application in YYYYMMDDHHMMSS format (24-hour format). Data type: Numeric(14) |
20161031214559 |
customerId optional |
A unique customer ID provided by the calling application. If omitted, the platform will auto-generate a unique value for this field. Data type: String(50) |
89342546 |
customerDetails.firstName mandatory |
Customer's first name. Validation rules: Start and end with valid characters, contain only uppercase letters (A-Z), lowercase letters (a-z), periods (.), spaces ( ), no special symbols or numbers allowed, maximum length: 50 characters. Data type: String(50) |
Sourav |
customerDetails.middleName optional |
Customer's middle name. Validation rules: Start and end with valid characters, contain only uppercase letters (A-Z), lowercase letters (a-z), periods (.), spaces ( ), no special symbols or numbers allowed, maximum length: 50 characters. Data type: String(50) |
Kumar |
customerDetails.lastName optional |
Customer's last name. Validation rules: Start and end with valid characters, contain only uppercase letters (A-Z), lowercase letters (a-z), periods (.), spaces ( ), no special symbols or numbers allowed, maximum length: 50 characters. Data type: String(50) |
Mishra |
customerDetails.gender optional |
Customer's gender. Allowed values: M (Male), F (Female), O (Other). Data type: String(1) |
M |
customerDetails.dateOfBirth mandatory |
Customer's date of birth in DD-MM-YYYY format. Data type: String(10) |
11-07-1993 |
customerDetails.mobileNumber mandatory |
Mobile number that must be unique and start with ISD country code followed by a valid mobile number. Limited to 15 numeric characters. Data type: Numeric(15) |
919988776655 |
customerDetails.emailAddress optional |
Customer's valid email address following standard email format. Maximum length: 50 characters. Data type: String(50) |
[email protected] |
kycProfile mandatory |
Type of KYC to be passed if KYC is performed by the calling application. Allowed values: 30 (Minimal KYC), 150 (Full KYC), 300 (Shortfall KYC). Default value: 30. Data type: Numeric(3) |
30 |
riskCategory mandatory |
Risk assessment of the customer. Allowed values: "Low" or "100", "Medium" or "500", "High" or "200". Default value: "Low". Data type: String(20) |
Low |
productId mandatory |
Unique product or program ID where the customer will be enrolled. Data type: Numeric(5) |
121 |
formFactorRequired mandatory |
Whether to create the form factor. Indicates if a form factor is required. Allowed values: true (Form factor required), false (Form factor not required). Default value: false. Data type: Boolean |
false |
Response Parameters
Parameter | Description | Example |
---|---|---|
responseCode | Response status code | 00 |
messageCode | API response code | 3511 |
clientTxnId | Mirrors the request's clientTxnId | 20150701235959xhstiesqfds |
formfactor.accountNumber | Generated account number for form factors | 72623345 |
formfactor.uniqueNumber | Unique number generated for form factors | 8543213624292443 |
formfactor.urn | Proxy reference number generated for the unique number | 70000000008 |
responseMessage | Response message | CUSTOMER REGISTERED SUCCESSFULLY |
Sample Request
Encrypted Packet
curl --location --request POST 'http://apitest.payu.in/loyalty-points/v1/wallet/enroll' \
--header 'walletIdentifier: CLW' \
--header 'date: Wed, 12 Jun 2024 08:53:43 GMT' \
--header 'authorization: hmac username="smsplus", algorithm="sha512", headers="date", signature="hmac_generated_signature"' \
--header 'Content-Type: application/json' \
--data-raw '{
"token": "h/0YSUd9jKOQ8+2Dc3Phr4s7vxyz123..."
}'
Decrypted Packet
{
"messageCode": 3510,
"clientTxnId": "txn12345",
"requestDateTime": "20230810123015",
"customerDetails": {
"firstName": "Alice",
"lastName": "Smith",
"dateOfBirth": "12-12-2000",
"mobileNumber": "917001122334"
},
"kycProfile": 150,
"riskCategory": "Low",
"productId": 35,
"formFactorRequired": true
}
Sample Response
Encrypted Response
{
"result": "h/0YSUd9jKOQ8+2Dc3Phr4s7vxyz789..."
}
Decrypted Response
{
"responseCode": "00",
"messageCode": 3511,
"clientTxnId": "txn12345",
"formFactor": {
"uniqueNumber": "7262334512345678",
"urn": 10000234
},
"responseMessage": "CUSTOMER REGISTERED SUCCESSFULLY"
}
HTTP Status Codes
Status Code | Description |
---|---|
200 | OK - Request processed successfully |
400 | Bad Request - Invalid request parameters |
401 | Unauthorized - Authentication failed |
500 | Internal Server Error |
Error Codes
Error Code | Description |
---|---|
3511 | Customer registered successfully |
1010 | Invalid message code |
1020 | Missing required parameters |
1030 | Customer already exists |