# Create a new payment method

`POST /api/financial/payment-methods`

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

HTML version: [Create a new payment method](https://support.gladstonesoftware.cloud/reference/payments/create-a-new-payment-method)

## 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](list-all-collection-interfaces.md)
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](retrieve-a-payment-method.md); 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](../../guides/authenticating-with-gladstone-apis.md).

## 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](retrieve-a-payment-method.md), [Update](update-a-payment-method.md) and [Delete](delete-a-payment-method.md), 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](list-all-collection-interfaces.md). 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](delete-a-payment-method.md) 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](get-all-eft-systems.md). 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

```bash title="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. |