Checkout.com API logo

Platforms

Manage all your sub-entities (also known as sub-merchants) through one integration, globally.

Onboard an entity

Onboard an entity so they can start using Checkout services.

SecurityOAuth2: OAuth
Request
header Parameters
Accept
required
string

Used to describe the type of content the client can interpret. Use the schema_version value to specify the payload format. The latest version is 3.0.

Example: application/json;schema_version=3.0
Request Body schema: application/json
required

The entity to be onboarded. Use the relevant format for the platform type, region and payload version.

One of:

Beta

Create a sub-entity and send an invite to the seller to onboard with Checkout.com. The seller will receive an email with a link to the Dashboard, where they can complete their onboarding application. Only one user can be invited to onboard the sub-entity through Hosted Onboarding.

To enable the Hosted Onboarding feature, contact your Account Manager.

reference
required
string [ 1 .. 50 ] characters

A unique reference you can later use to identify the sub-entity.

required
object (Contact details)

The contact details of the members invited to onboard the sub-entity

is_draft
required
boolean

Specifies whether the sub-entity details are in draft.

Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.

Responses
201

Entity onboarded successfully

400

Bad Request

401

Unauthorized

409

Entity onboarding request conflicted with an existing entity

422

Invalid data was sent

post/accounts/entities
Request samples
application/json
{
  • "reference": "superhero1234",
  • "is_draft": true,
  • "contact_details": {
    }
}
Response samples
application/json
{}

Get sub-entity Members

Beta

Retrieve information on all users of a sub-entity that has been invited through Hosted Onboarding. Only one user can be invited to onboard the sub-entity through Hosted Onboarding.

To enable the Hosted Onboarding feature, contact your Account Manager.

SecurityOAuth2: OAuth or API Key: ApiSecretKey
Request
path Parameters
entityId
required
string

The ID of the sub-entity

Example: ent_w4jelhppmfiufdnatam37wrfc4
Responses
200

Sub-Entity member retrieved successfully

401

Unauthorized

404

Sub-entity not found

get/accounts/entities/{entityId}/members
Request samples 
Response samples 
application/json
{
  • "data": [
    ]
}
Reinvite a sub-entity member
Beta

Resend an invitation to the user of a sub-entity. The user will receive another email to continue their Hosted Onboarding application. An invitation can only be resent to the user originally registered to the sub-entity.


To enable the Hosted Onboarding feature, contact your Account Manager.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
entityId
required
string
The ID of the sub-entity


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
userId
required
string
The ID of the invited user.


 
 Example:  usr_eyk754cqieqexfh6u46no5nnha
Request Body schema: application/json
required
object (Reinvite sub-entity member) 
 
Responses 
200
Sub-entity member retrieved successfully


401
Unauthorized


404
Sub-entity not found


put/accounts/entities/{entityId}/members/{userId}
Request samples 
application/json
{ }
Response samples 
application/json
{
  • "id": "usr_eyk754cqieqexfh6u46no5nnha"
}
Get entity details
Use this endpoint to retrieve an entity and its full details.


SecurityOAuth2: OAuth 
Request 
path Parameters
id
required
string
The ID of the entity.


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
header Parameters
Accept
required
string
Used to describe the type of content the client can interpret.
Use the schema_version value to specify the payload format. The latest version is 3.0.


 
 Example:  application/json;schema_version=3.0
Responses 
200
Entity retrieved successfully


401
Unauthorized


404
Entity not found


422
Invalid data was sent


get/accounts/entities/{id}
Request samples 
// For more information please refer to https://github.com/checkout/checkout-sdk-net
using Checkout.Accounts;

ICheckoutApi api = CheckoutSdk.Builder().OAuth()
    .ClientCredentials("client_id", "client_secret")
    .Scopes(OAuthScope.Accounts)
    .Environment(Environment.Sandbox)
    .EnvironmentSubdomain("{prefix}") // Your base URL's {prefix} value is unique to your account and environment. To learn how to retrieve your base URLs for the sandbox and production environments, see https://www.checkout.com/docs/developer-resources/api/api-endpoints.
    .HttpClientFactory(new DefaultHttpClientFactory())
    .Build();

try
{
    OnboardEntityDetailsResponse response = await api.AccountsClient().GetEntity("entity_id");
}
catch (CheckoutApiException e)
{
    // API error
    string requestId = e.RequestId;
    var statusCode = e.HttpStatusCode;
    IDictionary<string, object> errorDetails = e.ErrorDetails;
}
catch (CheckoutArgumentException e)
{
    // Bad arguments
}
catch (CheckoutAuthorizationException e)
{
    // Invalid authorization
}
Response samples 
application/json
{
  • "reference": "string",
  • "status": "string",
  • "profile": {
    },
  • "contact_details": {
    },
  • "capabilities": { },
  • "requirements_due": [
    ],
  • "company": {
    },
  • "processing_details": {
    },
  • "documents": {
    }
}
Update entity details
Update an entity.


Note: when you update a entity we may conduct further due diligence checks when necessary. During these checks, your payment capabilities will remain the same.


SecurityOAuth2: OAuth 
Request 
path Parameters
id
required
string
The ID of the entity.


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
header Parameters
Accept
required
string
Used to describe the type of content the client can interpret.
Use the schema_version value to specify the payload format. The latest version is 3.0.


 
 Example:  application/json;schema_version=3.0
Request Body schema: application/json
required
The entity to be updated. Use the relevant format for the platform type, region and payload version.


One of:
reference
required
string (Unique reference)   [ 1 .. 50 ] characters 
A unique reference you can later use to identify the sub-entity.


 
required
object (Company) 
Information about the company represented by the sub-entity.


 
required
object (Profile) 
Information about the profile of the sub-entity, primarily regarding the products/services offered.


 
required
object (Contact Details) 
Contact details of this sub-entity.


 
required
object (Documents) 
The documents used to support the verification of company details.


 
required
object (Processing Details) 
Seller processing details.


 
is_draft
boolean
Specifies whether the sub-entity details are in draft.


Marking a sub-entity as a draft allows sub-entity details to be updated, without triggering due diligence checks.


 
Responses 
200
Entity updated successfully


401
Unauthorized


404
Entity not found


422
Invalid data was sent


put/accounts/entities/{id}
Request samples 
application/json
{
  • "reference": "string",
  • "is_draft": true,
  • "profile": {
    },
  • "contact_details": {
    },
  • "company": {
    },
  • "processing_details": {
    },
  • "documents": {
    }
}
Response samples 
application/json
{}
Upload a file
Our Platforms solution provides an easy way to upload documentation required for full due diligence.


Use this endpoint to generate a file upload link, which you can then upload a file to using a data-binary type request.


See the documentation for more information.


Please note that the sub-domain – https://files.checkout.com – is slightly different to Checkout.com's other endpoints. See the documentation for more information.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
entityId
required
string
The ID of the sub-entity


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
Request Body schema: application/json
purpose
required
string
The purpose of the file upload.


 Enum: "additional_document" "articles_of_association" "bank_verification" "certified_authorised_signatory" "company_ownership" "company_verification" "financial_verification" "identity_verification" "proof_of_legality" "proof_of_principal_address" "shareholder_structure" "tax_verification" "proof_of_residential_address" "proof_of_registration"  
Responses 
200
File uploaded successfully


401
Unauthorized


422
Unprocessable


429
Too many requests


post/entities/{entityId}/files
Request samples 
application/json
{
  • "purpose": "identity_verification"
}
Response samples 
application/json
{}
Retrieve a file
Retrieve information about a previously uploaded file.


Please note that the sub-domain – https://files.checkout.com – is slightly different to Checkout.com's other endpoints. See the documentation for more information.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
entityId
required
string
The ID of the sub-entity


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
fileId
required
string
The ID of the file. The value is always prefixed with file_.


 
 Example:  file_w4jelhppkaskd0dnatam37wrfc4
Responses 
200
OK


401
Unauthorized


404
File not found


get/entities/{entityId}/files/{fileId}
Request samples 
Response samples 
application/json
{}
➔ Next to Payment instruments