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 /
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_ | The bank account in the settlement config does not belong to the same account. |
403 | ACCOUNT_ | The merchant’s “country” does not match the “region” on the Account. |
Get a Merchant
GET /
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 /
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 /
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_ | The bank account in the settlement config does not belong to the same account. |
Set Merchant Onboarding Status
POST /
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 /
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"
}
]
}