Update a payment method

PUT /api/financial/payment-methods/{id}

Products: Operator (FOH)
Features: Front of House Generic Access (FOHGENERIC)

Overview

Replaces the configuration of an existing payment method.

This is a full replacement, not a patch. Every field is written on every call, and the boolean fields are not nullable — one you leave out of the body is read as false and saved as false. Fetch the current state with Retrieve a payment method first, change what you need, and send the whole object back. Sending only description will silently switch the payment method off at the till and mark it inactive.

The id in the path and the id in the body must be identical, or the call is rejected before anything else is checked. The id itself cannot be changed by this endpoint — to rename the code you must create a new payment method and retire the old one.

Everything the create call validates is validated again here against the collection interface you send, so read the field notes on Create a new payment method as well; the one difference is that a payment method is allowed to keep the collection interface it already occupies even when that interface only permits one.

On success you get 204 No Content with an empty body, and reads see the change immediately.

Endpoint

PUT {base_url}/api/financial/payment-methods/{id}

{base_url} is the environment URL issued to your integration. See Authenticating with Gladstone APIs.

Path parameters

Name	Type	Required	Description
`id`	string	Yes	The payment method to update, as returned in `id` by List all payment methods. It must match the `id` in the request body exactly, or the call fails with `400` and `The ID to update does not match the ID in the request`. An id with no payment method behind it returns `404` and `Payment method {id} does not exist`.

Request body

Field	Type	Required	Description
`id`	string	Yes	Must repeat the `id` from the path exactly — this endpoint cannot rename a payment method, and a mismatch is rejected with `400` and `The ID to update does not match the ID in the request` before the record is even looked up. Maximum 15 characters, and it must not be blank.
`description`	string	Yes	The display name staff see against this tender type. Must not be blank; maximum 255 characters. Required on every call — because this is a full replacement there is no way to leave the current description untouched.
`collectionInterfaceId`	integer (int32)	Yes	The tender mechanism this payment method is built on, from `[].id` in List all collection interfaces: `0` Manual, `3` External, `5` Cashless, `6` Loyalty, `7` Chip and PIN, `8` Invoicing, `9` Electronic Funds Transfer (EFT). It may be changed, which also re-derives `openCashDrawer` and can clear `eftSystemId`. It must exist and be active. If the target interface has `multiplePaymentMethodsAllowed: false`, the check ignores this payment method itself, so staying on your current interface always passes and moving onto an occupied one fails with `A payment method of this collection interface type already exists.`
`isActive`	boolean	No	Whether the payment method can still be used. Send `true` to keep it live: omitting it reads as `false` and retires the payment method. Setting it to `false` is the intended way to withdraw a payment method that has already been used, because Delete returns `409` once sales exist against it.
`giveChange`	boolean	No	Whether change is given from this tender. Only accepted as `true` when the collection interface has `canModifyGiveChange: true`, otherwise the call fails with `GiveChange is not allowed for this collection interface type.` Omitting it sets `false`.
`useAtPOS`	boolean	No	Whether the payment method is offered as a tender option at the point of sale. Only accepted as `true` when the collection interface has `canModifyUseAtPos: true`, otherwise the call fails with `UseAtPOS is not allowed for this collection interface type.` Omitting it sets `false` and removes the method from the till.
`nonBankedIncome`	boolean	No	Whether takings on this method are non-banked income — money that never reaches a bank account, such as loyalty points — and so are excluded from banking figures. This flag inverts the usual rule: where the collection interface has `canModifyNonBankedIncome: false` a `false` is rejected with `NonBankedIncome cannot be changed from the default for this collection interface type.` Since an omitted boolean reads as `false`, updates against those interfaces must send `true` explicitly or they fail outright.
`openCashDrawer`	boolean	No	Whether taking this payment pops the till drawer. Whatever you send here is discarded. The value is recalculated on every update from `collectionInterfaceId` alone: `true` for Manual (`0`) and Chip and PIN (`7`), `false` otherwise.
`allowCountedTotal`	boolean	No	Whether takings on this method count towards the counted daily totals at till reconciliation. Saved exactly as supplied and unrestricted by the collection interface — which also means omitting it silently sets it to `false`.
`avsWhenCustomerPresent`	boolean	No	Require Address Verification when the cardholder is at the till. This and the three flags below share one gate: if any is `true` while the collection interface has `canModifyAVSCVSSettings: false`, the whole update is rejected with `Address or Card Number verification cannot be true for this collection interface type.` Omitting them sets `false`.
`avsWhenCustomerNotPresent`	boolean	No	Require Address Verification for a cardholder-not-present sale, such as a telephone or online payment. Subject to the same `canModifyAVSCVSSettings` gate.
`cvsWhenCustomerPresent`	boolean	No	Require card number verification when the cardholder is at the till. Subject to the same `canModifyAVSCVSSettings` gate.
`cvsWhenCustomerNotPresent`	boolean	No	Require card number verification for a cardholder-not-present sale. Subject to the same `canModifyAVSCVSSettings` gate.
`eftSystemId`	integer (int32)	No	The bank collection scheme money is taken through, from `[].id` in Get all EFT systems. Conditionally required in both directions. When `collectionInterfaceId` is `9` (EFT) it must be non-zero — absent or `0` fails with `EftSystemId is required for a collection interface type of Electronic Funds Transfer.` — and the scheme must already have at least one site bank account configured, or you get `A bank account must be configured for this type of Electronic Funds Transfer.` For any other collection interface you must send `0`; omitting the field reads as `null` and fails with `An EftSystemId of 0 is required if the collection interface type is not Electronic Funds Transfer.`
`produceDuplicateReceipt`	boolean	No	Print a second copy of the receipt. Only accepted as `true` when the collection interface has `canModifyDuplicateReceipt: true`, otherwise the call fails with `ProduceDuplicateReceipt is not allowed for this collection interface type.` Omitting it sets `false`.
`printSignatureOnReceipt`	boolean	No	Print a signature line on the receipt. Only accepted as `true` when the collection interface has `canModifySignatureOnReceipt: true`, otherwise the call fails with `PrintSignatureOnReceipt is not allowed for this collection interface type.` Omitting it sets `false`.

Sample request

cURL

curl -X PUT '{base_url}/api/financial/payment-methods/{id}' \
  -H 'Authorization: Bearer {accessToken}' \
  -H 'X-Use-SSO: true' \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "string",
  "description": "string",
  "collectionInterfaceId": 12345,
  "isActive": true,
  "giveChange": true,
  "useAtPOS": true,
  "nonBankedIncome": true,
  "openCashDrawer": true,
  "allowCountedTotal": true,
  "avsWhenCustomerPresent": true,
  "avsWhenCustomerNotPresent": true,
  "cvsWhenCustomerPresent": true,
  "cvsWhenCustomerNotPresent": true,
  "eftSystemId": 12345,
  "produceDuplicateReceipt": true,
  "printSignatureOnReceipt": true
}'

Errors

Status	Meaning	When
`400`	Bad request	`The ID to update does not match the ID in the request` — the path id and the body `id` differ. Checked before the payment method is looked up, so you get this rather than a `404` even when neither id exists.
`400`	Bad request	A field fails basic validation — `Id cannot be blank`, `Id cannot be more than 15 characters`, `Description cannot be blank`, `Description cannot be more than 255 characters` or `Collection interface cannot be blank`. Returned as a validation error object keyed by field name rather than a plain string.
`400`	Bad request	`EftSystemId is required for a collection interface type of Electronic Funds Transfer.`, `A bank account must be configured for this type of Electronic Funds Transfer.` or `An EftSystemId of 0 is required if the collection interface type is not Electronic Funds Transfer.` — see `eftSystemId` above.
`400`	Bad request	`Collection interface ID {collectionInterfaceId} does not exist.` or `Collection interface {description} is not active.` A payment method cannot be updated at all while its collection interface is inactive.
`400`	Bad request	`A payment method of this collection interface type already exists.` — you are moving onto a collection interface that only permits one payment method and is already occupied by a different one.
`400`	Bad request	A flag was set that the collection interface forbids: `UseAtPOS is not allowed for this collection interface type.`, `GiveChange is not allowed…`, `ProduceDuplicateReceipt is not allowed…`, `PrintSignatureOnReceipt is not allowed…`, `NonBankedIncome cannot be changed from the default for this collection interface type.` or `Address or Card Number verification cannot be true for this collection interface type.`
`404`	Not found	`Payment method {id} does not exist` — no payment method exists with that id.
`500`	Internal server error	An unexpected server-side failure while saving. The response body is empty.

This page as markdown · All pages · llms.txt