Go to home page
Docs API Reference

Merchant Configs

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

Merchant Config Model

Attributes

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

  • allowedRedirectUrls

    array experimental

    Allowed prefixes for the redirectUrl property on Payment Requests created with this Config.

Payment Option Config Model

Attributes

  • type

    string required

    Type of payment method. See supported payment types below.

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

  • 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 epay, stadius, quartz, payap-debit and uplinkapi.test types.

  • collectionIds

    string

    Id of the Token Collection , can be discount collection type. Required for centrapay.ledger types.

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

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

Create Merchant Config

This endpoint allows you to create a Merchant Config for a Merchant.

Attributes

  • paymentOptions

    array required

    A list of Payment Option Configs .

  • allowedRedirectUrls

    array experimental

    Allowed prefixes for the redirectUrl property on Payment Requests created with this Config.

Errors

  • INVALID_WALLET_TYPE

    403

    walletId does not belong to a Settlement Wallet .

  • LIVENESS_MISMATCH

    403

    Only Merchants with the test flag can have merchant configs with test assets, vice versa

  • COLLECTIONS_INVALID

    403

    An item in the collectionIds array does not exist or does not belong to a supported collection type.

Request
curl -X POST \
 https://service.centrapay.com/api/merchants/5ee0c486308f590260d9a07f/configs \
 -H 'content-type: application/json' \
 -H 'x-api-key: <TOKEN>' \
 -d '
{
 "paymentOptions": [
  {
   "type": "centrapay.nzd.main",
   "walletId": "1234c486308f3f0a23f0f92b"
  },
  {
   "type": "epay.main",
   "externalMerchantId": "11000021"
  },
  {
   "type": "farmlands.nzd.main",
   "farmlandsMerchantNumber": "DbgY2SyD5M85zkePJjsQEf"
  },
  {
   "type": "quartz.nzd.main",
   "externalMerchantId": "0012399012"
  }
 ]
}
'
Response
{
  "id": "mc_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.main",
      "externalMerchantId": "11000021"
    },
    {
      "type": "farmlands.nzd.main",
      "farmlandsMerchantNumber": "DbgY2SyD5M85zkePJjsQEf"
    },
    {
      "type": "quartz.nzd.main",
      "externalMerchantId": "0012399012"
    }
  ]
}

Get Merchant Config

This endpoint allows you to retrieve a Merchant Config by id.

Request
curl -X GET \
 https://service.centrapay.com/api/merchants/5ee0c486308f590260d9a07f/configs/5ee168e8597be5002af7b454 \
 -H 'x-api-key: <TOKEN>'
Response
{
  "id": "mc_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": "farmlands.nzd.main",
      "farmlandsMerchantNumber": "DbgY2SyD5M85zkePJjsQEf"
    }
  ]
}

List Merchant Configs

This endpoint allows you to retrieve a list of Merchant Configs.

Request
curl -X GET \
 https://service.centrapay.com/api/merchants/5ee0c486308f590260d9a07f/configs \
 -H 'x-api-key: <TOKEN>'
Response
[
  {
    "id": "mc_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": "farmlands.nzd.main",
        "farmlandsMerchantNumber": "DbgY2SyD5M85zkePJjsQEf"
      }
    ]
  },
  {
    "id": "mc_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 Merchant Config

This endpoint allows you to update a Merchant Config.

Attributes

  • paymentOptions

    array required

    A list of Payment Option Configs .

  • allowedRedirectUrls

    array experimental

    Allowed prefixes for the redirectUrl property on Payment Requests created with this Config.

Errors

  • INVALID_WALLET_TYPE

    403

    walletId does not belong to a Settlement Wallet .

  • LIVENESS_MISMATCH

    403

    Only Merchants with the test flag can have merchant configs with test assets, vice versa

  • COLLECTIONS_INVALID

    403

    An item in the collectionIds array does not exist or does not belong to a supported collection type.

Request
curl -X PUT \
 https://service.centrapay.com/api/merchants/5ee0c486308f590260d9a07f/configs/mc_5ee168e8597be5002af7baed \
 -H 'content-type: application/json' \
 -H 'x-api-key: <TOKEN>' \
 -d '
{
 "paymentOptions": [
  {
   "type": "bitcoin.main"
  },
  {
   "type": "centrapay.nzd.test",
   "walletId": "1234c486308f3f0a23f0f92b"
  },
  {
   "type": "farmlands.nzd.main",
   "farmlandsMerchantNumber": "DbgY2SyD5M85zkePJjsQEf"
  }
 ]
}
'
Response
{
  "id": "mc_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"
    }
  ]
}