2020-10-31

Customer Object

The Customer Object is a standard data structure to hold information relating to one of your customers. It has the following major components:

• A Type of customer (Individual or Business)
• Basic descriptive details of that customer
• Addresses of the customer
• Identity accounts and KYC documents to prove the legitimacy of the customer
• Other metadata

When one (or more) customers is returned by endpoints in this section, the response body will contain a Customer Object (or an array of Customer Objects). Each object has the following structure:

Example Customer Object - Individual

{
    "id": "cust-239c16f4-866d-43e8-9341-7badafbc019f",
    "reference_id": "demo_1475801962607",
    "type": "INDIVIDUAL",
    "individual_detail": {
        "given_names": "John",
        "surname": "Doe",
        "nationality": "ID",
        "place_of_birth": "Jakarta",
        "date_of_birth": "1980-01-01",
        "gender": "MALE",
        "employment": {
            "employer_name": "Xendit",
            "nature_of_business": "Payment Gateway",
            "role_description": "Test dummy"
        }
    },
    "business_detail": null,
    "email": "customer@website.com",
    "mobile_number": "+628121234567890",
    "phone_number": "+628121234567890",
    "addresses": [{
        "street_line1": "Panglima Polim IV",
        "street_line2": "Ruko Grand Panglima Polim, Blok E",
        "city": "Jakarta Selatan",
        "province_state": "DKI Jakarta",
        "postal_code": "993448",
        "country": "ID",
        "category": "HOME",
        "is_primary": true
    }],
    "identity_accounts": [{
        "type": "CREDIT_CARD",
        "company": "OCBC",
        "description": "My account",
        "country": "ID",
        "properties":{
            "token_id": "586f0ba2ab70de5d2b409e0d"
        }
    }],
    "kyc_documents": [{
        "type": "IDENTITY_CARD",
        "sub_type": "NATIONAL_ID",
        "country": "ID",
        "document_name": "KTP",
        "document_number": "12356789012456",
        "expires_at": null,
        "holder_name": "John Doe",
        "document_images": [
            "file-ec700c1c-db17-4496-b1fb-04ebe551b412"
        ]
    }],
    "description": "My first customer",
    "metadata": {
        "foo": "bar"
    },
    "created": "2020-03-30T06:12:47.212Z",
    "updated": "2020-03-30T06:12:47.212Z"
}

Example Customer Object - Business

{
    "id": "cust-239c16f4-866d-43e8-9341-7badafbc019f",
    "reference_id": "demo_1475801962607",
    "type": "BUSINESS",
    "individual_detail": null,
    "business_detail": {
        "business_name": "ACME Corp",
        "business_type": "CORPORATION",
        "nature_of_business": null,
        "business_domicile": null,
        "date_of_registration": null
    },
    "email": "customer@website.com",
    "mobile_number": null,
    "phone_number": null,
    "addresses": [],
    "identity_accounts": [],
    "kyc_documents": [],
    "description": null,
    "metadata": null,
    "created": "2020-03-30T06:12:47.212Z",
    "updated": "2020-03-30T06:12:47.212Z"
}

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

Body Parameter	Type	Description
id	string	Xendit-generated Customer ID. Will start with cust-...
reference_id required	string	Merchant-provided identifier for the customer
type required	string	Type of customer. Supported values: INDIVIDUAL, BUSINESS Defaults to INDIVIDUAL if not provided in customer creation.
individual_detail optional	object	JSON object containing details of the individual. Will be null if type is not 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 optional	object	JSON object containing details of the business. Will be null if type is not BUSINESS Business detail child parameters business_name required string Name of 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 required	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 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 required	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 required 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 as provided in customer creation
created required	string	Timestamp of customer creation in ISO format
updated required	string	Timestamp of customer update in ISO format

Changelog

Version 2020-10-31

Update to support BUSINESS type customers and generic identity accounts

Version 2020-05-19

Original version