Worldline Currency Conversion (Extended services) API

openapi: 3.2.0
info:
  title: Open Banking Payment Initiation Service Currency Conversion (Extended services) API
  description: '### Introduction

    There are several flows (sequence of API calls) to complete a payment. Which

    API''s are required depend on the choosen `PaymentProduct`, ASPSP (debtor bank) and the chosen strong customer

    authentication approach. The response of an API call will indicate in the ''Links'' section which next

    API call is required to complete the payment. Both PSD2 and IDEAL payments are supported.


    #### PSD2 Sandbox

    Several AspspId''s are available to test specific PSD2 payment initiation scenario''s, see sandbox documentation.


    The following authorization token can be used to test in the sandbox (unlike a real token this one doesn''t expire):

    **97fb13a74c712d8c7a50476e71769eaf**

    '
  version: 3.15.0
servers:
- url: https://xs2a.awltest.de/xs2a/routingservice/services/ob/pis/v3
  description: PSD2 Sandbox
- url: https://digitalroutingservice.awltest.de/xs2a/routingservice/services/ob/pis/v3
  description: iDEAL Sandbox
tags:
- name: Currency Conversion (Extended services)
paths:
  /exchangerate:
    post:
      security:
      - Authorization: []
      tags:
      - Currency Conversion (Extended services)
      summary: Exchange rate request
      description: 'Utilize this API to obtain exchange rate details relative to the payer''s local currency and the merchant''s currency as the base currency (EURO). This will allow you to calculate the total amount payable in the payer''s local currency, including any markup for currency conversion fees.

        '
      operationId: exchangeRate
      parameters:
      - $ref: '#/components/parameters/X-Request-ID'
      - $ref: '#/components/parameters/MessageCreateDateTime'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ExchangeRateRequest'
        required: false
      responses:
        201:
          description: 'CREATED

            '
          headers:
            X-Request-ID:
              $ref: '#/components/headers/X-Request-ID'
            MessageCreateDateTime:
              $ref: '#/components/headers/MessageCreateDateTime'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExchangeRateResponse'
        400:
          $ref: '#/components/responses/400'
        401:
          $ref: '#/components/responses/401'
        403:
          $ref: '#/components/responses/403'
        404:
          $ref: '#/components/responses/404'
        500:
          $ref: '#/components/responses/500'
        503:
          $ref: '#/components/responses/503'
components:
  schemas:
    ExchangeRateReferences:
      type: object
      additionalProperties: false
      properties:
        SourceCurrencyReferenceId:
          maxLength: 35
          minLength: 1
          type: string
          description: 'This should be used to refer to this exchange rate details for currency conversion from the new exchange rate table.

            '
        TargetCurrencyReferenceId:
          maxLength: 35
          minLength: 1
          type: string
          description: 'This should be used to reference the second entry ID in the exchange rate table row when cross-currency conversion is required, and two entries are selected for calculation.

            '
    ExchangeRateInformation:
      type: object
      additionalProperties: false
      required:
      - UnitCurrency
      - ExchangeRate
      - RateType
      properties:
        UnitCurrency:
          pattern: '[A-Z]{3,3}'
          type: string
          description: 'Currency in which the rate of exchange is expressed in a currency exchange.

            '
          example: EUR
        ExchangeRate:
          type: number
          description: 'The factor used for conversion of an amount from one currency

            to another. This reflects the price at which one currency was bought with

            another currency. Rate expressed as a decimal, for example, 0.7 is 7/10

            and 70%.

            '
        RateType:
          type: string
          description: 'Specifies the type used to complete the currency exchange.

            * Spot: Exchange rate applied is the spot rate.

            '
          enum:
          - Spot
    ExchangeRateRequest:
      type: object
      additionalProperties: false
      properties:
        Amount:
          pattern: ^\d{1,13}\.\d{1,5}$
          type: string
          description: 'Amount of the payment. Amount to be converted. The decimal separator is a dot.

            '
          example: '123.45'
        TargetCurrency:
          pattern: '[A-Z]{3,3}'
          type: string
          description: 'Currency of the payment. The currency being referenced or converted from. ISO 4217 currency codes should be used.

            '
          example: CHF
        UnitCurrency:
          pattern: '[A-Z]{3,3}'
          type: string
          description: 'The currency against which the target currency is being measured. ISO 4217 currency codes should be used.

            '
          example: EUR
      required:
      - Amount
      - TargetCurrency
      - UnitCurrency
    ExchangeRateResponse:
      type: object
      additionalProperties: false
      properties:
        ExchangeRateReferences:
          $ref: '#/components/schemas/ExchangeRateReferences'
        ExchangeRateInformation:
          $ref: '#/components/schemas/ExchangeRateInformation'
        CurrencyConversionFee:
          $ref: '#/components/schemas/CurrencyConversionFee'
        EstimatedTotalAmount:
          $ref: '#/components/schemas/EstimatedTotalAmount'
        ValidUntil:
          type: string
          description: 'This exchange rate is valid until the next run of the scheduled batch to get new exchange rate details. ISO 8601 DateTime.

            '
          format: date-time
      description: 'ExchangeRateResponse

        '
      required:
      - ExchangeRateInformation
      - CurrencyConversionFee
      - EstimatedTotalAmount
      - ValidUntil
    EstimatedTotalAmount:
      type: object
      additionalProperties: false
      required:
      - Currency
      - Amount
      properties:
        Currency:
          pattern: '[A-Z]{3,3}'
          type: string
          description: 'A code allocated to a currency by a Maintenance Agency under

            an international identification scheme, as described in the latest edition

            of the international standard ISO 4217 "Codes for the representation of

            currencies and funds".

            '
        Amount:
          pattern: ^\d{1,13}\.\d{1,2}$
          type: string
          description: 'Amount

            '
      description: 'Estimated Total Amount.

        '
    CurrencyConversionFee:
      type: object
      additionalProperties: false
      required:
      - Currency
      - Amount
      - Rate
      properties:
        Currency:
          pattern: '[A-Z]{3,3}'
          type: string
          description: 'A code allocated to a currency by a Maintenance Agency under

            an international identification scheme, as described in the latest edition

            of the international standard ISO 4217 "Codes for the representation of

            currencies and funds".

            '
        Amount:
          pattern: ^\d{1,13}\.\d{1,2}$
          type: string
          description: 'Amount of the fees.

            '
        Rate:
          type: number
      description: 'Currency Conversion Fee

        '
  headers:
    MessageCreateDateTime:
      required: true
      schema:
        type: string
        format: date-time
      description: 'The message create date time.


        ISO 8601 DateTime.

        '
      example: '2020-09-25T08:15:00.856Z'
    X-Request-ID:
      required: true
      description: 'UUID for unique request identification

        '
      schema:
        type: string
        maxLength: 36
        minLength: 1
      example: abcdef2e-3000-4000-88cc-ae40e3b113d7
  parameters:
    X-Request-ID:
      name: X-Request-ID
      in: header
      description: 'UUID for unique request identification.

        '
      required: true
      schema:
        maxLength: 36
        minLength: 1
        type: string
      example: abcdef2e-3000-4000-88cc-ae40e3b113d7
    MessageCreateDateTime:
      name: MessageCreateDateTime
      in: header
      description: 'The message create date time.


        ISO 8601 DateTime.

        '
      required: true
      schema:
        type: string
        format: date-time
      example: '2020-09-25T08:15:00.856Z'
  securitySchemes:
    Authorization:
      type: http
      scheme: bearer
      description: 'The ''Authorization'' field must be filled with an access token.

        #### How to get an access token

        To request an access token, the Initiating Party must digitally sign the relevant request headers using the private key that corresponds to the certificate uploaded to the Open Banking Service Portal. This action is to be performed in the `POST /token` endpoint.


        Upon a successful request, the Open Banking Service provides the Initiating Party with an access token.


        #### Validity

        Tokens are valid for 60 minutes (3600 seconds). After 60 minutes have elapsed, the Initiating Party will need to request a new token.


        There is an overlap period during the last 10 minutes (between the 50th and 60th minute). This means if the Initiating Party were to request a new token between 50th minute to 60th minute, they would receive a new access token. However, for those 10 minutes, the previous token would also still be valid.

        '