Register Customer API

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
token `mandatory`	`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