Manage Account Co-ordinates

Banking coordinates are the public-facing account identifiers used for incoming and outgoing payments like IBANs, account numbers, routing codes, or BICs. XYB lets you attach one or more coordinate sets to an account, making them interoperable with both internal systems and third-party payment providers.

Coordinates represent the banking identity of an account. These may include:

• IBAN / Account Number: standard identifiers for SEPA, SWIFT, or local rails

• Routing Code / Bank Code / Branch Code: for clearing systems like ACH, FPS

• BIC / SWIFT Codes: international routing

• Country Code / Currency / National IDs: metadata for regional compliance

Each coordinate entry is a JSON object that can include optional tags, metadata, and external references (e.g. from CurrencyCloud or LHV).

---

How Coordinates Are Managed

Coordinates are not created by default, you attach them explicitly after the account is created.

a) Add Coordinates

Use the API:

POST /api/v2.0/account/{idRef}/coordinates

Payload includes coordinates, tags, and optional metadata.

Example use cases:

• Attach an IBAN to a retail account

• Assign an internal account number for legacy processing

• Tag coordinates as SWIFT, DOMESTIC, or INSTANT for routing logic

---

b) Update or Replace Tags

You can update coordinate tags without modifying the full object:

• PUT /account/{idRef}/coordinates/{id} - Replace all tags

• PATCH /account/{idRef}/coordinates/{id} - Add new tags

---

c) Delete Coordinates

To retire coordinates (e.g., when rotating IBANs), use:

DELETE /api/v2.0/account/{idRef}/coordinates/{id}

Deletion is idempotent — safe to call multiple times, no side effects.

---

Coordinate Metadata

Each coordinate object may also contain:

• external: 3rd-party IDs or mappings

• internal: system-specific references

• tags: used to group or filter coordinates in APIs

This makes it easy to build rules-based processing, for example: “Prefer coordinates tagged as DOMESTIC in EUR for SEPA payouts."

Summary

Action	Endpoint
Add coordinates	POST /account/{idRef}/coordinates
Replace tags	PUT /account/{idRef}/coordinates/{id}
Add tags	PATCH /account/{idRef}/coordinates/{id}
Delete coordinates	DELETE /account/{idRef}/coordinates/{id}

Banking coordinates give your accounts their external identity, attach as many as you need, tag them for clarity, and remove them safely when no longer needed.