CPN API changes and compatibility

Additive and breaking changes as CPN adds fields, values, events, and capabilities, and how to keep your integration compatible.

The Circle Payments Network (CPN) API evolves as Circle adds corridors, payment methods, blockchains, compliance rules, and failure conditions. Circle classifies API changes as backward compatible or breaking. Most backward-compatible changes are additive: they introduce a resource, field, value, or capability while preserving documented behavior for existing valid requests. An Originating Financial Institution (OFI) integration must tolerate these changes so that new response data or event types don’t cause client failures.

Backward-compatible and breaking changes

Circle expects OFI integrations to accept the changes in the backward-compatible column without failing or requiring an immediate update. Breaking changes alter or remove part of the documented contract and may require integration work.

Area	Backward-compatible change	Breaking change
Endpoints and resources	Add an endpoint or resource	Remove or rename an endpoint or resource
Requests	Add an optional parameter when omitting it preserves existing behavior	Add a required parameter, make an optional parameter required, or change the behavior when a parameter is omitted
Responses	Add a property	Remove or rename a property, change its data type, or make an always-present property conditionally omitted
Enum values	Add a value for a new condition or capability	Remove a value or change what an existing value means
Errors	Add an error code for a new failure condition or revise human-readable message text	Change the HTTP status or error code for an existing condition
Webhooks	Add an event type or a field to an existing payload	Stop emitting a documented event type, remove a field, or change an existing event’s meaning
Validation	Relax validation so that a previously rejected request is accepted	Tighten validation so that a previously accepted request is rejected

Use the release notes and relevant migration guides to identify changes that require integration work. When a migration includes a deadline, complete the required work in the communicated timeline.

Build a tolerant integration

Backward-compatible changes don’t require your integration to adopt a new capability. They do require clients to accept response and event data that they don’t use yet.

Optional request parameters

A new request parameter is backward compatible only when it’s optional and omitting it preserves existing behavior. Existing requests can retain their current shape until the integration needs the capability controlled by the new parameter.

New response fields

Parse the response fields your integration uses and ignore unfamiliar properties. Strict deserialization that rejects extra properties can turn an otherwise successful API response into a client-side failure.

General enum values

Send only documented enum values in requests. For responses, preserve any unfamiliar raw value and map it to a neutral fallback instead of rejecting the entire response. Storage and downstream processing must also accept unfamiliar values.

Don’t infer the meaning of an unfamiliar value or use it to trigger an irreversible action. Add first-class handling after you confirm the value’s documented meaning.

Lifecycle statuses

An unfamiliar lifecycle status needs a more conservative fallback than a general enum value. Keep the resource in its current local state, preserve the raw status, and route the record for review. Don’t interpret an unfamiliar status as success or failure, and don’t release funds or take another irreversible action based on it.

Resource and reference IDs

The CPN OpenAPI schemas define system-generated resource IDs as UUID-formatted strings and reference IDs as strings. Treat each identifier according to its documented schema and as an opaque value: don’t derive business meaning from its shape or impose an undocumented length limit.

Error codes

Match errors by their machine-readable code, not their human-readable message. A new code is backward compatible when it represents a new failure condition; changing the HTTP status or code for an existing condition is breaking. Preserve and surface an unfamiliar code so that you can add specific handling without losing the original failure detail.

Webhook events

After verifying a webhook signature, record or surface an unsupported event type for follow-up, then acknowledge it with a 2xx response. This prevents retries that can’t succeed while preserving the event for later handling. Don’t process the event as a known type. Continue to reject webhooks when signature verification fails.