Counterparties

Counterparties are Devengo's managed address book. Each entry pairs a recipient's name with an IBAN and gets a stable identifier, so you can reference it by ID on payment requests instead of passing raw account data every time.

Most businesses send money to the same people repeatedly — suppliers, employees, partners, refund recipients. Storing those details as counterparties, rather than handling them inline on each request, reduces friction and keeps sensitive account information in one controlled place.

Why it matters

Clean separation between onboarding and payments. You can register a counterparty when you onboard a recipient — during KYC, supplier setup, or account creation — and keep it there indefinitely. The payment flow then has no reason to know or handle account details; it just references an ID. Collecting data and using data become two distinct, independent steps.

Fewer places where sensitive data can go wrong. IBAN and name are submitted once, at registration time, and stored securely by Devengo. Your payment requests from that point on contain only an opaque ID. This reduces the surface area for data entry errors, logging exposure, and accidental leaks across your systems.

A structured foundation for compliance and fraud prevention. A managed recipient list makes it straightforward to detect duplicates, spot reused IBANs across different named recipients, flag unexpected changes, or identify patterns consistent with synthetic account creation. Depending on your business and regulatory context, this kind of auditability can be directly relevant to your AML or fraud prevention obligations.

Cleaner payment workflows. A counterparty ID is stable and meaningful. It is easier to audit, easier to reuse across systems, and easier to reason about than a raw IBAN repeated across hundreds of payment records.

A foundation for stronger controls. Because counterparties are a discrete, manageable set, they unlock controls that are impossible with ad-hoc IBAN entry — things like verification, approval workflows, or restricting payments to pre-approved recipients only.

How it works today

You register a counterparty by providing a name and an IBAN. Devengo validates the IBAN format and stores the entry. From that moment, you can use the counterparty's ID anywhere you would previously have passed creditor details directly.## Operating modes

Devengo supports three counterparty operating modes. Which one applies to your integration depends on your use case, industry, and agreement with Devengo.

Optional. You can send payments either inline — passing name and IBAN directly — or by referencing a counterparty ID. Both work interchangeably. This is the default for general-purpose integrations.

Mandatory. All payments must reference a registered counterparty. Inline IBAN entry is not available. This mode ensures every recipient is a known, managed entity before any money moves.

Restrictive. All payments must reference a counterparty, and that counterparty must be in verified status. Payments to unverified counterparties are rejected. This mode is required in certain regulated industries and may also be applied by Devengo if your payment flows present elevated AML or fraud risk.

Counterparty status

Every counterparty has a status field that reflects its current state. Understanding these statuses is important for building reliable payment flows, since only counterparties in certain states can be used as payment recipients.

Status	Description
`unverified`	The default state when a counterparty is created and has not yet gone through a verification process. Counterparties created automatically from incoming payments also start here. In optional and mandatory modes, payments to `unverified` counterparties are allowed. In restrictive mode, they are rejected.
`verified`	The counterparty has successfully completed a verification process — for example, a Verification of Payee check. The specific method used is recorded separately.
`archived`	The counterparty has been retired by your team and is no longer intended for use. Archived counterparties cannot be used in new payments. Because counterparties may be referenced in historical payment records, they cannot be permanently deleted — archiving is the intended way to decommission one.
`inactive`	Devengo has marked this counterparty inactive following a payment event that suggests the destination account is no longer valid — for example, a transfer that was returned because the account is closed. Payments to inactive counterparties are blocked until the status is reviewed.
`blocked_by_client`	Your team has blocked this counterparty. No payments can be made to them until you explicitly unblock them. You should store a reason when blocking (see below).
`blocked_by_devengo`	Devengo has blocked this counterparty, typically for a compliance or risk reason. Only Devengo can lift this block.

Blocking reasons

When a counterparty is blocked — by you or by Devengo — a reason is recorded alongside the status. This is both a practical audit trail and, in some cases, a compliance requirement. Expected values include aml, fraud, tms (transaction monitoring), sanctions, and other.

If you are blocking a counterparty through the API, providing a reason is required.

What's coming

The Counterparties API is the first step in a broader set of features around payment recipient management.

Mandatory and restrictive modes. Currently all integrations operate in optional mode. Mandatory mode — where all payments must reference a registered counterparty — and restrictive mode — where only verified counterparties are accepted — are both on the roadmap and will be available for integrations that require tighter controls or are subject to specific compliance requirements.

Verification. Before activating a counterparty, Devengo will be able to confirm that the account holder name actually matches the owner of that IBAN. This turns your address book into a verified list, not just a stored one — and is the mechanism that underpins restrictive mode.

Hosted data capture. A Devengo-hosted widget will let your end users submit their own IBAN directly, without that data ever passing through your frontend or servers. This is especially useful for payout platforms collecting recipient details from customers or contractors.

These features will be announced through the API changelog and the developer newsletter as they become available.