# Citi > Citi is the consumer and institutional brand of Citigroup, a global bank serving over 200 million customers in 160 countries. Citi publishes 118 machine-readable OpenAPI/Swagger contracts covering 297 operations for its institutional API estate — payments, account reporting, commercial cards, FX, custody, trade and open banking — at developer.citi.com. Access to production is relationship-managed: the sandbox is self-service after developer registration, but going live requires a sales conversation and a Citi Relationship Manager. This file was generated by API Evangelist (apievangelist.com) from Citi's own published contracts and documentation on 2026-09-05. Citi does not publish an llms.txt of its own; /llms.txt returns 404 on citi.com, developer.citi.com and partner.citi.com. ## Key facts for an agent - **Auth**: OAuth 2.0 client-credentials over mutual TLS. Four concurrent authentication endpoint versions (V1-V4); each API's contract names the one it needs. V1-V3 additionally require the payload to be signed and encrypted with client-held PKI keys. V4 does not. - **No refresh tokens.** Renew the access token only on a 401, then retry once. - **Idempotency is partial.** An `Idempotency-Id` header is declared on only 10 of roughly 180 mutating operations. Payment initiation is NOT one of them — do not blind-retry a payment on a timeout. - **No reversal window is published anywhere.** Cancellation and refund operations exist and are real; the time limit on using them is not stated in any contract or guide. - **Rate limits**: `RateLimit-Limit`/`Remaining`/`Reset` headers are declared on 3 of 118 contracts. No numeric limit is published; 429 is declared on 82 operations with no Retry-After. - **ISO 20022 throughout the payment estate**: pain.001, pain.002, pacs.008, pacs.009, pacs.002, camt.052, camt.056, pain.008. Most payment APIs are published in matched JSON and XML encodings. - **Region and Country request headers** select the servicing Citi legal entity and are load-bearing on 52 operations. - **No MCP server, no agent card, no /.well-known documents.** Verified by probe on 8 Citi hosts, 2026-09-05. ## Developer surface - [Citi Developer Experience](https://developer.citi.com/apidocs/): institutional API documentation (Docusaurus). The 118 specs are served at https://developer.citi.com/apidocs/redocusaurus/.yaml - [Citi Partner Portal](https://partner.citi.com/developers): retail and open-banking partner programme. API Catalog, API Playground, Onboarding Guide and Workspace all require registration. - [Register](https://partner.citi.com/user/register) | [Log in](https://partner.citi.com/user/login) | [Contact sales](https://partner.citi.com/contact-us) - Developer support: devsupport@citi.com - [Authentication Guide](https://developer.citi.com/apidocs/authentication/authentication-only-guide) | [Certificate Management Guide](https://developer.citi.com/apidocs/authentication/certificate-management-guide) - [Report a vulnerability](https://www.citi.com/reporting-vulnerability) | [Citi's Responsible Disclosure Program on Bugcrowd](https://bugcrowd.com/engagements/citi) ## API families ### Authentication — 4 contracts, 4 operations - [Authentication Services v1.0.0](https://developer.citi.com/apidocs/redocusaurus/authentication_api_1.yaml): 3.0.1, 1 operations - [Authentication Services](https://developer.citi.com/apidocs/redocusaurus/authentication_api_2.yaml): 3.0.1, 1 operations - [Authentication Services](https://developer.citi.com/apidocs/redocusaurus/authentication_api_3.yaml): 3.0.1, 1 operations - [Authentication Services v4.0.0](https://developer.citi.com/apidocs/redocusaurus/authentication_api_4.yaml): 3.0.1, 1 operations ### Account Reporting — 7 contracts, 15 operations - [Account Statement Services v1.0.0](https://developer.citi.com/apidocs/redocusaurus/blocksandfilters.yaml): 3.1.0, 5 operations - [Accounts v4.0.0](https://developer.citi.com/apidocs/redocusaurus/accounts.yaml): 3.0.3, 3 operations - [Accounts v5.0.0](https://developer.citi.com/apidocs/redocusaurus/accountsv5.yaml): 3.1.0, 2 operations - [Statement Services v1.0.0](https://developer.citi.com/apidocs/redocusaurus/statements_api.yaml): 3.0.1, 2 operations - [Account Notifications v1.0.0](https://developer.citi.com/apidocs/redocusaurus/account-notifications-api.yaml): 3.0.0, 1 operations - [Balances API v3.0.0](https://developer.citi.com/apidocs/redocusaurus/balances_api.yaml): 3.0.3, 1 operations - [accountreporting_2-0-0 v2.0.0](https://developer.citi.com/apidocs/redocusaurus/statementsv2_api.yaml): 3.0.2, 1 operations ### Outgoing Payments — 27 contracts, 71 operations - [Payment Acceptance API v1.0.0](https://developer.citi.com/apidocs/redocusaurus/DigitalPaymentsCollectionsv12.yaml): 3.0.2, 19 operations - [Instant Payments v1.0.0](https://developer.citi.com/apidocs/redocusaurus/express_payments_api.yaml): 3.0.2, 10 operations - [eMandate Service API v1.0.0](https://developer.citi.com/apidocs/redocusaurus/PayTo.yaml): 3.0.3, 5 operations - [Receivable Services v1.0.0](https://developer.citi.com/apidocs/redocusaurus/VAManagement.yaml): 3.0.3, 5 operations - [CCAPI Payments(JSON) v1.0.0](https://developer.citi.com/apidocs/redocusaurus/add-on-service.yaml): 3.0.2, 4 operations - [Add-on Services v1.0.0](https://developer.citi.com/apidocs/redocusaurus/AddOnService.yaml): 3.0.3, 3 operations - [WorldLink v2.0.0](https://developer.citi.com/apidocs/redocusaurus/WorldLink_V2_api.yaml): 3.0.1, 3 operations - [WorldLink v3.0.0](https://developer.citi.com/apidocs/redocusaurus/WorldLink_V3_api.yaml): 3.0.1, 3 operations - [Payment Status Inquiry v3.0.0](https://developer.citi.com/apidocs/redocusaurus/payment-status.yaml): 2.0, 2 operations - [WorldLink Payment v5.0.0](https://developer.citi.com/apidocs/redocusaurus/WorldLink_V5_api.yaml): 3.0.2, 2 operations - [Bulk Payment Initiation API v1.0.0](https://developer.citi.com/apidocs/redocusaurus/bulk-payments.yaml): 3.0.3, 1 operations - [WorldLink Payment v1.0.0](https://developer.citi.com/apidocs/redocusaurus/contractstatusinquiry.yaml): 3.0.2, 1 operations - [Payment Services v3.0.0](https://developer.citi.com/apidocs/redocusaurus/payment-reconfirmation.yaml): 2.0, 1 operations - [Payment Refund v2.0.0](https://developer.citi.com/apidocs/redocusaurus/payment-refund.yaml): 2.0, 1 operations - [FI Payment Services v3.0.0](https://developer.citi.com/apidocs/redocusaurus/paymentcancellation-json.yaml): 2.0, 1 operations - [FI Payment Services v3.0.0](https://developer.citi.com/apidocs/redocusaurus/paymentcancellation-xml.yaml): 2.0, 1 operations - [Enhanced Payment Status Inquiry v3.0.3](https://developer.citi.com/apidocs/redocusaurus/paymentenhancedinquiry-json.yaml): 3.0.1, 1 operations - [Enhanced Payment Status Inquiry v3.0.1](https://developer.citi.com/apidocs/redocusaurus/paymentenhancedinquiry-xml.yaml): 3.0.1, 1 operations - [Payment Initiation Service v3.0.0](https://developer.citi.com/apidocs/redocusaurus/paymentinitiation-pacs008.yaml): 3.0.1, 1 operations - [Payment Initiation Service v3.0.0](https://developer.citi.com/apidocs/redocusaurus/paymentinitiation-pacs009.yaml): 3.0.1, 1 operations - [Payment Initiation Service v3.0.0](https://developer.citi.com/apidocs/redocusaurus/paymentinitiation-pain102.yaml): 3.0.1, 1 operations - [Payment Initiation Service v3.0.1](https://developer.citi.com/apidocs/redocusaurus/paymentinitiation-pain103.yaml): 3.0.1, 1 operations - [Proof_of_Payment v1.0.0](https://developer.citi.com/apidocs/redocusaurus/proof-of-payment.yaml): 3.0.1, 1 operations - [FX Rate v1.0.0](https://developer.citi.com/apidocs/redocusaurus/WorldLink_IR_api.yaml): 3.1.0, 1 operations - [WorldLink v1.0.0](https://developer.citi.com/apidocs/redocusaurus/WorldLink_V1_api.yaml): 3.0.1, 1 operations - [CCAPI Payments(JSON) v1.0.0](https://developer.citi.com/apidocs/redocusaurus/DigitalPaymentsCollections-webhooks.yaml): 3.1.0, 0 operations - [CCAPI Payments(JSON) v1.0.1](https://developer.citi.com/apidocs/redocusaurus/express_payments_webhooks.yaml): 3.1.0, 0 operations ### Payment Acceptance — 10 contracts, 44 operations - [API Pix v2.8.1](https://developer.citi.com/apidocs/redocusaurus/BrazilLocalMandate.yaml): 3.0.0, 17 operations - [Online Payment Acceptance API v1.0.0](https://developer.citi.com/apidocs/redocusaurus/online-payment-acceptance-api.yaml): 3.0.2, 6 operations - [PayerID Management Services v1.0.3](https://developer.citi.com/apidocs/redocusaurus/payerid_api.yaml): 3.0.2, 5 operations - [Brazil QR code - Dynamic Collections with Due Date API v1.0.0](https://developer.citi.com/apidocs/redocusaurus/due-date.yaml): 3.0.3, 4 operations - [Brazil QR code - Dynamic Immediate Collections API v1.0.0](https://developer.citi.com/apidocs/redocusaurus/immediate.yaml): 3.0.3, 4 operations - [eMandate API v1.0.0](https://developer.citi.com/apidocs/redocusaurus/e-mandate-api-v1.yaml): 2.0, 2 operations - [eMandate API v2.0.0](https://developer.citi.com/apidocs/redocusaurus/e-mandate-api-v2.yaml): 2.0, 2 operations - [Instant Direct Debit v1.0.0](https://developer.citi.com/apidocs/redocusaurus/IDD.yaml): 3.0.3, 2 operations - [Direct Debit API v3.0.0](https://developer.citi.com/apidocs/redocusaurus/direct-debit-api.yaml): 2.0, 1 operations - [Brazil QR code - Static Collections v1.0.0](https://developer.citi.com/apidocs/redocusaurus/Static.yaml): 3.0.3, 1 operations ### Commercial Cards & Virtual Card Accounts — 26 contracts, 57 operations - [Grace Wallet Marqeta API](https://developer.citi.com/apidocs/redocusaurus/marqueta.yaml): 2.0, 5 operations - [Virtual Accounts Single Entity v1.0.0](https://developer.citi.com/apidocs/redocusaurus/VCA_api.yaml): 3.0.0, 4 operations - [vca events subscriptions v2.0.0](https://developer.citi.com/apidocs/redocusaurus/vcaEventsSubscriptions.yaml): 3.0.0, 4 operations - [Virtual Cards Notifications API](https://developer.citi.com/apidocs/redocusaurus/virtual-cards-notifications.yaml): 2.0, 4 operations - [mVCA Distributed Partner Lifecycle APIs v1.0.0](https://developer.citi.com/apidocs/redocusaurus/mobileCardOnboarding.yaml): 2.0, 3 operations - [Mobile VirtualCard Lifecycle v1.0.6](https://developer.citi.com/apidocs/redocusaurus/MobileVirtualLifecycle.yaml): 2.0, 3 operations - [Statement Transactions](https://developer.citi.com/apidocs/redocusaurus/statement-transactions.yaml): 2.0, 3 operations - [Virtual Cards Life Cycle Management v1.0.0](https://developer.citi.com/apidocs/redocusaurus/virtual-cards-lifecycle-v1.yaml): 2.0, 3 operations - [VCA Life Cycle Management v2.0.0](https://developer.citi.com/apidocs/redocusaurus/virtual-cards-lifecycle-v4.yaml): 3.0.0, 3 operations - [VCA Life Cycle Management for Payment Intermediaries](https://developer.citi.com/apidocs/redocusaurus/virtual-cards-pi.yaml): 2.0, 3 operations - [VCA Life Cycle Management for Payment Intermediaries v2.0.0](https://developer.citi.com/apidocs/redocusaurus/virtual-cards-pi-v2.yaml): 3.0.0, 3 operations - [cards-disputes_1-0-0 v1.0.0](https://developer.citi.com/apidocs/redocusaurus/card-disputes.yaml): 3.0.0, 2 operations - [IVA-GRACE](https://developer.citi.com/apidocs/redocusaurus/grace-iva.yaml): 2.0, 2 operations - [Grace Mobile Virtual Cards Wallet API](https://developer.citi.com/apidocs/redocusaurus/mobile-wallets.yaml): 2.0, 2 operations - [VCA Reporting v2.0.0](https://developer.citi.com/apidocs/redocusaurus/virtual-cards-reporting.yaml): 3.0.0, 2 operations - [Account Balance Inquiry v1.0.0](https://developer.citi.com/apidocs/redocusaurus/account_balance_inquiry_api.yaml): 2.0, 1 operations - [VCA Clearing Exception Report](https://developer.citi.com/apidocs/redocusaurus/clearing-exception-report.yaml): 2.0, 1 operations - [Cards Disputes v1.0.0](https://developer.citi.com/apidocs/redocusaurus/dispute-webhook.yaml): 3.0.0, 1 operations - [VCA ID Provisioning v1.0.0](https://developer.citi.com/apidocs/redocusaurus/id-provisioning.yaml): 3.0.0, 1 operations - [VCA Purchase Template Details](https://developer.citi.com/apidocs/redocusaurus/purchase.yaml): 2.0, 1 operations - [get-vca-details v2.0.0](https://developer.citi.com/apidocs/redocusaurus/reporting-get-2.yaml): 3.0.0, 1 operations - [Dual Auth Authorization API v2.0.0](https://developer.citi.com/apidocs/redocusaurus/vca-dual-auth-authorization.yaml): 3.0.1, 1 operations - [Dual Auth Notification v1.0.0](https://developer.citi.com/apidocs/redocusaurus/vca-dual-auth-notification.yaml): 3.0.1, 1 operations - [vca events notifications v2.0.0](https://developer.citi.com/apidocs/redocusaurus/vcaGetNotifications.yaml): 3.0.0, 1 operations - [CommercialEventNotifications v2.0.0](https://developer.citi.com/apidocs/redocusaurus/vcaNotificationsWebhooks.yaml): 3.0.0, 1 operations - [VCA Life Cycle Webhook Client Notification v1.0.0](https://developer.citi.com/apidocs/redocusaurus/virtual-cards-pi-webhooks.yaml): 3.0.0, 1 operations ### CitiFX Gateway & Instant FX — 17 contracts, 16 operations - [FX Authorization API](https://developer.citi.com/apidocs/redocusaurus/fx_authentication_api.yaml): 3.1.0, 1 operations - [FX Benchmark Order](https://developer.citi.com/apidocs/redocusaurus/fx_benchmark_async_api.yaml): 3.0.3, 1 operations - [FX Benchmark Order](https://developer.citi.com/apidocs/redocusaurus/fx_benchmark_sync_api.yaml): 3.0.3, 1 operations - [FX Order Cancel](https://developer.citi.com/apidocs/redocusaurus/fx_cancel_async_api.yaml): 3.0.3, 1 operations - [FX Order Cancel](https://developer.citi.com/apidocs/redocusaurus/fx_cancel_sync_api.yaml): 3.0.3, 1 operations - [Fixed Rate API](https://developer.citi.com/apidocs/redocusaurus/fx_eCommerce_api.yaml): 2.0, 1 operations - [FX Order Enquiry](https://developer.citi.com/apidocs/redocusaurus/fx_gateway_reporting_async_api.yaml): 3.0.3, 1 operations - [FX Order Enquiry](https://developer.citi.com/apidocs/redocusaurus/fx_gateway_reporting_sync_api.yaml): 3.0.3, 1 operations - [FX Market Order](https://developer.citi.com/apidocs/redocusaurus/fx_market_async_api.yaml): 3.0.3, 1 operations - [FX Market Order](https://developer.citi.com/apidocs/redocusaurus/fx_market_sync_api.yaml): 3.0.3, 1 operations - [InstantFX Order](https://developer.citi.com/apidocs/redocusaurus/fx_orders_async_api.yaml): 3.1.0, 1 operations - [InstantFX Order (SYNCHRONOUS CALL)](https://developer.citi.com/apidocs/redocusaurus/fx_orders_sync_api.yaml): 3.1.0, 1 operations - [InstantFX Quote Request](https://developer.citi.com/apidocs/redocusaurus/fx_quote_async_api.yaml): 3.1.0, 1 operations - [InstantFX Quote Request (SYNCHRONOUS CALL)](https://developer.citi.com/apidocs/redocusaurus/fx_quote_sync_api.yaml): 3.1.0, 1 operations - [InstantFX Reporting](https://developer.citi.com/apidocs/redocusaurus/fx_reporting_async_api.yaml): 3.1.0, 1 operations - [InstantFX Reporting (SYNCHRONOUS CALL)](https://developer.citi.com/apidocs/redocusaurus/fx_reporting_sync_api.yaml): 3.1.0, 1 operations - [Rates API method signature and return type v1.0.0](https://developer.citi.com/apidocs/redocusaurus/fx_test.yaml): 3.1.0, 0 operations ### Custody & Securities Services — 12 contracts, 23 operations - [Custody Billing API vv1.0.0](https://developer.citi.com/apidocs/redocusaurus/custody-billing.yaml): 3.0.1, 6 operations - [Cash Balances API](https://developer.citi.com/apidocs/redocusaurus/cash-balances.yaml): 3.0.1, 2 operations - [Cash Transactions API](https://developer.citi.com/apidocs/redocusaurus/cash-transactions.yaml): 3.0.1, 2 operations - [Custody Penalities API vv1.0.0](https://developer.citi.com/apidocs/redocusaurus/custody-penalties.yaml): 3.0.1, 2 operations - [Safekeeping Positions API](https://developer.citi.com/apidocs/redocusaurus/safekeeping-positions.yaml): 3.0.1, 2 operations - [The Safekeeping Transactions API v3.0.0](https://developer.citi.com/apidocs/redocusaurus/securitytransactionsaccounts.yaml): 3.0.1, 2 operations - [Tax Reclaims API vv1.0.0](https://developer.citi.com/apidocs/redocusaurus/tax-reclaims.yaml): 3.0.1, 2 operations - [FX Transactions API vv1.0.0](https://developer.citi.com/apidocs/redocusaurus/custody-fx-transactions.yaml): 3.0.1, 1 operations - [ACES ETF OrderApprovalAPI v1.0](https://developer.citi.com/apidocs/redocusaurus/order-approval.yaml): 3.1.0, 1 operations - [ACES ETF SubmitPLF v1.0](https://developer.citi.com/apidocs/redocusaurus/portfolio-listing.yaml): 3.1.0, 1 operations - [Custody Accounts API v2.16.1](https://developer.citi.com/apidocs/redocusaurus/safekeeping-accounts.yaml): 3.0.1, 1 operations - [ACES ETF Order Approval API v1.0](https://developer.citi.com/apidocs/redocusaurus/submit-action.yaml): 3.1.0, 1 operations ### Funds Transfer Agency — 4 contracts, 4 operations - [Transfer Agency Account vv2.0.0](https://developer.citi.com/apidocs/redocusaurus/transfer-agency-accounts.yaml): 3.1.0, 1 operations - [Transfer Agency Holding vv2.0.0](https://developer.citi.com/apidocs/redocusaurus/transfer-agency-holding.yaml): 3.1.0, 1 operations - [Transfer Agency Investor vv2.0.0](https://developer.citi.com/apidocs/redocusaurus/transfer-agency-investors.yaml): 3.1.0, 1 operations - [Transfer Agency Transactions vv2.0.0](https://developer.citi.com/apidocs/redocusaurus/transfer-agency-transactions.yaml): 3.1.0, 1 operations ### Open Banking — 3 contracts, 11 operations - [Bank Data Sharing v1.0.0](https://developer.citi.com/apidocs/redocusaurus/ukraine_bank_data_sharing_api.yaml): 3.0.2, 6 operations - [Bank Service Initiation v1.0.0](https://developer.citi.com/apidocs/redocusaurus/ukraine_payment_service_initiation_api.yaml): 3.0.2, 4 operations - [Authentication Services v1.0.0](https://developer.citi.com/apidocs/redocusaurus/ukraine_open_banking_authentication_api.yaml): 3.0.1, 1 operations ### Trade Services — 2 contracts, 7 operations - [Trade Finance Undertaking API v0.0.1](https://developer.citi.com/apidocs/redocusaurus/finance_undertaking_api.yaml): 3.0.2, 4 operations - [Trade API](https://developer.citi.com/apidocs/redocusaurus/trade_api.yaml): 2.0, 3 operations ### Gateway Services — 1 contracts, 19 operations - [Gateway Services v1.0.0](https://developer.citi.com/apidocs/redocusaurus/marketplace-management.yaml): 3.0.2, 19 operations ### Additional Payment Services — 4 contracts, 24 operations - [Additional Payment Services](https://developer.citi.com/apidocs/redocusaurus/self-service_api.yaml): 3.0.1, 13 operations - [Request To Pay](https://developer.citi.com/apidocs/redocusaurus/request-to-pay.yaml): 2.0, 6 operations - [Entity Whitelisting v1.0.0](https://developer.citi.com/apidocs/redocusaurus/EntityID.yaml): 3.0.3, 3 operations - [Self Services v3.0.0](https://developer.citi.com/apidocs/redocusaurus/beneficiary-search.yaml): 2.0, 2 operations ## Artifacts in this profile - `openapi/` — 118 first-party contracts, saved verbatim - `authentication/citi-authentication.yml` — every declared securityScheme across the estate - `scopes/citi-scopes.yml` — 24 OAuth scopes derived from the contracts - `conventions/citi-conventions.yml` — idempotency coverage, reversibility, pagination, tracing, versioning - `errors/citi-problem-types.yml` — status-code catalogue and the three error envelopes in use - `errors/citi-decline-codes.yml` — 272 ISO 20022 external return reason codes with meanings - `conformance/citi-conformance.yml` — standards asserted from the contracts, including ISO 20022 - `lifecycle/citi-lifecycle.yml` — versioning, RFC 8594 Deprecation/Sunset headers, onboarding lifecycle - `rate-limits/citi-rate-limits.yml` — the headers Citi declares and the numbers it does not publish - `plans/citi-plans-pricing.yml` — no published tiers — enterprise, relationship-managed - `sandbox/citi-sandbox.yml` — the parallel sandbox estate declared inside the contracts - `asyncapi/citi-webhooks.yml` — the webhook and subscription surface - `data-model/citi-data-model.yml` — recurring domain objects across 2,511 schemas - `packages/citi-packages.yml` — no first-party SDK on any registry — checked, not assumed - `mcp/citi-mcp.yml` — candidate tool list; Citi ships no MCP server - `well-known/citi-well-known.yml` — 64 probes across 8 hosts, zero documents - `skills/` — six agent skills grounded in real operationIds - `security/citi-vulnerability-disclosure.yml` — first-party VDP page plus the Bugcrowd engagement - `security/citi-domain-security.yml` — TLS, HSTS, DNSSEC, CAA, SPF, DMARC probe