overlay: 1.0.0
info:
  title: API Evangelist enhancements — Citi Outgoing Payments
  version: 1.0.0
  description: Non-destructive annotations applied on top of the 27 Citi Outgoing Payments contract(s) in openapi/.
    Adds provenance, cross-links to the derived artifacts in this repository, and two safety facts about the estate
    that no single contract states. The original specifications are never mutated.
x-generated: '2026-09-05'
x-method: generated
x-source: openapi/ — Citi contracts harvested verbatim from https://developer.citi.com/apidocs on 2026-09-05
extends:
- openapi/citi-digitalpaymentscollectionsv12-openapi.yaml
- openapi/citi-express-payments-api-openapi.yaml
- openapi/citi-payto-openapi.yaml
- openapi/citi-vamanagement-openapi.yaml
- openapi/citi-add-on-service-openapi.yaml
- openapi/citi-addonservice-openapi.yaml
- openapi/citi-worldlink-v2-api-openapi.yaml
- openapi/citi-worldlink-v3-api-openapi.yaml
- openapi/citi-payment-status-openapi.yaml
- openapi/citi-worldlink-v5-api-openapi.yaml
- openapi/citi-bulk-payments-openapi.yaml
- openapi/citi-contractstatusinquiry-openapi.yaml
- openapi/citi-payment-reconfirmation-openapi.yaml
- openapi/citi-payment-refund-openapi.yaml
- openapi/citi-paymentcancellation-json-openapi.yaml
- openapi/citi-paymentcancellation-xml-openapi.yaml
- openapi/citi-paymentenhancedinquiry-json-openapi.yaml
- openapi/citi-paymentenhancedinquiry-xml-openapi.yaml
- openapi/citi-paymentinitiation-pacs008-openapi.yaml
- openapi/citi-paymentinitiation-pacs009-openapi.yaml
- openapi/citi-paymentinitiation-pain102-openapi.yaml
- openapi/citi-paymentinitiation-pain103-openapi.yaml
- openapi/citi-proof-of-payment-openapi.yaml
- openapi/citi-worldlink-ir-api-openapi.yaml
- openapi/citi-worldlink-v1-api-openapi.yaml
- openapi/citi-digitalpaymentscollections-webhooks-openapi.yaml
- openapi/citi-express-payments-webhooks-openapi.yaml
actions:
- target: $.info
  description: Record where this contract came from and when it was harvested, so a consumer can re-fetch the original
    and diff it.
  update:
    x-apievangelist-source: https://developer.citi.com/apidocs/redocusaurus/
    x-apievangelist-harvested: '2026-09-05'
    x-apievangelist-family: Outgoing Payments
    x-apievangelist-provider: Citi
- target: $.info
  description: Attach the cross-cutting runtime semantics that are true of this contract but are not expressible
    inside it.
  update:
    x-conventions: conventions/citi-conventions.yml
    x-error-catalog: errors/citi-problem-types.yml
    x-decline-codes: errors/citi-decline-codes.yml
    x-authentication: authentication/citi-authentication.yml
    x-rate-limits: rate-limits/citi-rate-limits.yml
    x-lifecycle: lifecycle/citi-lifecycle.yml
- target: $.info
  description: State the idempotency and reversibility posture for this family, measured across the whole estate.
  update:
    x-idempotency-coverage: partial
    x-idempotency-header: Idempotency-Id
    x-reversibility-grade: documented
    x-reversibility-note: Reversal operations exist; no reversal WINDOW is published in any Citi contract or guide.
- target: $.paths.*.*[?(@.responses['429'])]
  description: Flag that a 429 on this estate usually arrives with no RateLimit-* headers and no Retry-After, so
    clients must back off exponentially.
  update:
    x-rate-limit-signal: status-code-only
    x-retry-strategy: exponential-backoff
- target: $.paths.*.post
  description: Warn that most POST operations in this estate do not declare an Idempotency-Id header, so a timeout
    is ambiguous and must be resolved by inquiry rather than by retry.
  update:
    x-retry-safety: inquire-before-retry