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