Create a new payment method

POST /api/financial/payment-methods

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

Overview

Creates a payment method — a tender type the operator can accept, such as cash, a card scheme, a direct debit arrangement or loyalty points. You choose the id yourself; the platform does not generate one.

Call List all collection interfaces first. The collection interface you pick in collectionInterfaceId decides almost everything else in this request: its canModify… flags say which of the boolean fields below you are allowed to set to true, and its multiplePaymentMethodsAllowed flag says whether a second payment method of that kind may exist at all. Guessing here produces a 400 with a message naming the offending field.

Validation runs in a fixed order and stops at the first failure — duplicate id, then the EFT rules, then that the collection interface exists, then that it is active, then the per-flag rules. A consequence worth knowing: if you send an unrecognised collectionInterfaceId together with a non-zero eftSystemId, the error you get back complains about eftSystemId, not about the unknown collection interface.

On success you get 201 Created with a Location header pointing at Retrieve a payment method; the body is empty. The new record is immediately visible to reads.

Endpoint

POST {base_url}/api/financial/payment-methods

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

Request body

Field	Type	Required	Description
`id`	string	Yes	The code you want this payment method to be known by; it becomes the path segment for Retrieve, Update and Delete, so choose something stable. Maximum 15 characters, and it must not be blank. Uniqueness is checked case-insensitively, so `CASH` clashes with an existing `cash` and is rejected with `A payment method with this ID already exists.`
`description`	string	Yes	The display name staff see against this tender type, for example on the point-of-sale tender list. Must not be blank; maximum 255 characters. Free text — it carries no behaviour, and it is not required to be unique.
`collectionInterfaceId`	integer (int32)	Yes	The tender mechanism to build this payment method on, taken from `[].id` in List all collection interfaces. The recognised values are `0` Manual, `3` External, `5` Cashless, `6` Loyalty, `7` Chip and PIN, `8` Invoicing and `9` Electronic Funds Transfer (EFT). It must exist and have `isActive: true`, or you get `400`. If its `multiplePaymentMethodsAllowed` is `false` and a payment method already uses it, creation fails with `A payment method of this collection interface type already exists.`
`isActive`	boolean	No	Whether the payment method can be used. Defaults to `false` when omitted, which creates it in a retired state — send `true` explicitly if you want it usable. Later, deactivating is the intended way to withdraw a payment method that has been used, because Delete returns `409` once sales exist against it.
`giveChange`	boolean	No	Whether change is given from this tender — meaningful for cash-like methods. Only accepted as `true` when the chosen collection interface has `canModifyGiveChange: true`; otherwise the request fails with `GiveChange is not allowed for this collection interface type.` Defaults to `false` when omitted.
`useAtPOS`	boolean	No	Whether to offer this payment method as a tender option at the point of sale. Only accepted as `true` when the collection interface has `canModifyUseAtPos: true`; otherwise the request fails with `UseAtPOS is not allowed for this collection interface type.` Defaults to `false` when omitted, which creates a payment method that never appears at 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 redeemed against a sale — and so are excluded from banking figures. This one inverts the usual rule: where the collection interface has `canModifyNonBankedIncome: false` the platform sets the value to `true` and rejects a `false` with `NonBankedIncome cannot be changed from the default for this collection interface type.` Because an omitted boolean is read as `false`, you must send `true` explicitly for those interfaces.
`openCashDrawer`	boolean	No	Whether taking this payment pops the till drawer. Whatever you send here is discarded. The platform sets the value from `collectionInterfaceId` alone: `true` for Manual (`0`) and Chip and PIN (`7`), `false` for every other type.
`allowCountedTotal`	boolean	No	Whether takings on this method count towards the counted daily totals at till reconciliation. Saved exactly as supplied — this is the one flag the collection interface places no restriction on. Defaults to `false` when omitted.
`avsWhenCustomerPresent`	boolean	No	Require Address Verification when the cardholder is at the till. This and the three flags below share a single gate: if any of them is `true` and the collection interface has `canModifyAVSCVSSettings: false`, the whole request is rejected with `Address or Card Number verification cannot be true for this collection interface type.` Defaults to `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 as `avsWhenCustomerPresent`. Defaults to `false`.
`cvsWhenCustomerPresent`	boolean	No	Require card number verification when the cardholder is at the till. Subject to the same `canModifyAVSCVSSettings` gate. Defaults to `false`.
`cvsWhenCustomerNotPresent`	boolean	No	Require card number verification for a cardholder-not-present sale. Subject to the same `canModifyAVSCVSSettings` gate. Defaults to `false`.
`eftSystemId`	integer (int32)	No	The bank collection scheme money is taken through, from `[].id` in Get all EFT systems. Conditionally required, and the rule cuts both ways. When `collectionInterfaceId` is `9` (EFT) you must send a non-zero id — omitting it or sending `0` fails with `EftSystemId is required for a collection interface type of Electronic Funds Transfer.` — and that 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 every other collection interface you must send `0`; any other value, including omitting the field (which reads as `null`), 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 for this tender. Only accepted as `true` when the collection interface has `canModifyDuplicateReceipt: true`; otherwise the request fails with `ProduceDuplicateReceipt is not allowed for this collection interface type.` Defaults to `false`.
`printSignatureOnReceipt`	boolean	No	Print a signature line on the receipt. Only accepted as `true` when the collection interface has `canModifySignatureOnReceipt: true`; otherwise the request fails with `PrintSignatureOnReceipt is not allowed for this collection interface type.` Defaults to `false`.

Sample request

cURL

curl -X POST '{base_url}/api/financial/payment-methods' \
  -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	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	`A payment method with this ID already exists.` — the id clashes with an existing payment method, compared case-insensitively.
`400`	Bad request	`EftSystemId is required for a collection interface type of Electronic Funds Transfer.` — `collectionInterfaceId` is `9` but `eftSystemId` is absent or `0`.
`400`	Bad request	`A bank account must be configured for this type of Electronic Funds Transfer.` — the EFT scheme exists but no site bank account references it yet.
`400`	Bad request	`An EftSystemId of 0 is required if the collection interface type is not Electronic Funds Transfer.` — `eftSystemId` is anything other than `0`, including omitted, on a non-EFT collection interface.
`400`	Bad request	`Collection interface ID {collectionInterfaceId} does not exist.`
`400`	Bad request	`Collection interface {description} is not active.`
`400`	Bad request	`A payment method of this collection interface type already exists.` — the collection interface has `multiplePaymentMethodsAllowed: false` and is already in use.
`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.`
`500`	Internal server error	An unexpected server-side failure while saving. The response body is empty.

This page as markdown · All pages · llms.txt