Create Customer

Introduction

Create a customer

The customer object represents a customer of your business. It lets you create recurring payments and track payments that belong to the same customer.

Interface

POST /v1/customers

Request Params

Field	Name	Type	Range	Example	Default	Optional	Remark	Rule
reference	Reference	string	[1, 64]	2022123	optional	Refer to merchant side's customer ID, see Unique Reference Mode
first_name	First Name	string	[1,64]	David	optional	First name(and middle name if exists) of customer
last_name	Last Name	string	[1,64]	Smith	optional	Last name of customer
company	Company	string	[1,64]	company name	optional	Customer's company
description	Description	string		company description	optional			yyyy-mm-dd
birth_date	Birth Date	string			optional	Customer's birth date
email	Email	string			optional	Email of customer		E.164
phone	Phone	string			optional	Phone of customer
country	Country	string			optional	Customer's country		ISO 3166 alpha-2
address	Residential Address	hash	-	optional		Customer's residential address, see more on Address
billing_address	Billing Address	hash	-	optional		Customer's billing address, see more on Address
document	Document	hash	-	optional

address

Field	Name	Type	Range	Example	Default	Optional	Remark	Rule
country	Country	string	[1, 64]	US	required	Country for address, in ISO 3166 alpha-2 format
state	State	string	[1, 64]	Washington DC	required	Also called as province in some country
city	City name	string	[1, 64]	Washington	required
line1	Line 1	string	[1, 64]		required	detail address 1
line2	Line 2	string	[1, 64]		optional	detail address 2
postal_code	Postal code	string	[1, 64]		optional	Also called as zip code in some country

billing_address

same as address

document

Field	Name	Type	Range	Example	Default	Optional	Remark	Rule
country	Country	string	[1, 64]	US	required	Country for address, in ISO 3166 alpha-2 format
type	Type	string	enum		required	national_id, passport, driving_license, business_license, tax_id
number	Number	string	enum		required	Document number

Response Params

Response Example

200 success:

{
  "id": "cst_un9WL8ervLWDqTGW",
  "object": "customer",
  "account": "acct_yz50aD",
  "time_created": "2022-07-15T14:00:46+08:00",
  "livemode": true,
  "reference": "2022000000000",
  "first_name": "David",
  "last_name": "Smith",
  "company": "comany name",
  "country": null,
  "description": "company description",
  "birth_date": "2020-01-01",
  "email": "test@company.com",
  "phone": "+8613000000000",
  "address": {
    "country": "US",
    "state": "Washington DC",
    "city": "Washington",
    "line1": "detail address 1",
    "line2": "detail address 2",
    "postal_code": "200000",
    "time_created": "2022-07-15T14:00:46+08:00"
  },
  "deleted": false
}

400 error:

{
  "error": {
    "type": "invalid_request_error",
    "message": "reference duplicated: 2022050500002",
    "code": "request_param_error"
  }
}

For some payment methods, specific fields are mandatory, if your customer's payment is possible to be initiated with these payment methods, be sure to pass these fields beforehand.

Payment Method	Required Field
ovo_id	customer.phone
boleto_br	customer.document, customer.billing_address