Go to home page
Docs API Reference

Businesses

A Business represents a company registered with the New Zealand Companies Office. It is associated with a single Account .

Business Model

Attributes

  • id

    string

    The unique identifier.

  • accountId

    string

    The Centrapay accountId for an org account.

  • accountName

    string

    The Centrapay account name for an org account.

  • nzbn

    string

    The unique NZBN identifier.

  • name

    string

    Legal name recorded in the Companies Register.

  • tradingName

    string

    Trading name recorded in the Companies Register.

  • companyNumber

    string

    Company number recorded in the Companies Register.

  • createdAt

    timestamp

    When the Business was created.

  • updatedAt

    timestamp

    When the Business was updated.

  • createdBy

    crn

    The User or API Key that created the Business.

  • updatedBy

    crn

    The User or API Key that updated the Business.

  • taxNumber

    object

    The value-added tax configuration for the Business. See Tax Number Model .

  • onboardingStatus

    crn

    The onboarding status of the Business. See Onboarding Statuses for possible values.

  • onboardingStatusReason

    string

    The reason associated with the Onboarding Status . See Onboarding Status Reasons for possible values.

Onboarding Statuses

StatusDescriptionAllowed Reasons
appliedIdentifies businesses that have registered to be activated for the Centrapay service.
provisioningIdentifies businesses that are in the process of being activated for the Centrapay service.
activeIdentifies businesses that have been activated for Centrapay services successfully (i.e. they have successfully created a Payment Request).
deactivatedIdentifies businesses that have been de-registered for the Centrapay service.data-quality-issues,change-of-ownership, centrapay-discontinued, duplicate, blocked
on-holdIdentifies businesses that have been placed on hold.seasonal-business-closure, no-response

Onboarding Status Reasons

ReasonDescription
duplicateThe business already exists in the Centrapay system.
data-quality-issuesData quality issues are preventing the business from onboarding.
no-responseNo response has been received from the business.
change-of-ownershipThe business has changed ownership.
centrapay-discontinuedThe business is no longer using Centrapay.
seasonal-business-closureThe business has closed temporarily.

Tax Number Model

Attributes

  • value

    string

    The tax number.

  • type

    string

    Type of value-added tax. Can be nz-gst.

Create Business experimental

This endpoint allows you to create a new Business. If accountId is not provided when creating a Business, then a new org account will be created and associated to the Business.

Attributes

  • nzbn

    string required

    The unique NZBN identifier.

  • accountId

    string

    The Centrapay accountId.

  • test

    string

    The created Centrapay org account will have the test flag.

  • taxNumber

    object

    The value-added tax configuration.

Errors

  • INVALID_ACCOUNT

    403

    Account does not exist, is not authorized, is of the wrong type, or is not in the NZ region.

  • INVALID_NZBN

    403

    The NZBN provided does not match any NZ business.

  • BUSINESS_ALREADY_EXISTS

    403

    The account already has a business or there is already a business with the provided NZBN.

Request
curl -X POST \
 https://service.centrapay.com/api/businesses \
 -H 'content-type: application/json' \
 -H 'x-api-key: <TOKEN>' \
 -d '
{
 "nzbn": "9429046246448",
 "taxNumber": {
  "value": "123-456-789",
  "type": "nz-gst"
 }
}
'
Response
{
  "id": "DKTs3U38hdhfEqwF1JKoT2",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "accountName": "Centrapay",
  "nzbn": "9429046246448",
  "name": "CENTRAPAY LIMITED",
  "tradingName": "CentraPay",
  "companyNumber": "6340244",
  "createdAt": "2020-06-12T01:17:46.499Z",
  "updatedAt": "2020-06-12T01:17:46.499Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "taxNumber": {
    "value": "123-456-789",
    "type": "nz-gst"
  },
  "onboardingStatus": "applied"
}

Update Business experimental

This endpoint allows you to update a Business.

Attributes

  • tradingName

    string

    The trading name of the business.

  • taxNumber

    object

    The value-added tax configuration.

  • farmlandsBusinessNumber

    string

    The number associated with your Farmlands business.

Request
curl -X PUT \
 https://service.centrapay.com/api/businesses/DKTs3U38hdhfEqwF1JKoT2 \
 -H 'content-type: application/json' \
 -H 'x-api-key: <TOKEN>' \
 -d '
{
 "taxNumber": {
  "value": "123-456-789",
  "type": "nz-gst"
 },
 "farmlandsBusinessNumber": "12345678"
}
'
Response
{
  "id": "DKTs3U38hdhfEqwF1JKoT2",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "accountName": "Centrapay",
  "nzbn": "9429046246448",
  "name": "CENTRAPAY LIMITED",
  "tradingName": "CentraPay",
  "companyNumber": "6340244",
  "createdAt": "2020-06-12T01:17:46.499Z",
  "updatedAt": "2020-06-12T01:17:46.499Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "taxNumber": {
    "value": "123-456-789",
    "type": "nz-gst"
  },
  "farmlandsBusinessNumber": "12345678",
  "onboardingStatus": "applied"
}

Get Business by Account Id experimental

This endpoint allows you to retrieve a Business by account id.

Request
curl -X GET \
 https://service.centrapay.com/api/accounts/Jaim1Cu1Q55uooxSens6yk/business \
 -H 'x-api-key: <TOKEN>'
Response
{
  "id": "DKTs3U38hdhfEqwF1JKoT2",
  "accountId": "Jaim1Cu1Q55uooxSens6yk",
  "accountName": "Centrapay",
  "nzbn": "9429046246448",
  "name": "CENTRAPAY LIMITED",
  "tradingName": "CentraPay",
  "companyNumber": "6340244",
  "createdAt": "2020-06-12T01:17:46.499Z",
  "updatedAt": "2020-06-12T01:17:46.499Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey"
}

Search NZ Company Register experimental

This endpoint returns a list of companies that match the queried param on company name, nzbn number or company number. Results are paginated and ordered by relevance.

Request
curl -X GET \
 'https://service.centrapay.com/api/nzbn-search?q=centrapay' \
 -H 'x-api-key: <TOKEN>'
Response
{
  "items": [
    {
      "nzbn": "9429046246448",
      "companyName": "CENTRAPAY LIMITED",
      "companyNumber": "6340244"
    }
  ]
}

Get Business Details from NZ Company Register experimental

This endpoint allows you to retrieve a Business by account id.

Request
curl -X GET \
 https://service.centrapay.com/api/nzbn/9429046246448 \
 -H 'x-api-key: <TOKEN>'
Response
{
  "nzbn": "9429046246448",
  "companyName": "CENTRAPAY LIMITED",
  "tradingName": "CentraPay",
  "companyNumber": "6340244",
  "directors": [
    {
      "firstName": "John",
      "lastName": "DOE",
      "addressLines": [
        "7 Tara Street",
        "Downmore",
        "Auckland"
      ]
    },
    {
      "firstName": "Jane",
      "lastName": "DOE",
      "addressLines": [
        "82 Greatwood Road",
        "Northclover",
        "Auckland"
      ]
    }
  ]
}

Set Business Onboarding Status

This endpoint returns allows you to set the onboarding status of a Business.

Attributes

Errors

  • BUSINESS_ALREADY_EXISTS

    403

    The account already has a business or there is already a business with the provided NZBN.

Request
curl -X POST \
 https://service.centrapay.com/api/businesses/DKTs3U38hdhfEqwF1JKoT2/set-onboarding-status \
 -H 'content-type: application/json' \
 -H 'x-api-key: <TOKEN>' \
 -d '
{
 "onboardingStatus": "deactivated",
 "onboardingStatusReason": "change-of-ownership"
}
'
Response
{
  "type": "set-onboarding-status",
  "onboardingStatus": "deactivated",
  "onboardingStatusReason": "change-of-ownership",
  "businessId": "DKTs3U38hdhfEqwF1JKoT2",
  "createdAt": "2020-06-12T01:17:46.499Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "activityNumber": 2
}