ConvertCurrency API Operation

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.

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

ConvertCurrencyRequest Message

TheConvertCurrencyRequest 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.

ConvertCurrencyRequest Fields

The table below describes the fields for the ConvertCurrencyRequest message.

Field, Description
Field	Description
`baseAmountList`	`ap:CurrencyList` (Required) A list of amounts with associated currencies to be converted.
`convertToCurrencyList`	`ap:CurrencyCodeList` (Required) A list of currencies to convert to.
`requestEnvelope`	`common:RequestEnvelope` (Required) Information common to each API operation, such as the language in which an error message is returned.
`countryCode`	`xs:string` (Optional)The two-character ISO code for the country where the function is supposed to happen. The default value is `US`.
`conversionType`	`xs:string` (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` .

CurrencyType Fields

Field, Description
Field	Description
`amount`	`xs:decimal` (Required) The amount to be converted.
`code`	`xs:string` (Required) The currency code. Allowable values are: Australian Dollar — `AUD` Brazilian Real — `BRL` 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: 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

Field, Description
Field	Description
`currency`	`ap:CurrencyType` (Required) The currency code. Allowable values are: Australian Dollar — `AUD` Brazilian Real — `BRL` 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: 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

Field, Description
Field	Description
`currencyCode`	xs:string(Required) The currency code. Allowable values are: Australian Dollar — `AUD` Brazilian Real — `BRL` 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: 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

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

ConversionType Fields

The table below describes the ConversionType field.

Field, Description
Field	Description
`conversionType`	`xs:string` (Optional) The conversion type allows you to determine the converted amounts for a PayPal user in different currency conversion scenarios. Value is: `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

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

ConversionCurrencyResponse Fields

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

CurrencyConversionTable Fields

Field, Description
Field	Description
`currencyConversionList`	`ap:CurrencyConversionList` The list of converted currencies.

CurrencyConversionList Fields

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

CurrencyType Fields

Field, Description
Field	Description
`amount`	`xs:decimal` The converted amount.
`code`	`xs:string` The currency code for the converted amount. Value is: Australian Dollar — `AUD` Brazilian Real — `BRL` 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: 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

Field, Description
Field	Description
`currency`	`ap:CurrencyType` The list of converted amounts with their target currency codes.

ResponseEnvelope Fields

Field, Description
Field	Description
`ack`	`common:AckCode` Acknowledgment code. Value is: `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`	`xs:string` Build number. It is used only by PayPal Merchant Technical Support.
`correlationId`	`xs:string` Correlation identifier. It is a 13-character, alphanumeric string (for example, `db87c705a910e`) that is used only by PayPal Merchant Technical Support. 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`	`xs:datetime` Date on which the response was sent, for example: `2012-04-02T22:33:35.774-07:00` 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

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

FaultMessage Fields

Field, Description
Field	Description
`error`	`common:ErrorData` Detailed error information.
`responseEnvelope`	`common:ResponseEnvelope` Common response information, including a timestamp and the response acknowledgment status.

ErrorData Fields

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

ResponseEnvelope Fields

Field, Description
Field	Description
`ack`	`common:AckCode` Acknowledgment code. Value is: `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`	`xs:string` Build number. It is used only by PayPal Merchant Technical Support.
`correlationId`	`xs:string` Correlation identifier. It is a 13-character, alphanumeric string (for example, `db87c705a910e`) that is used only by PayPal Merchant Technical Support. 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`	`xs:datetime` Date on which the response was sent, for example: `2012-04-02T22:33:35.774-07:00` 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

Code, Message, Additional Information
Code	Message	Additional Information
520002	Internal error
580022	Your request was invalid. Check the parameter of the error to see which is invalid
580027	The argument is unsupported

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

ConvertCurrencyRequest Message

TheConvertCurrencyRequest 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.

ConvertCurrencyRequest Fields

The table below describes the fields for the ConvertCurrencyRequest message.

Field, Description
Field	Description
`baseAmountList`	`ap:CurrencyList` (Required) A list of amounts with associated currencies to be converted.
`convertToCurrencyList`	`ap:CurrencyCodeList` (Required) A list of currencies to convert to.
`requestEnvelope`	`common:RequestEnvelope` (Required) Information common to each API operation, such as the language in which an error message is returned.
`countryCode`	`xs:string` (Optional)The two-character ISO code for the country where the function is supposed to happen. The default value is `US`.
`conversionType`	`xs:string` (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` .

CurrencyType Fields

Field, Description
Field	Description
`amount`	`xs:decimal` (Required) The amount to be converted.
`code`	`xs:string` (Required) The currency code. Allowable values are: Australian Dollar — `AUD` Brazilian Real — `BRL` 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: 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

Field, Description
Field	Description
`currency`	`ap:CurrencyType` (Required) The currency code. Allowable values are: Australian Dollar — `AUD` Brazilian Real — `BRL` 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: 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

Field, Description
Field	Description
`currencyCode`	xs:string(Required) The currency code. Allowable values are: Australian Dollar — `AUD` Brazilian Real — `BRL` 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: 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

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

ConversionType Fields

The table below describes the ConversionType field.

Field, Description
Field	Description
`conversionType`	`xs:string` (Optional) The conversion type allows you to determine the converted amounts for a PayPal user in different currency conversion scenarios. Value is: `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

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

ConversionCurrencyResponse Fields

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

CurrencyConversionTable Fields

Field, Description
Field	Description
`currencyConversionList`	`ap:CurrencyConversionList` The list of converted currencies.

CurrencyConversionList Fields

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

CurrencyType Fields

Field, Description
Field	Description
`amount`	`xs:decimal` The converted amount.
`code`	`xs:string` The currency code for the converted amount. Value is: Australian Dollar — `AUD` Brazilian Real — `BRL` 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: 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

Field, Description
Field	Description
`currency`	`ap:CurrencyType` The list of converted amounts with their target currency codes.

ResponseEnvelope Fields

Field, Description
Field	Description
`ack`	`common:AckCode` Acknowledgment code. Value is: `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`	`xs:string` Build number. It is used only by PayPal Merchant Technical Support.
`correlationId`	`xs:string` Correlation identifier. It is a 13-character, alphanumeric string (for example, `db87c705a910e`) that is used only by PayPal Merchant Technical Support. 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`	`xs:datetime` Date on which the response was sent, for example: `2012-04-02T22:33:35.774-07:00` 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

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

FaultMessage Fields

Field, Description
Field	Description
`error`	`common:ErrorData` Detailed error information.
`responseEnvelope`	`common:ResponseEnvelope` Common response information, including a timestamp and the response acknowledgment status.

ErrorData Fields

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

ResponseEnvelope Fields

Field, Description
Field	Description
`ack`	`common:AckCode` Acknowledgment code. Value is: `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`	`xs:string` Build number. It is used only by PayPal Merchant Technical Support.
`correlationId`	`xs:string` Correlation identifier. It is a 13-character, alphanumeric string (for example, `db87c705a910e`) that is used only by PayPal Merchant Technical Support. 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`	`xs:datetime` Date on which the response was sent, for example: `2012-04-02T22:33:35.774-07:00` 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

Code, Message, Additional Information
Code	Message	Additional Information
520002	Internal error
580022	Your request was invalid. Check the parameter of the error to see which is invalid
580027	The argument is unsupported

ConvertCurrency API Operation

On this page

On this page

On this page

We currently use cookies to improve and customize your experience on our site. If you accept, we’ll also use marketing cookies to show you personalized ads. Manage your cookies and learn more.

ConvertCurrency API Operation

On this page

On this page