Metadata and External IDs
How Metadata and External IDs works in Paycux, what it is for, and the smallest setup that gets it running.
Introduction
Metadata and External IDs is part of the Paycux platform. This page explains what it does, when to reach for it, and the smallest working setup you can ship.
Everything below applies to both environments. Build and test in staging, then promote the same configuration to production without changing your code — only the API key and client ID differ.
External identifiers
External identifiers is handled by Metadata and External IDs rather than by your application code. Paycux exposes it through the same API surface as the rest of the platform, so the client you already configured needs no additional setup.
Configuration lives in the dashboard and is versioned per environment. Change it in staging, confirm the behaviour, then apply the same change to production.
Metadata
Paste the provider's metadata URL into the connection. Paycux reads the signing certificate and endpoints from it and re-reads them on a schedule, so a certificate rotation does not break the connection.
Static metadata
If the provider only offers a metadata file rather than a URL, upload the XML instead. Static metadata does not auto-refresh — set a calendar reminder for the certificate expiry date.
Set an external identifier
Set an external identifier is handled by Metadata and External IDs rather than by your application code. Paycux exposes it through the same API surface as the rest of the platform, so the client you already configured needs no additional setup.
Configuration lives in the dashboard and is versioned per environment. Change it in staging, confirm the behaviour, then apply the same change to production.
Query by external identifier
Query by external identifier is handled by Metadata and External IDs rather than by your application code. Paycux exposes it through the same API surface as the rest of the platform, so the client you already configured needs no additional setup.
Configuration lives in the dashboard and is versioned per environment. Change it in staging, confirm the behaviour, then apply the same change to production.
Add and update metadata
Add and update metadata applies specifically to Metadata and External IDs. It behaves the same in both environments, and the values it depends on are visible in the dashboard for the environment you have selected.
If the behaviour you see does not match this description, check which environment your API key belongs to before anything else — a staging key against production data is the most common cause.
Exposing metadata in JWTs
Access tokens are JWTs signed with a rotating key. Verify them against the JWKS endpoint for your client rather than a pinned public key, so rotation never causes an outage.
1https://api.paycux.com/sso/jwks/client_01M4KXD1PZXFWGWE9ZKPCQRAQ
Cache the key set and re-fetch on an unknown key ID. Reject any token whose issuer, audience or expiry does not match what you expect.