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