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: always true for the keys returned. Only the partner-writable settings are exposed through this API; settings managed in the backoffice are not returned at all.

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 to 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, so 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 (for example "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.

Settings Propagation

These settings propagate to the gateway automatically. Ensure that updates to live merchant settings are checked and validated before submission.