Onboard an entity

​

Onboard an entity so they can start using Checkout services.

Headers
  • Accept
    Type: string
    required

    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.

Body
required
application/json

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

    • reference
      Type: string · Unique reference
      min length:  
      1
      max length:  
      50
      required

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

    • agreed_terms
      Type: object · Agreed Terms
      required

      Details of the person who agreed to the terms and conditions on behalf of the sub-entity, captured as evidence of consent to Checkout.com onboarding.

    • seller_category
      Type: string · Seller category
      required

      The identifier of a seller category set up for your platform. Seller categories define the pricing, capabilities, and risk profile applied to sub-entities, and are configured during your platform's onboarding with Checkout.com. Contact your account manager for your platform's list of available identifiers.

    • profile
      Type: object · Profile
      required

      Information about the profile of the sub-entity, primarily regarding the products/services offered.

    • contact_details
      Type: object · Contact Details
      required

      Contact details of this sub-entity.

    • processing_details
      Type: object · Processing Details
      required

      Information about the sub-entity's expected processing.

    • company
      Type: object · Company
      required

      Information about the company represented by the sub-entity.

    • is_draft
      Type: boolean
      write-only

      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.

    • documents
      Type: object · Documents

      Verification documents for the sub-entity.

Responses
  • application/json
  • 400

    Bad Request

  • 401

    Unauthorized

  • application/json
  • application/json
Request Example for post/accounts/entities
curl 'https://{prefix}.api.sandbox.checkout.com/accounts/entities' \
  --request POST \
  --header 'Accept: application/json;schema_version=3.0' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN' \
  --data '{
  "reference": "isv-seller-example001",
  "agreed_terms": {
    "date": "2026-07-02T10:30:00Z",
    "ip_address": "8.8.8.8",
    "name": "Toby Arden",
    "email": "toby.arden@example.com",
    "version": "cko-platform-terms-1.0.0"
  },
  "seller_category": "cat_retail_001",
  "processing_details": {
    "annual_processing_volume": 1000,
    "average_transaction_value": 2000,
    "average_order_fulfillment_time": 3,
    "target_countries": [
      "US"
    ],
    "currency": "USD",
    "payments": {
      "ach": {
        "annual_ach_volume": 100000,
        "average_ach_transaction_size": 5000,
        "estimated_monthly_credit_volume": 50000,
        "average_credit_amount": 2500
      }
    }
  },
  "contact_details": {
    "phone": {
      "number": "4155678900",
      "country_code": "US"
    },
    "email_addresses": {
      "primary": "toby.arden@example.com",
      "pci_compliance_contact": "pci.contact@example.com"
    }
  },
  "profile": {
    "urls": [
      "https://www.isv-seller-example.com"
    ],
    "mccs": [
      "5551"
    ],
    "holding_currencies": [
      "USD"
    ],
    "default_holding_currency": "USD"
  },
  "company": {
    "business_registration_number": "12-3456789",
    "business_type": "private_corporation",
    "legal_name": "ISV Seller Example Inc",
    "trading_name": "ISV Seller Example",
    "registered_address": {
      "address_line1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US"
    },
    "principal_address": {
      "address_line1": "123 Main Street",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94105",
      "country": "US"
    },
    "date_of_incorporation": {
      "year": 2025,
      "month": 10,
      "day": 1
    },
    "representatives": [
      {
        "roles": [
          "ubo",
          "control_person"
        ],
        "ownership_percentage": 25,
        "company_position": "ceo",
        "individual": {
          "first_name": "Toby",
          "last_name": "Arden",
          "email_address": "toby.arden@example.com",
          "national_id_type": "ssn",
          "national_id_number": "123456789",
          "date_of_birth": {
            "day": 15,
            "month": 1,
            "year": 1990
          },
          "place_of_birth": {
            "country": "US"
          },
          "citizenships": [
            {
              "country": "US"
            }
          ],
          "phone": {
            "country_code": "US",
            "number": "4155678901"
          },
          "address": {
            "address_line1": "123 Main Street",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94105",
            "country": "US"
          }
        }
      },
      {
        "roles": [
          "authorised_signatory"
        ],
        "individual": {
          "first_name": "Alex",
          "last_name": "Morgan",
          "email_address": "alex.morgan@example.com",
          "national_id_type": "ssn",
          "national_id_number": "987654321",
          "date_of_birth": {
            "day": 22,
            "month": 6,
            "year": 1985
          },
          "place_of_birth": {
            "country": "US"
          },
          "citizenships": [
            {
              "country": "US"
            }
          ],
          "phone": {
            "country_code": "US",
            "number": "4155678902"
          },
          "address": {
            "address_line1": "123 Main Street",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94105",
            "country": "US"
          }
        }
      }
    ]
  }
}'

{
  "id": "ent_wxglze3wwywujg4nna5fb7ldli",
  "reference": "superhero1234",
  "requirements_due": [
    {
      "field": "individual.identification.document",
      "reason": "required",
      "message": "required"
    }
  ],
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/accounts/entities/ent_wxglze3wwywujg4nna5fb7ldli"
    }
  }
}

Entity onboarded successfully