Create payment method

POST https://api.invunion.com/api/v1/payment-methods payment_methods:write Idempotency-Key Markdown

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.

Body parameters

Name	Type	Required
`name` Display name of the instrument. Example: Leones Cars EUR	string Max 255	Required
`iban` IBAN. Required unless identifier is set. Unique per tenant catalog. Example: FR7630006000011234567890189	string Max 50	Recommended
`identifier` Non-IBAN instrument key (PayPal email, wallet id, terminal number). Required unless iban is set. Unique per tenant catalog. Example: [email protected]	string Max 120	Optional
`code` Your payment-method code. Unique per tenant. If omitted, Invunion assigns PM-NNN. Example: PM-001	string Max 50	Recommended
`type` Instrument type. Default bank_account.	string No maximum	Recommended
Allowed values`bank_accountcredit_cardpaypalwerotwintcrypto_walletother`
`bic` BIC. Bank name and country are filled from the BIC directory when omitted. Example: BNPAFRPP	string Max 11	Optional
`currency` ISO 4217 currency code. Default EUR. Example: EUR	string Max 3	Optional
`counterparty_id` Counterparty code (`account_code`) to link. For exclusive mode this becomes the owner. For shared mode it is added as an association. Example: CPT-042	string No maximum	Recommended
`association_mode` exclusive (one owner) or shared (several counterparties). Default exclusive. Allowed values`exclusiveshared`	string No maximum	Recommended
`account_type` Optional account type label. Example: checking	string No maximum	Optional
`bank_name` Bank name. Filled from BIC when omitted. Example: BNP Paribas	string No maximum	Optional
`bank_country` ISO 3166-1 alpha-2 of the bank, not the counterparty country. Example: FR	string No maximum	Optional
`status` Instrument status. Default active.	string No maximum	Optional
Allowed values`activeinactiveerror`
`metadata` JSON object. At most 32 keys, nested depth 3, 8 KB serialized, and 64-character key names. Keys __proto__, constructor, and prototype are rejected. Example: {"erp_pm":"BANK-042"}	object	Optional

Errors

This operation can return the following errors in addition to generic HTTP failures.

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	More than 100 requests in one minute from this API key or IP address. Wait for the Retry-After header (seconds) and retry.
`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.
`Idempotency-Key must be 8-255 characters: letters, digits, ".", "_", ":" or "-".`	400	The Idempotency-Key header is present but malformed.
`A request with this Idempotency-Key is still being processed.`	409	The first request with this key has not finished. Retry after it completes. code is idempotency_in_progress.
`This Idempotency-Key was already used with a different request body.`	422	Send a new key for a different request. code is idempotency_key_reuse.