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`
Production	`https://api.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

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`	`Numeric(4)` API Code to uniquely identify 'Register Customer' API	3510
clientTxnId `mandatory`	`AlphaNumeric(100)` Unique Id generated by the calling application for each transaction. This ID should always unique in all API Requests.	20150701235959xhstiesqfds
requestDateTime `mandatory`	`Numeric(14)` Local Date and time stamp when the transaction originated from the calling application in YYYYMMDDHHMMSS in 24 hour format	20161031214559
customerId `optional`	`String(50)` A unique customer ID from calling application to be shared. If the value is not passed in the request, the platform will auto-generate a unique value for this field.	89342546
customerDetails.firstName `mandatory`	`String(50)` Customer first Name. Below are validations for this field 1. Start and end with valid characters (no extra characters outside the allowed set). 2. Contain only: Uppercase letters (A-Z) Lowercase letters (a-z) Periods (.) Spaces ( ) Have at least one character and no invalid symbols like numbers, special characters outside the allowed set, etc.	Sourav
customerDetails.middleName `optional`	`String(50)` Customer middle name. Below are validations for this field 1. Start and end with valid characters (no extra characters outside the allowed set). 2. Contain only: Uppercase letters (A-Z) Lowercase letters (a-z) Periods (.) Spaces ( ) Have at least one character and no invalid symbols like numbers, special characters outside the allowed set, etc.	Kumar
customerDetails.lastName `optional`	`String(50)` Customer last name. Below are validations for this field 1. Start and end with valid characters (no extra characters outside the allowed set). 2. Contain only: Uppercase letters (A-Z) Lowercase letters (a-z) Periods (.) Spaces ( ) Have at least one character and no invalid symbols like numbers, special characters outside the allowed set, etc.	Mishra
customerDetails.gender `optional`	`String(1)` M or F or O	M
customerDetails.dateOfBirth `mandatory`	`String(10)` DOB (FORMAT: DD-MM-YYYY)	11-07-1993
customerDetails.mobileNumber `mandatory`	`Numeric(15)` Unique and starting with ISD country code and valid mobile number	919988776655
customerDetails.emailAddress `optional`	`String(50)` Valid email address	[email protected]
kycProfile `mandatory`	`Numeric(3)` Type of KYC: Min KYC (30), Shortfall KYC (300), Full KYC (150)	150
riskCategory `mandatory`	`String(20)` Risk type: Low, Medium, High (Low=100, Medium=500, High=200)	Low
productId `mandatory`	`Numeric(5)` Program/product ID	121
formFactorRequired `mandatory`	`Boolean` Indicates whether a form factor is required (True/False)	true

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