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.
onboardingStatus String The onboarding status of the Merchant. See Onboarding Statuses for possible values.

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.
onboardingStatusReason String The reason associated with the Onboarding Status. See Onboarding Status Reasons for possible values.

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.

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

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

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

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

Error Responses

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

Set Merchant Onboarding Status

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

curl -X POST https://service.centrapay.com/api/merchants/5ee0c486308f590260d9a07f/set-onboarding-status \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "onboardingStatus": "deactivated",
    "onboardingStatusReason": "change-of-ownership"
  }'

Example response payload 

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

List all Merchants DEPRECATED

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