openapi: 3.0.2
info:
description: >-
WorldLink is a complete cross-border payment and Foreign-Exchange (FX)
service that allows you to perform payments in 135 currencies without having
the need to maintain local currency accounts for each of them. CitiConnect
API now offers you WorldLink services of FX Contract Status Inquiry, FX rate
enquiry, FX deal booking, cross-border payment initiation with 24X7
availability.
contact:
name: Standards & Developer Hub
url: https://tts.sandbox.developer.citi.com/citiconnect/
email: developer-support@citi.com
version: 1.0.0
title: WorldLink Payment
servers:
- url: https://tts.apib2b.citi.com/citiconnect/prod/worldlinkservices
description: production gateway url
- url: https://tts.sandbox.apib2b.citi.com/citiconnect/sb/worldlinkservices
description: sandbox url
tags:
- name: Contract status inquiry
security:
- clientCredentials: []
paths:
/worldlinkservices/v1/fx/inquiry:
get:
tags:
- Contract status inquiry
summary: Contract Status Inquiry
description: >-
Currently FX rates can be retrieved through the WorldLink FX Rate
Inquiry endpoint, Book FX through WorldLink FX Book API endpoint and
Cancel FX via the WorldLink FX Cancel API endpoint. The FX contract
Status endpoint verifies the FX status if the the response of FX Book is
not received or non-conclusive. The FX contract might be in various
statuses - such as Booked, Cancelled, or Not found because the Deal may
not even exist. The FX Contract Status will inquire about the
whereabouts of an FX deal. Supports “application/XML” and
“application/JSON”. The OAuth Token prefixed with “Bearer“ and
space in between.
servers:
- url: https://tts.apib2b.citi.com/citiconnect/prod
operationId: processContractStatus
parameters:
- name: Content-Type
in: header
description: Supports "application/XML" and "application/JSON"
required: true
schema:
type: string
- name: Authorization
in: header
description: The OAuth Token prefixed with "Bearer" and space in between.
required: true
schema:
type: string
- name: WLClntId
in: header
description: >-
WorldLink Client ID. WorldLink Client Number and Branch Number.
Provide Branch number if the same was part of FX request
required: true
schema:
type: string
maxLength: 9
example: '123451234'
- name: ContractRef
in: query
description: >-
WorldLink Contract Reference number. WorldLink Contract Number and
WorldLink Sequence Number - this is the true unique identifier.
External interfaces use contract number concatenated to sequence
number to designate unique deals. Please use this if available.
schema:
type: string
maxLength: 15
example: M10001000123456
- name: UserId
in: query
description: >-
Unique UserId created by WorldLink and returned as part of FX Deal
confirmation. If User inquires using UserId, then other parameters
PymtCcy, FundCcy and PymtCcyAmt/FundCcyAmt will be mandatory. If
Contract Reference number is provided UserId can be left blank
schema:
type: string
maxLength: 8
example: WL123456
- name: PymtCcy
in: query
description: >-
WorldLink Payment Currency SWIFT code. Mandatory parameter to
proceed with search by `UserId` parameter.
schema:
type: string
maxLength: 3
example: GBP
- name: PymtCcyAmt
in: query
description: >-
WorldLink Payment Currency amount. The actual deal amount must be
greater than this amount. There are cases where the same deal
number is passed by the source system for multiple payments
therefore an amount less than the full deal amount can be a match.
If not included the funding/remit amount must be included. Either of
PymtCcyAmt or FundCcyAmt to be provided to proceed with search by
`UserId` parameter
schema:
type: string
maxLength: 16
pattern: ^\d{1,13}(\.\d{1,2})?$
example: '1234567891234.00'
- name: FundCcy
in: query
description: >-
WorldLink Funding Currency SWIFT code. Mandatory parameter to
proceed with search by `UserId` parameter.
schema:
type: string
maxLength: 3
example: EUR
- name: FundCcyAmt
in: query
description: >-
WorldLink Funding Currency amount. The actual deal amount must be
greater than this amount. There are cases where the same deal
number is passed by the source system for multiple payments
therefore an amount less than the full deal amount can be a match.
If not included the payment amount must be included. Either of
PymtCcyAmt or FundCcyAmt to be provided to proceed with search by
`UserId` parameter.
schema:
type: string
maxLength: 16
pattern: ^\d{1,13}(\.\d{1,2})?$
example: '1234567891234.00'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/FxGetDealOperationResponse'
examples:
Deal-Response-Success:
$ref: '#/components/examples/FxGetDealOperationResponse'
Deal-Response-Deal-Not-Found:
$ref: >-
#/components/examples/Fx-Deal-Inquiry-API-Response-Deal-Not-Found-Example
Deal-Response-Cancelled:
$ref: >-
#/components/examples/Fx-Deal-Inquiry-API-Response-Deal-Cancelled-Example
Deal-Response-Invalid-Contract-Reference:
$ref: >-
#/components/examples/Fx-Deal-Inquiry-API-Response-Invalid-Contract-Reference-Example
application/xml:
schema:
$ref: '#/components/schemas/FxGetDealOperationResponse'
examples:
Deal-Response-Success:
value: >-
145.00000:
Requested deal
foundEUR62955000190.04CADEUR0.62100000145.00CAD145.000.002025-10-24-04.02.26.701438000APIM0.000.0090.04XBACBC40.0020251024M164631008796072026-04-13-10:15:402025102790.04
Deal-Response-Deal-Not-Found:
value: >-
145100:
No FX contract found matching the search criteria. Please
review and
re-inputEUR629550001XBACBC4M164631008796072026-04-10-10:42:22CAR100APIM90.04
Deal-Response-Cancelled:
value: >-
145177:
Deal already
cancelled.EUR629550001XBACBC4AA82601015554102026-04-14-13:17:37CAD177APIM90.04
Deal-Response-Invalid-Contract-Reference:
value: >-
87.16003:
Invalid FX contract
numberUSD583700001XML10N34M16463100879602026-04-10-11:10:33EUR003APIM100.00
'400':
description: Bad Request.
content:
application/json:
schema:
$ref: '#/components/schemas/Error-Response'
examples:
Bad-Request-Example-ClientId-Missing:
$ref: '#/components/examples/Bad-Request-Example-ClientId-Missing'
Bad-Request-Example-ContractRef-UserId-Missing:
$ref: >-
#/components/examples/Bad-Request-Example-ContractRef-UserId-Missing
Bad-Request-Example-Funding-Currency-Missing:
$ref: >-
#/components/examples/Bad-Request-Example-Funding-Currency-Missing
Bad-Request-Example-Payment-Currency-Missing:
$ref: >-
#/components/examples/Bad-Request-Example-Payment-Currency-Missing
Bad-Request-Example-Currency-Amount-Missing:
$ref: >-
#/components/examples/Bad-Request-Example-Currency-Amount-Missing
application/xml:
schema:
$ref: '#/components/schemas/Error-Response'
examples:
Bad-Request-Example-ClientId-Missing:
value: >-
400Mismatch of WorldLink
Client ID or Client ID not
maintainedq2te~bd8e9b8f-d8e5-4a48-ad13-5d1ec8bb32e829318
Bad-Request-Example-ContractRef-UserId-Missing:
value: >-
q2te~120f2560-c6aa-4061-9038-bdb53da20d1043650ContractRef
or UserId is mandatory. Please provide value for either of
ContractRef or
UserId.400
Bad-Request-Example-Funding-Currency-Missing:
value: >-
q2te~8b8b4912-1b37-449a-9e1a-3401d7ab7d8343578FundCcy
is mandatory when UserId is selected. Please provide value
for FundCcy.400
Bad-Request-Example-Payment-Currency-Missing:
value: >-
q2te~bd8e9b8f-d8e5-4a48-ad13-5d1ec8bb32e829332PymtCcy
is mandatory when UserId is selected. Please provide value
for PymtCcy.400
Bad-Request-Example-Currency-Amount-Missing:
value: >-
q2te~8b8b4912-1b37-449a-9e1a-3401d7ab7d8343581PymtCcyAmt
or FundCcyAmt is mandatory when UserId is selected. Please
provide value for either of PymtCcyAmt or
FundCcyAmt.400
'401':
description: >-
The request is Unauthorized. Please try again with valid
credentials.
content:
application/json:
schema:
$ref: '#/components/schemas/Error-Detail'
examples:
Unauthorized-Example:
$ref: '#/components/examples/Unauthorized-Example'
application/xml:
schema:
$ref: '#/components/schemas/Error-Detail'
examples:
Unauthorized-Example:
value: >-
401Invalid
OAuth TokenPlease use valid
OAuth Token
'403':
description: The request is Forbidden
content:
application/json:
schema:
$ref: '#/components/schemas/Error-Detail'
examples:
Request-Forbidden-Example:
$ref: '#/components/examples/Request-Forbidden-Example'
application/xml:
schema:
$ref: '#/components/schemas/Error-Detail'
examples:
Request-Forbidden-Example:
value: >-
Forbidden403You
are forbidden to access this
service.
'404':
description: Not Found. Please check your URL.
content:
application/json:
schema:
$ref: '#/components/schemas/Error-Detail'
examples:
Not-Found-Example:
$ref: '#/components/examples/Not-Found-Example'
application/xml:
schema:
$ref: '#/components/schemas/Error-Detail'
examples:
Not-Found-Example:
value: >-
404Not
FoundNo resources match
requested URI
'500':
description: Unable to serve your request at this moment. Please try again later.
content:
application/json:
schema:
$ref: '#/components/schemas/Error-Response'
examples:
Internal-Server-Example:
$ref: '#/components/examples/Internal-Server-Example'
application/xml:
schema:
$ref: '#/components/schemas/Error-Response'
examples:
Internal-Server-Example:
value: >-
500Unable to process
your
requestq2te~120f2560-c6aa-4061-9038-bdb53da20d1043788
components:
schemas:
FxGetDealOperationResponse:
title: Fx-Deal-Inquiry-API-Response
properties:
FXP588INOperationResponse:
$ref: '#/components/schemas/FXP588INOperationResponse'
FXP588INOperationResponse:
type: object
title: Fx-Get-Deal-Operation-Response
required:
- FxDealInquiryRsp
properties:
FXP588IN-Operation-Response:
$ref: '#/components/schemas/FxDealInquiryRsp'
FxDealInquiryRsp:
type: object
title: FXP588IN-Operation-Response
properties:
WLClntId:
type: string
description: >-
WorldLink Client ID. WorldLink Client Number and Branch Number.
Provide Branch number if the Branch Number was part of FX request
maxLength: 9
example: '123451234'
title: WLClntId
ContractRef:
type: string
description: >-
WorldLink Contract Reference number. WorldLink Contract Number and
WorldLink Sequence Number - this is the true unique identifier.
External interfaces use contract number concatenated to sequence
number to designate unique deals. Please use this if available.
maxLength: 15
example: M10001000123456
title: ContractRef
UserId:
type: string
description: >-
Unique UserId created by WorldLink. It will be used as a key to
reference the requests and accepts. For successful deal lookup
responses, UserId will be mandatorily populated by WorldLink. In
case the lookup fails or the Deal is not found in WorldLink, then
UserId will not be populated in the response.
maxLength: 8
example: ABCD1234
title: UserId
ResTime:
type: string
description: >-
Date and Time when the response is generated by WorldLink. Format:
"YYYY-MM-DD-HH:MM:SS"
maxLength: 19
example: 2024-07-07-07:07:07
title: ResTime
PymtCcy:
type: string
description: WorldLink Payment Currency SWIFT code.
maxLength: 3
example: GBP
title: PymtCcy
PymtCcyAmt:
type: string
description: WorldLink Payment Currency amount.
maxLength: 16
example: '1234567891234.00'
title: PymtCcyAmt
FundCcy:
type: string
description: WorldLink Funding Currency SWIFT code.
maxLength: 3
example: USD
title: FundCcy
FundCcyAmt:
type: string
description: WorldLink Funding Currency amount.
maxLength: 16
example: '1234567891234.00'
title: FundCcyAmt
Rate:
type: number
description: FX Rate for Prebook.
maximum: 99999999.99999999
example: 100.1010101
title: Rate
BookDate:
type: string
description: >-
FX Booking date in WorldLink. If the deal is found the actual
booking date is shared Format: YYYYMMDD.
maxLength: 8
example: '20200626'
title: BookDate
ValueDate:
type: string
description: 'FX Contract Value Date Format: YYYYMMDD.'
maxLength: 8
example: '20200426'
title: ValueDate
DealTs:
type: string
description: >-
Date and Time when the prebook deal was booked in OLR. Format:
"YYYY-MM-DD-HH.MM.SS.nnnnnn"
maxLength: 26
example: 2024-12-03-03.51.04.146766
title: DealTs
FundActTotalLmt:
type: string
description: >-
Total FX limit set-up by OLR - Funding account. This will only be
populated if LinkToPymt is "N"
maxLength: 16
example: '1234567891234.00'
title: FundActTotalLmt
FundActAvlLmt:
type: string
description: >-
Total available limit - Funding account (Total limit - Limit
earmarked). This will only be populated if LinkToPymt is "N"
maxLength: 16
example: '1234567891234.00'
title: FundActAvlLmt
FundActEarMrkLmt:
type: string
description: >-
Current limit earmarked - Funding account (Current earmarked limit +
current drawdown amt). This will only be populated if LinkToPymt is
"N"
maxLength: 16
example: '1234567891234.00'
title: FundActEarMrkLmt
FundActUtilLmt:
type: string
description: >-
Funding account - Current FX limit utilized post payment release
(current utilized limit + receipt of infotelex). This will only be
populated if LinkToPymt is "N"
maxLength: 16
example: '1234567891234.00'
title: FundActUtilLmt
PymtActTotalLmt:
type: string
description: >-
Total FX limit set-up by OLR - Payment account. This will only be
populated if LinkToPymt is "N"
maxLength: 16
example: '1234567891234.00'
title: PymtActTotalLmt
PymtActAvlLmt:
type: string
description: >-
Total available limit - Payment account. Total limit - Limit
earmarked . This will only be populated if LinkToPymt is "N"
maxLength: 16
example: '1234567891234.00'
title: PymtActAvlLmt
PymtActEarMrkLmt:
type: string
description: >-
Current limit earmarked - Payment account (Current earmarked limit +
current drawdown amt). This will only be populated if LinkToPymt is
"N"
maxLength: 16
example: '1234567891234.00'
title: PymtActEarMrkLmt
PymtActUtilLmt:
type: string
description: >-
Payment account - Current FX limit utilized post payment release
(current utilized limit + receipt of infotelex). This will only be
populated if LinkToPymt is "N"
maxLength: 16
example: '1234567891234.00'
title: PymtActUtilLmt
StatusCode:
type: string
description: >-
This parameter will be mandatorily sent in WorldLink response as per
the following scenarios - 1. For successful execution WorldLink
will return "000" 2. For any detail level error, a non-zero value is
shown
maxLength: 3
example: '000'
title: StatusCode
StatusMsg:
type: string
description: >-
This parameter will be mandatorily sent in WorldLink response along
with StatusCode. Message describing the error code/reason.
maxLength: 255
example: '000: Request Processed Successfully'
title: StatusMsg
Error-Detail:
title: Error-Detail
xml:
name: ErrorDetail
properties:
httpCode:
type: string
title: status
description: Error status that provides more details on issue.
httpMessage:
type: string
title: message
description: More information about the issue.
moreInformation:
type: string
title: correlationId
description: Unique identifier for the request.
Error-Response:
properties:
status:
type: string
message:
type: string
correlationId:
type: string
securitySchemes:
clientCredentials:
description: >+
All CitiConnect APIs use the oAuth2 authentication scheme, which
requires a bearer token to authenticate your API call. The Token URL
includes the version of authentication used by this API. See the Citi Authentication API reference for
information on requesting a token.
type: oauth2
flows:
authorizationCode:
authorizationUrl: /authenticationservices/v3/oauth/token
tokenUrl: /authenticationservices/v3/oauth/token
scopes:
authenticationservices/v3: Grant read-only access to WorldLink FX service
examples:
FxGetDealOperationResponse:
value:
FxGetDealOperationResponse:
FXP588INOperationResponse:
FxDealInquiryRsp:
Source: APIM
WLClntId: '123451234'
ContractRef: M10001000123456
ResTime: 2025-08-13-04:40:37
UserId: XBACBC4
PymtCcy: CAD
PymtCcyAmt: '145'
FundCcy: EUR
FundCcyAmt: '90.04'
Symbol: CADEUR
Rate: 0.621
BookDate: '20251024'
ValueDate: '20251027'
DealTs: 2025-10-24-04.02.26.701438
FundActTotalLmt: '90.04'
FundActAvlLmt: '90.04'
FundActEarMrkLmt: '0.00'
FundActUtilLmt: '0.00'
PymtActTotalLmt: '145.00'
PymtActAvlLmt: '145.00'
PymtActEarMrkLmt: '0.00'
PymtActUtilLmt: '0.00'
StatusCode: '000'
StatusMsg: '000: Requested deal found'
Fx-Deal-Inquiry-API-Response-Deal-Not-Found-Example:
value:
FxGetDealOperationResponse:
FXP588INOperationResponse:
FxDealInquiryRsp:
Source: APIM
WLClntId: '123451234'
ContractRef: M16463100879607"
UserId: XBACBC4
ResTime: 2025-12-12-04:40:04
PymtCcy: CAD
PymtCcyAmt: '145'
FundCcy: EUR
FundCcyAmt: '90.04'
StatusCode: '100'
StatusMsg: >-
100: No FX contract found matching the search criteria. Please
review and re-input
Fx-Deal-Inquiry-API-Response-Deal-Cancelled-Example:
value:
FxGetDealOperationResponse:
FXP588INOperationResponse:
FxDealInquiryRsp:
Source: APIM
WLClntId: '123451234'
ContractRef: M10001000123456
UserId: XBACBC4
ResTime: 2025-08-08-04:40:37
PymtCcy: CAD
PymtCcyAmt: '145'
FundCcy: EUR
FundCcyAmt: '90.04'
StatusCode: '177'
StatusMsg: '177: Deal already cancelled'
Fx-Deal-Inquiry-API-Response-Invalid-Contract-Reference-Example:
value:
FxGetDealOperationResponse:
FXP588INOperationResponse:
FxDealInquiryRsp:
Source: APIM
WLClntId: '123451234'
ContractRef: M10001000123456
ResTime: 2025-08-13-04:40:37
UserId: XBACBC4
PymtCcy: CAD
PymtCcyAmt: '145'
FundCcy: EUR
FundCcyAmt: '90.04'
StatusCode: '100'
StatusMsg: >-
100: No FX contract found matching the search criteria. Please
review and re-input
Bad-Request-Example-ClientId-Missing:
value:
status: '400'
message: >-
WLClntID is mandatory and it cannot be empty. Please provide valid
value for WLClntID.
correlationId: testFxContractInquiry-400
Bad-Request-Example-ContractRef-UserId-Missing:
value:
status: '400'
message: >-
ContractRef or UserId is mandatory. Please provide value for either of
ContractRef or UserId.
correlationId: testFxContractInquiry-400
Bad-Request-Example-Funding-Currency-Missing:
value:
status: '400'
message: >-
FundCcy is mandatory when UserId is selected. Please provide value for
FundCcy.
correlationId: testFxContractInquiry-400
Bad-Request-Example-Payment-Currency-Missing:
value:
status: '400'
message: >-
PymtCcy is mandatory when UserId is selected. Please provide value for
PymtCcy.
correlationId: testFxContractInquiry-400
Bad-Request-Example-Currency-Amount-Missing:
value:
status: '400'
message: >-
PymtCcyAmt or FundCcyAmt is mandatory when UserId is selected. Please
provide value for either of PymtCcyAmt or FundCcyAmt.
correlationId: testFxContractInquiry-400
Unauthorized-Example:
value:
httpCode: '401'
httpMessage: Unauthorized
moreInformation: This server could not verify that you are authorized to access the URL
Request-Forbidden-Example:
value:
httpCode: '403'
httpMessage: Forbidden
moreInformation: >-
User does not have sufficient privileges to access this functionality.
Please reach out to the support team to enable this feature.
Not-Found-Example:
value:
httpMessage: Not Found
httpCode: '404'
moreInformation: No resources match requested URI
Internal-Server-Example:
value:
message: Unable to process your request
status: '500'
correlationId: q2te~8b8b4912-1b37-449a-9e1a-3401d7ab7d8312352