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:
reference
required
string (Unique reference) [ 1 .. 50 ] characters

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

required
object (Submitter)
seller_category
required
string (Seller category)

Identifier of a seller category configured on your platform during onboarding. Categories define the pricing, capabilities, and risk profile applied to sub-entities; ask your Checkout.com contact for the list available to your platform.

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 (Processing Details)

Information about the sub-entity's expected processing.

is_draft
boolean

Indicates whether the sub-entity should remain in Draft on PUT, skipping due-diligence checks. POST always creates the entity in Draft regardless of this field.

object (Documents)

Verification documents for the sub-entity.

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": "isv-seller-example001",
  • "submitter": {
    },
  • "seller_category": "cat_retail_001",
  • "documents": {
    },
  • "processing_details": {
    },
  • "contact_details": {
    },
  • "profile": {},
  • "company": {
    }
}
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. Immutable after creation.


 
required
object (Submitter) 
 
seller_category
required
string (Seller category) 
Identifier of a seller category configured on your platform during onboarding. Categories define the pricing, capabilities, and risk profile applied to sub-entities; ask your Checkout.com contact for the list available to your platform.


 
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 (Processing Details) 
Information about the sub-entity's expected processing.


 
is_draft
boolean
Indicates whether the sub-entity should remain in Draft on PUT, skipping due-diligence checks. POST always creates the entity in Draft regardless of this field.


 
object (Documents) 
Verification documents for the sub-entity.


 
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": "isv-seller-example001",
  • "submitter": {
    },
  • "seller_category": "cat_retail_001",
  • "documents": {
    },
  • "processing_details": {
    },
  • "contact_details": {
    },
  • "profile": {},
  • "company": {
    }
}
Response samples 
application/json
{}
Get a list of requirements
Retrieve the list of pending requirements that the sub-entity must resolve. Requirements may be raised as part of onboarding, periodic AML reviews, or ongoing compliance checks. Each item in the response includes a priority and deadline to help you surface the most urgent items first.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
id
required
string
The sub-entity's ID.


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
Responses 
200
Requirements retrieved successfully


401
Unauthorized


404
Sub-entity not found


get/accounts/entities/{id}/requirements
Request samples 
Response samples 
application/json
{}
Get requirement details
Retrieve detailed information for a single requirement, including the JSON Schema that defines the shape of the value expected when resolving it.


Once a response has been submitted for a requirement (see PUT /accounts/entities/{id}/requirements/{requirementId}), that requirement is no longer retrievable via this endpoint until it is re-issued or cleared.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
id
required
string
The sub-entity's ID.


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
requirementId
required
string
The requirement's ID, as returned by GET /accounts/entities/{id}/requirements.


 
 Example:  req_5wmacwhrhbzhqkhx5hlqmzje44
Responses 
200
Requirement details retrieved successfully


401
Unauthorized


404
Requirement not found, or a response has already been submitted for it.


get/accounts/entities/{id}/requirements/{requirementId}
Request samples 
Response samples 
application/json
{}
Resolve a requirement
Submit a response to resolve a requirement. The shape of value is defined by the requirement's _schema, returned from GET /accounts/entities/{id}/requirements/{requirementId}.


The response is accepted for processing and applied asynchronously. While processing, the requirement is no longer retrievable via the GET endpoints; if validation fails downstream the requirement may reappear.


SecurityOAuth2: OAuth or API Key: ApiSecretKey 
Request 
path Parameters
id
required
string
The sub-entity's ID.


 
 Example:  ent_w4jelhppmfiufdnatam37wrfc4
requirementId
required
string
The requirement's ID, as returned by GET /accounts/entities/{id}/requirements.


 
 Example:  req_5wmacwhrhbzhqkhx5hlqmzje44
Request Body schema: application/json
required
required
object or Array of any or string or number or boolean
The response to the requirement. The expected shape depends on the requirement and is defined by the JSON Schema returned in the requirement details response. Common shapes include a file reference (for document uploads), a primitive value, or a structured object.


 
Responses 
202
Response accepted for processing


400
The request body could not be parsed.


401
Unauthorized


404
Requirement not found, or a response has already been submitted for it.


422
The supplied value did not validate against the requirement's _schema.


put/accounts/entities/{id}/requirements/{requirementId}
Request samples 
application/json
{
  • "value": "Acme Holdings Limited"
}
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