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