JavaScript is disabled. Some features may not work. You can also read the static version: View text version

Create Customer API

This API is responsible for creating a new customer object in Juspay systems. You can invoke this API whenever a new user registers in your App/Website and is triggering the payment process.

Customer creation at Juspay end is required for : Tokenization/Storing Cards, Linked Wallet Flows and Subscription flows.

Request

Response

API Endpoints

Sandbox Link

POST

https://sandbox.juspay.in/customers

Production Link

POST

https://api.juspay.in/customers

                      Basic Auth
                      *
                      

Base64 Encoded username:password

required

Consists of two parts.

Username: API Key obtained from Juspay dashboard
Password: Empty string

Example:-
Basic MUQ2QUxxxxxxxxxxxxU5QTIxQzNFNTQwNkFDMEZCOg==

                      x-merchantid
                      
                      

string

Recommended

Unique identifier for the merchant. This is the Merchant ID provided by Juspay. The value is case sensitive.

Passing this value will help us route efficiently at network level.

Example:- x-merchantid: testaccount

                      Content-Type
                      *
                      

String

Mandatory

application/x-www-form-urlencoded

Body

Request Schema: application/json

                      object_reference_id
                      *
                      

string

required

Max Length :255

Unique ID that you use to represent the customer in your database. This must be atleast 8 characters and must be unique. The typical value for this field would be email address or mobile number or auto increment ID that you have in your DB

Example:-
cust_123489

                      mobile_number
                      *
                      

string

required

Max Length : 300

Customers mobile number. We recommend passing number without appending "+" or mobile country code.

Dummy values can be passed if customer details are unavailable.

Must contain digits only. Spaces or special characters are not supported.
Passing formatted values will result in a 400 – Validation error.

Example:- 99887766

                      email_address
                      
                      

string

Max Length : 300

Email address of the customer. If the backend gateway requires it, then you must send this value.

Dummy values can be passed if customer details are unavailable.

Constraints : You are allowed to use alphanumeric characters and the following special characters:!#$%&'*+-/=?^_.{|}~`@

_ and . cannot appear at the beginning or end of the local part of the email address (before and after the @ symbol).

                      first_name
                      
                      

string

Max Length :255

First Name of customer. This value will be used for customer identification.

Constraints : You are allowed to use alphanumeric characters and the following special characters: ().-_

                      last_name
                      
                      

string

Max Length :255

Last Name of customer. This value will be used for customer identification.

Constraints : You are allowed to use alphanumeric characters and the following special characters: ().-_

                      mobile_country_code
                      
                      

string

Max Length :64

Your mobile's country code. No need to add prefix ‘+’ in front of it.

Defaults to 91(India) if not provided in the request.

Example:- 65

Response Body

id

string

The ID created at Juspay end for each object_reference_id during create customer API call

                      object
                      
                      

string

Refers to the API object type

                      mobile_country_code
                      
                      

string

Customer's mobile country code

                      mobile_number
                      
                      

string

Customers mobile number

                      last_updated
                      
                      

string

Last updated date on the customer information

                      last_name
                      
                      

string

Customer's last name

                      first_name
                      
                      

string

Customer's first name

                      email_address
                      
                      

string

Customer's e-mail address

                      date_created
                      
                      

string

Customer creation date at Juspay’s end

Response Body

                      error_message
                      
                      

String

Error message of the API response

Example:- sample response: [objectReferenceId] cannot be null

                      status
                      
                      

String

Denotes what type of error message

Example:- Response: invalid_request_error

                      error_info
                      
                      

JSON

Detaield information on the error message

                      user_message
                      
                      

String

Error message can be duispaleyd to the user

Example:- sample response: Mandatory fields are missing.

                      fields
                      
                      

Array

Denotes what exact parameter is missing in the request

                      developer_message
                      
                      

String

ccAurate information on the error messaeg to the user

Example:- sample response: Missing object reference id. Please pass valid object reference id.

                      category
                      
                      

String

Denotes the type of category the error

Example:- sample response: USER_ERROR

Response Body

                      status
                      
                      

String

Status of the api response

Example:- Response: error

                      error_code
                      
                      

String

error code information

Example:- Sample response: access_denied

                      error_info
                      
                      

JSON

Detailed information of the error

                      user_message
                      
                      

String

User error message

Example:- Response: Unauthorized.

                      developer_message
                      
                      

String

Provide accurate details on the error message

Example:- Sample Response: Invalid API Key. Please pass a valid and active api key.

                      category
                      
                      

String

Denotes the category of the error

Example:- Sample Response: USER_ERROR

Error Codes:

Scroll inside to view more

Scenario	Error Codes	Description	Sample Error Message
customer creation with same object_reference_id	400	Bad Request	{"error_message":"Customer with given object reference id already exist for your account.","status":"invalid_request_error","error_code":"unique","error_info": {"user_message":"Already exists.","developer_message":"Customer account with given object reference already exists.","code":"ALREADY_EXISTS","category":"USER_ERROR"}}
Passing object_reference_id as empty value	400	Bad Request	{"error_message":"Wrong value in object_reference_id","status":"Invalid Request","error_code":"Invalid Request","error_info": {"user_message":"Invalid request params. Please verify your input.","fields": [{"field_name":"object_reference_id","reason":"Invalid value."}],"developer_message":"Invalid request params","code":"INVALID_INPUT","category":"USER_ERROR"}}
Passing mobile_number as empty value	400	Bad Request	{"error_message":"Wrong value in mobile_number","status":"Invalid Request","error_code":"Invalid Request","error_info": {"user_message":"Invalid request params. Please verify your input.","fields": [{"field_name":"mobile_number","reason":"Invalid value."}],"developer_message":"Invalid request params","code":"INVALID_INPUT","category":"USER_ERROR"}}
Whitelisting of IP in dashboard	403	IP Verification Failed	{"error":true,"error_message":"Internal Server error.","user_message":"Bad Origin.","error_info":{"code":"BAD_ORIGIN","category":"USER_ERROR","user_message":"Bad Origin.","developer_message":"IP Verification Failed"}}
Wrong API Key	401	Unauthorized	{"status":"error","error_code":"access_denied","error_info": {"user_message":"Unauthorized.","developer_message":"Invalid API Key. Please pass a valid and active api key.","code":"UNAUTHORIZED","category":"USER_ERROR"}}
Wrong API endpoint	404	Not Found
passing "-" before mobile_number value	400	Bad Request	{"error_message":"Wrong value in mobile_number","status":"Invalid Request","error_code":"Invalid Request","error_info": {"user_message":"Invalid request params. Please verify your input.","fields": [{"field_name":"mobile_number","reason":"Invalid value."}],"developer_message":"Invalid request params","code":"INVALID_INPUT","category":"USER_ERROR"}}

Have questions?
Need help? Contact support
LLM? Read llms.txt