# Create payment method Create a catalog payment method. Creates a catalog instrument. name is required, and either iban or identifier is required. If code is omitted, Invunion assigns the next PM-NNN code. counterparty_id must already exist; this endpoint does not create a counterparty. To create a counterparty and a catalog instrument in one request, use POST /counterparties with payment_method. An IBAN or identifier that already belongs to another catalog instrument returns 409. - HTTP method: `POST` - Path: `/api/v1/payment-methods` - URL: `https://api.invunion.com/api/v1/payment-methods` - Required scope: `payment_methods:write` - HTML docs: https://www.invunion.com/knowledge-base/api/create-payment-method/ - Markdown docs: https://www.invunion.com/knowledge-base/api/create-payment-method.md ## Body parameters | Name | Type | Required | Description | Allowed values | Example | | --- | --- | --- | --- | --- | --- | | `name` | string, max 255 | required | Display name of the instrument. | | `Leones Cars EUR` | | `iban` | string, max 50 | recommended | IBAN. Required unless identifier is set. Unique per tenant catalog. | | `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` | | `code` | string, max 50 | recommended | Your payment-method code. Unique per tenant. If omitted, Invunion assigns PM-NNN. | | `PM-001` | | `type` | string, no maximum | recommended | 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 | recommended | 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 | recommended | 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. | | `name is required` | `400` | The body does not include name. | | `IBAN or identifier is required` | `400` | Neither iban nor identifier was provided. | | `Invalid association_mode` | `400` | association_mode is not exclusive or shared. | | `Counterparty not found` | `400` | counterparty_id does not exist in this tenant. | | `Tenant ID required` | `400` | The authenticated credential is not bound to a tenant. | | `This IBAN already belongs to a catalog payment method` | `409` | Another catalog instrument already uses this IBAN. | | `This identifier already belongs to a catalog payment method` | `409` | Another catalog instrument already uses this identifier. | | `Internal server error` | `500` | Unexpected server error. The JSON body includes correlationId. Retry with backoff. | ## Request (curl) ```bash curl --request POST \ --url https://api.invunion.com/api/v1/payment-methods \ --header 'accept: application/json' \ --header 'authorization: Bearer uk_live_YOUR_API_KEY' \ --header 'content-type: application/json' \ --data '{ "name": "Leones Cars EUR", "iban": "FR7630006000011234567890189", "bic": "BNPAFRPP", "currency": "EUR", "type": "bank_account", "counterparty_id": "CPT-042", "association_mode": "exclusive" }' ``` ## Request (Python) ```python import requests url = "https://api.invunion.com/api/v1/payment-methods" headers = { "Accept": "application/json", "Authorization": "Bearer uk_live_YOUR_API_KEY", "Content-Type": "application/json", } payload = { "name": "Leones Cars EUR", "iban": "FR7630006000011234567890189", "bic": "BNPAFRPP", "currency": "EUR", "type": "bank_account", "counterparty_id": "CPT-042", "association_mode": "exclusive" } response = requests.post(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") http = Net::HTTP.new(uri.host, uri.port) http.use_ssl = true request = Net::HTTP::Post.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 EUR\",\n \"iban\": \"FR7630006000011234567890189\",\n \"bic\": \"BNPAFRPP\",\n \"currency\": \"EUR\",\n \"type\": \"bank_account\",\n \"counterparty_id\": \"CPT-042\",\n \"association_mode\": \"exclusive\"\n}" response = http.request(request) puts response.body ``` ## Request (JavaScript) ```javascript const response = await fetch("https://api.invunion.com/api/v1/payment-methods", { method: "POST", headers: { "Accept": "application/json", "Authorization": "Bearer uk_live_YOUR_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ "name": "Leones Cars EUR", "iban": "FR7630006000011234567890189", "bic": "BNPAFRPP", "currency": "EUR", "type": "bank_account", "counterparty_id": "CPT-042", "association_mode": "exclusive" }), }); const data = await response.json(); ``` ## Request (Go) ```go package main import ( "bytes" "fmt" "io" "net/http" ) func main() { payload := []byte(`{ "name": "Leones Cars EUR", "iban": "FR7630006000011234567890189", "bic": "BNPAFRPP", "currency": "EUR", "type": "bank_account", "counterparty_id": "CPT-042", "association_mode": "exclusive" }`) req, err := http.NewRequest("POST", "https://api.invunion.com/api/v1/payment-methods", 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", { method: "POST", headers: { "Accept": "application/json", "Authorization": "Bearer uk_live_YOUR_API_KEY", "Content-Type": "application/json" }, body: JSON.stringify({ "name": "Leones Cars EUR", "iban": "FR7630006000011234567890189", "bic": "BNPAFRPP", "currency": "EUR", "type": "bank_account", "counterparty_id": "CPT-042", "association_mode": "exclusive" }), }); console.log(await response.json()); ``` ## Success (201) ```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 EUR", "iban": "FR7630006000011234567890189", "bic": "BNPAFRPP", "currency": "EUR", "account_type": "checking", "bank_name": "BNP Paribas", "bank_country": "FR", "identifier": null, "status": "active", "association_mode": "exclusive", "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 created successfully" } ```