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
stringrequired
Registered legal name of the business (3-100 characters).
tradingName
string
Trading name of the business (3-100 characters). Defaults to legalName if omitted.
location
objectrequired
Physical location of the business. See Location Model.
contactEmail
stringrequired
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
objectrequired
Merchant information including name, location, and contact details. See Merchant Model.
assetProgram
objectrequired
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.
sendInvitation
boolean
Whether to send the onboarding sign-up invitation email to the contact. Defaults to true.
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
stringrequired
The GST number (e.g., 123-456-789).
type
stringrequired
Must be nz-gst.

Merchant Model

Attributes

name
stringrequired
Display name of the merchant (2-100 characters).
categoryCode
stringrequired
ISO 18245 Merchant category code (4 digits).
type
stringrequired
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.
redirectUrls
array
Allowed redirect URLs for e-commerce merchants. Required if type is e-commerce.
searchHidden
boolean
Whether the merchant should be hidden from the Merchant Search API.

Location Model

Attributes

street
stringrequired
Street number and name (max 255 characters).
suburb
string
Suburb (max 255 characters).
city
stringrequired
Town or city (max 255 characters).
state
string
Region or state (max 255 characters).
postCode
string
Postal code (4-10 digits).
country
stringrequired
ISO 3166-1 alpha-2 country code (e.g., NZ).

Asset Program Model

Attributes

assetProgramId
stringrequired
The unique identifier of the asset program that the business will accept (max 35 characters).
params.settlementAccountNumber
string
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. Only allowed if settlementAccountNumber is also provided.
params.externalMerchantId
string
Merchant identifier in the partner system (max 35 characters). If omitted, Centrapay will assign one.

Sales Channel Model

Attributes

params.vendor
stringrequired
Terminal software/hardware vendor (3-100 characters).
params.reseller
string
Terminal distributor (3-100 characters).
params.deviceId
string
Software device ID (max 35 characters). Required unless vendor is nomad.
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
stringrequired
Registered legal name (3-100 characters).
tradingName
string
Trading name (3-100 characters). Defaults to legalName if omitted.
location
objectrequired
Physical location of the business. See Location Model.
contactEmail
stringrequired
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
objectrequired
Merchant details. See Merchant Model.
assetProgram
objectrequired
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.
sendInvitation
boolean
Whether to send the onboarding sign-up invitation email to the contact. Defaults to true.

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.

LIVENESS_MISMATCH

403

The account and asset program do not match on test/live status.

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",
  "location": {
    "street": "1 Head Office Way",
    "city": "Wellington",
    "state": "Wellington",
    "postCode": "6011",
    "country": "NZ"
  },
  "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",
  "location": {
    "street": "1 Head Office Way",
    "city": "Wellington",
    "state": "Wellington",
    "postCode": "6011",
    "country": "NZ"
  },
  "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"
}

E-commerce Example

Example request for onboarding an e-commerce merchant. E-commerce merchants require redirectUrls instead of a location, and typically use an e-commerce platform such as Shopify as their sales channel.

curl -X POST https://service.centrapay.com/api/businesses/onboard \
-H 'content-type: application/json' \
-H 'x-api-key: <TOKEN>' \
-d '{
  "legalName": "Centrapay Online Limited",
  "tradingName": "Centrapay Online Store",
  "contactEmail": "admin@centraonline.example",
  "contactName": "Alice Anderson",
  "externalId": "ext-online-001",
  "taxNumber": {
    "value": "123-456-789",
    "type": "nz-gst"
  },
  "merchant": {
    "name": "Centrapay Online Store",
    "categoryCode": "5999",
    "type": "e-commerce",
    "contactName": "Carol Chen",
    "contactEmail": "ecommerce@centraonline.example",
    "contactPhone": "6491234568",
    "redirectUrls": [
      "https://centraonline.example/checkout/callback"
    ]
  },
  "assetProgram": {
    "assetProgramId": "YGRo6TYYSxH3js7",
    "params": {
      "settlementAccountNumber": "12-3456-7890123-00",
      "externalMerchantId": "ext-merchant-online-789"
    }
  },
  "salesChannels": [
    {
      "params": {
        "vendor": "shopify",
        "deviceId": "centraonline.myshopify.com"
      }
    }
  ],
  "metadata": {
    "referenceId": "ref-67890"
  }
}'

{
  "id": "bo_2b3c4d5e6f7g8h9i0j1k",
  "legalName": "Centrapay Online Limited",
  "tradingName": "Centrapay Online Store",
  "contactEmail": "admin@centraonline.example",
  "contactName": "Alice Anderson",
  "externalId": "ext-online-001",
  "taxNumber": {
    "value": "123-456-789",
    "type": "nz-gst"
  },
  "merchant": {
    "name": "Centrapay Online Store",
    "categoryCode": "5999",
    "type": "e-commerce",
    "contactName": "Carol Chen",
    "contactEmail": "ecommerce@centraonline.example",
    "contactPhone": "6491234568",
    "redirectUrls": [
      "https://centraonline.example/checkout/callback"
    ]
  },
  "assetProgram": {
    "assetProgramId": "YGRo6TYYSxH3js7",
    "params": {
      "settlementAccountNumber": "12-3456-7890123-00",
      "externalMerchantId": "ext-merchant-online-789"
    }
  },
  "salesChannels": [
    {
      "params": {
        "vendor": "shopify",
        "deviceId": "centraonline.myshopify.com"
      }
    }
  ],
  "metadata": {
    "referenceId": "ref-67890"
  },
  "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
stringrequired
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",
  "location": {
    "street": "1 Head Office Way",
    "city": "Wellington",
    "state": "Wellington",
    "postCode": "6011",
    "country": "NZ"
  },
  "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

location

contactEmail

contactName

externalId

taxNumber

merchant

assetProgram

salesChannels

metadata

sendInvitation

createdAt

createdBy

status

Tax Number Model

Attributes

value

type

Merchant Model

Attributes

name

categoryCode

type

contactName

contactEmail

contactPhone

location

redirectUrls

searchHidden

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

location

contactEmail

contactName

externalId

taxNumber

merchant

assetProgram

salesChannels

metadata

sendInvitation

Error Responses

Bad Request

Unauthorized

DUPLICATE_EXTERNAL_ID

INVALID_ASSET_PROGRAM