Using Account Holder object, learn how to submit required documents and get your Partner Accounts verified

Start the onboarding process of your Partner Account by creating an Account Holder. Account Holder is an object that represents the legal entity of your Partner which constitutes legal information and legal documents so that Xendit can verify the legitimacy of the Accounts that you onboarded to your Platform.

Creating an Account Holder for your Partners may be required in either one or both of the following scenarios:

You are a platform / reseller merchant

This means that you onboard non-affiliated Partner accounts to Xendit and provide them with access to money-in and/or money out payment flows
Example: PoS systems, Payment Resellers, SaaS

You would like to activate a payment channel that requires an additional verification process to create credential for your Partner accounts

Example: Gcash, Cards UBP, Cards Maya

info

Account Holder is currently only compatible for owned account type

info

Account Holder is currently only available in the Philippines 🇵🇭

info

Account Holder is currently only available for Money-in capabilities: Gcash

Flow and Implementation

After you created an owned account, you will need to follow the steps below in order to complete your Partner's onboarding verification process:

1. Create Account Holder

Use the Platform account’s API key( with write API key permission for Account Holder and create Account Holder. You will need to fill in the required parameters according to your entity type. Upon successful creation, we will return account_holder_id

First, you will need to identify the entity type of your Partners, as the required documents will differ according to the entity type.

See entity type and full requirements here

Second, you will need to collect in the required information from your Partners which includes:

Legal name
Trading name
Buisness description
Industry category
Given names
Surname
Phone number
Email
Address
Website / social media URL

Next, you will also need to use upload file API in order to upload the documents you collected from your Partners to Xendit.
Lastly, you will need to collect these information from your Partners, and then forward them to Xendit via API using the Account Holder endpoint. See API reference.

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

Sample request payload for individual entity type

{
  "business_detail": {
    "type": "INDIVIDUAL",
    "legal_name": "test17",
    "trading_name": "test",
    "description": "testing",
    "industry_category": "ACCOMMODATION",
    "date_of_registration": "2023-02-02",
    "country_of_operation":"PH"
  },
  "individual_details": [
    {
      "given_names": "test",
      "surname": "test",
      "phone_number": "+63021234567",
      "email": "test@xendit.co",
      "nationality": "PH",
      "place_of_birth": "PH",
      "date_of_birth": "2000-02-02",
      "gender": "MALE"
    },
    {
      "given_names": "test",
      "surname": "test",
      "phone_number": "+63021234567",
      "email": "test@xendit.co",
      "nationality": "PH",
      "place_of_birth": "PH",
      "date_of_birth": "2000-02-02",
      "gender": "MALE"
    }
  ],
   "address": {
        "city": "test1",
        "country": "PH",
        "district": "test",
        "postal_code": "1111",
        "street_line1": "test",
        "street_line2": "test",
        "sub_district": "test",
        "province_state": "test"
    },
  "kyc_documents": [
        {
            "type": "SELFIE_WITH_PRIMARY_ID_DOCUMENT",
            "country": "PH",
            "file_id": "63f8719642f5856dcb142bd2"
        },
        {
            "type": "ACR_OR_IMMIGRANT_COR_DOCUMENT",
            "country": "PH",
            "file_id": "63f8719642f5856dcb142bd2"
        },
        {
            "type": "ADDITIONAL_PROOF_OF_BUSINESS_DOCUMENT",
            "country": "PH",
            "file_id": "63f8719642f5856dcb142bd2"
        }
    ],
  "website_url": "https://xendit.co",
  "phone_number": "+63281234567",
  "email": "test@xendit.co"
}

Sample request payload for sole proprietorship entity type

{
  "business_detail": {
    "type": "SOLE_PROPRIETORSHIP",
    "legal_name": "test17",
    "trading_name": "test",
    "description": "testing",
    "industry_category": "ACCOMMODATION",
    "date_of_registration": "2023-02-02",
    "country_of_operation":"PH"
  },
  "individual_details": [
    {
      "given_names": "test",
      "surname": "test",
      "phone_number": "+63021234567",
      "email": "test@xendit.co",
      "nationality": "PH",
      "place_of_birth": "PH",
      "date_of_birth": "2000-02-02",
      "gender": "MALE"
    },
    {
      "given_names": "test",
      "surname": "test",
      "phone_number": "+63021234567",
      "email": "test@xendit.co",
      "nationality": "PH",
      "place_of_birth": "PH",
      "date_of_birth": "2000-02-02",
      "gender": "MALE"
    }
  ],
   "address": {
        "city": "test1",
        "country": "PH",
        "district": "test",
        "postal_code": "1111",
        "street_line1": "test",
        "street_line2": "test",
        "sub_district": "test",
        "province_state": "test"
    },
  "kyc_documents": [
        {
            "type": "DTI_REGISTRATION_DOCUMENT",
            "country": "PH",
            "file_id": "63f8719642f5856dcb142bd2"
        },
        {
            "type": "ACR_OR_IMMIGRANT_COR_DOCUMENT",
            "country": "PH",
            "file_id": "63f8719642f5856dcb142bd2"
        },
        {
            "type": "ADDITIONAL_PROOF_OF_BUSINESS_DOCUMENT",
            "country": "PH",
            "file_id": "63f8719642f5856dcb142bd2"
        }
    ],
  "website_url": "https://xendit.co",
  "phone_number": "+63281234567",
  "email": "test@xendit.co"
}

Sample request payload for partnership entity type

{
  "business_detail": {
    "type": "PARTNERSHIP",
    "legal_name": "test17",
    "trading_name": "test",
    "description": "testing",
    "industry_category": "ACCOMMODATION",
    "date_of_registration": "2023-02-02",
    "country_of_operation":"PH"
  },
  "individual_details": [
    {
      "given_names": "test",
      "surname": "test",
      "phone_number": "+63021234567",
      "email": "test@xendit.co",
      "nationality": "PH",
      "place_of_birth": "PH",
      "date_of_birth": "2000-02-02",
      "gender": "MALE"
    },
    {
      "given_names": "test",
      "surname": "test",
      "phone_number": "+63021234567",
      "email": "test@xendit.co",
      "nationality": "PH",
      "place_of_birth": "PH",
      "date_of_birth": "2000-02-02",
      "gender": "MALE"
    }
  ],
   "address": {
        "city": "test1",
        "country": "PH",
        "district": "test",
        "postal_code": "1111",
        "street_line1": "test",
        "street_line2": "test",
        "sub_district": "test",
        "province_state": "test"
    },
  "kyc_documents": [
        {
            "type": "SEC_CERTIFICATE_REGISTRATION_DOCUMENT",
            "country": "PH",
            "file_id": "63f8719642f5856dcb142bd2"
        },
        {
            "type": "ARTICLES_OF_PARTNERSHIP_DOCUMENT",
            "country": "PH",
            "file_id": "63f8719642f5856dcb142bd2"
        },
        {
            "type": "NOTARIZED_PARTNER_CERTIFICATE_DOCUMENT",
            "country": "PH",
            "file_id": "63f8719642f5856dcb142bd2"
        },
        {
            "type": "ACR_OR_IMMIGRANT_COR_DOCUMENT",
            "country": "PH",
            "file_id": "63f8719642f5856dcb142bd2"
        },
        {
            "type": "ADDITIONAL_PROOF_OF_BUSINESS_DOCUMENT",
            "country": "PH",
            "file_id": "63f8719642f5856dcb142bd2"
        }
    ],
  "website_url": "https://xendit.co",
  "phone_number": "+63281234567",
  "email": "test@xendit.co"
}

Sample request payload for corporation entity type

{
  "business_detail": {
    "type": "CORPORATION",
    "legal_name": "test17",
    "trading_name": "test",
    "description": "testing",
    "industry_category": "ACCOMMODATION",
    "date_of_registration": "2023-02-02",
    "country_of_operation":"PH"
  },
  "individual_details": [
    {
      "given_names": "test",
      "surname": "test",
      "phone_number": "+63021234567",
      "email": "test@xendit.co",
      "nationality": "PH",
      "place_of_birth": "PH",
      "date_of_birth": "2000-02-02",
      "gender": "MALE"
    },
    {
      "given_names": "test",
      "surname": "test",
      "phone_number": "+63021234567",
      "email": "test@xendit.co",
      "nationality": "PH",
      "place_of_birth": "PH",
      "date_of_birth": "2000-02-02",
      "gender": "MALE"
    }
  ],
   "address": {
        "city": "test1",
        "country": "PH",
        "district": "test",
        "postal_code": "1111",
        "street_line1": "test",
        "street_line2": "test",
        "sub_district": "test",
        "province_state": "test"
    },
  "kyc_documents": [
        {
            "type": "SEC_CERTIFICATE_REGISTRATION_DOCUMENT",
            "country": "PH",
            "file_id": "63f8719642f5856dcb142bd2",
        },
        {
            "type": "ARTICLES_OF_INCORPORATION_DOCUMENT",
            "country": "PH",
            "file_id": "63f8719642f5856dcb142bd2"
        },
        {
            "type": "NOTARIZED_SECRETARY_CERTIFICATE_DOCUMENT",
            "country": "PH",
            "file_id": "63f8719642f5856dcb142bd2"
        },
        {
            "type": "LATEST_GIS_DOCUMENT",
            "country": "PH",
            "file_id": "63f8719642f5856dcb142bd2"
        },
        {
            "type": "ACR_OR_IMMIGRANT_COR_DOCUMENT",
            "country": "PH",
            "file_id": "63f8719642f5856dcb142bd2"
        },
        {
            "type": "ADDITIONAL_PROOF_OF_BUSINESS_DOCUMENT",
            "country": "PH",
            "file_id": "63f8719642f5856dcb142bd2"
        }
    ],
  "website_url": "https://xendit.co",
  "phone_number": "+63281234567",
  "email": "test@xendit.co"
}

2. Link Account Holder the Account

Use the Platform account’s API key with write API key permission for Accounts in order to link Account Holder to the Account.Once you’ve created your Account Holder, you will need to link the Account Holder to your Partner’s Account.

Using the update account endpoint, you will need to link the account_holder_id to a valid business_id that represents your Partner’s Account. You can do this by specifying the account_holder_id on the request body
Note that during this linking process, we will also start the verification process of this Account Holder. This will change the Know Your Customer (KYC) verification status from not_started to verification_in_progress

info

During verification process, you may not be able to update information in your Account Holder

PATCH https://api.xendit.co/v2/accounts

{
    "account_holder_id": "3bd4dcdd-e6c0-4057-89bf-58d1564b517b"
}

3. Request Capabilities to the Account

Once your account has passed verification and the Account Holder KYC status is passed, you can start requesting capabilities for your Accounts. You will be notified via webhook when KYC verification for your Accounts have been successful.

In order to do this, you will need to use the Update Account Holder endpoint and input the capabilities type and channel_code. See the document requirements for money-in capabilities

info

Account Holder is currently only available for Money-in capabilities: Gcash

PATCH https://api.xendit.co/account_holders

{
    "capabilities": [
        {
            "type": "MONEY_IN",
            "channel_code": "GCASH"
        }
    ]
}

4. Handling Account Holder Callbacks

You can also use the available webhook / callbacks and decide your systems’ response to each event.

Before you start, you will need to make sure that you have set your callback url for xenPlatform - Account Holder.
See guide to set your callback url from dashboard or API

The table below lists and describes the types of webhooks available

Webhook event	Trigger	Description
Accounts KYC verification passed `account_holder.kyc.status:passed`	When Xendit decides that Account Holder information is sufficient for Account to go live	Platform can use this event to notify their Partners that their Account has passed KYC verification from Xendit
Accounts KYC verification failed `account_holder.kyc.status:failed`	When Xendit decides that Account Holder does not have sufficient information for Account to go live	Platform an use this event to notify their Partners that their onboarding is declined by Xendit Platform can also use the `failure_reason` to notify their Partners the reason why their submission is failed
Accounts KYC needs documents resubmission `account_holder.kyc.status:resubmission_required`	When Xendit requires additional documents so that Platform can resubmit the correct onboarding information	Platform can use this event to notify their Partners that their onboarding information is invalid and needs document resubmission We will also notify Platform via webhook and and specify the invalid fields so that Partners can update the invalid fields with the right information
Capabilities has been activated `account_holder.capabilities.status:live`	When capabilities has been activated for the Account	Platform can use this event to notify their Partners that the requested capabilities or payment channel have been activated for the Partner’s Account
Capabilities activation request has been declined `account_holder.capabilities.status:declined`	When capabilities has been declined for the Account and Platform can no longer resubmit	Platform an use this event to notify their Partners that their activation request is declined by Xendit Platform can also use the `failure_reason` to notify their Partners the reason why their submission is declined
Capabilities activation needs documents resubmission `account_holder.capabilities.status:resubmission_required`	When Xendit request additional documents so that Platform can resubmit the correct information to activate certain capabilities	Platform can use this event to notify their Partners that their information is invalid and needs resubmission Platform can also use the invalid fields specified in the webhook eventso that Partners can update the invalid fields accordingly

5. Update Account Holder

Use the Platform account’s API key with write API key permission for Account Holder in order to use the Update Account Holder endpoint.

You may be required to Update Account Holder information via API in case you are prompted to revise your document submission. Some examples would be due to: invalid ID, blurry documents, invalid website etc.

You will receive Account Holder webhook notification that will give you specific information to update the Account Holder accordingly
Update Account Holder with the right information or documents as specified in the callback

Sample callback payload

{
    "created": "2021-01-01T10:00:00Z",
    "event": "account_holder.kyc.status",
    "business_id": "5fe2b0137b7d62542fe6d7de",
    "data": {
        "id": "57fb4e076fa3fa296b7f5a97",
        "created": "2021-01-01T10:00:00Z",
        "updated": "2021-01-01T10:00:00Z",
        "kyc: {
            "status": "RESUBMISSION_REQUIRED",
            "verified_at": "2021-01-01T10:00:00Z",
            "requested_at": "2021-01-01T10:00:00Z",
            "failure_reasons": [
                {
                    "field": "website_url",
                    "message": "Website is Invalid"
                }
            ]
        }
    }
}

Sample update Account Holder request

PATCH https://api.xendit.co/account_holders

{
    "website_url": "louisa-marketplace.xendit.com"
}

Next steps

Congratulations! You have now successfully completed account verification and activate capabilities, learn more about managing their payments below:

Accepting payments
Managing funds via Transfers or Platform fee
Paying out
Invite Partners to access the Dashboard

Was this page helpful?

info

info

info

Flow and Implementation​

1. Create Account Holder​

2. Link Account Holder the Account​

info

3. Request Capabilities to the Account​

info

4. Handling Account Holder Callbacks​

5. Update Account Holder​

Next steps​

Flow and Implementation

1. Create Account Holder

2. Link Account Holder the Account

3. Request Capabilities to the Account

4. Handling Account Holder Callbacks

5. Update Account Holder

Next steps