Merchants

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.

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
  • refundConfig

    object

    Merchant Refund 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.

  • 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.

Onboarding Statuses

StatusDescriptionAllowed Reasons
appliedIdentifies merchants that have registered to be activated for the Centrapay service.
provisioningIdentifies merchants that are in the process of being activated for the Centrapay service.
activeIdentifies merchants that have been activated for Centrapay services successfully (i.e. they have successfully created a Payment Request).
deactivatedIdentifies merchants that have been de-registered for the Centrapay service.duplicate, data-quality-issues, no-response, change-of-ownership, centrapay-discontinued.
on-holdIdentifies merchants that have been placed on hold.seasonal-business-closure, incompatible-terminal, no-response

Onboarding Status Reasons

ReasonDescription
duplicateThe merchant already exists in the Centrapay system.
data-quality-issuesData quality issues are preventing the merchant from onboarding.
no-responseNo response has been received from the merchant.
change-of-ownershipThe merchant has changed ownership.
centrapay-discontinuedThe merchant is no longer using Centrapay.
seasonal-business-closureThe merchant has closed temporarily.
incompatible-terminalThe merchant does not have any compatible terminals.

Attributes

  • bankAccountId

    string

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


Attributes

  • bankAccountId

    string

    The id of the bank account that will be used when processing refunds. The bank account must belong to the same account as the merchant.

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


Attributes


Attributes

  • id

    string

    Product’s unique identifier.


POST/api/merchants

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
  • refundConfig

    object

    Merchant Refund 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.

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}

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

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}

This endpoint allows you to update a Merchant.

Attributes

  • name

    string

    Merchant name.

  • settlementConfig

    object
  • refundConfig

    object

    Merchant Refund 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.

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

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

Attributes

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

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 productCode for epay.nzd  API  asset types or 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.nzd.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.nzd.main",
          "products": [
            {
              "id": "37873"
            },
            {
              "id": "38183"
            }
          ]
        },
        {
          "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

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