# Update payment method

Update fields on a catalog payment method.

Partial update. Send only the fields you want to change. At least one updatable field is required. Bank-connection rows cannot be edited here. Switching association_mode to exclusive fails if more than one counterparty is still linked.


- HTTP method: `PATCH`
- Path: `/api/v1/payment-methods/:code`
- URL: `https://api.invunion.com/api/v1/payment-methods/:code`
- Required scope: `payment_methods:write`
- HTML docs: https://www.invunion.com/knowledge-base/api/update-payment-method/
- Markdown docs: https://www.invunion.com/knowledge-base/api/update-payment-method.md

## Path parameters

| Name | Type | Required | Description | Allowed values | Example |
| --- | --- | --- | --- | --- | --- |
| `code` | string, max 50 | required | Payment method code (`code`). |  | `PM-001` |


## Body parameters

| Name | Type | Required | Description | Allowed values | Example |
| --- | --- | --- | --- | --- | --- |
| `name` | string, max 255 | optional | Display name of the instrument. At least one updatable field is required. |  | `Leones Cars EUR` |
| `iban` | string, max 50 | optional | IBAN. Catalog instruments other than the empty Default still need an IBAN or identifier. |  | `FR7630006000011234567890189` |
| `identifier` | string, max 120 | optional | Non-IBAN instrument key (PayPal email, wallet id, terminal number). Required unless iban is set. Unique per tenant catalog. |  | `carl@leonescars.fr` |
| `type` | string, no maximum | optional | Instrument type. Default bank_account. | `bank_account`, `credit_card`, `paypal`, `wero`, `twint`, `crypto_wallet`, `other` |  |
| `bic` | string, max 11 | optional | BIC. Bank name and country are filled from the BIC directory when omitted. |  | `BNPAFRPP` |
| `currency` | string, max 3 | optional | ISO 4217 currency code. Default EUR. |  | `EUR` |
| `counterparty_id` | string, no maximum | optional | Counterparty code (`account_code`) to link. For exclusive mode this becomes the owner. For shared mode it is added as an association. |  | `CPT-042` |
| `association_mode` | string, no maximum | optional | exclusive (one owner) or shared (several counterparties). Default exclusive. | `exclusive`, `shared` |  |
| `account_type` | string, no maximum | optional | Optional account type label. |  | `checking` |
| `bank_name` | string, no maximum | optional | Bank name. Filled from BIC when omitted. |  | `BNP Paribas` |
| `bank_country` | string, no maximum | optional | ISO 3166-1 alpha-2 of the bank, not the counterparty country. |  | `FR` |
| `status` | string, no maximum | optional | Instrument status. Default active. | `active`, `inactive`, `error` |  |
| `metadata` | object | optional | JSON object. At most 32 keys, nested depth 3, 8 KB serialized, and 64-character key names. Keys __proto__, constructor, and prototype are rejected. |  | `{"erp_pm":"BANK-042"}` |

## Errors

| Error | HTTP code | Description |
| --- | --- | --- |
| `Missing Bearer token` | `401` | The Authorization header is missing or is not a Bearer token. |
| `Invalid or revoked API key` | `401` | The API key is unknown, malformed, expired, or has been revoked. |
| `API key is missing scope payment_methods:write` | `403` | The key does not include payment_methods:write. A write scope does not imply the matching read scope. |
| `Too many requests, please try again later` | `429` | Wait and retry. The Retry-After header is the number of seconds to wait. |
| `No fields to update` | `400` | The body did not contain any updatable field. |
| `IBAN or identifier is required` | `400` | The update would leave the instrument without an IBAN or identifier. |
| `Invalid association_mode` | `400` | association_mode is not exclusive or shared. |
| `Payment method not found` | `404` | No catalog payment method with this code exists in the authenticated tenant. |
| `Enable Banking accounts are managed from Bank connections, not from payment methods.` | `403` | The row is a bank-connection account, not a catalog instrument. |
| `Parked payment methods cannot be shared` | `409` | The instrument is parked and cannot switch to shared mode. |
| `Remove all but one association before switching to exclusive mode` | `409` | More than one counterparty is still linked. |
| `This IBAN already belongs to a catalog payment method` | `409` | Another catalog instrument already uses this IBAN. |
| `Internal server error` | `500` | Unexpected server error. The JSON body includes correlationId. Retry with backoff. |

## Request (curl)

```bash
curl --request PATCH \
  --url https://api.invunion.com/api/v1/payment-methods/PM-001 \
  --header 'accept: application/json' \
  --header 'authorization: Bearer uk_live_YOUR_API_KEY' \
  --header 'content-type: application/json' \
  --data '{
  "name": "Leones Cars SEPA EUR",
  "association_mode": "shared"
}'
```

## Request (Python)

```python
import requests

url = "https://api.invunion.com/api/v1/payment-methods/PM-001"
headers = {
    "Accept": "application/json",
    "Authorization": "Bearer uk_live_YOUR_API_KEY",
    "Content-Type": "application/json",
}
payload = {
    "name": "Leones Cars SEPA EUR",
    "association_mode": "shared"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.json())
```

## Request (Ruby)

```ruby
require 'net/http'
require 'json'
require 'uri'

uri = URI("https://api.invunion.com/api/v1/payment-methods/PM-001")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Patch.new(uri)
request['Accept'] = 'application/json'
request['Authorization'] = 'Bearer uk_live_YOUR_API_KEY'
request['Content-Type'] = 'application/json'
request.body = "{\n  \"name\": \"Leones Cars SEPA EUR\",\n  \"association_mode\": \"shared\"\n}"
response = http.request(request)
puts response.body
```

## Request (JavaScript)

```javascript
const response = await fetch("https://api.invunion.com/api/v1/payment-methods/PM-001", {
  method: "PATCH",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer uk_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "name": "Leones Cars SEPA EUR",
  "association_mode": "shared"
}),
});
const data = await response.json();
```

## Request (Go)

```go
package main

import (
	"bytes"
	"fmt"
	"io"
	"net/http"
)

func main() {
	payload := []byte(`{
  "name": "Leones Cars SEPA EUR",
  "association_mode": "shared"
}`)
	req, err := http.NewRequest("PATCH", "https://api.invunion.com/api/v1/payment-methods/PM-001", bytes.NewBuffer(payload))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Accept", "application/json")
	req.Header.Set("Authorization", "Bearer uk_live_YOUR_API_KEY")
	req.Header.Set("Content-Type", "application/json")
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	body, _ := io.ReadAll(resp.Body)
	fmt.Println(string(body))
}
```

## Request (Node)

```javascript
const response = await fetch("https://api.invunion.com/api/v1/payment-methods/PM-001", {
  method: "PATCH",
  headers: {
    "Accept": "application/json",
    "Authorization": "Bearer uk_live_YOUR_API_KEY",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "name": "Leones Cars SEPA EUR",
  "association_mode": "shared"
}),
});
console.log(await response.json());
```

## Success (200)

```json
{
  "success": true,
  "data": {
    "id": "8a1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
    "tenant_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "counterparty_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "code": "PM-001",
    "type": "bank_account",
    "name": "Leones Cars SEPA EUR",
    "iban": "FR7630006000011234567890189",
    "bic": "BNPAFRPP",
    "currency": "EUR",
    "account_type": "checking",
    "bank_name": "BNP Paribas",
    "bank_country": "FR",
    "identifier": null,
    "status": "active",
    "association_mode": "shared",
    "purpose": "catalog",
    "instrument_role": null,
    "is_default": false,
    "counterparty_name": "Leones Cars",
    "counterparty_code": "CPT-042",
    "counterparties": [
      {
        "counterparty_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
        "counterparty_name": "Leones Cars",
        "counterparty_code": "CPT-042"
      }
    ],
    "tx_count": 12,
    "last_transaction_date": "2026-09-12",
    "created_at": "2026-03-04T12:40:56.656Z",
    "updated_at": "2026-09-12T08:15:22.110Z",
    "metadata": {
      "erp_pm": "BANK-042"
    }
  },
  "message": "Payment method updated successfully"
}
```