---
title: "Request exchange rate information."
method: POST
path: "/v2/exchange-rates"
tags: ["Exchange"]
---

# Request exchange rate information.

`POST /v2/exchange-rates`

## Request

- Base URL: `https://api.sandbox.payall.com`
- URL: `https://api.sandbox.payall.com/v2/exchange-rates`
- Auth: OAuth 2
  - Client credentials
  - Token URL: `/v2/oauth/token`

The exchange rate can be later used to initiate a new payment.
Obtaining the exchange rate before payment is optional.

## Request body

- ExchangeRateRequest: Use either `source_amount` and `target_currency` or just `target_amount` to receive rate in the currency of the source account referenced by the `source_account_id`. `source_amount` represents a value in the currency **from** which the exchange is made. `target_amount` represents a value in the currency **to** which the exchange is made. Examples: 1. Exchange 10 EUR (`source_amount`) **to** `target_currency` GBP 2. Get amount in EUR (`source_account_id`'s currency) for the `target_amount` being 10 GBP `source_currency` and `source_account_id` are mutually exclusive. Also there is no need to provide `source_currency` if you're providing `source_amount` as it is already contains currency. Providing both will result in an error with 409 status code. `recipient_instrument_id` and `payment_instrument_category` are mutually exclusive. Providing both will result in an error with 409 status code. This is because instrument category is already part of existing payment instrument. `payment_type` is not needed when providing `source_account_id` and `recipient_instrument_id` and `payment_type`. Providing both will result in an error with 409 status code. This is because payment type is defined by payer and recipient types.
  - `source_account_id` string, uuid: ID of the account to use as source of funds. Provide either source or target amount to receive the opposite value.
  - `source_currency` string, iso-4217: Currency of the source amount. This field is required only if both `source_amount` and `source_account_id` are NOT provided. This is useful if you're not using currency exchange markup based on payer segmentation (ie high volume business payers having different rates than individuals).
  - `source_amount` Amount
    - `currency` string, iso-4217, required
    - `value` integer, required: Amounts are always in the smallest currency unit. Example: 1000.23 EUR is represented as 100023 euro cents.
  - `target_amount` Amount
    - `currency` string, iso-4217, required
    - `value` integer, required: Amounts are always in the smallest currency unit. Example: 1000.23 EUR is represented as 100023 euro cents.
  - `recipient_instrument_id` string: Represents recipient's payment instrument id of already existent entity. This field is for backward compatibility and will be removed in the future. Please use `payment_instrument_category` instead.
  - `payment_instrument_category` 'BankAccount' | 'MobileWallet' | 'CashPickup' | 'Card'
  - `payment_type` 'B2B' | 'B2P' | 'P2B' | 'P2P'
  - `target_currency` string, iso-4217
  - `destination_country` string, iso-3166-alpha-2, required: Destination country for the payment. 3166-1 alpha-2 value. Hint: It is `GB`, not `UK`.

## Response `201`

Created

- ExchangeRateInstance: `source_amount` represents a value in the currency **from** which the exchange is made. `target_amount` represents a value in the currency **to** which the exchange is made. For example 10 EUR (`source_amount`) converted **to** GBP will result in 8 GBP (`target_amount`).
  - `id` string, uuid
  - `source_amount` Amount
    - `currency` string, iso-4217, required
    - `value` integer, required: Amounts are always in the smallest currency unit. Example: 1000.23 EUR is represented as 100023 euro cents.
  - `target_amount` Amount
    - `currency` string, iso-4217, required
    - `value` integer, required: Amounts are always in the smallest currency unit. Example: 1000.23 EUR is represented as 100023 euro cents.
  - `expiration_date` string, date-time: Exchange rate is valid until this date and time.

## Other responses

- `409`: Conflict This response is returned in following scenarios: 1. If both source and target currencies are the same and there is no need for exchange. 2. If `source_account_id` is provided together with `source_amount` but `source_amount` currency is different than the one of the source account - this is because source account already has associated currency. 3. If both `source_account_id` and `source_currency` are provided - this is because source account already has associated currency. 4. If both `source_currency` and `source_amount` are provided - this is because the currency is already part of the source amount. 5. If both `recipient_instrument_id` and either `payment_instrument_category` are provided - this is because instrument category id already a part of existing payment instrument. 6. If both `source_account_id` and `recipient_instrument_id` are provided and `payment_type` is present - this is because payment type is already defined by payer and recipient.

---

[API](https://skmtc.dev/payall/apis/payall-m2m-authentication-api.md) - [All operations](https://skmtc.dev/payall/apis/payall-m2m-authentication-api/llms.txt) - [OpenAPI document](https://skmtc.dev/payall/apis/payall-m2m-authentication-api/revisions/5f561eccd6ce?raw)