{
  "openapi": "3.0.0",
  "info": {
    "title": "Currency API",
    "description": "REST 2.0 Currency API.",
    "version": "3.4.0"
  },
  "servers": [
    {
      "url": "https://api-sandbox.nuvei.com/currency-api",
      "description": "sandbox"
    },
    {
      "url": "https://api.nuvei.com/currency-api",
      "description": "prod"
    }
  ],
  "tags": [
    {
      "name": "Currency Conversion"
    }
  ],
  "paths": {
    "/currencies/entities/{processing-entity-id}/rates": {
      "get": {
        "tags": [
          "Currency Conversion"
        ],
        "summary": "Retrieve rate details.",
        "description": "Retrieves the rate details of a given processing entity according to the provided set of parameters.",
        "operationId": "getCurrencyRates",
        "parameters": [
          {
            "name": "processing-entity-id",
            "in": "path",
            "description": "ID of Processing Entity.",
            "required": true,
            "style": "simple",
            "explode": false,
            "schema": {
              "$ref": "#/components/schemas/EntityIdType"
            }
          },
          {
            "name": "from_currency",
            "in": "query",
            "description": "Mandatory. Single value. The original merchant currency.",
            "required": true,
            "style": "form",
            "explode": true,
            "schema": {
              "$ref": "#/components/schemas/Currency"
            },
            "example": "USD"
          },
          {
            "name": "to_currencies",
            "in": "query",
            "description": "Optional. The list of target currencies, separated by commas. If not supplied, all the merchant site-related currencies are retrieved.",
            "required": false,
            "style": "form",
            "explode": true,
            "schema": {
              "$ref": "#/components/schemas/Currencies"
            },
            "example": [
              "EUR",
              "CAD"
            ]
          },
          {
            "name": "payment_methods",
            "in": "query",
            "description": "Mandatory. A comma-separated list of payment method names.",
            "required": true,
            "style": "form",
            "explode": true,
            "schema": {
              "$ref": "#/components/schemas/PaymentMethods"
            },
            "example": [
              "card",
              "ach"
            ]
          },
          {
            "name": "rate_type",
            "in": "query",
            "description": "The Values are: payment (default), payout (brings Visa rates), masterCardpayout (brings MC rates)",
            "required": false,
            "style": "form",
            "explode": true,
            "schema": {
              "$ref": "#/components/schemas/RateType"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RatesResponse"
                },
                "examples": {
                  "Card USD to EUR and BGN Rates": {
                    "summary": "Exchange rates for credit cards for USD to EUR and BGN",
                    "value": {
                      "rates": [
                        {
                          "paymentMethod": "CARD",
                          "fromCurrency": "USD",
                          "toCurrency": "EUR",
                          "rate": 0.928821
                        },
                        {
                          "paymentMethod": "CARD",
                          "fromCurrency": "USD",
                          "toCurrency": "BGN",
                          "rate": 1.816942
                        }
                      ],
                      "result": {
                        "status": "success"
                      }
                    }
                  },
                  "Card and ACH USD to EUR Rates": {
                    "summary": "Exchange rates for credit cards and ACH for USD to EUR",
                    "value": {
                      "rates": [
                        {
                          "paymentMethod": "CARD",
                          "fromCurrency": "USD",
                          "toCurrency": "EUR",
                          "rate": 0.928824
                        },
                        {
                          "paymentMethod": "ACH",
                          "fromCurrency": "USD",
                          "toCurrency": "EUR",
                          "rate": 0.919931
                        }
                      ],
                      "result": {
                        "status": "success"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad Request",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RatesResponse"
                },
                "examples": {
                  "Missing Mandatory Field Value": {
                    "value": {
                      "result": {
                        "status": "error",
                        "errors": {
                          "code": "5000.1000",
                          "reason": "[processingEntityId] must not be null"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RatesResponse"
                },
                "examples": {
                  "Authorization Error": {
                    "summary": "Authorization error",
                    "value": {
                      "result": {
                        "status": "error",
                        "errors": {
                          "code": "7300.3000",
                          "reason": "Authorization error."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "Forbidden",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RatesResponse"
                },
                "examples": {
                  "Authorization Error": {
                    "summary": "Authorization error",
                    "value": {
                      "result": {
                        "status": "error",
                        "errors": {
                          "code": "7300.3000",
                          "reason": "Authorization error."
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RatesResponse"
                },
                "examples": {
                  "Not Found Error": {
                    "summary": "Not found error",
                    "value": {
                      "result": {
                        "status": "error",
                        "errors": {
                          "code": "9100.1005",
                          "reason": "Not found"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "500": {
            "description": "Internal Server Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RatesResponse"
                },
                "examples": {
                  "Internal Processing Error": {
                    "summary": "Internal processing error",
                    "value": {
                      "result": {
                        "status": "error",
                        "errors": {
                          "code": "7000.1000",
                          "reason": "Internal Processing Error."
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "accessToken": []
          },
          {
            "apiKey": []
          }
        ]
      }
    }
  },
  "components": {
    "schemas": {
      "EntityIdType": {
        "type": "string",
        "format": "uuid"
      },
      "RateValue": {
        "type": "number",
        "description": "A value of rate. May have many digits after decimal point.",
        "example": 2.48590452
      },
      "Currency": {
        "maxLength": 3,
        "minLength": 3,
        "type": "string",
        "description": "The [3-letter ISO currency code](https://docs.nuvei.com/?p=8513#currency-codes)."
      },
      "Currencies": {
        "title": "currencies",
        "minItems": 1,
        "uniqueItems": true,
        "type": "array",
        "description": "Each item in a currencies array is a currency code.",
        "items": {
          "$ref": "#/components/schemas/Currency"
        }
      },
      "PaymentMethod": {
        "type": "string",
        "description": "The name of the payment method. 'CARD' for credit cards; other names for alternative payment methods."
      },
      "PaymentMethods": {
        "minItems": 1,
        "uniqueItems": true,
        "type": "array",
        "description": "Each item in a array is a payment method name.",
        "items": {
          "$ref": "#/components/schemas/PaymentMethod"
        }
      },
      "RateType": {
        "type": "string",
        "default": "payment",
        "enum": [
          "payment",
          "payout",
          "masterCardPayout"
        ]
      },
      "Rate": {
        "required": [
          "fromCurrency",
          "rate",
          "toCurrency"
        ],
        "type": "object",
        "properties": {
          "paymentMethod": {
            "$ref": "#/components/schemas/PaymentMethod"
          },
          "fromCurrency": {
            "$ref": "#/components/schemas/Currency"
          },
          "toCurrency": {
            "$ref": "#/components/schemas/Currency"
          },
          "rate": {
            "$ref": "#/components/schemas/RateValue"
          }
        },
        "description": "Collections of attributes for a single rate item in the result of rates."
      },
      "Rates": {
        "type": "array",
        "description": "Collection of result rates for the rates. An array of complex items, each array item is a collection of values.",
        "items": {
          "$ref": "#/components/schemas/Rate"
        }
      },
      "RatesResponse": {
        "title": "Rates Response",
        "required": [
          "result"
        ],
        "type": "object",
        "properties": {
          "rates": {
            "$ref": "#/components/schemas/Rates"
          },
          "rateType": {
            "$ref": "#/components/schemas/RateType"
          },
          "result": {
            "$ref": "#/components/schemas/ApiResultOutput"
          }
        },
        "description": "Returns a collection of rates for the current date."
      },
      "ResultError": {
        "title": "resultError",
        "required": [
          "code"
        ],
        "type": "object",
        "properties": {
          "code": {
            "maxLength": 11,
            "type": "string",
            "description": "If an error occurred on the request side, an error code is returned in this parameter.",
            "example": "7000.1000"
          },
          "reason": {
            "maxLength": 400,
            "type": "string",
            "description": "If an error occurred on the request side, then an error reason is returned in this parameter.",
            "example": "Internal Processing Error"
          },
          "reference": {
            "maxLength": 400,
            "type": "string",
            "description": "Reference value for troubleshooting",
            "example": "110.1260"
          }
        }
      },
      "ApiResultOutput": {
        "title": "apiResultOutput",
        "required": [
          "status"
        ],
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "error",
              "success"
            ]
          },
          "errors": {
            "$ref": "#/components/schemas/ResultError"
          }
        }
      }
    },
    "responses": {
      "OkResponse": {
        "description": "OK",
        "content": {}
      },
      "BadRequest": {
        "description": "Bad Request",
        "content": {}
      },
      "Unauthorized": {
        "description": "Unauthorized",
        "content": {}
      },
      "Forbidden": {
        "description": "Forbidden",
        "content": {}
      },
      "NotFound": {
        "description": "Not Found",
        "content": {}
      },
      "InternalServerError": {
        "description": "Internal Server Error",
        "content": {}
      }
    },
    "parameters": {
      "processing-entity-id-path": {
        "name": "processing-entity-id",
        "in": "path",
        "description": "ID of Processing Entity.",
        "required": true,
        "style": "simple",
        "explode": false,
        "schema": {
          "$ref": "#/components/schemas/EntityIdType"
        }
      },
      "entity-id-path": {
        "name": "entity-id",
        "in": "path",
        "description": "ID of Processing Entity.",
        "required": true,
        "style": "simple",
        "explode": false,
        "schema": {
          "$ref": "#/components/schemas/EntityIdType"
        },
        "example": "369bbe6d-4cbd-4d33-9205-2c83541cddab"
      },
      "from_currency_query_string": {
        "name": "from_currency",
        "in": "query",
        "description": "Mandatory. Single value. The original merchant currency.",
        "required": true,
        "style": "form",
        "explode": true,
        "schema": {
          "$ref": "#/components/schemas/Currency"
        },
        "example": "USD"
      },
      "to_currencies_query_string": {
        "name": "to_currencies",
        "in": "query",
        "description": "Optional. The list of target currencies, separated by commas. If not supplied, all the merchant site-related currencies are retrieved.",
        "required": false,
        "style": "form",
        "explode": true,
        "schema": {
          "$ref": "#/components/schemas/Currencies"
        },
        "example": [
          "EUR",
          "CAD"
        ]
      },
      "payment_methods_query_string": {
        "name": "payment_methods",
        "in": "query",
        "description": "Mandatory. A comma-separated list of payment method names.",
        "required": true,
        "style": "form",
        "explode": true,
        "schema": {
          "$ref": "#/components/schemas/PaymentMethods"
        },
        "example": [
          "card",
          "ach"
        ]
      },
      "rate_type_query_string": {
        "name": "rate_type",
        "in": "query",
        "description": "The Values are: payment (default), payout (brings Visa rates), masterCardpayout (brings MC rates)",
        "required": false,
        "style": "form",
        "explode": true,
        "schema": {
          "$ref": "#/components/schemas/RateType"
        }
      }
    },
    "securitySchemes": {
      "accessToken": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      },
      "apiKey": {
        "type": "apiKey",
        "name": "X-API-KEY",
        "in": "header"
      }
    }
  }
}