Skip to main content
Version: v2alpha1

Onboard accounts using the API

Before you start​

Steps​

1. Create account​

The platform must create an account in the name of its clients or its subsidiaries to start involving them in the getpaid's system. The account can be created with different capabilities, depending on the type of account, for example, a buyer or a seller may have different capabilities enabled.

Create the account by calling POST /accounts with the minimum required information and the capabilities desired. It will assign a unique identifier to the new account (id) and return the required information (requirements_due) to complete the onboarding process for the selected capabilities.

In this scenario, the account is created with the receive_invoices capability enabled and the required fields are business_profile.trading_name and business_profile.registration_number.

Request​

POST /accounts
{
  "capabilities": {
    "receive_invoices": {
      "enabled": true
    }
  },
  "country": "DE",
  "business_profile": {
    "type": "company",
    "legal_name": "Wildcat Pumps GmbH"
  }
}

Response​

201 Created
{
  "id": "acc_44678r08jtm8zbt227tzhc4nw5",
  "version": "20241217132818130",
  "capabilities": {
    "receive_invoices": {
      "enabled": true,
      "status": "information_due"
    }
  },
  "requirements_due": [
    {
      "field": "business_profile.trading_name",
      "requested_by": {
        "receive_invoices": {
          "reason": "required"
        }
      }
    },
    {
      "field": "business_profile.registration_number",
      "requested_by": {
        "receive_invoices": {
          "reason": "required"
        }
      }
    }
  ]
}

2. Complete required info​

The platform must collect the required information indicated at requirements_due to activate the capabilities and update the account data by calling PATCH /accounts/{account_id}.

The platform must collect the required information indicated at requirements_due to update the account data by calling PATCH /accounts/{account_id} to activate the capabilities after performing the required verification checks.

Use the id from the previous step to update the account with the required information.

In this scenario, if the capability does not require any verification check, the account is updated and the capability status is set to active.

Request​

POST /accounts/{account_id}
{
  "business_profile": {
    "type": "company",
    "trading_name": "Wildcat Pumps",
    "registration_number": "HRB 123456"
  }
}

Response​

200 OK
{
  "id": "acc_44678r08jtm8zbt227tzhc4nw5",
  "version": "20241218080140999",
  "capabilities": {
    "receive_invoices": {
      "enabled": true,
      "status": "active"
    }
  },
  "requirements_due": [],
  [...]
}