Initiate onboarding

POST

/onboarding

Code sample: Shell / cURL

curl --request POST \
  --url https://welcome.ztlpay.io/onboarding \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "country": "SE", "organizationNumber": "5569994600", "redirectUrl": "https://example.org" }'

• Production environment
• Sandbox environment for testing

Authorizations

• OAuth2Sandbox
  api://ac0d1aea-5e3a-463f-9dd1-194898ee5820/.default
• OAuth2Production
  api://1f115cad-5576-4db9-a7f9-8921c47a86e4/.default

Request Body

Media typeapplication/json

object

country

required

Countrycode for the company being onboarded

string

Example

SE

organizationNumber

required

Organization number for the company being onboarding

string

Example

5569994600

redirectUrl

The user is redirected to this URL after the onboarding process has completed as well as if they cancel the onboarding process. Normally this will be the URL of the ERP the end-user originated from. Must start with a protocol (HTTP/HTTPS).

string

Example

https://example.org

Responses

200

Onboarding started successfully

Media typeapplication/json

object

id

required

Id for the started onboarding, used for status

string format: uuid

url

required

string format: url

Example

{
  "id": "941d1877-73b8-45bf-8c65-47233b58926a",
  "url": "https://welcome.sandbox.ztlpay-test.io/onboarding/941d1877-73b8-45bf-8c65-47233b58926a"
}

Headers

ztl-request-id

string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example

3a797348-ef0c-4f52-b821-fdfcdb98c4d9

400

Bad request

Media typeapplication/json

object

ztlRequestId

required

Unique RequestId, please provide this Id in case of support requests

string format: uuid

message

required

The underlying reason for the error

string

Example

{
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid account"
}

Headers

ztl-request-id

string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example

3a797348-ef0c-4f52-b821-fdfcdb98c4d9

403

Forbidden

Media typeapplication/json

object

ztlRequestId

required

Unique RequestId, please provide this Id in case of support requests

string format: uuid

message

required

The underlying reason for the error

string

Example

{
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid account"
}

Headers

ztl-request-id

string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example

3a797348-ef0c-4f52-b821-fdfcdb98c4d9

404

Not found

409

Conflict

Media typeapplication/json

object

failure

required

string

Allowed value: COMPANY_ALREADY_EXISTS

ztlRequestId

required

Unique RequestId, please provide this Id in case of support requests

string format: uuid

message

required

The underlying reason for the error

string

additionalInformation

Additional context related to the error

object

onboardingId

The ID of the onboarding used to onboard the existing company. This onboarding is always in status Accepted and cannot be modified.

onboardingId and additionalInformation can be null when the original onboarding details are unavailable.

string format: uuid

nullable

Example

{
  "failure": "COMPANY_ALREADY_EXISTS",
  "ztlRequestId": "d188e4f9-91fa-4fd8-98be-e725dc44090a",
  "message": "A company with organization number 5569994600 already exists. Initiation of new onboardings is not permitted.",
  "additionalInformation": {
    "onboardingId": "9256411a-5c80-40e5-b50c-768dbca443af"
  }
}

Headers

ztl-request-id

string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example

3a797348-ef0c-4f52-b821-fdfcdb98c4d9

500

Internal server error

Media typeapplication/json

object

ztlRequestId

required

Unique RequestId, please provide this Id in case of support requests

string format: uuid

message

required

The underlying reason for the error

string

Example

{
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid account"
}

Headers

ztl-request-id

string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example

3a797348-ef0c-4f52-b821-fdfcdb98c4d9

503

Service unavailable

Media typeapplication/json

object

ztlRequestId

required

Unique RequestId, please provide this Id in case of support requests

string format: uuid

message

required

The underlying reason for the error

string

Example

{
  "ztlRequestId": "3a797348-ef0c-4f52-b821-fdfcdb98c4d9",
  "message": "Invalid account"
}

Headers

ztl-request-id

string format: uuid

Unique RequestId, please provide this Id in case of support requests

Example

3a797348-ef0c-4f52-b821-fdfcdb98c4d9