Link Search Menu Expand Document
Centrapay Docs

Merchants

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

Contents

Models

Merchant

Mandatory Fields

Field Type Description
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.

Optional Fields

Field Type Description
test Boolean EXPERIMENTAL Flag indicating merchant is for testing.
settlementConfig Settlement Config EXPERIMENTAL Merchant settlement config
location Location EXPERIMENTAL Physical Location of Merchant

Settlement Config

Optional Fields

Field Type Description
bankAccountId String The id of the bank account funds should be settled into. This must belong to the account

Operations

Create a Merchant

POST /api/merchants 

curl -X POST https://service.centrapay.com/api/merchants \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "accountId": "C4QnjXvj8At6SMsEN4LRi9",
    "name": "Centrapay Cafe Auckland",
    "country": "NZ",
    "test": false
  }'

Example response payload 

{
  "id": "5ee0c486308f590260d9a07f",
  "accountId": "yqwyya0rzz3vvshqw0474u89xtj5fn",
  "name": "Centrapay Cafe Auckland",
  "country": "NZ",
  "test": false,
  "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"
}

Error Responses

Status Code Description
403 BANK_ACCOUNT_MISMATCH The bank account in the settlement config does not belong to the same account.
403 ACCOUNT_REGION_MISMATCH The merchant’s “country” does not match the “region” on the Account.

Get a Merchant

GET /api/merchants/{merchantId} 

curl https://service.centrapay.com/api/merchants/5ee0c486308f590260d9a07f \
  -H "X-Api-Key: $api_key"

Example response payload 

{
  "id": "5ee0c486308f590260d9a07f",
  "accountId": "yqwyya0rzz3vvshqw0474u89xtj5fn",
  "name": "Parisian - Brown",
  "test": false,
  "country": "AD",
  "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 all Merchants

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

GET /api/merchants 

curl https://service.centrapay.com/api/merchants \
  -H "X-Api-Key: $api_key"

Example response payload 

{
  "items": [
    {
      "accountId": "3xsjxxwmnpkunjbcpekyekc84rzxr4",
      "country": "BT",
      "id": "5f6bf6ff81552101f8ff6122",
      "name": "Adams, Runolfsdottir and Botsford",
      "test": true,
      "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,
      "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,
      "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

Returns a paginated list of Merchants attached to an Account.

GET /api/accounts/{accountId}/merchants 

curl https://service.centrapay.com/api/accounts/Jaim1Cu1Q55uooxSens6yk/merchants \
  -H "X-Api-Key: $api_key"

Example response payload 

{
  "items": [
    {
      "accountId": "Jaim1Cu1Q55uooxSens6yk",
      "country": "BT",
      "id": "5f6bf6ff81552101f8ff6122",
      "name": "Adams, Runolfsdottir and Botsford",
      "test": true,
      "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,
      "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 a Merchant

PUT /api/merchants/{merchantId} 

curl -X PUT https://service.centrapay.com/api/merchants/5ee0c486308f590260d9a07f \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Centrapay Café",
    "location": {
      "lat": "-36.8483579",
      "lng": "174.7725834",
      "city": "Auckland",
      "postCode": "1010",
      "country": "NZ"
    },
    "settlementConfig": {
      "bankAccountId": "WRhAxxWpTKb5U7pXyxQjjY"
    }
  }'

Example response payload 

{
  "id": "5ee0c486308f590260d9a07f",
  "accountId": "yqwyya0rzz3vvshqw0474u89xtj5fn",
  "name": "Centrapay Café",
  "test": false,
  "country": "NZ",
  "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"
}

Error Responses

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