API Create customer

API Create customer

Chat with AI▼

Endpoint: /api/v1/customers

Method: POST

Header Params

Param	Required	Type	Description	Note
X-APPOTAPAY-AUTH	required	String	How to generate JWT_TOKEN
Content-Type	required	String	Value: application/json
X-Request-ID	optional	String	UUIDv4 format. Request ID to check when a problem occurs	max:42
Language	optional	String	The value vi or en corresponding to the payment link will be Vietnamese or English, (default: vi)	in:vi,en
X-Account-Ref-ID	optional	String	Iidentifier of the sub account provided by AppotaPay. Mandatory be passed over when processing payment for transactions of owner-type sub account

{
    "X-APPOTAPAY-AUTH": "JWT_TOKEN",
    "Content-Type": "application/json",
    "X-Request-ID": "Your_Unique_id",
    "Language": "vi",
    "X-Account-Ref-ID": "9723f73b-9295-4acb-884b-ab6310c2e653"
}

Request params

Param	Required	Type	Description	Note
customerRefId	required	String	Unique code from your side Partner-provided identifier for the customer. Requests with a duplicate customerRefId will return an error.	min:1, max: 50, format: alphanumeric
customer	required	Object	Customer information
customer.firstName	required	String	First name	min:1, max: 50, only unaccented letters (a-z, A-Z), digits (0-9) and spaces are allowed; special characters, accented letters and non-Latin characters (e.g. Japanese, Chinese) are not allowed
customer.lastName	optional	String	Last name	min:1, max: 50, only unaccented letters (a-z, A-Z), digits (0-9) and spaces are allowed; special characters, accented letters and non-Latin characters (e.g. Japanese, Chinese) are not allowed
customer.mobileNumber	Conditional, required mobileNumber or email	String	Phone number Format: +[Country code][Phone number] Example: +84919333777	min:1, max:16, format: E.164
customer.email	Conditional, required mobileNumber or email	String	Email	min:1, max: 50
customer.gender	optional	String	Gender - MALE: male - FEMALE: female - OTHER: other	in: MALE, FEMALE, OTHER
customer.dateOfBirth	optional	String	Date of birth	format YYYY-MM-DD string
customer.placeOfBirth	optional	String	Place of birth	max:50
customer.nationality	optional	String	Nationality code	format ISO 3166-2 Country Code

Example Request

{
    "customerRefId": "ASKJLKALK213",
    "customer": {
        "firstName": "Ha",
        "lastName": "Phan",
        "mobileNumber": "+84123456789",
        "email": "ha@gmail.com",
        "gender": "MALE",
        "dateOfBirth": "1996-04-23",
        "placeOfBirth": "HN",
        "nationality": "EC"
    }
}

Response data

Success

Http Status Code 200 - OK

Success responses will contain a single Customer object

Failure

HTTP Status Code != 200

Error response params

Param	Required	Type	Description
errorCode	required	Integer	Error code
message	required	String	Error message
errors	optional	Array	Detailed error description
errors.*.field	optional	String	Field data is corrupted
errors.*.reason	optional	String	Description of the data field in error

{
    "errorCode": 1,
    "message": "Missing or Invalid Params",
    "errors": [
        {
            "field": "customerRefId",
            "reason": "The customer ref id field is required."
        }
    ]
}

Common error code table

Full error code, please check this error code list

Error code	Description
0	Success
1	Missing or Invalid Params
11	Partner is not found
13	Partner has been blocked
14	API Key is invalid
15	API Key is not activated or blocked
92	IP is not allowed to access
99	Undefined error, please contact AppotaPay for more detailed information
401	Unauthorized
500	Server error
3002	Duplicate reference code of partner, please try again

Code Examples

curl --location 'https://gateway.dev.appotapay.com/api/v1/customers' \
  --header 'X-APPOTAPAY-AUTH: JWT_TOKEN' \
  --header 'Content-Type: application/json' \
  --header 'X-Request-ID: Your_Unique_id' \
  --header 'Language: vi' \
  --header 'X-Account-Ref-ID: 9723f73b-9295-4acb-884b-ab6310c2e653' \
  -d '{
  "customerRefId": "ASKJLKALK213",
  "customer": {
    "firstName": "Ha",
    "lastName": "Phan",
    "mobileNumber": "+84123456789",
    "email": "ha@gmail.com",
    "gender": "MALE",
    "dateOfBirth": "1996-04-23",
    "placeOfBirth": "HN",
    "nationality": "EC"
  }
}'

Request

REQUEST

Base URL

https://gateway.dev.appotapay.com

Development server

Path

Auth REQUIRED

Bearer Token

Language — header

vien

The value corresponding to the payment link can be in Vietnamese or English (default: vi)

Parameters

Body REQUIRED

Example (from schema)

{ "customerRefId": "ASKJLKALK213", "customer": { "firstName": "Ha", "lastName": "Phan", "mobileNumber": "+84123456789", "email": "ha@gmail.com", "gender": "MALE", "dateOfBirth": "1996-04-23", "placeOfBirth": "HN", "nationality": "EC" } }