Go to home page

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

    arrayexperimental

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

Payment Option Config Model

Attributes

  • type

    stringrequired

    Type of payment method. See supported payment types below.

  • walletId

    string

    Merchant's Centrapay Settlement Wallet Asset to receive payments. Optional for centrapay.nzd types, if not supplied then a settlement wallet asset 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

    arrayrequired

    A list of Payment Option Configs.

  • allowedRedirectUrls

    arrayexperimental

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

  • 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 by Id

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

Request
curl -X GET https://service.centrapay.com/api/merchant-configs/mc_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

    arrayrequired

    A list of Payment Option Configs.

  • allowedRedirectUrls

    arrayexperimental

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

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

Get Merchant Config deprecated

This endpoint allows you to retrieve a Merchant Config by Merchant id and Merchant Config 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"
    }
  ]
}