Businesses

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

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.

Attributes

  • value

    string

    The tax number.

  • type

    string

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


POST/api/businesses

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

    stringrequired

    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.

Request
POST/api/businesses
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"
}

PUT/api/businesses/{businessId}

This endpoint allows you to update a Business.

Attributes

  • taxNumber

    object

    The value-added tax configuration.

  • farmlandsBusinessNumber

    string

    The number associated with your Farmlands business.

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.

Request
PUT/api/businesses/DKTs3U38hdhfEqwF1JKoT2
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/api/accounts/{accountId}/business

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

Request
GET/api/accounts/Jaim1Cu1Q55uooxSens6yk/business
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"
}

GET/api/nzbn-search

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

Request
GET/api/nzbn-search
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/api/nzbn/{nzbn}

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

Request
GET/api/nzbn/9429046246448
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"
      ]
    }
  ]
}

POST/api/businesses/{businessId}/set-onboarding-status

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

Attributes

Request
POST/api/businesses/DKTs3U38hdhfEqwF1JKoT2/set-onboarding-status
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
}