Gateway Settings

Read and write a merchant's EFT gateway settings: the type model, the writable allowlist, compare-before-write, and copying from a sibling.

Each merchant has a set of EFT gateway settings that control how its payments behave. This API lets you read all of them (with the metadata you need to build against them) and write the subset that partners are permitted to change.

Reading settings

GET /v1/merchants/{merchantId}/settings returns every setting with its definition:

curl -s https://dev.boapi.ppgw.net/v1/merchants/10544/settings \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "merchantid": 10544,
  "settings": [
    {
      "key": "CUSTOM_GATEWAY_NAME",
      "label": "Custom gateway name",
      "value": "Acme Pay",
      "type": 0,
      "typename": "text",
      "validation": "Free text.",
      "writable": true
    },
    {
      "key": "MINIMUM_EFT_AMOUNT",
      "label": "Minimum EFT amount",
      "value": "10",
      "type": 1,
      "typename": "number",
      "validation": "Numeric value.",
      "writable": true
    }
  ]
}

Each entry tells you everything needed to validate a value client-side rather than discovering the rule through a 400:

type / typename — the value type (see the table below).
validation — a plain-language statement of what a valid value looks like.
writable — true if you may change it through this API, false if it is read-only to partners. Read-only keys are still returned so you can see the full picture.

The type model

`type`	`typename`	Validation	Notes
`0`	`text`	Free text.	Includes redirect and webhook URL keys — there is no dedicated URL type.
`1`	`number`	Numeric value.	A non-numeric value is rejected.
`2`	`checkbox`	`1` to enable, anything else is stored as `0`.	Booleans on the wire are the strings `"1"` / `"0"`.
`3`	`colour`	Free text; the backoffice presents a colour picker.	Typically a hex colour.
`4`	`asset`	Reference to an existing uploaded asset.	This API has no upload endpoint, so you can only reference an asset that already exists.

Writing settings

PUT /v1/merchants/{merchantId}/settings. Supply a settings map of key → value:

curl -s -X PUT https://dev.boapi.ppgw.net/v1/merchants/10544/settings \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "settings": {
      "CUSTOM_GATEWAY_NAME": "Acme Pay",
      "MINIMUM_EFT_AMOUNT": "10",
      "CHECK_FNBSB": "1"
    }
  }'

{
  "merchantid": 10544,
  "updated": 2,
  "applied": ["CUSTOM_GATEWAY_NAME", "MINIMUM_EFT_AMOUNT"],
  "copied": false
}

Three rules govern a write:

Allowlist. Only keys on the partner-writable allowlist may be written. A key outside it is rejected — the whole request fails with validation_failed, it is not silently dropped. This is deliberate: you learn immediately that a key isn't writable rather than believing a change took effect when it didn't.
Type check. The value must satisfy the key's type. A non-numeric value for a number key is rejected; a checkbox value coerces to 1/0.
Compare-before-write. A key sent with its existing value produces no write and does not count toward updated. In the example above, CHECK_FNBSB was already 1, so updated is 2, not 3, and applied lists only the keys that actually changed.

Values are stored as text. Send checkbox values as "1" or "0" and numbers as numeric strings (e.g. "10") — the settings map is a string-to-string object.

Copy from a sibling merchant

Instead of a settings map, you can copy every writable setting from another merchant in your scope:

{ "copy_settings_from": 10231 }

When copy_settings_from is present it overrides settings entirely — copy wins, the two are never merged, so you are never guessing which source set a given key. The response comes back with "copied": true. Naming a merchant outside your scope returns source_out_of_scope.

What replication means for you

These settings live on the live payment gateway. A write here propagates to the gateway automatically — there is no separate "publish" step. That is exactly why compare-before-write matters: an unchanged value produces no write and therefore no needless propagation. Send only what you intend to change, and trust that unchanged keys stay untouched.