Create a business entity

TxB APIs allow users to create entities (aka onboard new customers) and submit all necessary supporting documentation. Once the entities have been created, you can create accounts, make payments, retrieve reporting, and request FX rates on behalf of the newly created entities. This guide will explain the steps necessary to open a client Entity.

Step by step guide

Step 1 - Create an entity

Firstly, you should send all the necessary client details for the type of business you are onboarding. Specific information per business type will be agreed upfront as part of the onboarding process.

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

{
    "businessEntityRequest": {
        "requestId": "PartnershipClient1",
        "branchCountry": "US",
        "role": "PARTNERSHIP_CLIENT",
        "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"
}

Role Descriptions

Once the initial entity onboarding request has been submitted you can now send the necessary documentation to TxB.

Step 2 (Optional) – Edit entity payload prior to submission

Prior to submitting the entity for review, you can edit the entity payload. To do this you will need to resend a complete payload including all necessary attributes.

POST /v2/entities/8C1BFE0D82374B6DBDDA2617CAD12269 with a representative payload:

{
    "businessEntityRequest": {
        "requestId": "PartnershipClient1Edit",
        "branchCountry": "US",
        "role": "PARTNERSHIP_CLIENT",
        "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"
}

The entityId will be the same as the original provided.

Step 3 - Submit entity for review

Once all documents have been sent, you can now submit the information for review.

POST /v2/entities/8C1BFE0D82374B6DBDDA2617CAD12269/submit

This will return a 200 okay response.

This will create a task for the TxB operations team who will review the request and supporting documentation. Onboarding checks such as KYC, Compliance and Tax will be conducted at this time and no further changes to your request payload will be possible. If operations identify incorrect or missing information/ documentation, then they will return the onboarding and advise the reason.

Step 4 – 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": "REVIEW"
}

Once the entity onboarding request has been reviewed and fully onboarded then the status will show as “COMPLETED”.

Step 5 – 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 4’ 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": […]
		},
		“…”
	},
	“…”
}