Welcome to Xendit’s latest documentation. For legacy content, access the previous documentation here or the previous API reference here.

Create Account

Prev Next

Post

/v2/accounts

Create Account API allows you to create Accounts for your Partners on your Platform. Once an Account is created, you can accept and route payments through the Transfers API or Platform Fee API.

If you do not want to configure a pre-specified type of account (Managed or Owned), you can also choose to configure the account yourself using the configurations parameter below, instead of specifying a type. Remember to store the returned account id value to make transactions for that Account in the future.

Note: For the /v2/accounts endpoint, we allow a maximum of 5 write requests per second. Please contact help@xendit.co if you require a higher load.

Emails that are used to create Accounts with a Test API key, cannot be re-used to create Accounts with a Live API key

Version

This version of the API is asynchronous to improve performance and scalability. We have also added API permissions in this version. If you are using an existing API key, please edit your permissions in your Settings page.

It is mandatory to wait for the account.created callback before attempting to create transactions. Set a Callback URL in your Dashboard to receive Account Updated Callbacks and know when payments can be processed for your Accounts.

Use API key permission Account Write to perform this request

Account Suspension Callbacks

The Account Suspension webhook can be used to let your system know when Xendit has suspected, suspended or cleared the Accounts linked to your Platform. Our teams and systems automatically and regularly review Account behaviour to help Platforms mitigate potential fraud.

These events may occur if we have reason to believe that the Account has engaged in fraudulent activity. When these events occur, only the transactions occurring on that specific Account will be affected. This approach allows your Platform to continue accepting payments for your other Accounts normally.

Security

HTTP

Type basic

Body parameters

Owned

{
  "email": "angie@pinkpanther.com",
  "type": "OWNED",
  "public_profile": {
    "business_name": "Angie lemonade stand"
  }
}

Expand All

object

string (email) Required

A valid email address associated with the object

Max length255

Exampletest@example.co

type

string

The type of account created

Valid values[ "MANAGED", "OWNED", "CUSTOM" ]

public_profile

object (xenPlatform_public_profile)

name

string

Public name of the account.

description

string

Additional description visible publicly.

configurations

object (xenPlatform_configurations)

Contains the configurations for CUSTOM sub-accounts. Parameters available: payment_settings_follow_platform, has_withdrawal, has_dashboard

payment_settings_follow_platform

boolean

Indicates if payment settings follow the platform.

has_withdrawal

boolean

Indicates if the account has withdrawal enabled.

has_dashboard

boolean

Indicates if the account has access to the dashboard.

Responses

200

Owned Sub-account

{
  "id": "5cafeb170a2b18519b1b8761",
  "created": "2021-01-01T10:00:00Z",
  "updated": "2021-01-01T10:00:00Z",
  "type": "OWNED",
  "email": "angie@pinkpanther.com",
  "public_profile": {
    "business_name": "Angie's lemonade stand"
  },
  "status": "LIVE"
}

Custom Sub-account

{
  "id": "5cafeb170a2b18519b1b8761",
  "created": "2021-01-01T10:00:00Z",
  "updated": "2021-01-01T10:00:00Z",
  "type": "CUSTOM",
  "email": "angie@pinkpanther.com",
  "public_profile": {
    "business_name": "Angie's customized stand"
  },
  "status": "LIVE",
  "configurations": {
    "has_dashboard": true,
    "payment_settings_follow_platform": true,
    "has_withdrawal": false
  }
}

Expand All

object

string

ID of your Account, use this in the for-user-id header to create transactions on behalf of your Account

created

string

Timestamp of when the object was created

updated

string

Timestamp of when the object was updated

type

string

The type of account created

Valid values[ "MANAGED", "OWNED", "CUSTOM" ]

string (email)

A valid email address associated with the object

Max length255

Exampletest@example.co

public_profile

object (xenPlatform_public_profile)

name

string

Public name of the account.

description

string

Additional description visible publicly.

country

string

The country (based on ISO 3166-1 Alpha-2) of incorporation for a business, or the country of residence for an individual.

Valid values[ "ID", "PH", "VN", "MY", "TH" ]

status

string

Status of the Account you are creating.

Valid values[ "INVITED", "REGISTERED", "AWAITING_DOCS", "LIVE", "SUSPENDED" ]

configurations

object (xenPlatform_configurations)

Contains the configurations for CUSTOM sub-accounts. Parameters available: payment_settings_follow_platform, has_withdrawal, has_dashboard

payment_settings_follow_platform

boolean

Indicates if payment settings follow the platform.

has_withdrawal

boolean

Indicates if the account has withdrawal enabled.

has_dashboard

boolean

Indicates if the account has access to the dashboard.

400

Validation errors for creating accounts

OneOf

xenPlatform_400ApiValidationError

object (xenPlatform_400ApiValidationError)

error_code

string

ExampleAPI_VALIDATION_ERROR

error_message

string

ExampleInputs are failing validation. The errors field contains details about which fields are violating validation.

xenPlatform_400InvalidConfigurationError

object (xenPlatform_400InvalidConfigurationError)

error_code

string

ExampleINVALID_CONFIGURATION

error_message

string

ExampleThe `configurations` parameter combination is invalid. Please follow the requirement of each parameter written in Request section.

xenPlatform_400TypeConfigConflictError

object (xenPlatform_400TypeConfigConflictError)

error_code

string

ExampleTYPE_AND_CONFIGURATION_CONFLICT

error_message

string

ExamplePlease provide either one of the `type` field or the `configurations` field

Callbacks

Post

/{account_created_callback_url}

Body parameters

{
  "event": "account.created",
  "created": "2021-01-01T10:00:00Z",
  "data": {
    "id": "5cafeb170a2b18519b1b8761",
    "created": "2021-01-01T10:00:00Z",
    "updated": "2021-01-01T10:00:00Z",
    "type": "OWNED",
    "email": "test@xendit.co",
    "public_profile": {
      "business_name": "My Store"
    },
    "country": "ID",
    "status": "LIVE"
  }
}

Expand All

object

event

string

Your OWNED sub-account has been successfully created

Valid values[ "account.created" ]

Exampleaccount.created

business_id

string

ID of your Account, use this in the for-user-id header to create transactions on behalf of your Account

created

string

Timestamp of when the webhook was sent

updated

string

Timestamp of when the webhook was updated

data

object (xenPlatform_CreateAccountResponseSchema)

string

ID of your Account, use this in the for-user-id header to create transactions on behalf of your Account

created

string

Timestamp of when the object was created

updated

string

Timestamp of when the object was updated

type

string

The type of account created

Valid values[ "MANAGED", "OWNED", "CUSTOM" ]

string (email)

A valid email address associated with the object

Max length255

Exampletest@example.co

public_profile

object (xenPlatform_public_profile)

name

string

Public name of the account.

description

string

Additional description visible publicly.

country

string

The country (based on ISO 3166-1 Alpha-2) of incorporation for a business, or the country of residence for an individual.

Valid values[ "ID", "PH", "VN", "MY", "TH" ]

status

string

Status of the Account you are creating.

Valid values[ "INVITED", "REGISTERED", "AWAITING_DOCS", "LIVE", "SUSPENDED" ]

configurations

object (xenPlatform_configurations)

Contains the configurations for CUSTOM sub-accounts. Parameters available: payment_settings_follow_platform, has_withdrawal, has_dashboard

payment_settings_follow_platform

boolean

Indicates if payment settings follow the platform.

has_withdrawal

boolean

Indicates if the account has withdrawal enabled.

has_dashboard

boolean

Indicates if the account has access to the dashboard.

Responses

200

Post

/{account_updated_callback_url}

Body parameters

{
  "event": "account.updated",
  "created": "2021-01-01T10:00:00Z",
  "data": {
    "id": "5cafeb170a2b18519b1b8761",
    "created": "2021-01-01T10:00:00Z",
    "updated": "2021-01-01T10:00:00Z",
    "type": "MANAGED",
    "email": "test@xendit.co",
    "public_profile": {
      "business_name": "My Store"
    },
    "country": "ID",
    "status": "LIVE"
  }
}

Expand All

object

event

string

Your MANAGED sub-account have successfully registered and enabled for live payments

Valid values[ "account.updated" ]

Exampleaccount.updated

business_id

string

ID of your Account, use this in the for-user-id header to create transactions on behalf of your Account

created

string

Timestamp of when the webhook was sent

updated

string

Timestamp of when the webhook was updated

data

object (xenPlatform_CreateAccountResponseSchema)

string

ID of your Account, use this in the for-user-id header to create transactions on behalf of your Account

created

string

Timestamp of when the object was created

updated

string

Timestamp of when the object was updated

type

string

The type of account created

Valid values[ "MANAGED", "OWNED", "CUSTOM" ]

string (email)

A valid email address associated with the object

Max length255

Exampletest@example.co

public_profile

object (xenPlatform_public_profile)

name

string

Public name of the account.

description

string

Additional description visible publicly.

country

string

The country (based on ISO 3166-1 Alpha-2) of incorporation for a business, or the country of residence for an individual.

Valid values[ "ID", "PH", "VN", "MY", "TH" ]

status

string

Status of the Account you are creating.

Valid values[ "INVITED", "REGISTERED", "AWAITING_DOCS", "LIVE", "SUSPENDED" ]

configurations

object (xenPlatform_configurations)

Contains the configurations for CUSTOM sub-accounts. Parameters available: payment_settings_follow_platform, has_withdrawal, has_dashboard

payment_settings_follow_platform

boolean

Indicates if payment settings follow the platform.

has_withdrawal

boolean

Indicates if the account has withdrawal enabled.

has_dashboard

boolean

Indicates if the account has access to the dashboard.

Responses

200

Post

/{account_status_callback_url}

Body parameters

{
  "event": "account.updated",
  "created": "2021-01-01T10:00:00Z",
  "data": {
    "id": "5cafeb170a2b18519b1b8761",
    "created": "2021-01-01T10:00:00Z",
    "updated": "2021-01-01T10:00:00Z",
    "type": "MANAGED",
    "email": "test@xendit.co",
    "public_profile": {
      "business_name": "My Store"
    },
    "status": "SUSPENDED",
    "reason": "FRAUD_PROMO_ABUSE"
  }
}

Expand All

object

event

string

These events may occur if we have reason to believe that the Account has engaged in fraudulent activity.

Valid values[ "account.suspected", "account.suspended", "account.cleared" ]

Exampleaccount.suspended

business_id

string

ID of your Account, use this in the for-user-id header to create transactions on behalf of your Account

created

string

Timestamp of when the webhook was sent

updated

string

Timestamp of when the webhook was updated

data

object (xenPlatform_AccountSuspensionCallbackSchema)

string

ID of your Account, use this in the for-user-id header to create transactions on behalf of your Account

created

string

Timestamp of when the object was created

updated

string

Timestamp of when the object was updated

string (email)

A valid email address associated with the object

Max length255

Exampletest@example.co

public_profile

object (xenPlatform_public_profile)

name

string

Public name of the account.

description

string

Additional description visible publicly.

status

string

Valid values[ "SUSPECTED", "SUSPENDED", "CLEARED" ]

reason

string

Reason given for the status change

Responses

200

Was this article helpful?