Merchants - Centrapay Docs

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.

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

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.

POST /api/merchants

Create Merchant

This endpoint allows you to create a Merchant.

Attributes

accountId
string required

Id of Merchant’s owning Centrapay account.
name
string required

Merchant name.
country
string required

Merchant ISO 3166 country code. Must match the “region” on the Account.
test
boolean required

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 /api/merchants/{merchantId}

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"
}

GET /api/accounts/{accountId}/merchants

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"
    }
  ]
}

PUT /api/merchants/{merchantId}

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"
}

POST /api/merchants/{merchantId}/set-onboarding-status

Set Merchant Onboarding Status

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

Attributes

onboardingStatus
string required

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"
}

GET /api/merchants/search

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 asset types.
name
string

Name of the merchant
pageKey
string

pageKey of next merchant to fetch
paginationLimit
string

Maximum amount of merchants to return

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' \
 -H 'x-api-key: <TOKEN>'

{
  "totalItems": 100,
  "items": [
    {
      "id": "M001",
      "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"
      }
    }
  ],
  "nextPageKey": "20"
}

GET /api/merchants

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

Onboarding Statuses

Onboarding Status Reasons

Settlement Config Model

Attributes

bankAccountId

Merchant Search Result Model

Attributes

id

name

acceptedAssets

location

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

Search Merchants

Query Parameters

Attributes

origin

distance

asset

name

pageKey

paginationLimit

List Merchants deprecated