# Update a payment method

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

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

HTML version: [Update a payment method](https://support.gladstonesoftware.cloud/reference/payments/update-a-payment-method)

## 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](retrieve-a-payment-method.md) 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](create-a-new-payment-method.md) 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](../../guides/authenticating-with-gladstone-apis.md).

## Path parameters

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `id` | string | Yes | The payment method to update, as returned in `id` by [List all payment methods](list-all-payment-methods.md). 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](list-all-collection-interfaces.md): `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](delete-a-payment-method.md) 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](get-all-eft-systems.md). 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

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