Skip to main content
POST
This request creates a customer resource. You need to provide several parameters of the customer in the request body, including the unique identifier of the customer in the external merchant, personal information, as well as billing and shipping addresses. Creating a customer generates a customer id that can be used to initialize the checkout.
merchant_customer_id is scoped to the organization, not the accountIf your organization has several accounts, merchant_customer_id still has to be unique across all of them. Creating a customer from one account with an id already used by another account in the same organization returns CUSTOMER_ID_DUPLICATED. See Accounts for how to structure ids if you run several companies under one organization.
ImportantThere are certain objects that are not mandatory when creating a “Customer.” However, the more information you provide, the more it can help approval, conversion, and fraud prevention rates.

Authorizations

​
public-api-key
string
header
default:<Your public-api-key>
required
​
private-secret-key
string
header
default:<Your private-secret-key>
required

Body

application/json
​
merchant_customer_id
string
required

The unique identifier of the customer in the external merchant (MAX 255; MIN 3). Unique per organization, not per account: reusing an id already used by another account in the same organization returns CUSTOMER_ID_DUPLICATED.

​
merchant_customer_created_at
string<date-time>

Customer's registration date on the merchants platform (MAX 27; MIN 27; ISO 8601)

​
first_name
string

The customer's first name (MAX 255; MIN 3).

​
last_name
string

The customer's last name (MAX 255; MIN 3).

​
gender
string

The customer's gender.

​
date_of_birth
string

The customer's date of birth in the YYYY-MM-DD format (MAX 10; MIN 10).

​
email
string

The customer's e-mail (MAX 255; MIN 3).

​
nationality
enum<string>

The customer's nationality (MAX 2; MIN 2; ISO 3166-1 [blocked]).

Available options:
AF,
AX,
AL,
DZ,
AS,
AD,
AO,
AI,
AQ,
AG,
AR,
AM,
AW,
AU,
AT,
AZ,
BS,
BH,
BD,
BB,
BY,
BE,
BZ,
BJ,
BM,
BT,
BO,
BQ,
BA,
BW,
BV,
BR,
IO,
BN,
BG,
BF,
BI,
CV,
KH,
CM,
CA,
KY,
CF,
TD,
CL,
CN,
CX,
CC,
CO,
KM,
CG,
CD,
CK,
CR,
CI,
HR,
CU,
CW,
CY,
CZ,
DK,
DJ,
DM,
DO,
EC,
EG,
SZ,
GQ,
ER,
EE,
ET,
FK,
FO,
FJ,
FI,
FR,
GF,
PF,
TF,
GA,
GM,
GE,
DE,
GH,
GI,
GR,
GL,
GD,
GP,
GU,
GT,
GG,
GN,
GW,
GY,
HT,
HM,
VA,
HN,
HK,
HU,
IS,
IN,
ID,
IR,
IQ,
IE,
IM,
IL,
IT,
JM,
JP,
JE,
JO,
KZ,
KE,
KI,
KR,
KW,
KG,
LA,
LV,
LB,
LS,
LR,
LY,
LI,
LT,
LU,
MO,
MK,
MG,
MW,
MY,
MV,
ML,
MT,
MH,
MQ,
MR,
MU,
YT,
MX,
FM,
MD,
MC,
MN,
ME,
MS,
MA,
MZ,
MM,
NA,
NR,
NP,
NL,
NC,
NZ,
NI,
NE,
NG,
NU,
NF,
MP,
NO,
OM,
PK,
PW,
PS,
PA,
PG,
PY,
PE,
PH,
PN,
PL,
PT,
PR,
QA,
RE,
RO,
RU,
RW,
BL,
SH,
KN,
LC,
MF,
PM,
VC,
WS,
SM,
ST,
SA,
SN,
RS,
SC,
SL,
SG,
SX,
SK,
SI,
SB,
SO,
ZA,
GS,
SS,
ES,
LK,
SD,
SR,
SJ,
SE,
CH,
SY,
TW,
TJ,
TZ,
TH,
TL,
TG,
TK,
TO,
TT,
TN,
TR,
TM,
TC,
TV,
UG,
UA,
AE,
GB,
US,
UM,
UY,
UZ,
VU,
VE,
VN,
VG,
VI,
WF,
EH,
YE,
ZM,
ZW
​
country
enum<string>

The customer's country (MAX 2; MIN 2; ISO 3166-1 [blocked]).

Available options:
AF,
AX,
AL,
DZ,
AS,
AD,
AO,
AI,
AQ,
AG,
AR,
AM,
AW,
AU,
AT,
AZ,
BS,
BH,
BD,
BB,
BY,
BE,
BZ,
BJ,
BM,
BT,
BO,
BQ,
BA,
BW,
BV,
BR,
IO,
BN,
BG,
BF,
BI,
CV,
KH,
CM,
CA,
KY,
CF,
TD,
CL,
CN,
CX,
CC,
CO,
KM,
CG,
CD,
CK,
CR,
CI,
HR,
CU,
CW,
CY,
CZ,
DK,
DJ,
DM,
DO,
EC,
EG,
SZ,
GQ,
ER,
EE,
ET,
FK,
FO,
FJ,
FI,
FR,
GF,
PF,
TF,
GA,
GM,
GE,
DE,
GH,
GI,
GR,
GL,
GD,
GP,
GU,
GT,
GG,
GN,
GW,
GY,
HT,
HM,
VA,
HN,
HK,
HU,
IS,
IN,
ID,
IR,
IQ,
IE,
IM,
IL,
IT,
JM,
JP,
JE,
JO,
KZ,
KE,
KI,
KR,
KW,
KG,
LA,
LV,
LB,
LS,
LR,
LY,
LI,
LT,
LU,
MO,
MK,
MG,
MW,
MY,
MV,
ML,
MT,
MH,
MQ,
MR,
MU,
YT,
MX,
FM,
MD,
MC,
MN,
ME,
MS,
MA,
MZ,
MM,
NA,
NR,
NP,
NL,
NC,
NZ,
NI,
NE,
NG,
NU,
NF,
MP,
NO,
OM,
PK,
PW,
PS,
PA,
PG,
PY,
PE,
PH,
PN,
PL,
PT,
PR,
QA,
RE,
RO,
RU,
RW,
BL,
SH,
KN,
LC,
MF,
PM,
VC,
WS,
SM,
ST,
SA,
SN,
RS,
SC,
SL,
SG,
SX,
SK,
SI,
SB,
SO,
ZA,
GS,
SS,
ES,
LK,
SD,
SR,
SJ,
SE,
CH,
SY,
TW,
TJ,
TZ,
TH,
TL,
TG,
TK,
TO,
TT,
TN,
TR,
TM,
TC,
TV,
UG,
UA,
AE,
GB,
US,
UM,
UY,
UZ,
VU,
VE,
VN,
VG,
VI,
WF,
EH,
YE,
ZM,
ZW
​
document
object

Specifies the customer's document object, including its number and type. This object is not mandatory. However, if you send this information, the payment experience will be enhanced for your user.

​
phone
object

Specifies the customer's phone number object. This object is not mandatory. However, if you send this information, the payment experience will be enhanced for your user.

​
billing_address
object

Specifies the customer's billing address object. This object is not mandatory. However, if you send this information, the payment experience will be enhanced for your user.

​
shipping_address
object

Specifies the customer's shipping address object. This object is not mandatory. However, if you send this information, the payment experience will be enhanced for your user.

​
metadata
object[]

Specifies a list of metadata objects. You can add up to 50 metadata objects.

Response

201

​
id
string
Example:

"bf64527c-5531-4ece-bf2c-51a8e775d8e1"

​
merchant_customer_id
string
Example:

"AAAAAAAAAAAAAA0002"

​
first_name
string
Example:

"John"

​
last_name
string
Example:

"Doe"

​
gender
string
Example:

"M"

​
date_of_birth
string
Example:

"1990-02-28"

​
email
string
Example:

"john.doe@email.com"

​
nationality
string
Example:

"US"

​
country
string
Example:

"US"

​
document
object
​
phone
object
​
billing_address
object
​
shipping_address
object
​
metadata
object[]
​
created_at
string
Example:

"2025-04-24T18:54:54.351969Z"

​
updated_at
string
Example:

"2025-04-24T18:54:54.351971Z"

​
merchant_customer_created_at
string
Example:

"2022-05-09T20:46:54.786342Z"