NAV undefined
bash php javascript java go python

2020-10-31

Create Customer

Make a POST request to this endpoint to create a customer for later use with a payments endpoint.

Endpoint: Create Customer

POST https://api.xendit.co/customers

Version

You are currently viewing API version 2020-10-31. Click here to view older versions.

Version Changelog
2020-10-31 (Latest) Update to support BUSINESS type customers and generic identity accounts
2020-05-19 Original version

Request Parameters

Example Create Customer Request

curl https://api.xendit.co/customers -X POST \
   -u xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==: \
   -H 'Content-Type: application/json'
   --data-raw '{
     "reference_id": "demo_1475801962607",
     "type": "INDIVIDUAL",
     "individual_detail": {
       "given_names": "John",
       "surname": "Doe"
     },
     "email": "customer@website.com",
     "mobile_number": "+628121234567890"
     }'
<?php
  $url = "https://api.xendit.co/customers";
  $apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:";
  $headers = [];
  $headers[] = "Content-Type: application/json";
  $data = [
    "reference_id" => "demo_1475801962607",
    "type" => "INDIVIDUAL",
    "individual_detail" => [
       "given_names" => "John",
       "surname" => "Doe"
    ],
    "email" => "customer@website.com",
    "mobile_number" => "+628121234567890"
  ];

  $curl = curl_init();

  $payload = json_encode($data);
  curl_setopt($curl, CURLOPT_HTTPHEADER, $headers);
  curl_setopt($curl, CURLOPT_USERPWD, $apiKey.":");
  curl_setopt($curl, CURLOPT_URL, $url);
  curl_setopt($curl, CURLOPT_POST, true);
  curl_setopt($curl, CURLOPT_POSTFIELDS, $payload);
  curl_setopt($curl, CURLOPT_RETURNTRANSFER, true);

  $result = curl_exec($curl);
  echo $result;
let apiKey = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:";
let url = "https://api.xendit.co/customers";

var headers = new Headers();
headers.append("Authorization", "Basic " + btoa(apiKey + ":"));
headers.append("Content-Type", "application/json");

var reqBody = JSON.stringify({
  "reference_id": "demo_1475801962607",
  "type": "INDIVIDUAL",
  "individual_detail": {
    "given_names": "John",
    "surname": "Doe"
  },
  "email": "customer@website.com",
  "mobile_number": "+628121234567890"});

var requestOptions = {
  method: 'POST',
  headers: headers,
  body: reqBody,
  redirect: 'follow'
};

fetch(url, requestOptions)
  .then(response => response.text())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));
import requests
import base64

api_key = "xnd_development_O46JfOtygef9kMNsK+ZPGT+ZZ9b3ooF4w3Dn+R1k+2fT/7GlCAN3jg==:"
url = "https://api.xendit.co/customers"

api_key_bytes = api_key.encode('ascii')
base64_bytes = base64.b64encode(api_key_bytes)
base64_token = base64_bytes.decode('ascii')

payload = {
  "reference_id": "demo_1475801962607",
  "type": "INDIVIDUAL",
  "individual_detail": {
    "given_names": "John",
    "surname": "Doe"
  },
  "email": "customer@website.com",
  "mobile_number": "+628121234567890"
}
auth_token = 'Basic ' + base64_token
headers = {
  'Authorization': auth_token
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)
Header Parameter Type Description
IDEMPOTENCY-KEY
optional
string A unique key to prevent processing duplicate requests. Can be your reference_id or any GUID. Must be unique across development & production environments. Idempotency keys are stored on the request layer; it expires after 24 hours from the first request.

Characters Special and alphanumeric
Maximum length 100 characters
Minimum length 1 character
API-VERSION
optional
string API version in date semantic (e.g. 2020-10-31). Attach this parameter when calling a specific API version. List of API versions can be found here.
Body Parameter Type Description
reference_id
required
string Merchant-provided identifier for the customer.
Requests with a duplicate reference_id will return an error. You should PATCH the customer object resource instead.

Maximum length 255 characters
type
optional
string Type of customer.
Supported values: INDIVIDUAL, BUSINESS
Defaults to INDIVIDUAL if not provided.
individual_detail
conditionally required
object JSON object containing details of the individual. Required if type is INDIVIDUAL
Individual detail child parameters
given_names
required
string Primary or first name/s of customer
surname
optional
string Last or family name of customer
nationality
optional
string Country code for customer's nationality

Format ISO 3166-2 Country Code
place_of_birth
optional
string City or other relevant location for the customer’s birth place
date_of_birth
optional
string Date of birth of the customer

Format YYYY-MM-DD string
gender
optional
string Gender of customer. Supported values: MALE,
FEMALE,
OTHER
employment
optional
string Name of account holder as per the account provider
employer_name
optional
string Name of the employer
nature_of_business
optional
string Industry or nature of business
role_description
optional
string Occupation or title
business_detail
conditionally required
object JSON object containing details of the business. Required if type is BUSINESS
Business detail child parameters
business_name
required
string Name of business. Required if type is BUSINESS
business_type
required
string Legal entity type of the business
Supported values: CORPORATION,
SOLE_PROPRIETOR,
PARTNERSHIP,
COOPERATIVE,
TRUST,
NON_PROFIT,
GOVERNMENT
nature_of_business
optional
string Free text description of the type of business this entity pursues. Examples are: Ecommerce, Travel
business_domicile
optional
string Registered country of the business

Format ISO 3166-2 Country Code
date_of_registration
optional
string Business registration date

Format YYYY-MM-DD string
mobile_number
optional
string Mobile number of customer in E.164 format

Maximum length 50 characters
phone_number
optional
string Additional contact number of customer in E.164 format. May be a landline

Maximum length 50 characters
FormatE.164 international standard +(country code)(subscriber number)
email
optional
string E-mail address of customer

Maximum length 255 characters
addresses
optional
array Array of address JSON objects containing the customer's various address information.
Addresses child parameters
Field Description
country
required
string Country of residence of customer

Format ISO 3166-2 Country Code
street_line1
optional
string Line 1 of street address e.g., building name and apartment number

Maximum length 255 characters
street_line2
optional
string Line 2 of street address e.g., street number and name

Maximum length 255 characters
city
optional
string City, village or town of residence of customer

Maximum length 255 characters
province_state
optional
string Province, state or region of residence of customer

Maximum length 255 characters
postal_code
optional
string ZIP/Postal Code of customer

Maximum length 255 characters
category
optional
string Address type. Supported values: HOME,
WORK,
PROVINCIAL
is_primary
optional
boolean Defaults to false. Indicates that the information provided refers to the customer’s primary address
identity_accounts
optional
array Array of JSON objects with information relating to financial, social media or other accounts associated with the customer. This array can store details for KYC purposes and can support storing of account details for execution of payments within the Xendit API ecosystem.
Identity accounts child parameters
Field Description
country
required
string Issuing country of the account

Format ISO 3166-2 Country Code
type
required
string The account type. Supported values: BANK_ACCOUNT,
EWALLET,
CREDIT_CARD,
PAY_LATER,
OTC,
QR_CODE,
SOCIAL_MEDIA
company
optional
string The issuing institution associated with the account (e.g., OCBC, GOPAY, 7-11). If adding financial accounts that Xendit supports, we recommend you use the channel_code for this field

Maximum length 100 characters
description
optional
string Free text description for the account

Maximum length 255 characters
country
optional
string Issuing country for the account, if relevant

Format ISO 3166-2 Country Code
properties
optional
string JSON object with any account-specific content as required e.g.,

For BANK_ACCOUNT types:
Bank account parameters
account_number
required
string Unique account identifier as per the bank records
account_holder_name
required
string Name of account holder as per the bank records. Should match the registered account name exactly
swift_code
optional
string The swift code for international payments
account_type
optional
string Free text account type, e.g., Savings, Transaction, Virtual Account
account_details
optional
string Potentially masked account detail, for display purposes only
currency
optional
string Primary currency of the account, if relevant.

Format ISO 4217 Currency Code

For EWALLET types:
eWallet parameters
account_number
required
string Unique account identifier as per the ewallet records
account_holder_name
optional
string Name of account holder as per the ewallet records. Should match the registered account name exactly
currency
optional
string Primary currency of the account, if relevant.

Format ISO 4217 Currency Code

For CREDIT_CARD types:
Credit card parameters
token_id
required
string The token id returned in tokenisation

For OTC types:
Over The Counter parameters
payment_code
required
string Complete fixed payment code (including prefix)
expires_at
optional
string Expiry date for the payment code

Format YYYY-MM-DD string

For QR_CODE types:
QR code parameters
qr_string
required
string String representation of the unique QR code

For PAY_LATER types:
Pay later parameters
account_id
required
string Alphanumeric string identifying this account. Usually an email address or phone number
account_holder_name
optional
string Name of account holder as per the account provider
currency
optional
string Primary currency of the account, if relevant.

Format ISO 4217 Currency Code

For SOCAL_MEDIA types:
Social media parameters
account_id
required
string Alphanumeric string identifying this account. Usually an email address or phone number
account_handle
optional
string Name of account as per the account provider
kyc_documents
optional
array Array of JSON objects with documents collected for KYC of this customer.
KYC documents child parameters
Field Description
country
required
string Issuing country of the document

Format ISO 3166-2 Country Code
type
required
string Generic ID type
Supported values: BIRTH_CERTIFICATE,
BANK_STATEMENT,
DRIVING_LICENSE,
IDENTITY_CARD,
PASSPORT,
VISA,
BUSINESS_REGISTRATION,
BUSINESS_LICENSE
sub_type
optional
string Specific ID type for IDENTITY_CARD types.
Supported values: NATIONAL_ID,
CONSULAR_ID,
VOTER_ID,
POSTAL_ID,
RESIDENCE_PERMIT,
TAX_ID,
STUDENT_ID,
MILITARY_ID,
MEDICAL_ID
document_name
optional
string Free text description of the type of document (e.g., NIB, SIUP, AKTA)

Maximum length 255 characters
document_number
optional
string Unique alphanumeric identity document number or code

Maximum length 255 characters
expires_at
optional
string Expiry date, if relevant.

Format YYYY-MM-DD string
holder_name
optional
string Free text to capture the full name(s) of the individual or business as defined on the document, if relevant

Maximum length 255 characters
document_images
optional
string[] Array of file ids returned from uploads to the files endpoint, representing images of the front/back of the document, in png/jpg/jpeg/pdf format
description
optional
string Merchant-provided description for the customer.

Maximum length 500 characters
metadata
optional
object Object of additional information related to the customer. Define the JSON properties and values as required to pass information through the APIs.
You can specify up to 50 keys, with key names up to 40 characters long and values up to 500 characters long.
This is only for your use and will not be used by Xendit.

Response Parameters

Success responses will contain a single Customer Object

Error Codes

See other common errors here.

Error Code Description
DUPLICATE_ERROR
409
The provided reference_id has been used before. Please enter a unique reference_id.
IDEMPOTENCY_ERROR
409
Provided Idempotency-key already exists but the request body provided does not match the original request

Changelog

Version 2020-10-31

Update to support BUSINESS type customers and generic identity accounts

Version 2020-05-19

Original version