Link Search Menu Expand Document

Merchant Configs

A Merchant Config defines the available payment options for paying a Payment Request.

Contents

Models

Merchant Config

Required Fields

Field Type Description
paymentOptions Array Array of Payment Option Configs.
createdAt Timestamp When the Merchant Config was created.
createdBy CRN The User or API Key that created the Merchant Config.
updatedAt Timestamp When the Merchant Config was updated.
updatedBy CRN The User or API Key that updated the Merchant Config.

Optional Fields

Field Type Description
allowedRedirectUrls Array Experimental Allowed prefixes for the redirectUrl property on Payment Requests created with this Config.

Payment Option Config

Required Fields

Field Type Description
type String Type of payment method. See supported payment types below.

Optional Fields

Field Type Description
walletId String Merchant’s Centrapay Settlement Wallet to receive payments. Optional for centrapay.nzd types, if not supplied then a settlement wallet may be created and then assigned.
assetId String Merchant’s Centrapay Settlement Asset to receive payments. Optional for kete.nzd and quartz.nzd types, if not supplied then a settlement asset may be created and then assigned.
terminalId String Merchant’s Epay terminal id.
wavesPublicAddress String Merchant’s public waves address. Required for zap.main types.
paypalMerchantAccountId String Id of the PayPal merchants account. Required for paypal.usd and venmo.usd types.
paypalStoreId String Id of the PayPal merchants store. Required for paypal.usd and venmo.usd types.
farmlandsMerchantNumber String Id of the Farmlands merchant that funds will be transferred to.
externalMerchantId String Id of the external merchant. Required for stadius and uplinkapi.test types.

See Asset Types for values that may be present in the type field.

Warning: Test payment options should never be used for live merchant configurations.

Operations

Create a Merchant Config

POST /api/merchants/{merchantId}/configs

curl -X POST https://service.centrapay.com/api/merchants/5ee0c486308f590260d9a07f/configs \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentOptions": [
      {
        "type": "centrapay.nzd.main",
        "walletId": "1234c486308f3f0a23f0f92b"
      },
      {
        "type": "epay.nzd.main",
        "terminalId": "11000021"
      },
      {
        "type": "pocketvouchers"
      },
      {
        "type": "farmlands.nzd.main",
        "farmlandsMerchantNumber": "DbgY2SyD5M85zkePJjsQEf"
      }
    ]
  }'

Example response payload

{
  "id": "5ee168e8597be5002af7b454",
  "merchantId": "5ee0c486308f590260d9a07f",
  "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",
  "paymentOptions": [
    {
      "type": "centrapay.nzd.main",
      "walletId": "1234c486308f3f0a23f0f92b"
    },
    {
      "type": "epay.nzd.main",
      "terminalId": "11000021"
    },
    {
      "type": "pocketvouchers"
    },
    {
      "type": "farmlands.nzd.main",
      "farmlandsMerchantNumber": "DbgY2SyD5M85zkePJjsQEf"
    }
  ]
}

Error Responses

Status Code Description
403 INVALID_WALLET_TYPE walletId does not belong to a Settlement Wallet.
403 LIVENESS_MISMATCH Only Merchants with the test flag can have merchant configs with test assets, vice versa

Get a Merchant Config

GET /api/merchants/{merchantId}/configs/{configId}

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

Example response payload

{
  "id": "5ee168e8597be5002af7b454",
  "merchantId": "5ee0c486308f590260d9a07f",
  "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",
  "paymentOptions": [
    {
      "type": "pocketvouchers"
    },
    {
      "type": "farmlands.nzd.main",
      "farmlandsMerchantNumber": "DbgY2SyD5M85zkePJjsQEf"
    }
  ]
}

List Merchant Configs

GET /api/merchants/{merchantId}/configs

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

Example response payload

[
  {
    "id": "5ee168e8597be5002af7b454",
    "merchantId": "5ee0c486308f590260d9a07f",
    "createdAt": "2021-09-12T01:17:46.499Z",
    "updatedAt": "2021-09-12T01:17:46.499Z",
    "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
    "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
    "paymentOptions": [
      {
        "type": "pocketvouchers"
      },
      {
        "type": "farmlands.nzd.main",
        "farmlandsMerchantNumber": "DbgY2SyD5M85zkePJjsQEf"
      }
    ]
  },
  {
    "id": "5ee168e8597be5002af7baed",
    "merchantId": "5ee0c486308f590260d9a07f",
    "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",
    "paymentOptions": [
      {
        "type": "test"
      }
    ]
  }
]

Update a Merchant Config

PUT /api/merchants/{merchantId}/configs/{configId}

curl -X PUT https://service.centrapay.com/api/merchants/5ee0c486308f590260d9a07f/configs/5ee168e8597be5002af7baed \
  -H "X-Api-Key: $api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "paymentOptions": [
      {
        "type": "bitcoin.main"
      },
      {
        "type": "centrapay.nzd.test",
        "walletId": "1234c486308f3f0a23f0f92b"
      },
      {
        "type": "farmlands.nzd.main",
        "farmlandsMerchantNumber": "DbgY2SyD5M85zkePJjsQEf"
      }
    ]
  }'

Example response payload

{
  "id": "5ee168e8597be5002af7baed",
  "merchantId": "5ee0c486308f590260d9a07f",
  "createdAt": "2021-09-12T01:17:46.499Z",
  "updatedAt": "2021-12-12T01:17:46.499Z",
  "createdBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "updatedBy": "crn:WIj211vFs9cNACwBb04vQw:api-key:MyApiKey",
  "paymentOptions": [
    {
      "type": "bitcoin.main"
    },
    {
      "type": "centrapay.nzd.test",
      "walletId": "1234c486308f3f0a23f0f92b"
    },
    {
      "type": "farmlands.nzd.main",
      "farmlandsMerchantNumber": "DbgY2SyD5M85zkePJjsQEf"
    }
  ]
}

Error Responses

Status Code Description
403 INVALID_WALLET_TYPE walletId does not belong to a Settlement Wallet.
403 LIVENESS_MISMATCH Only Merchants with the test flag can have merchant configs with test assets, vice versa