Create a marketplace entity

TxB APIs allow clients to onboard entities associated to their own. Once the entities have been created, accounts can be opened and clients can make payments, retrieve reporting, and request FX rates. This guide will explain the steps necessary to open an entity.

Step by step guide

Step 1 - Create an entity

You can create an entity linked to your own by using the entities API. To ensure proper linkage it's important that the “role” specified is aligned with the type of entity you are creating:

POST /v2/entities/BUSINESS with a representative payload:

{
    "businessEntityRequest": {
        "requestId": "MyRequest",
        "branchCountry": "US",
        "role": "MARKETPLACE_USER",
        "legalName": "Wayne Enterpises Inc",
        "legalStructure": "CORP",
        "addresses": [
            {
                "addressLines": [
                    "Wayne Tower"
                ],
                "city": "Gotham",
                "postalCode": "GO 10030",
                "countryISOCode": "US",
			“…”
            }
	    ]
    }
}

Once submitted you should receive a 200 okay response detailing the associated entityId.

{
    "message": "8C1BFE0D82374B6DBDDA2617CAD12269"
}

Step 2 – Monitor status of onboarding request

You can monitor the status of your onboarding by using the v1 entities API.

GET /v1/entities/entityRequests/8C1BFE0D82374B6DBDDA2617CAD12269 returns:

{
    "entityId": "8C1BFE0D82374B6DBDDA2617CAD12269",
    "message": null,
    "status": "IN_PROGRESS"
}

Once the entity onboarding request has been reviewed (where applicable) and created then the status will show as “COMPLETED”.

Step 3 – View your entity

Once your entities have been created then you can retrieve the details. If the entity onboarding is not in a “COMPLETED” status then the entity details will not be visible, and you can return to ‘Step 2’ to monitor the status.

GET /v2/entities/8C1BFE0D82374B6DBDDA2617CAD12269 returns:

{
    "entityId": "8C1BFE0D82374B6DBDDA2617CAD12269 ",
    "aliasId": " Wayne Enterpises Inc ",
    "status": "ACTIVE",
    "entityData": {
        "businessEntity": {
            "legalName": " Wayne Enterpises Inc ",
            "legalStructure": "CORP",
            "addresses": […]
		},
		“…”
	},
	“…”
}

Useful Information

Once you have an active entity then you can proceed to opening virtual & multi-currency accounts.

In order to create an account linked to a MARKETPLACE_USER entity you must use some of the information from GET/v2/entities/{entityId}. All account fields below exist within the ownershipAndControl object on POST/v2/accounts/VIRTUAL.