Merchants

A merchant is an initiator of Payment Requests. A Merchant has Merchant Configs which define the payment methods available for a Payment Request.

Merchant Model

Attributes

id
string
Merchant's unique identifier.
accountId
string
Id of Merchant's owning Centrapay account.
name
string
Merchant name.
country
string
Merchant ISO 3166 country code. Must match the "region" on the Account.
createdAt
timestamp
When the Merchant was created.
createdBy
crn
The User or API Key that created the Merchant.
updatedAt
timestamp
When the Merchant was updated.
updatedBy
crn
The User or API Key that updated the Merchant.
test
boolean
Flag indicating merchant is for testing.
settlementConfig
object
Merchant Settlement Config.
type
string
Valid values: physical or e-commerce. Merchants with a physical store should provide type physical. Online only merchants should provide type e-commerce. E-commerce merchants will not be displayed in the store finder.
location
location
Physical Location of Merchant. It is highly recommended that you provide this otherwise, users won't be able to find you with our Merchant Search API if they perform a origin + distance query. This field is forbidden when the provided type is e-commerce.
onboardingStatus
string
The onboarding status of the Merchant. See Onboarding Statuses for possible values.
onboardingStatusReason
string
The reason associated with the Onboarding Status. See Onboarding Status Reasons for possible values.
categoryCode
string
The category code assigned to the Merchant by Centrapay. Must be 4 digits.
metadata
object
Arbitrary key-value data associated with the Merchant. See Set Merchant Metadata.

Onboarding Statuses

Status	Description	Allowed Reasons
applied	Identifies merchants that have registered to be activated for the Centrapay service.
provisioning	Identifies merchants that are in the process of being activated for the Centrapay service.
active	Identifies merchants that have been activated for Centrapay services successfully (i.e. they have successfully created a Payment Request).
deactivated	Identifies merchants that have been de-registered for the Centrapay service.	duplicate, data-quality-issues, no-response, change-of-ownership, centrapay-discontinued.
on-hold	Identifies merchants that have been placed on hold.	seasonal-business-closure, incompatible-terminal, no-response

Onboarding Status Reasons

Reason	Description
duplicate	The merchant already exists in the Centrapay system.
data-quality-issues	Data quality issues are preventing the merchant from onboarding.
no-response	No response has been received from the merchant.
change-of-ownership	The merchant has changed ownership.
centrapay-discontinued	The merchant is no longer using Centrapay.
seasonal-business-closure	The merchant has closed temporarily.
incompatible-terminal	The merchant does not have any compatible terminals.

Settlement Config Model

Attributes

bankAccountId
string
The id of the bank account funds should be settled into. This must belong to the account

Merchant Search Result Model

Attributes

id
string
Merchant's unique identifier
name
string
Merchant's name
acceptedAssets
array
List of assets accepted by the merchant. See Accepted Asset Model.
location
location
Physical location of the merchant
accountId
string
Id of Merchant's owning Centrapay account.
categoryCode
string
The category code assigned to the Merchant by Centrapay. Must be 4 digits.
loyaltyPrograms
array
Array of Loyalty Programs that the merchant supports. If auth is provided, we will also compute whether the caller is a member of each loyalty program.

Accepted Asset Model

Attributes

assetType
string
The type of the asset
products
object
List of Products supported by the asset type. Only available for centrapay.token asset type.

Product Model

Attributes

id
string
Product's unique identifier.

Create Merchant

This endpoint allows you to create a Merchant.

Attributes

accountId
stringrequired
Id of Merchant's owning Centrapay account.
name
stringrequired
Merchant name.
country
stringrequired
Merchant ISO 3166 country code. Must match the "region" on the Account.
test
booleanrequired
Flag indicating merchant is for testing.
settlementConfig
object
Merchant Settlement Config.
type
string
Valid values: physical or e-commerce.
location
location
Physical Location of Merchant. It is highly recommended that you provide this otherwise, users won't be able to find you with our Merchant Search API if they perform a origin + distance query.
categoryCode
string
The category code assigned to the Merchant by Centrapay. Must be 4 digits.

Errors

BANK_ACCOUNT_MISMATCH
403
The bank account in the settlement config does not belong to the same account.
ACCOUNT_REGION_MISMATCH
403
The merchant's "country" does not match the "region" on the Account.

curl -X POST https://service.centrapay.com/api/merchants \
-H 'content-type: application/json' \
-H 'x-api-key: <TOKEN>' \
-d '{
  "accountId": "C4QnjXvj8At6SMsEN4LRi9",
  "name": "Centrapay Cafe Auckland",
  "country": "NZ",
  "test": false
}'

{
  "id": "5ee0c486308f590260d9a07f",
  "accountId": "C4QnjXvj8At6SMsEN4LRi9",
  "name": "Centrapay Cafe Auckland",
  "country": "NZ",
  "test": false,
  "onboardingStatus": "applied",
  "createdAt": "2021-11-12T01:17:46.499Z",
  "updatedAt": "2021-11-12T01:17:46.499Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey"
}

Get Merchant

This endpoint allows you to retrieve a Merchant by id.

curl -X GET https://service.centrapay.com/api/merchants/5ee0c486308f590260d9a07f \
-H 'x-api-key: <TOKEN>'

{
  "id": "5ee0c486308f590260d9a07f",
  "accountId": "yqwyya0rzz3vvshqw0474u89xtj5fn",
  "name": "Parisian - Brown",
  "test": false,
  "country": "AD",
  "onboardingStatus": "applied",
  "createdAt": "2021-11-12T01:17:46.499Z",
  "updatedAt": "2021-11-12T01:17:46.499Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey"
}

List Merchants for Account

This endpoint allows you to retrieve a paginated list of Merchants attached to an Account.

curl -X GET https://service.centrapay.com/api/accounts/Jaim1Cu1Q55uooxSens6yk/merchants \
-H 'x-api-key: <TOKEN>'

{
  "items": [
    {
      "accountId": "Jaim1Cu1Q55uooxSens6yk",
      "country": "BT",
      "id": "5f6bf6ff81552101f8ff6122",
      "name": "Adams, Runolfsdottir and Botsford",
      "test": true,
      "onboardingStatus": "applied",
      "createdAt": "2021-11-12T01:17:46.499Z",
      "updatedAt": "2021-11-12T01:17:46.499Z",
      "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
      "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey"
    },
    {
      "accountId": "Jaim1Cu1Q55uooxSens6yk",
      "country": "GM",
      "id": "5f6bf6ff81552101f8ff6123",
      "name": "Vandervort Inc",
      "test": false,
      "onboardingStatus": "applied",
      "createdAt": "2021-11-12T01:17:46.499Z",
      "updatedAt": "2021-11-12T01:17:46.499Z",
      "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
      "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey"
    }
  ]
}

Update Merchant

This endpoint allows you to update a Merchant.

Attributes

name
string
Merchant name.
settlementConfig
object
Merchant Settlement Config.
location
location
Physical Location of Merchant. It is highly recommended that you provide this otherwise, users won't be able to find you with our Merchant Search API if they perform a origin + distance query.
categoryCode
string
The category code assigned to the Merchant by Centrapay. Must be 4 digits.

Errors

BANK_ACCOUNT_MISMATCH
403
The bank account in the settlement config does not belong to the same account.

curl -X PUT https://service.centrapay.com/api/merchants/5ee0c486308f590260d9a07f \
-H 'content-type: application/json' \
-H 'x-api-key: <TOKEN>' \
-d '{
  "name": "Centrapay Café",
  "location": {
    "lat": "-36.8483579",
    "lng": "174.7725834",
    "city": "Auckland",
    "postCode": "1010",
    "country": "NZ"
  },
  "settlementConfig": {
    "bankAccountId": "WRhAxxWpTKb5U7pXyxQjjY"
  }
}'

{
  "id": "5ee0c486308f590260d9a07f",
  "accountId": "yqwyya0rzz3vvshqw0474u89xtj5fn",
  "name": "Centrapay Café",
  "test": false,
  "country": "NZ",
  "onboardingStatus": "applied",
  "location": {
    "lat": "-36.8483579",
    "lng": "174.7725834",
    "city": "Auckland",
    "postCode": "1010",
    "country": "NZ"
  },
  "settlementConfig": {
    "bankAccountId": "WRhAxxWpTKb5U7pXyxQjjY"
  },
  "createdAt": "2021-09-12T01:11:22.491Z",
  "updatedAt": "2021-11-12T01:17:46.499Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey"
}

Set Merchant Onboarding Status

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

Attributes

onboardingStatus
stringrequired
The onboarding status of the Merchant. See Onboarding Statuses for possible values.
onboardingStatusReason
string
The reason associated with the Onboarding Status. Required if the onboardingStatus is on-hold or deactivated. See Onboarding Status Reasons for possible values.

curl -X POST https://service.centrapay.com/api/merchants/5ee0c486308f590260d9a07f/set-onboarding-status \
-H 'content-type: application/json' \
-H 'x-api-key: <TOKEN>' \
-d '{
  "onboardingStatus": "deactivated",
  "onboardingStatusReason": "change-of-ownership"
}'

{
  "type": "set-onboarding-status",
  "onboardingStatus": "deactivated",
  "onboardingStatusReason": "change-of-ownership",
  "merchantId": "MhocUmpxxmgdHjr7DgKoKw",
  "createdAt": "2021-09-12T01:11:22.491Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "activityNumber": "2"
}

Set Merchant Metadata

This endpoint allows you to set metadata on a Merchant. Metadata is merged with any existing keys — only the keys provided in the request are affected. To remove a key, set its value to an empty string.

Attributes

metadata
objectrequired
A map of key-value pairs to attach to the Merchant. Keys must be alphanumeric with underscores or dashes (max 64 characters). Values must be strings (max 256 characters). A maximum of 10 keys is allowed.

curl -X POST https://service.centrapay.com/api/merchants/5ee0c486308f590260d9a07f/metadata \
-H 'content-type: application/json' \
-H 'x-api-key: <TOKEN>' \
-d '{
  "metadata": {
    "deviceId": "device-001"
  }
}'

{
  "merchantId": "MhocUmpxxmgdHjr7DgKoKw",
  "createdAt": "2021-09-12T01:11:22.491Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "metadata": {
    "deviceId": "device-001"
  }
}

Search Merchants

Returns a paginated response of Merchant Search Results that match the search query. This endpoint does not require Auth.

Query Parameters

Attributes

origin
string
The point to be searched around, formatted as a latitude,longitude
distance
number
The distance from the origin to be searched around in km
asset
string
A string of the format assetType, productId describing the asset where assetType is the type of asset to filter the merchants by and productId is the asset's collectionId for centrapay.token and centrapay.ledger asset types.
name
string
Name of the merchant
pageKey
string
pageKey of next merchant to fetch
paginationLimit
string
Maximum amount of merchants to return
accountId
string
The ID of the Account that owns the merchant.
categoryCode
string
The category code assigned to the Merchant by Centrapay. Must be 4 digits.
test
boolean
Set to true to search for test merchants.
hasLoyaltyProgram
boolean
Set to true to only return merchants with public loyalty programs.

curl -X GET 'https://service.centrapay.com/api/merchants/search?origin=123.42%2C32.22&distance=100&asset=epay.main%2C37873&pageKey=10&paginationLimit=10&categoryCode=1740&test=true&hasLoyaltyProgram=true'

{
  "totalItems": 100,
  "items": [
    {
      "id": "M001",
      "accountId": "Jaim1Cu1Q55uooxSens6yk",
      "name": "Store 1",
      "acceptedAssets": [
        {
          "assetType": "centrapay.nzd.main"
        },
        {
          "assetType": "epay.main"
        },
        {
          "assetType": "centrapay.token.main",
          "products": [
            {
              "id": "Xv990BzkgfoDS7bBls50pd"
            }
          ]
        }
      ],
      "location": {
        "lat": "123.45",
        "lng": "32.21",
        "city": "Auckland",
        "country": "NZ",
        "postCode": "1234",
        "state": "Auckland",
        "street": "2 Street Street",
        "suburb": "Place"
      },
      "categoryCode": "1740",
      "loyaltyPrograms": [
        {
          "id": "5f6bf6ff81552101f8ff6122",
          "isMember": true
        },
        {
          "id": "5f6bf6ff81552101f8ff6122",
          "isMember": false
        }
      ]
    }
  ],
  "nextPageKey": "20"
}

List Merchants deprecated

Returns a paginated list of Merchants which belong to the authenticated subject.

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

{
  "items": [
    {
      "accountId": "3xsjxxwmnpkunjbcpekyekc84rzxr4",
      "country": "BT",
      "id": "5f6bf6ff81552101f8ff6122",
      "name": "Adams, Runolfsdottir and Botsford",
      "test": true,
      "onboardingStatus": "applied",
      "createdAt": "2021-11-12T01:17:46.499Z",
      "updatedAt": "2021-11-12T01:17:46.499Z",
      "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
      "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey"
    },
    {
      "accountId": "3xsjxxwmnpkunjbcpekyekc84rzxr4",
      "country": "GM",
      "id": "5f6bf6ff81552101f8ff6123",
      "name": "Vandervort Inc",
      "test": false,
      "onboardingStatus": "applied",
      "createdAt": "2021-11-12T01:17:46.499Z",
      "updatedAt": "2021-11-12T01:17:46.499Z",
      "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
      "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey"
    },
    {
      "accountId": "3xsjxxwmnpkunjbcpekyekc84rzxr4",
      "country": "MZ",
      "id": "5f6bf6ff81552101f8ff6124",
      "name": "West, O'Reilly and Huels",
      "test": true,
      "onboardingStatus": "applied",
      "createdAt": "2021-11-12T01:17:46.499Z",
      "updatedAt": "2021-11-12T01:17:46.499Z",
      "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
      "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey"
    }
  ]
}

Merchant Model

Attributes

id

accountId

name

country

createdAt

createdBy

updatedAt

updatedBy

test

settlementConfig

type

location

onboardingStatus

onboardingStatusReason

categoryCode

metadata

Onboarding Statuses

Onboarding Status Reasons

Settlement Config Model

Attributes

bankAccountId

Merchant Search Result Model

Attributes

id

name

acceptedAssets

location

accountId

categoryCode

loyaltyPrograms

Accepted Asset Model

Attributes

assetType

products

Product Model

Attributes

id

Create Merchant

Attributes

accountId

name

country

test

settlementConfig

type

location

categoryCode

Errors

BANK_ACCOUNT_MISMATCH

ACCOUNT_REGION_MISMATCH

Get Merchant

List Merchants for Account

Update Merchant

Attributes

name

settlementConfig

location

categoryCode

Errors

BANK_ACCOUNT_MISMATCH

Set Merchant Onboarding Status

Attributes

onboardingStatus

onboardingStatusReason

Set Merchant Metadata

Attributes

metadata

Search Merchants

Query Parameters

Attributes

origin

distance

asset

name

pageKey

paginationLimit

accountId

categoryCode