Merchants - Centrapay Docs

A merchant is an initiator of Payment Requests API . A Merchant has Merchant Configs API 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 API .
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 API of the asset
products
object
List of Products supported by the asset type. Only available for centrapay.token API 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
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 API .
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.

Request

POST/api/merchants

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

Response

{
  "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.

Request

GET/api/merchants/5ee0c486308f590260d9a07f

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

Response

{
  "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 API list of Merchants attached to an Account.

Request

GET/api/accounts/Jaim1Cu1Q55uooxSens6yk/merchants

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

Response

{
  "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.

Request

PUT/api/merchants/5ee0c486308f590260d9a07f

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

Response

{
  "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
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.

Request

POST/api/merchants/5ee0c486308f590260d9a07f/set-onboarding-status

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

Response

{
  "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 API response of Merchant Search Results that match the search query. This endpoint does not require Auth API .

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 API to filter the merchants by and productId is the asset’s collectionId for centrapay.token API asset types.
name
string
Name of the merchant
pageKey
string
pageKey of next merchant to fetch
paginationLimit
string
Maximum amount of merchants to return

Request

GET/api/merchants/search

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>'

Response

{
  "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 API list of Merchants which belong to the authenticated subject.

Request

GET/api/merchants

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

Response

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