ConvertCurrency API Operation

Important: Adaptive Payments is now a limited release product. It is restricted to select partners for approved use cases and should not be used for new integrations without guidance from PayPal.

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

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

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: The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts.
  • Canadian Dollar — CAD
  • Czech Koruna — CZK
  • Danish Krone — DKK
  • Euro — EUR
  • Hong Kong Dollar — HKD
  • Hungarian Forint — HUF
  • Israeli New Sheqel — 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

currency

ap:CurrencyType

(Required) The currency code. Allowable values are:


  • Australian Dollar — AUD
  • Brazilian Real — BRL
    Note: The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts.
  • Canadian Dollar — CAD
  • Czech Koruna — CZK
  • Danish Krone — DKK
  • Euro — EUR
  • Hong Kong Dollar — HKD
  • Hungarian Forint — HUF
  • Israeli New Sheqel — 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

currencyCode

xs:string

(Required) The currency code. Allowable values are:


  • Australian Dollar — AUD
  • Brazilian Real — BRL
    Note: The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts.
  • Canadian Dollar — CAD
  • Czech Koruna — CZK
  • Danish Krone — DKK
  • Euro — EUR
  • Hong Kong Dollar — HKD
  • Hungarian Forint — HUF
  • Israeli New Sheqel — 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

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

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

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

currencyConversionList

ap:CurrencyConversionList

The list of converted currencies.

CurrencyConversionList Fields

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

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: The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts.
  • Canadian Dollar — CAD
  • Czech Koruna — CZK
  • Danish Krone — DKK
  • Euro — EUR
  • Hong Kong Dollar — HKD
  • Hungarian Forint — HUF
  • Israeli New Sheqel — 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

currency

ap:CurrencyType

The list of converted amounts with their target currency codes.

ResponseEnvelope Fields

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

error

common:ErrorData

Detailed error information.

responseEnvelope

common:ResponseEnvelope

Common response information, including a timestamp and the response acknowledgment status.

ErrorData Fields

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

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

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