With the new Accounts API V3, there are some key concepts that have changed as compared to the previous V2 Accounts API.
Key changes
The below list highlights the key changes from the previous version
The V3 API is also constantly update and we will update the main documentation when we make changes and additions to the resource.
Area | Legacy (V2) | Accounts API (V3) |
|---|---|---|
Endpoint |
|
|
Sub-account type |
| - |
Sub-account name |
|
|
Sub-account e-mail |
|
|
Legal identity | - |
|
Settings |
|
|
Webhook recipient values |
|
|
Response |
|
|
Account statuses |
| Adds |
KYC status updates | Account status webhooks ( |
|
Submitting KYC by API |
| Only via the Xendit Dashboard |
The API key you call with decides which master account the sub-account links to. It needs the Account Write permission.
Request example
Legacy (V2):
POST /v2/accounts
{
"email": "owner@tokoberkah.co.id",
"type": "MANAGED",
"public_profile": { "business_name": "Toko Berkah" }
}Accounts API (V3):
POST /v3/accounts
{
"name": "Toko Berkah",
"email": "owner@tokoberkah.co.id",
"identity": {
"country_of_incorporation": "ID",
"entity_type": "INDIVIDUAL"
},
"configuration": {
"users": { "send_email_invite": true },
"webhooks": { "recipient": "SUB_ACCOUNT" }
}
}A successful V3 call returns the sub-account with status REGISTERED.
Accepted entity types
The entity_type you send must be valid for the country. Any country not listed follows the Singapore list.
Country | Entity types |
|---|---|
Indonesia (ID) |
|
Philippines (PH) |
|
Vietnam (VN) |
|
Thailand (TH) |
|
Malaysia (MY) |
|
Singapore (SG) |
|
Hong Kong (HK) |
|
Mexico (MX) |
|
An invalid combination returns 400 INVALID_DATA_PROVIDED. If you set the wrong entity type, create a new sub-account with the correct one.
Behavioural changes
Behaviour | Legacy (V2) | Accounts API (V3) | What to do |
|---|---|---|---|
Webhook routing | Managed sub-account events go to the sub-account's own webhook URLs | Events go to the master account's URLs unless you set | Set |
Owner invitation | Managed sub-accounts get an invitation email automatically | No email is sent unless | Set it to |
Ready to transact | Wait for the | The sub-account starts at | Wait for |
Resubmission | No field-level detail |
| Show the reasons to the sub-merchant and collect only what's listed |
Missed webhooks | Varies by event | No resend for | Poll the Retrieve account verification API as a fallback |
Webhook delivery logs | Shown on the account the URL belongs to | Shown on the sub-account's dashboard, even when routed to the master URL | Check the sub-account's dashboard when debugging |
Country | Sub-accounts in your supported markets |
| Speak to your Account Manager before creating sub-accounts in another country |
Payment channels | Owned sub-accounts inherit the master's channels | Each sub-account activates its own channels | Plan channel activation into your onboarding flow |
Moving funds between accounts | In-house transfers available | Paused from 1 February 2027 | Use split rules at payment time instead of moving balances afterwards |
Test mode | Owned or Managed test sub-accounts |
| Test other entity types in Live mode with a real sub-merchant |
The verification webhook
Set the Account Verification Status webhook URL on your master account. Each event looks like this:
{
"event": "account.verification",
"business_id": "<master account ID>",
"data": {
"id": "<sub-account ID>",
"kyc": {
"status": "AWAITING_RESUBMISSION",
"failure_reasons": [
{
"field": "authorized_person_selfie_document",
"reason": "BLURRY_IMAGE",
"message": "This document is blurry."
}
]
}
}
}kyc.status is one of VERIFICATION_IN_PROGRESS, PASSED, AWAITING_RESUBMISSION or FAILED. reason is one of NEW_DOCUMENT, WRONG_DOCUMENT, NEW_INFORMATION or BLURRY_IMAGE. If no URL is set, events aren't delivered.
Migration steps
Give your API key the Account Write permission.
Set the Account Verification Status webhook URL on your master account and build a handler for
account.verification.Map your sub-merchant records to
identity.country_of_incorporationandidentity.entity_type.Switch sub-account creation to
POST /v3/accounts, settingconfiguration.users.send_email_inviteandconfiguration.webhooks.recipientexplicitly.Gate live payments on
kyc.status=PASSED, and handleAWAITING_RESUBMISSIONandFAILED.Re-create split rules with the Create split rule API.
Test in Test mode, then run one real sub-merchant end to end in Live mode before switching all traffic.
Reference: Create account (V3), Account verification webhook, Create account (V2, legacy).