202606 API Version: Counterparties

A managed address book for payment recipients, plus a unified counterparty object in payment responses.

Counterparties API

We're introducing Counterparties, Devengo's managed address book for payment recipients. Register a recipient once with a name and IBAN, then reference it by a stable ID on payment requests instead of passing raw account details every time.

What's new

• Create and manage counterparties — POST /v1/counterparties, GET /v1/counterparties, and GET /v1/counterparties/{id}. Devengo validates the IBAN, resolves bank details in the background, and returns a stable ctp_ identifier. An optional legal identifier can be attached when your use case requires it.
• Reference counterparties on payments — POST /v1/payments and POST /v1/payments/preview now accept a counterparty_id as an alternative to inline recipient + destination. Provide one or the other; sending counterparty_id together with recipient/destination returns invalid_parameters_combination.

Each counterparty carries a status that controls whether it can receive payments, and integrations operate in one of three modes (optional, mandatory, restrictive). See the Counterparties guide for status definitions, operating modes, and what's on the roadmap.

Breaking changes

Payment and Incoming Payment responses now use a unified counterparty object.

The beneficiary information previously split across separate response fields is consolidated into a single counterparty object. This affects responses only — the payment request still accepts inline recipient + destination as before.

• Payment — the recipient, destination, and third_party response fields are replaced by counterparty (\{id, name, account, bank\}).
• Incoming Payment — the third_party response field is replaced by counterparty, now including a counterparty id.

Update any integration that reads recipient, destination, or third_party from payment payloads to read from counterparty instead.