openapi: 3.0.1
info:
  title: FX API
  version: '1'
  description: >-

    __Authentication Header__

      ```
        Authorization: {your_credentials}
      ```
      Replace `{your_credentials}` with your base64-encoded Basic Auth username and password given to you by your Implementation Manager.
      <br /> <br />
      You **must** use the `Authorization` header for any request you send to our FX APIs.
      <br /><br />
      __Accept Header__
      ```
        Accept: application/vnd.worldpay.foreignexchange-v1+json
      ```

    We use the Accept header to identify which version of our API you are using.
    You must use the Accept header for any request you send to our FX APIs.

    <br /><br />

    __DNS Whitelisting__


    Whitelist the following URLs:

    * `https://try.access.worldpay.com/`

    * `https://access.worldpay.com/`


    Please ensure you use DNS whitelisting, not explicit IP whitelisting. When
    you make a request within Access Worldpay, you should always cache the
    response returned.
servers:
  - url: https://try.access.worldpay.com
    description: testing (try) - Account Payouts customers only
  - url: https://access.worldpay.com
    description: live
paths:
  /foreignExchange/rates:
    get:
      summary: Get FX rates
      description: Retrieve an FX rate for a particular payment method.
      operationId: getFXrates
      parameters:
        - name: intent
          in: query
          description: Transaction type (intention) for which rates should be retrieved.
          required: false
          schema:
            type: string
            minLength: 1
            maxLength: 50
            enum:
              - PAYOUT
              - FX DEAL
              - MULTI-CURRENCY PRICING
              - CONSUMER RATES
              - PAYOUT LIVE RATE
        - name: entity
          in: query
          description: >-
            For Multi-Currency Pricing customers, `entity` is MCP Account
            Identifier (PartyID- Merchant Company ID, Unique ID given to you
            during the onboarding process.) for which rates should be retrieved.
            <br><br> For Account Payout customers, `entity` is 6-digit reference
            given to you by your Implementation Manager during the onboarding
            process.
          required: false
          example: '100001'
          schema:
            type: string
            minLength: 6
            maxLength: 6
        - name: sourceCurrency
          in: query
          description: >-
            The transaction currency code. If not supplied, the response
            contains rates for all source currencies against the target
            currency.
          required: false
          example: USD
          schema:
            $ref: '#/components/schemas/CurrencyCode'
            minLength: 3
            maxLength: 3
        - name: targetCurrency
          in: query
          description: >-
            Your funding (settlement) currency code. If not supplied, the
            response contains rates for all target currencies against the source
            currency.
          required: false
          example: EUR
          schema:
            $ref: '#/components/schemas/CurrencyCode'
            minLength: 3
            maxLength: 3
        - in: header
          name: Accept
          required: true
          schema:
            type: string
            example: application/vnd.worldpay.foreignexchange-v1+json
        - name: WP-CorrelationId
          in: header
          description: Optional ID to trace requests, if not provided, it is generated.
          required: false
          schema:
            type: string
          example: 15cd16b2-7b82-41cb-9b11-21be9dacad88
      responses:
        '200':
          description: OK response if the request is valid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ExternalRateResponse'
        '400':
          description: BAD REQUEST response if the request is not valid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400'
              examples:
                intent is not correct:
                  value:
                    validationErrors:
                      - queryParameter: Intent
                        errorName: fieldHasInvalidValue
                        message: Intent is not valid for the current Consumer.
                    errorName: urlContainsInvalidValue
                    message: The URL contains a value or values that are invalid
                source currency is not valid:
                  value:
                    validationErrors:
                      - queryParameter: SourceCurrency
                        errorName: fieldHasInvalidValue
                        message: Invalid SourceCurrency value.
                    errorName: urlContainsInvalidValue
                    message: The URL contains a value or values that are invalid
                target currency is not valid:
                  value:
                    validationErrors:
                      - queryParameter: TargetCurrency
                        errorName: fieldHasInvalidValue
                        message: Invalid TargetCurrency value
                    errorName: urlContainsInvalidValue
                    message: The URL contains a value or values that are invalid
        '401':
          description: UNAUTHORIZED response if credentials are invalid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  value:
                    errorName: unauthorizedRequest
                    message: The request is unauthorized
        '403':
          description: FORBIDDEN response if entitlements are not valid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  value:
                    errorName: forbidden
                    message: ''
        '404':
          description: NOT FOUND response
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                pageNotFound:
                  value:
                    errorName: notFound
                    message: No rates found
        '500':
          description: Internal server error
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errorName: internalErrorOccurred
                message: Something went wrong
  /foreignExchange/quote:
    post:
      summary: Create FX quote
      description: >-
        Lock the FX rate for a specific currency pairing. <br>For Account
        Payouts customers only.
      operationId: postFXquote
      parameters:
        - in: header
          name: Accept
          required: true
          schema:
            type: string
            example: application/vnd.worldpay.foreignexchange-v1+json
        - name: WP-CorrelationId
          in: header
          description: Optional ID to trace requests, if not provided, it is generated.
          required: false
          schema:
            type: string
          example: 15cd16b2-7b82-41cb-9b11-21be9dacad88
      requestBody:
        content:
          application/vnd.worldpay.foreignexchange-v1+json:
            schema:
              $ref: '#/components/schemas/postCreateQuoteItems'
            examples:
              Create a new quote:
                value:
                  entity: '100001'
                  intent: PAYOUT
                  sourceCurrency: USD
                  targetCurrency: EUR
      responses:
        '200':
          description: OK response if the request is valid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ExternalPostQuoteResponse'
        '400':
          description: BAD REQUEST response if the request is not valid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400Quote'
              examples:
                intent is not valid:
                  value:
                    validationErrors:
                      - jsonPath: Intent
                        errorName: fieldHasInvalidValue
                        message: Missing Intent value.
                    errorName: bodyDoesNotMatchSchema
                    message: The json body provided does not match the expected schema
                source currency is not valid:
                  value:
                    validationErrors:
                      - jsonPath: SourceCurrency
                        errorName: fieldHasInvalidValueg
                        message: Invalid SourceCurrency value.
                    errorName: urlContainsInvalidValue
                    message: The json body provided does not match the expected schema
                target currency is not valid:
                  value:
                    validationErrors:
                      - jsonPath: TargetCurrency
                        errorName: fieldHasInvalidValue
                        message: Invalid TargetCurrency value.
                    errorName: urlContainsInvalidValue
                    message: The json body provided does not match the expected schema
        '401':
          description: UNAUTHORIZED response if credentials are invalid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  value:
                    errorName: unauthorizedRequest
                    message: The request is unauthorized
        '403':
          description: FORBIDDEN response if Entitlements are not valid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  value:
                    errorName: forbidden
                    message: ''
        '404':
          description: NOT FOUND response
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                pageNotFound:
                  value:
                    errorName: notFound
                    message: No rate found for given input
        '500':
          description: Internal server error
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errorName: internalErrorOccurred
                message: Something went wrong
    get:
      summary: Retrieve an FX quote
      description: Retrieving an existing FX quote.<br>For Account Payouts customers only.
      operationId: getFXquote
      parameters:
        - name: entity
          in: query
          description: >-
            6-digit reference given to you by your Implementation Manager during
            the onboarding process.
          required: true
          example: '100001'
          schema:
            type: string
            maxLength: 6
        - name: quoteId
          in: query
          description: Unique ID of the quote.
          required: true
          example: Q000000001
          schema:
            type: string
            minLength: 1
            maxLength: 50
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/vnd.worldpay.foreignexchange-v1+json
        - name: WP-CorrelationId
          in: header
          description: Optional ID to trace requests, if not provided, it is generated.
          required: false
          schema:
            type: string
          example: 15cd16b2-7b82-41cb-9b11-21be9dacad88
      responses:
        '200':
          description: OK response if the request is valid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ExternalGetQuoteResponse'
        '401':
          description: UNAUTHORIZED response if credentials are invalid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  value:
                    errorName: unauthorizedRequest
                    message: The request is unauthorized
        '403':
          description: FORBIDDEN response if Entitlements are not valid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  value:
                    errorName: forbidden
                    message: ''
        '404':
          description: NOT FOUND response
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                pageNotFound:
                  value:
                    errorName: notFound
                    message: Quote for given input does not exist
        '500':
          description: Internal server error
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errorName: internalErrorOccurred
                message: Something went wrong
  /foreignExchange/contract:
    post:
      summary: Create an external contract
      description: >-
        Create an external contract to lock a forward FX rate. <br>For Account
        Payouts customers only.
      operationId: postContract
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/vnd.worldpay.foreignexchange-v1+json
        - name: WP-CorrelationId
          in: header
          description: Optional ID to trace requests, if not provided, it is generated.
          required: false
          schema:
            type: string
          example: 15cd16b2-7b82-41cb-9b11-21be9dacad88
      requestBody:
        content:
          application/vnd.worldpay.foreignexchange-v1+json:
            schema:
              $ref: '#/components/schemas/postCreateContractItems'
            examples:
              Create a new contract:
                value:
                  effectiveDate: '2025-12-31'
                  sourceCurrency: USD
                  targetCurrency: EUR
                  targetAmount: 1.23
                  entity: '100001'
                  customerReference: Customer 001
      responses:
        '200':
          description: OK response if the request is valid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ExternalPostContractResponse'
        '400':
          description: BAD REQUEST response if the request is not valid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400Quote'
              examples:
                EffectiveDate is longer than 30 days:
                  value:
                    validationErrors:
                      - jsonPath: EffectiveDate
                        errorName: fieldHasInvalidValueg
                        message: EffectiveDate must be within the next 30 days.
                    errorName: bodyDoesNotMatchSchema
                    message: The json body provided does not match the expected schema
                source currency is not valid:
                  value:
                    validationErrors:
                      - jsonPath: SourceCurrency
                        errorName: fieldHasInvalidValueg
                        message: Invalid SourceCurrency value.
                    errorName: bodyDoesNotMatchSchema
                    message: The json body provided does not match the expected schema
                target currency is not valid:
                  value:
                    validationErrors:
                      - jsonPath: TargetCurrency
                        errorName: fieldHasInvalidValue
                        message: Invalid TargetCurrency value.
                    errorName: bodyDoesNotMatchSchema
                    message: The json body provided does not match the expected schema
        '401':
          description: UNAUTHORIZED response if credentials are invalid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  value:
                    errorName: unauthorizedRequest
                    message: The request is unauthorized
        '403':
          description: FORBIDDEN response if Entitlements are not valid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  value:
                    errorName: forbidden
                    message: ''
        '404':
          description: NOT FOUND response
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                pageNotFound:
                  value:
                    errorName: notFound
                    message: Not found
        '500':
          description: Internal server error
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errorName: internalErrorOccurred
                message: Something went wrong
  /foreignExchange/contract/{contractId}:
    put:
      summary: Activate or cancel contract
      description: >-
        Enable a contract to use locked in FX rates in an Account Payout.
        <br>For Account Payouts customers only.
      operationId: putContract
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/vnd.worldpay.foreignexchange-v1+json
        - name: WP-CorrelationId
          in: header
          description: Optional ID to trace requests, if not provided, it is generated.
          required: false
          schema:
            type: string
          example: 15cd16b2-7b82-41cb-9b11-21be9dacad88
        - name: contractId
          in: path
          description: Unique ID of the contract.
          required: true
          schema:
            type: string
            minLength: 1
            maxLength: 50
          example: C000000001
      requestBody:
        content:
          application/vnd.worldpay.foreignexchange-v1+json:
            schema:
              $ref: '#/components/schemas/putActivatedContractItems'
            examples:
              Activate contract:
                value:
                  status: ACTIVE
                  entity: '100001'
              Cancel contract:
                value:
                  status: CANCELLED
                  entity: '100001'
      responses:
        '204':
          description: OK response if the request is valid
        '400':
          description: BAD REQUEST response if the status of the contract is not valid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse400Contract'
              examples:
                status is not correct:
                  value:
                    errorName: invalidInput
                    message: The input received is not valid
        '401':
          description: UNAUTHORIZED response if credentials are invalid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  value:
                    errorName: unauthorizedRequest
                    message: The request is unauthorized
        '403':
          description: FORBIDDEN response if Entitlements are not valid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  value:
                    errorName: forbidden
                    message: ''
        '404':
          description: NOT FOUND response
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                pageNotFound:
                  value:
                    errorName: notFound
                    message: Quote for given input does not exist
        '409':
          description: CONFLICT response
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                when a contract is re-activated or re-cancelled:
                  value:
                    errorName: conflict
                    message: >-
                      Current status of the contract is invalid for requested
                      transition
        '500':
          description: Internal server error
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errorName: internalErrorOccurred
                message: Something went wrong
  /foreignExchange/markup/{entity}:
    put:
      summary: Add a markup to your FX rate
      description: Adding a markup to an existing FX rate. <br>For MCP customers only.
      operationId: addMarkup
      parameters:
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/vnd.worldpay.foreignexchange-v1+json
        - name: WP-CorrelationId
          in: header
          description: Optional ID to trace requests, if not provided, it is generated.
          required: false
          schema:
            type: string
          example: 15cd16b2-7b82-41cb-9b11-21be9dacad88
        - name: entity
          in: path
          description: >-
            MCP Account Identifier (PartyID- Merchant Company ID, unique 6-digit
            ID given to you during the onboarding process) for which rates
            should be retrieved.
          required: true
          example: '100001'
          schema:
            type: string
      requestBody:
        content:
          application/vnd.worldpay.foreignexchange-v1+json:
            schema:
              $ref: '#/components/schemas/putMarkupRequestItems'
            examples:
              Add a markup:
                value:
                  sourceCurrency: AUD
                  targetCurrency: GBP
                  markup: 1.23
      responses:
        '204':
          description: OK response if the request is valid
        '401':
          description: UNAUTHORIZED response if credentials are invalid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  value:
                    errorName: unauthorizedRequest
                    message: The request is unauthorized
        '403':
          description: FORBIDDEN response if Entitlements are not valid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  value:
                    errorName: forbidden
                    message: ''
        '404':
          description: NOT FOUND response
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                pageNotFound:
                  value:
                    errorName: notFound
                    message: Not found
        '500':
          description: Internal server error
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errorName: internalErrorOccurred
                message: Something went wrong
    get:
      summary: Retrieve markup
      description: >-
        Retrieving an existing markup for a specific FX rate.<br>For MCP
        customers only.
      operationId: getMarkup
      parameters:
        - name: entity
          in: path
          description: >-
            MCP Account Identifier (PartyID- Merchant Company ID, unique 6-digit
            ID given to you during the onboarding process.) for which rates
            should be retrieved.
          required: true
          example: '100001'
          schema:
            type: string
            maxLength: 6
        - name: sourceCurrency
          in: query
          description: >-
            The transaction currency code. If not supplied, the response
            contains rates for all source currencies against the target
            currency.
          required: false
          example: USD
          schema:
            $ref: '#/components/schemas/CurrencyCode'
            minLength: 3
            maxLength: 3
        - name: targetCurrency
          in: query
          description: >-
            Your funding (settlement) currency code. If not supplied, the
            response contains rates for all target currencies against the source
            currency.
          required: false
          example: EUR
          schema:
            $ref: '#/components/schemas/CurrencyCode'
            minLength: 3
            maxLength: 3
        - name: Accept
          in: header
          required: true
          schema:
            type: string
            example: application/vnd.worldpay.foreignexchange-v1+json
        - name: WP-CorrelationId
          in: header
          description: Optional ID to trace requests, if not provided, it is generated.
          required: false
          schema:
            type: string
          example: 15cd16b2-7b82-41cb-9b11-21be9dacad88
      responses:
        '200':
          description: OK response if the request is valid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ExternalGetMarkupResponse'
        '401':
          description: UNAUTHORIZED response if credentials are invalid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                Unauthorized:
                  value:
                    errorName: unauthorizedRequest
                    message: The request is unauthorized
        '403':
          description: FORBIDDEN response if Entitlements are not valid
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                forbidden:
                  value:
                    errorName: forbidden
                    message: ''
        '404':
          description: NOT FOUND response
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                pageNotFound:
                  value:
                    errorName: notFound
                    message: Not found
        '500':
          description: Internal server error
          content:
            application/vnd.worldpay.foreignexchange-v1+json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                errorName: internalErrorOccurred
                message: Something went wrong
components:
  schemas:
    CurrencyCode:
      type: string
      minLength: 3
      maxLength: 3
      pattern: ^[A-Z]*$
    postCreateContractItems:
      required:
        - effectiveDate
        - sourceCurrency
        - targetCurrency
        - targetAmount
        - entity
      type: object
      properties:
        effectiveDate:
          description: >-
            A future date when the contract becomes available and can be used.
            Date must be within 30 days in the future.
          example: '2025-12-31'
          type: string
        sourceCurrency:
          description: >-
            The transaction currency code. If not supplied, the response
            contains rates for all source currencies against the target
            currency.
          example: USD
        targetCurrency:
          description: >-
            Your funding (settlement) currency code. If not supplied, the
            response contains rates for all target currencies against the source
            currency.
          example: EUR
        targetAmount:
          description: >-
            The total amount for your forward FX contract and future payout
            request in the targetCurrency.
          example: 1.23
        entity:
          description: >-
            6-digit reference given to you by your Implementation Manager during
            the onboarding process
          example: '100001'
        customerReference:
          description: >-
            A reference generated by you representing the payer who funds the FX
            contract.
          example: Customer 001
          maxLength: 35
    postCreateQuoteItems:
      required:
        - entity
        - intent
        - sourceCurrency
        - targetCurrency
      type: object
      properties:
        entity:
          description: >-
            6-digit reference given to you by your Implementation Manager during
            the onboarding process
          example: '100001'
          type: string
        intent:
          description: Transaction type (intention) for which rates should be retrieved.
          type: string
          enum:
            - PAYOUT
            - FX DEAL
            - MULTI-CURRENCY PRICING
            - CONSUMER RATES
            - PAYOUT LIVE RATE
        sourceCurrency:
          description: The debit currency.
          example: USD
          type: string
        targetCurrency:
          description: The credit currency.
          example: EUR
          type: string
    putActivatedContractItems:
      required:
        - status
        - entity
      type: object
      properties:
        status:
          description: New status of the contract.
          enum:
            - ACTIVE
            - CANCELLED
          type: string
        entity:
          description: >-
            6-digit reference given to you by your Implementation Manager during
            the onboarding process
          example: '100001'
          type: string
    putMarkupRequestItems:
      required:
        - sourceCurrency
        - targetCurrency
        - markup
      type: object
      properties:
        sourceCurrency:
          description: >-
            The transaction currency code. If not supplied, the response
            contains rates for all source currencies against the target
            currency.
          example: AUD
        targetCurrency:
          description: >-
            Your funding (settlement) currency code. If not supplied, the
            response contains rates for all target currencies against the source
            currency.
          example: GBP
        markup:
          description: The additional margin percentage set up on FX rates.
          example: 1.23
    ErrorResponse:
      type: object
      required:
        - errorName
        - message
      properties:
        errorName:
          description: The unique error name
          type: string
        message:
          description: Error description message
          type: string
    ExternalRateResponse:
      type: object
      properties:
        rates:
          description: A collection of rates items.
          type: array
          items:
            $ref: '#/components/schemas/ExternalRateItems'
    ErrorResponse400:
      type: object
      required:
        - validationErrors
        - errorName
        - message
      properties:
        validationErrors:
          description: Object containing details of validation errors occurred
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponse400Item'
        errorName:
          description: The unique error name
          type: string
        message:
          description: Error description message
          type: string
    ErrorResponse400Item:
      type: object
      required:
        - queryParameter
        - errorName
        - message
      properties:
        queryParameter:
          description: Parameter for which the error occurred
          type: string
        errorName:
          description: Unique name of the validation error
          type: string
        message:
          description: Error description message
          type: string
    ErrorResponse400Quote:
      type: object
      required:
        - validationErrors
        - errorName
        - message
      properties:
        validationErrors:
          description: Object containing details of validation errors occurred
          type: array
          items:
            $ref: '#/components/schemas/ErrorResponse400QuoteItem'
        errorName:
          description: The unique error name
          type: string
        message:
          description: Error description message
          type: string
    ErrorResponse400QuoteItem:
      type: object
      required:
        - jsonPath
        - errorName
        - message
      properties:
        jsonPath:
          description: Parameter for which the error occurred
          type: string
        errorName:
          description: Unique name of the validation error
          type: string
        message:
          description: Error description message
          type: string
    ErrorResponse400Contract:
      type: object
      required:
        - errorName
        - message
      properties:
        errorName:
          description: The unique error name
          type: string
        message:
          description: Error description message
          type: string
    ExternalRateItems:
      type: object
      properties:
        rateId:
          description: Unique reference for the rate.
          type: string
          nullable: false
          example: R12345678
        intent:
          description: Transaction type (intention) for which rates should be retrieved.
          type: string
          nullable: false
          example: PAYOUT
        sourceCurrency:
          description: The debit currency.
          type: string
          example: EUR
        targetCurrency:
          description: The credit currency.
          type: string
          nullable: false
          example: GBP
        bidRate:
          description: The buy/refund rate for the currency pairing.
          type: number
          format: double
          nullable: false
          example: '1.23456789'
        askRate:
          description: The sell/purchase rate for the currency pairing.
          type: number
          format: double
          nullable: false
          example: '1.23456789'
        entity:
          description: >-
            6-digit reference given to you by your Implementation Manager during
            the onboarding process.
          type: number
          nullable: false
          example: '100001'
        issuedDate:
          description: The posting date of the specific statement item.
          type: string
          format: date-time
          nullable: false
          example: '2025-01-01T12:00:00.000Z'
        validFrom:
          description: Validation date from.
          type: string
          format: date-time
          nullable: false
          example: '2025-01-10T12:00:00.000Z'
        validTo:
          description: Validation date to.
          type: string
          format: date-time
          nullable: false
          example: '2025-01-10T12:00:00.000Z'
    ExternalPostQuoteResponse:
      type: object
      properties:
        entity:
          description: >-
            6-digit reference given to you by your Implementation Manager during
            the onboarding process.
          type: string
          nullable: false
          example: '100001'
        intent:
          description: Transaction type (intention) for which rates should be retrieved.
          type: string
          nullable: false
          example: PAYOUT
        quote:
          description: A collection of account statement items.
          type: array
          items:
            $ref: '#/components/schemas/ExternalQuoteItems'
          nullable: false
    ExternalQuoteItems:
      type: object
      properties:
        quoteId:
          description: Unique quote id.
          type: string
          nullable: false
          example: Q000000001
        sourceCurrency:
          description: The debit currency.
          type: string
          nullable: false
          example: EUR
        targetCurrency:
          description: The credit currency.
          type: string
          nullable: false
          example: GBP
        rateId:
          description: Unique rate id.
          type: string
          nullable: false
          example: '12345678'
        rate:
          description: Rate amount
          type: string
          nullable: false
          example: '1.2345'
        quoteExpiryTime:
          description: Quote start time.
          type: string
          nullable: false
          example: '2025-01-10T12:00:00.000Z'
    ExternalGetQuoteResponse:
      type: object
      properties:
        entity:
          description: >-
            6-digit reference given to you by your Implementation Manager during
            the onboarding process.
          type: string
          nullable: false
          example: '100001'
        intent:
          description: Transaction type (intention) for which rates should be retrieved.
          type: string
          nullable: false
          example: PAYOUT
        quote:
          description: A collection of quote items.
          type: array
          items:
            $ref: '#/components/schemas/ExternalQuoteItems'
          nullable: false
    ExternalGetMarkupResponse:
      type: object
      properties:
        sourceCurrency:
          description: The debit currency.
          type: string
          nullable: false
          example: EUR
        targetCurrency:
          description: The credit currency.
          type: string
          nullable: false
          example: GBP
        paymentMethod:
          description: Payment method.
          type: string
          nullable: false
          example: ENDCONSUMERRATES
        entity:
          description: >-
            6-digit reference given to you by your Implementation Manager during
            the onboarding process.
          type: string
          nullable: false
          example: '100001'
        value:
          description: Markup value setup.
          type: string
          nullable: false
          example: '1.234'
    ExternalPostContractResponse:
      type: object
      properties:
        contractId:
          description: Unique ID of the contract.
          type: string
          nullable: false
          example: C000000001
        targetAmount:
          description: Crediting currency code.
          type: string
          nullable: false
          example: EUR
        sourceAmount:
          description: Debiting currency code.
          type: string
          nullable: false
          example: GBP
        status:
          description: Status of the contract.
          type: string
          nullable: false
          example: PENDING
        effectiveDate:
          description: Datetime representation in UTC of when the contract starts.
          type: string
          nullable: false
          example: '2025-01-01'
        customerReference:
          description: >-
            A reference generated by you representing the payer who funds the FX
            contract.
          type: string
          nullable: true
          example: Customer 001
        quote:
          description: A collection of quote items.
          type: array
          items:
            $ref: '#/components/schemas/ExternalContractQuoteItems'
          nullable: false
    ExternalContractQuoteItems:
      type: object
      properties:
        quoteId:
          description: Unique quote id.
          type: string
          nullable: false
          example: F000000001
        sourceCurrency:
          description: The debit currency.
          type: string
          nullable: false
          example: EUR
        targetCurrency:
          description: The credit currency.
          type: string
          nullable: false
          example: GBP
        entity:
          description: >-
            6-digit reference given to you by your Implementation Manager during
            the onboarding process.
          type: string
          nullable: false
          example: '100001'
        intent:
          description: Payment method (intent) for which rates are retrieved.
          type: string
          nullable: false
          example: FORWARD FX
        rateId:
          description: Unique rate id.
          type: string
          nullable: false
          example: '1234567'
        rate:
          description: Rate amount.
          type: string
          nullable: false
          example: '1.23456'
        quoteExpiryTime:
          description: Quote start time.
          type: string
          nullable: false
          example: 2025-01-015T23:59:59.999Z
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
security:
  - basicAuth: []
