{
  "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:\n* **buy**\n* **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:\n* **splitPayment**: for payments\n* **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:\n* **buy**\n* **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:\n* **splitPayment**: for payments\n* **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"
}