openapi: 3.1.0
servers:
- url: https://balanceplatform-api-test.adyen.com/fx/api/v1
  description: Test Environment
- url: https://balanceplatform-api-live.adyen.com/fx/api/v1
  description: Live Environment
info:
  title: Foreign Exchange API
  description: "The Foreign Exchange API allows you to manage and convert the currencies\
    \ that are enabled for your integration.\n## Authentication\nWe recommend that\
    \ you use an API key to connect to the Foreign Exchange API. You can generate\
    \ an API key in your Customer Area. If you have an Adyen Issuing integration,\
    \ generate an API key in your Balance Platform Customer Area.\n### Credential\
    \ format\n* For the `rates/calculate` endpoint: Generate an API key for the credential\
    \ with the format **ws@BalancePlatform.[YourBalancePlatform]**.\n\n### Header\
    \ format\nTo connect to the Foreign Exchange API, add an `X-API-Key` header with\
    \ the API key as the value, for example:\n\n ```\ncurl\n-H 'Content-Type: application/json'\
    \ \\\n-H 'X-API-Key: ADYEN_API_KEY' \\\n...\n```\n\n## Versioning\n\nThe Foreign\
    \ Exchange API supports [versioning](https://docs.adyen.com/development-resources/versioning)\
    \ using a version suffix in the endpoint URL. This suffix has the following format:\
    \ \"vXX\", where XX is the version number.\n\nFor example:\n\nhttps://balanceplatform-api-test.adyen.com/fx/v1/rates/calculate\n\
    \n## Going live\nWhen going live, generate an API key in your [live Customer Area](https://ca-live.adyen.com/ca/).\
    \ If you have an Adyen Issuing integration, [generate an API key](https://docs.adyen.com/issuing/manage-access/api-credentials-web-service/#generate-api-key)\
    \ in your [live Balance Platform Customer Area](https://balanceplatform-live.adyen.com/balanceplatform/).\
    \ You can then use the API key to send requests to `https://balanceplatform-api-test.adyen.com/fx/v1`.\n\
    \n"
  termsOfService: https://www.adyen.com/legal/terms-and-conditions
  contact:
    name: Adyen Developer Experience team
    url: https://github.com/Adyen/adyen-openapi
  version: '1'
  x-timestamp: '2025-02-11T15:32:15Z'
tags:
- name: Rates
paths:
  /rates/calculate:
    post:
      tags:
      - Rates
      summary: Calculate amount in a different currency
      description: Returns the calculated amounts and rates required to convert the
        currency of a transaction.
      operationId: post-rates-calculate
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CalculateRateRequest'
            examples:
              calculate:
                summary: Calculate an amount in a different currency
                description: The request to calculate an amount in a different currency.
                value:
                  exchangeCalculations:
                  - type: splitPayment
                    sourceAmount:
                      currency: CZK
                      value: 112300
                    targetCurrency: EUR
                    exchangeSide: buy
                  - type: splitRefund
                    sourceAmount:
                      currency: CZK
                      value: 24000
                    targetCurrency: USD
                    exchangeSide: sell
        required: true
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CalculateRateResponse'
              examples:
                calculate:
                  summary: Amount calculated in a different currency
                  description: The response returned when you calculate an amount
                    in a different currency.
                  value:
                    exchangeCalculations:
                    - type: splitPayment
                      exchangeSide: buy
                      sourceAmount:
                        value: 112300
                        currency: CZK
                      targetAmount:
                        value: 4480
                        currency: EUR
                      appliedExchangeRate: 0.039893143366
                    - type: splitRefund
                      exchangeSide: sell
                      sourceAmount:
                        value: 24000
                        currency: CZK
                      targetAmount:
                        value: 992
                        currency: USD
                      appliedExchangeRate: 0.0413333333333
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultErrorResponseEntity'
              examples:
                calculate-401:
                  summary: Unauthorized
                  description: Authentication failed.
                  value:
                    type: https://docs.adyen.com/errors/unauthorized
                    title: Unauthorized
                    status: 401
                    errorCode: '00_401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultErrorResponseEntity'
              examples:
                calculate-403:
                  summary: Forbidden
                  description: Most commonly happens when user does not have sufficient
                    roles or doesn't own requested resource.
                  value:
                    type: https://docs.adyen.com/errors/forbidden
                    errorCode: '00_403'
                    title: Forbidden
                    detail: User doesn't have access to all token policy resources
                    requestId: d42c493b5176df89e51516c6060cc34c
                    status: 403
        '422':
          description: Unprocessable Entity - a request validation error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DefaultErrorResponseEntity'
              examples:
                calculate-422:
                  summary: Bad request
                  description: Response returned when request parsing has failed or
                    some request fields were invalid.
                  value:
                    type: https://docs.adyen.com/errors/unprocessable-entity
                    errorCode: '999_422_000'
                    title: Validation failure
                    detail: Input data validation failed
                    requestId: 0890cfb8f4278217bd457b49ce572265
                    status: 422
                    invalidFields:
                    - name: exchangeCalculations[0].sourceAmount.currency
                      message: The currency is invalid.
                    - name: exchangeCalculations[0].sourceAmount.value
                      message: The value can't be negative.
      x-methodName: calculate
      x-sortIndex: 1
components:
  schemas:
    Amount:
      required:
      - currency
      - value
      type: object
      properties:
        currency:
          type: string
          description: The three-character [ISO currency code](https://docs.adyen.com/development-resources/currency-codes#currency-codes).
        value:
          type: integer
          description: The amount of the transaction, in [minor units](https://docs.adyen.com/development-resources/currency-codes#minor-units).
          format: int64
    CalculateRateRequest:
      required:
      - exchangeCalculations
      type: object
      properties:
        exchangeCalculations:
          maxItems: 1000
          minItems: 1
          type: array
          description: An array of objects, where each object defines a currency and
            value for which you want to perform an exchange calculation.
          items:
            $ref: '#/components/schemas/CalculateRateRequestItem'
      description: The request to calculate an amount in a different currency.
    CalculateRateRequestItem:
      required:
      - exchangeSide
      - sourceAmount
      - targetCurrency
      - type
      type: object
      properties:
        exchangeSide:
          description: 'The operation performed on the source amount. Possible values:

            * **buy**

            * **sell**'
          $ref: '#/components/schemas/ExchangeSide'
        sourceAmount:
          description: An object specifying the currency and value for which you want
            to perform an exchange calculation.
          $ref: '#/components/schemas/Amount'
        targetCurrency:
          type: string
          description: The currency to which you want to convert the source amount.
        type:
          description: 'The type of transaction. Possible values:

            * **splitPayment**: for payments

            * **splitRefund**: for refunds'
          $ref: '#/components/schemas/RateType'
      description: The request parameters required to calculate an amount in a different
        currency.
    ExchangeSide:
      type: string
      enum:
      - buy
      - sell
    RateType:
      type: string
      enum:
      - splitPayment
      - balanceConversion
      - transfer
      - splitRefund
    CalculateRateResponse:
      type: object
      properties:
        exchangeCalculations:
          type: array
          description: An array of objects, where each object returns a currency and
            value for which you performed an exchange calculation. You can use the
            calculated amounts in your payment requests.
          items:
            $ref: '#/components/schemas/CalculateRateResponseItem'
      description: The response returned when you calculate an amount in a different
        currency.
    CalculateRateResponseItem:
      type: object
      properties:
        appliedExchangeRate:
          type: number
          description: The exchange rate to convert the source currency to the target
            currency. This includes Adyen's markup.
        exchangeSide:
          type: string
          description: 'The operation performed on the source amount. Possible values:

            * **buy**

            * **sell**'
        sourceAmount:
          description: The currency of the amount you converted (the source amount).
          $ref: '#/components/schemas/Amount'
        targetAmount:
          description: An object specifying the currency and value to which you want
            to convert the source amount (the target amount).
          $ref: '#/components/schemas/Amount'
        type:
          type: string
          description: 'The type of transaction. Possible values:

            * **splitPayment**: for payments

            * **splitRefund**: for refunds'
      description: The response parameters returned when you calculate an amount in
        a different currency.
    DefaultErrorResponseEntity:
      type: object
      properties:
        detail:
          type: string
          description: A human-readable explanation specific to this occurrence of
            the problem.
        errorCode:
          type: string
          description: Unique business error code.
        instance:
          type: string
          description: A URI that identifies the specific occurrence of the problem
            if applicable.
        invalidFields:
          type: array
          description: Array of fields with validation errors when applicable.
          items:
            $ref: '#/components/schemas/InvalidField'
        requestId:
          type: string
          description: The unique reference for the request.
        status:
          type: integer
          description: The HTTP status code.
          format: int32
        title:
          type: string
          description: A short, human-readable summary of the problem type.
        type:
          type: string
          description: A URI that identifies the validation error type. It points
            to human-readable documentation for the problem type.
      description: Standardized error response following RFC-7807 format
      externalDocs:
        url: https://www.rfc-editor.org/rfc/rfc7807
    InvalidField:
      required:
      - message
      - name
      - value
      type: object
      properties:
        name:
          type: string
          description: The field that has an invalid value.
        value:
          type: string
          description: The invalid value.
        message:
          type: string
          description: Description of the validation error.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      name: X-API-Key
      in: header
    BasicAuth:
      type: http
      scheme: basic
jsonSchemaDialect: https://spec.openapis.org/oas/3.1/dialect/base