Business Onboarding

The Business Onboarding API allows acquirers to register businesses and merchants with Centrapay so they can begin accepting payments through supported asset programs.

Optionally, acquirers can specify which sales channels (such as payment terminals) should be enabled for that merchant.

API Behavior

Validation - Request validation is performed synchronously and errors are returned immediately for invalid data
Processing - After accepting the request, Centrapay processes the onboarding asynchronously in the background
Completion - When sufficient information is provided, the merchant will be onboarded and enabled for the relevant asset program. If information is missing or incomplete, the merchant may need to provide additional details to complete the onboarding process
Invitations - If the business is new to Centrapay, an invitation is sent to the contact email so the merchant can claim their account

Glossary

Term	Description
Acquirer	A third party with a relationship to a merchant. The acquirer initiates onboarding by supplying merchant details.
Merchant	A business entity that will accept payments through Centrapay.
Sales Channel	A payment terminal provider configured within Centrapay.
Asset Program	A payment program that enables merchants to accept specific payment methods.
Vendor	The organization that manufactures or provides the payment device or software.
Reseller	The distributor or third party that sells or supports the terminal to the merchant.

Onboarding Request Model

Attributes

id
string

The unique identifier for the onboarding request, prefixed with bo_.
nzbn
string

The 13-digit New Zealand Business Number. Optional identifier.
legalName
string required

Registered legal name of the business (3-100 characters).
tradingName
string

Trading name of the business (3-100 characters). Defaults to legalName if omitted.
contactEmail
string required

Contact email used for onboarding and notifications. Must be a valid email address.
contactName
string

Contact name used for onboarding and notifications (3-100 characters). If omitted, defaults to merchant.contactName or the part before @ in contactEmail.
externalId
string

Secondary identifier for acquirers to find their onboarding request (max 35 characters). Used for idempotency - submitting the same externalId with the same payload will return the existing request instead of creating a duplicate.
taxNumber
object

Tax number information for the business. See Tax Number Model .
merchant
object required

Merchant information including name, location, and contact details. See Merchant Model .
assetProgram
object required

Asset program configuration including settlement account details. See Asset Program Model .
salesChannels
array

Optional array of sales channel configurations for payment terminals. See Sales Channel Model .
metadata
object

Optional key-value pairs for additional contextual information (max 10 entries). Keys can be up to 100 characters and values up to 500 characters.
createdAt
timestamp

Timestamp when the onboarding request was created.
createdBy
string

The account ID that created the onboarding request.
status
string

Current status of the onboarding request.

Tax Number Model

Attributes

value
string required

The GST number (e.g., 123-456-789).
type
string required

Must be nz-gst.

Merchant Model

Attributes

name
string required

Display name of the merchant (2-100 characters).
categoryCode
string required

ISO 18245 Merchant category code (4 digits).
type
string required

Must be either physical or e-commerce.
contactName
string

Merchant contact name (3-100 characters).
contactEmail
string

Merchant contact email. Must be a valid email address.
contactPhone
string

Merchant contact phone number (max 20 characters).
location
object

Physical location of the merchant. Required if type is physical. See Location Model .

Location Model

Attributes

street
string required

Street number and name (max 255 characters).
suburb
string

Suburb (max 255 characters).
city
string required

Town or city (max 255 characters).
state
string

Region or state (max 255 characters).
postCode
string

Postal code (4-10 digits).
country
string required

ISO 3166-1 alpha-2 country code (e.g., NZ).

Asset Program Model

Attributes

assetProgramId
string required

The unique identifier of the asset program that the business will accept (max 35 characters).
params.settlementAccountNumber
string required

The settlement bank account in the format XX-XXXX-XXXXXXX-XXX (18-19 digits).
params.chargeAccountNumber
string

The billing bank account in the format XX-XXXX-XXXXXXX-XXX (18-19 digits). Defaults to settlement account if omitted.
params.externalMerchantId
string required

Merchant identifier in the partner system (max 35 characters).

Sales Channel Model

Attributes

params.vendor
string required

Terminal software/hardware vendor (3-100 characters).
params.reseller
string

Terminal distributor (3-100 characters).
params.deviceId
string required

Software device ID (max 35 characters).
params.serialNumber
string

Hardware serial number (max 35 characters).
params.deviceModel
string

Terminal model (3-100 characters), e.g., Verifone P630.

Create an Onboarding Request

This endpoint allows acquirers to submit a business for onboarding. The request is validated synchronously, and onboarding is processed asynchronously in the background.

Idempotency

If you provide an externalId, the API will prevent duplicate submissions. If you submit the same externalId with the same payload, the API will return the existing onboarding request with a 200 status code. If you submit the same externalId with a different payload, the API will return a 403 error with the code DUPLICATE_EXTERNAL_ID.

Required Permissions

The API key must have the business:onboard permission for the target account.

Request Body

Attributes

nzbn
string

13-digit NZ Business Number. Optional identifier.
legalName
string required

Registered legal name (3-100 characters).
tradingName
string

Trading name (3-100 characters). Defaults to legalName if omitted.
contactEmail
string required

Contact email for onboarding and notifications.
contactName
string

Contact name (3-100 characters). Defaults to merchant.contactName or email prefix if omitted.
externalId
string

Unique client-side identifier (max 35 characters) for idempotency.
taxNumber
object

Tax number information. See Tax Number Model .
merchant
object required

Merchant details. See Merchant Model .
assetProgram
object required

Asset program configuration. See Asset Program Model .
salesChannels
array

Optional sales channel configurations. See Sales Channel Model .
metadata
object

Optional key-value pairs for additional contextual information (max 10 entries). Keys can be up to 100 characters and values up to 500 characters.

Error Responses

Bad Request

400

The request is malformed or violates the schema validation.

Unauthorized

401

Missing or invalid API key.

DUPLICATE_EXTERNAL_ID

403

The supplied externalId has already been used with a different payload.

INVALID_ASSET_PROGRAM

403

The asset program is invalid or not permitted.

INVALID_SALES_CHANNEL

403

The vendor and/or reseller did not match a valid sales channel in Centrapay.

curl -X POST \
 https://service.centrapay.com/api/businesses/onboard \
 -H 'content-type: application/json' \
 -H 'x-api-key: <TOKEN>' \
 -d '
{
 "legalName": "Centrapay Cafe Limited",
 "tradingName": "Centrapay Cafe",
 "contactEmail": "admin@centracafe.example",
 "contactName": "Alice Anderson",
 "externalId": "ext-cafe-001",
 "taxNumber": {
  "value": "123-456-789",
  "type": "nz-gst"
 },
 "merchant": {
  "name": "Centrapay Cafe",
  "categoryCode": "5812",
  "type": "physical",
  "contactName": "Bob Brown",
  "contactEmail": "manager@centracafe.example",
  "contactPhone": "6491234567",
  "location": {
   "street": "123 Example Street",
   "suburb": "Newtown",
   "city": "Wellington",
   "state": "Wellington",
   "postCode": "6021",
   "country": "NZ"
  }
 },
 "assetProgram": {
  "assetProgramId": "YGRo6TYYSxH3js7",
  "params": {
   "settlementAccountNumber": "12-3456-7890123-00",
   "chargeAccountNumber": "12-3456-7890123-01",
   "externalMerchantId": "ext-merchant-789"
  }
 },
 "salesChannels": [
  {
   "params": {
    "vendor": "Example Vendor",
    "reseller": "Example Reseller",
    "deviceId": "device-001",
    "serialNumber": "SN123456",
    "deviceModel": "Example Terminal Model X1"
   }
  },
  {
   "params": {
    "vendor": "Example Vendor",
    "reseller": "Example Reseller",
    "deviceId": "device-002",
    "serialNumber": "SN123457",
    "deviceModel": "Example Terminal Model X1"
   }
  }
 ],
 "metadata": {
  "referenceId": "ref-12345",
  "notes": "Onboarding request submitted via partner portal"
 }
}
'

{
  "id": "bo_1a2b3c4d5e6f7g8h9i0j",
  "legalName": "Centrapay Cafe Limited",
  "tradingName": "Centrapay Cafe",
  "contactEmail": "admin@centracafe.example",
  "contactName": "Alice Anderson",
  "externalId": "ext-cafe-001",
  "taxNumber": {
    "value": "123-456-789",
    "type": "nz-gst"
  },
  "merchant": {
    "name": "Centrapay Cafe",
    "categoryCode": "5812",
    "type": "physical",
    "contactName": "Bob Brown",
    "contactEmail": "manager@centracafe.example",
    "contactPhone": "6491234567",
    "location": {
      "street": "123 Example Street",
      "suburb": "Newtown",
      "city": "Wellington",
      "state": "Wellington",
      "postCode": "6021",
      "country": "NZ"
    }
  },
  "assetProgram": {
    "assetProgramId": "YGRo6TYYSxH3js7",
    "params": {
      "settlementAccountNumber": "12-3456-7890123-00",
      "chargeAccountNumber": "12-3456-7890123-01",
      "externalMerchantId": "ext-merchant-789"
    }
  },
  "salesChannels": [
    {
      "params": {
        "vendor": "example vendor",
        "reseller": "example reseller",
        "deviceId": "device-001",
        "serialNumber": "SN123456",
        "deviceModel": "Example Terminal Model X1"
      }
    },
    {
      "params": {
        "vendor": "example vendor",
        "reseller": "example reseller",
        "deviceId": "device-002",
        "serialNumber": "SN123457",
        "deviceModel": "Example Terminal Model X1"
      }
    }
  ],
  "metadata": {
    "referenceId": "ref-12345",
    "notes": "Onboarding request submitted via partner portal"
  },
  "status": "pending",
  "createdAt": "2025-07-25T10:30:00.000Z",
  "createdBy": "Jaim1Cu1Q55uooxSens6yk"
}

Get an Onboarding Request

This endpoint retrieves an existing onboarding request by its ID.

Required Permissions

The API key must have the business:onboard permission for the account that created the onboarding request.

Path Parameters

Attributes

id
string required

The onboarding request ID, prefixed with bo_.

curl -X GET \
 https://service.centrapay.com/api/businesses/onboard/bo_1a2b3c4d5e6f7g8h9i0j \
 -H 'x-api-key: <TOKEN>'

{
  "id": "bo_1a2b3c4d5e6f7g8h9i0j",
  "legalName": "Centrapay Cafe Limited",
  "tradingName": "Centrapay Cafe",
  "contactEmail": "admin@centracafe.example",
  "contactName": "Alice Anderson",
  "externalId": "ext-cafe-001",
  "taxNumber": {
    "value": "123-456-789",
    "type": "nz-gst"
  },
  "merchant": {
    "name": "Centrapay Cafe",
    "categoryCode": "5812",
    "type": "physical",
    "contactName": "Bob Brown",
    "contactEmail": "manager@centracafe.example",
    "contactPhone": "6491234567",
    "location": {
      "street": "123 Example Street",
      "suburb": "Newtown",
      "city": "Wellington",
      "state": "Wellington",
      "postCode": "6021",
      "country": "NZ"
    }
  },
  "assetProgram": {
    "assetProgramId": "YGRo6TYYSxH3js7",
    "params": {
      "settlementAccountNumber": "12-3456-7890123-00",
      "chargeAccountNumber": "12-3456-7890123-01",
      "externalMerchantId": "ext-merchant-789"
    }
  },
  "salesChannels": [
    {
      "params": {
        "vendor": "example vendor",
        "reseller": "example reseller",
        "deviceId": "device-001",
        "serialNumber": "SN123456",
        "deviceModel": "Example Terminal Model X1"
      }
    },
    {
      "params": {
        "vendor": "example vendor",
        "reseller": "example reseller",
        "deviceId": "device-002",
        "serialNumber": "SN123457",
        "deviceModel": "Example Terminal Model X1"
      }
    }
  ],
  "metadata": {
    "referenceId": "ref-12345",
    "notes": "Onboarding request submitted via partner portal"
  },
  "status": "pending",
  "createdAt": "2025-07-25T10:30:00.000Z",
  "createdBy": "Jaim1Cu1Q55uooxSens6yk"
}

API Behavior

Glossary

Onboarding Request Model

Attributes

id

nzbn

legalName

tradingName

contactEmail

contactName

externalId

taxNumber

merchant

assetProgram

salesChannels

metadata

createdAt

createdBy

status

Tax Number Model

Attributes

value

type

Merchant Model

Attributes

name

categoryCode

type

contactName

contactEmail

contactPhone

location

Location Model

Attributes

street

suburb

city

state

postCode

country

Asset Program Model

Attributes

assetProgramId

params.settlementAccountNumber

params.chargeAccountNumber

params.externalMerchantId

Sales Channel Model

Attributes

params.vendor

params.reseller

params.deviceId

params.serialNumber

params.deviceModel

Create an Onboarding Request

Idempotency

Required Permissions

Request Body

Attributes

nzbn

legalName

tradingName

contactEmail

contactName

externalId

taxNumber

merchant

assetProgram

salesChannels

metadata

Error Responses

Bad Request

Unauthorized

DUPLICATE_EXTERNAL_ID

INVALID_ASSET_PROGRAM

INVALID_SALES_CHANNEL

Get an Onboarding Request

Required Permissions

Path Parameters

Attributes

id