# ConvertCurrency API Operation (/archive/adaptive-payments/api/convert-currency)



> **Note:** **Important:** Adaptive Payments is not available for new integrations. PayPal provides this documentation to support existing integrations. If you're starting an integration, [we recommend our latest solutions](https://www.paypal.com/us/business/accept-payments).

Requests the current foreign exchange (FX) rate for a specific amount and currency.

## ConvertCurrencyRequest Message [#convertcurrencyrequest-message]

The`ConvertCurrencyRequest` message enables you to have your application get an estimated exchange rate for a list of amounts. This API operation does not affect PayPal balances.

<img src="https://www.paypalobjects.com/webstatic/en_US/developer/docs/api/ConvertCurrencyRequest.gif" />

<img src="https://www.paypalobjects.com/webstatic/en_US/developer/docs/api/CurrencyList.gif" />

<img src="https://www.paypalobjects.com/webstatic/en_US/developer/docs/api/CurrencyCodeList.gif" />

### ConvertCurrencyRequest Fields [#convertcurrencyrequest-fields]

The table below describes the fields for the `ConvertCurrencyRequest` message.

| Field<br />                   | Description<br />                                                                                                                                                                                                                                                                                                                                                                                                              |
| ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `baseAmountList`<br />        | `ap:CurrencyList`<br /&#x3E; &#x2A;(Required)* A list of amounts with associated currencies to be converted.<br />                                                                                                                                                                                                                                                                                                             |
| `convertToCurrencyList`<br /> | `ap:CurrencyCodeList`<br /&#x3E; &#x2A;(Required)* A list of currencies to convert to.<br />                                                                                                                                                                                                                                                                                                                                   |
| `requestEnvelope`<br />       | `common:RequestEnvelope`<br /&#x3E; &#x2A;(Required)* Information common to each API operation, such as the language in which an error message is returned.<br />                                                                                                                                                                                                                                                              |
| `countryCode`<br />           | `xs:string`<br /> \*(Optional)\*The two-character ISO code for the country where the function is supposed to happen. The default value is `US`.<br />                                                                                                                                                                                                                                                                          |
| `conversionType`<br />        | `xs:string`<br /> \*(Optional)\*The conversion type allows you to determine the converted amounts for a PayPal user in different currency conversion scenarios, e.g., sending a payment in a different currency than what this user holds, accepting payment in a different currency than what the user holds, or converting a balance to a different currency than the user holds. The default value is `SENDER_SIDE `.<br /> |

### CurrencyType Fields [#currencytype-fields]

| Field<br />    | Description<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`<br /> | `xs:decimal`<br /&#x3E; &#x2A;(Required)* The amount to be converted.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `code`<br />   | `xs:string`<br /&#x3E; &#x2A;(Required)* The currency code. Allowable values are:<br /> <br />Australian Dollar — `AUD`Brazilian Real — `BRL` > **Note:** &#x2A;*Note:** This currency is supported as a payment currency and a currency balance for in-country PayPal accounts only.  If the receiver of funds is not from Brazil, then PayPal converts funds into the primary holding currency of the account with the applicable currency conversion rate.  The currency conversion rate includes PayPal's applicable spread or fee.Canadian Dollar — `CAD`Czech Koruna — `CZK`Danish Krone — `DKK`Euro — `EUR`Hong Kong Dollar — `HKD`Hungarian Forint — `HUF`Israeli New Shekel — `ILS`Japanese Yen — `JPY`Malaysian Ringgit — `MYR` > **Note:** &#x2A;*Note:** The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts.Mexican Peso — `MXN`Norwegian Krone — `NOK`New Zealand Dollar — `NZD`Philippine Peso — `PHP`Polish Zloty — `PLN`Pound Sterling — `GBP`Russian Ruble — `RUB`Singapore Dollar — `SGD`Swedish Krona — `SEK`Swiss Franc — `CHF`Taiwan New Dollar — `TWD`Thai Baht — `THB`U.S. Dollar — `USD` |

### CurrencyList Fields [#currencylist-fields]

| Field<br />      | Description<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `currency`<br /> | `ap:CurrencyType`<br /&#x3E; &#x2A;(Required)* The currency code. Allowable values are:<br /> <br />Australian Dollar — `AUD`Brazilian Real — `BRL` > **Note:** &#x2A;*Note:** This currency is supported as a payment currency and a currency balance for in-country PayPal accounts only.  If the receiver of funds is not from Brazil, then PayPal converts funds into the primary holding currency of the account with the applicable currency conversion rate.  The currency conversion rate includes PayPal's applicable spread or fee.Canadian Dollar — `CAD`Czech Koruna — `CZK`Danish Krone — `DKK`Euro — `EUR`Hong Kong Dollar — `HKD`Hungarian Forint — `HUF`Israeli New Shekel — `ILS`Japanese Yen — `JPY`Malaysian Ringgit — `MYR` > **Note:** &#x2A;*Note:** The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts.Mexican Peso — `MXN`Norwegian Krone — `NOK`New Zealand Dollar — `NZD`Philippine Peso — `PHP`Polish Zloty — `PLN`Pound Sterling — `GBP`Russian Ruble — `RUB`Singapore Dollar — `SGD`Swedish Krona — `SEK`Swiss Franc — `CHF`Taiwan New Dollar — `TWD`Thai Baht — `THB`U.S. Dollar — `USD` |

### CurrencyCodeList Fields [#currencycodelist-fields]

| Field<br />          | Description<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `currencyCode`<br /> | xs:string\*(Required)\* The currency code. Allowable values are:<br /> <br />Australian Dollar — `AUD`Brazilian Real — `BRL` > **Note:** &#x2A;*Note:** This currency is supported as a payment currency and a currency balance for in-country PayPal accounts only.  If the receiver of funds is not from Brazil, then PayPal converts funds into the primary holding currency of the account with the applicable currency conversion rate.  The currency conversion rate includes PayPal's applicable spread or fee.Canadian Dollar — `CAD`Czech Koruna — `CZK`Danish Krone — `DKK`Euro — `EUR`Hong Kong Dollar — `HKD`Hungarian Forint — `HUF`Israeli New Shekel — `ILS`Japanese Yen — `JPY`Malaysian Ringgit — `MYR` > **Note:** &#x2A;*Note:** The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts.Mexican Peso — `MXN`Norwegian Krone — `NOK`New Zealand Dollar — `NZD`Philippine Peso — `PHP`Polish Zloty — `PLN`Pound Sterling — `GBP`Russian Ruble — `RUB`Singapore Dollar — `SGD`Swedish Krona — `SEK`Swiss Franc — `CHF`Taiwan New Dollar — `TWD`Thai Baht`— THB`U.S. Dollar — `USD` |

### RequestEnvelope Fields [#requestenvelope-fields]

| Field<br />           | Description<br />                                                                                                                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `detailLevel`<br />   | `common:DetailLevelCode`<br /&#x3E; &#x2A;(Optional)* Level of detail required by the client application for components. The default value is `ReturnAll` which provides the maximum level of detail.<br /> |
| `errorLanguage`<br /> | `xs:string`<br /&#x3E; &#x2A;(Required)* RFC 3066 language in which error messages are returned; by default it is `en_US`, which is the only language currently supported.<br />                            |

### ConversionType Fields [#conversiontype-fields]

The table below describes the `ConversionType` field.

| Field<br />            | Description<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `conversionType`<br /> | `xs:string`<br /&#x3E; &#x2A;(Optional)* The conversion type allows you to determine the converted amounts for a PayPal user in different currency conversion scenarios. Value is:<br /> <br />`SENDER_SIDE` — Pass this conversion type when you convert amounts for a PayPal user who is sending a payment in a different currency from what he/she holds in PayPal.`RECEIVER_SIDE` — Pass this conversion type when you when you convert amounts for a PayPal user who is accepting a payment in a currency that he/she does not hold and who wants to convert the received payment.`BALANCE_TRANSFER` — Pass this conversion type when you convert amounts for a PayPal user who is converting a balance in one currency to a balance in a different currency on his/her profile. |

## ConvertCurrencyResponse Message [#convertcurrencyresponse-message]

The `ConvertCurrencyResponse` message returns the following information to the application in response to the `ConvertCurrencyRequest` message.

<img src="https://www.paypalobjects.com/webstatic/en_US/developer/docs/api/ConvertCurrencyResponse.gif" />

<img src="https://www.paypalobjects.com/webstatic/en_US/developer/docs/api/CurrencyConversionTable.gif" />

<img src="https://www.paypalobjects.com/webstatic/en_US/developer/docs/api/CurrencyConversionList.gif" />

<img src="https://www.paypalobjects.com/webstatic/en_US/developer/docs/api/CurrencyList.gif" />

### ConversionCurrencyResponse Fields [#conversioncurrencyresponse-fields]

| Field<br />                  | Description<br />                                                                                                                           |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `estimatedAmountTable`<br /> | `ap:CurrencyConversionTable`<br /> A list of the requested amounts converted to the requested currencies.<br />                             |
| `responseEnvelope`<br />     | `common:responseEnvelope`<br /> Information common to each API operation, such as the language in which an error message is returned.<br /> |

### CurrencyConversionTable Fields [#currencyconversiontable-fields]

| Field<br />                    | Description<br />                                                         |
| ------------------------------ | ------------------------------------------------------------------------- |
| `currencyConversionList`<br /> | `ap:CurrencyConversionList`<br /> The list of converted currencies.<br /> |

### CurrencyConversionList Fields [#currencyconversionlist-fields]

| Field<br />          | Description<br />                                                                                                |
| -------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `baseAmount`<br />   | `ap:CurrencyType`<br /> The base amount and currency code.<br />                                                 |
| `currencyList`<br /> | `ap:CurrencyList`<br /> The list of amounts converted to the requested currencies, and the currency codes.<br /> |

### CurrencyType Fields [#currencytype-fields-1]

| Field<br />    | Description<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `amount`<br /> | `xs:decimal`<br /> The converted amount.<br />                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `code`<br />   | `xs:string`<br /> The currency code for the converted amount. Value is:<br /> <br />Australian Dollar — `AUD`Brazilian Real — `BRL` > **Note:** &#x2A;*Note:** This currency is supported as a payment currency and a currency balance for in-country PayPal accounts only.  If the receiver of funds is not from Brazil, then PayPal converts funds into the primary holding currency of the account with the applicable currency conversion rate.  The currency conversion rate includes PayPal's applicable spread or fee.Canadian Dollar — `CAD`Czech Koruna — `CZK`Danish Krone — `DKK`Euro — `EUR`Hong Kong Dollar — `HKD`Hungarian Forint — `HUF`Israeli New Shekel — `ILS`Japanese Yen — `JPY`Malaysian Ringgit — `MYR` > **Note:** &#x2A;*Note:** The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts.Mexican Peso — `MXN`Norwegian Krone — `NOK`New Zealand Dollar — `NZD`Philippine Peso — `PHP`Polish Zloty — `PLN`Pound Sterling — `GBP`Russian Ruble — `RUB`Singapore Dollar — `SGD`Swedish Krona — `SEK`Swiss Franc — `CHF`Taiwan New Dollar — `TWD`Thai Baht — `THB`U.S. Dollar — `USD` |

### CurrencyList Fields [#currencylist-fields-1]

| Field<br />      | Description<br />                                                                             |
| ---------------- | --------------------------------------------------------------------------------------------- |
| `currency`<br /> | `ap:CurrencyType`<br /> The list of converted amounts with their target currency codes.<br /> |

### ResponseEnvelope Fields [#responseenvelope-fields]

| Field<br />           | Description<br />                                                                                                                                                                                                                                                                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ack`<br />           | `common:AckCode`<br /> Acknowledgment code. Value is:<br /> <br />`Success` — The operation completed successfully.`Failure` — The operation failed.`SuccessWithWarning` — The operation completed successfully; however, there is a warning message.`FailureWithWarning `— The operation failed with a warning message.                                    |
| `build`<br />         | `xs:string`<br /> Build number. It is used only by PayPal Merchant Technical Support.<br />                                                                                                                                                                                                                                                                 |
| `correlationId`<br /> | `xs:string`<br /> Correlation identifier. It is a 13-character, alphanumeric string (for example, `db87c705a910e`) that is used only by PayPal Merchant Technical Support.<br />  > **Note:** &#x2A;*Note:** You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. |
| `timestamp`<br />     | `xs:datetime`<br /> Date on which the response was sent, for example:<br /> `2012-04-02T22:33:35.774-07:00`<br />  > **Note:** &#x2A;*Note:** You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues.                                                                |

## PPFault Message [#ppfault-message]

The `PPFaultMessage` returns `ErrorData` and the `ResponseEnvelope` information to your application if an error occurs.

<img src="https://www.paypalobjects.com/webstatic/en_US/developer/docs/api/FaultMessage.gif" />

<img src="https://www.paypalobjects.com/webstatic/en_US/developer/docs/api/ErrorData.gif" />

### FaultMessage Fields [#faultmessage-fields]

| Field<br />              | Description<br />                                                                                                                |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------- |
| `error`<br />            | `common:ErrorData`<br /> Detailed error information.<br />                                                                       |
| `responseEnvelope`<br /> | `common:ResponseEnvelope`<br /> Common response information, including a timestamp and the response acknowledgment status.<br /> |

### ErrorData Fields [#errordata-fields]

| Field<br />         | Description<br />                                                                                                                                                                                                                                     |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `category`<br />    | `common:ErrorCategory`<br /> The location where the error occurred.<br /> Value is:<br /> <br />`System` — The system encountered errors; try again`Application` — The application encountered errors; try again`Request` — The request was incorrect |
| `domain`<br />      | `xs:string`<br /> The domain to which this service belongs.<br />                                                                                                                                                                                     |
| `errorId`<br />     | `xs:long`<br /> A 6-digit number that uniquely identifies a particular error.<br />                                                                                                                                                                   |
| `exceptionID`<br /> | This field is not used.<br />                                                                                                                                                                                                                         |
| `message`<br />     | `xs:string`<br /> A description of the error.<br />                                                                                                                                                                                                   |
| `parameter`<br />   | `common:ErrorParameter`<br /> Represents contextual information about the error.<br />                                                                                                                                                                |
| `severity`<br />    | `common:ErrorSeverity`<br /> The severity of the error encountered.<br /> Value is:<br /> <br />`Error` — Processing of the request was interrupted`Warning` — Processing of the request was completed                                                |
| `subdomain`<br />   | This field is not used.<br />                                                                                                                                                                                                                         |

### ResponseEnvelope Fields [#responseenvelope-fields-1]

| Field<br />           | Description<br />                                                                                                                                                                                                                                                                                                                                           |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ack`<br />           | `common:AckCode`<br /> Acknowledgment code. Value is:<br /> <br />`Success` — The operation completed successfully.`Failure` — The operation failed.`SuccessWithWarning` — The operation completed successfully; however, there is a warning message.`FailureWithWarning `— The operation failed with a warning message.                                    |
| `build`<br />         | `xs:string`<br /> Build number. It is used only by PayPal Merchant Technical Support.<br />                                                                                                                                                                                                                                                                 |
| `correlationId`<br /> | `xs:string`<br /> Correlation identifier. It is a 13-character, alphanumeric string (for example, `db87c705a910e`) that is used only by PayPal Merchant Technical Support.<br />  > **Note:** &#x2A;*Note:** You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. |
| `timestamp`<br />     | `xs:datetime`<br /> Date on which the response was sent, for example:<br /> `2012-04-02T22:33:35.774-07:00`<br />  > **Note:** &#x2A;*Note:** You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues.                                                                |

## ConvertCurrency Errors [#convertcurrency-errors]

| Code<br /> | Message<br />                                                                      | Additional Information<br /> |
| ---------- | ---------------------------------------------------------------------------------- | ---------------------------- |
| 520002     | Internal error                                                                     |                              |
| 580022     | Your request was invalid. Check the parameter of the error to see which is invalid |                              |
| 580027     | The argument is unsupported                                                        |                              |