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

Shows the pre-payment disclosure and response. This API is specific for merchants who must support the Consumer Financial Protection Bureau's Remittance Transfer Rule.

GetPrePaymentDisclosure Message

GetPrePaymentDisclosureRequest Fields

Field

Description

payKey

xs:string

(Required) The pay key that identifies the payment for which you want to retrieve details. This is the pay key returned in the pay response message.

receiverInfoList

ap:ReceiverInfoList

(Optional) List of payment receivers for unilateral scenarios. The list can contain details for a single simple payment or multiple receivers in support of parallel/chained payments.

requestEnvelope

common:RequestEnvelope

(Required) Information common to each API operation, such as the language in which an error message is returned.

ReceiverInfoList Field

This must be provided in the case of a unilateral scenario.

Field

Description

receiverInfo

ap:ReceiverInfo

(Required) List of receiver information details. For multiple receivers, this supports parallel/chained payments.

ReceiverInfo Fields

These fields must be populated for a receiver who does not have a PayPal account.

Field

Description

accountIdentifier

common:AccountIdentifier

(Required) Identifies the payment receiver.

countryCode

xs:string

(Required) The two-character country code of the end consumer's home country.

firstName

xs:string

(Optional) The first name of the consumer as known by the institution.

Maximum length: 64 characters

lastName

xs:string

(Optional) The last name of the consumer as known by the institution.

Maximum length: 64 characters

RequestEnvelope Fields

Field

Description

detailLevel

common:DetailLevelCode

(Optional) Level of detail required by the client application for components. Currently only one value is available:

  • ReturnAll — This value provides the maximum level of detail (default).

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.

GetPrePaymentDisclosure Response

GetPrePaymentDisclosureResponse Fields

Field

Description

disclaimer

xs:string

(Optional) Holds the disclaimer.

feesPayer xs:string

(Optional) The payer of PayPal fees. Value is:

  • SENDER — Sender pays all fees. (This is for personal, implicit simple/parallel payments; do not use for chained or unilateral payments.)
  • PRIMARYRECEIVER — Primary receiver pays all fees (chained payments only.)
  • EACHRECEIVER — Each receiver pays their own fee (default, personal, and unilateral payments.)
  • SECONDARYONLY — Secondary receivers pay all fees (use only for chained payments with one secondary receiver.)

receiverDisclosureList

ap:ReceiverDisclosureList

(Optional) Holds the disclosure information related to receivers. The merchant can parse the details available in the response and display them to the receiver.

responseEnvelope common:ResponseEnvelope

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

senderDisclosure

ap:SenderDisclosure

(Optional) Holds the disclosure related to the sender.

Merchants should display the details in SenderDisclosure.
The FeeDisclosure applies only if the feePayer is set to SENDER.

status

ap:Status

(Required) Indicates the response status:

  • Status = RTR: This is a Remittance Transfer Rule transaction.
  • Status = NON_RTR: This is not a Remittance Transfer Rule transaction.
  • Status = MISSING_RECEIVER_COUNTRY_INFORMATION: The Receiver country information is not found in the PayPal database. The merchant must call the API again with same set of parameters along with the receiver country code. This is useful in case of a Unilateral scenario, where the receiver does not hold a PayPal account.

ResponseEnvelope Fields

Field

Description

ack

common:AckCode

(Required) 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

(Required) Build number. It is used only by PayPal Merchant Technical Support.

correlationId

xs:string

(Required) 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

(Required) 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.

SenderDisclosure Fields

Field

Description

amountToTransfer

common:CurrencyType

(Required) The amount of the transaction.

conversionRate

ap:ConversionRate

(Required) The conversion rate from the sender currency to the transaction currency.

Note: In the case when there is no conversion of the sender currency, none of the elements in the conversion rate tag are returned.

feeDisclosure

ap:FeeDisclosure

(Optional) The fee, if any, associated with the transaction.

totalAmountToTransfer

common:CurrencyType

(Required) The total transaction that includes the main transaction amount adjusted for any associated fee.

Status Field

Field

Description

status

xs:string

(Required) Indicates the response status as one of the following:

  • RTR: This is a Remittance Transfer Rule transaction.
  • NON_RTR: This is not a Remittance Transfer Rule transaction.
  • MISSING_RECEIVER_COUNTRY_INFORMATION: The Receiver country information is not found in the PayPal database. The merchant must call the API again with same set of parameters along with the receiver country code. This is useful in case of a Unilateral scenario, where the receiver does not hold a PayPal account.

ReceiverDisclosureList Field

Field

Description

receiverDisclosure

ap:ReceiverDisclosure

(Required) List of the disclosures for the receivers.

ReceiverDisclosure Fields

Field

Description

accountIdentifier

common:AccountIdentifier

(Required) Identifies the payment receiver.

amountReceivedFromSender

common:CurrencyType

(Required) The amount received from the sender.

conversionRate

ap:ConversionRate

Note: The conversion rate in the receiver disclosure is obsolete. All the elements in this tag return NULL value.

countryCode

xs:string

(Required) The two-character country code of the end consumer's home country.

feeDisclosure

ap:FeeDisclosure

(Optional) The fee, if any, associated with the transaction.

TotalAmountReceived

ap:CurrencyType

(Required) The total transaction that includes the main transaction amount adjusted for any associated fee.

CurrencyType Fields

Field

Description

amount

xs:decimal

(Required) The converted amount.

code

xs:string

(Required) 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

  • Singapore Dollar — SGD

  • Swedish Krona — SEK

  • Swiss Franc — CHF

  • Taiwan New Dollar — TWD

  • Thai Baht — THB

  • U.S. Dollar — USD

ConversionRate Fields

Field

Description

exchangeRate

xs:decimal

(Required) The exchange rate that converts a unit of the sender's currency to the transaction currency.

receiverCurrency

xs:string

(Required) The transaction currency that the receiver will receive.

senderCurrency

xs:string

(Required) The sender's primary currency to be converted.

FeeDisclosure Fields

Field

Description

fee

ap:CurrencyType

(Required) The fee associated with the payment.

taxes

ap:CurrencyType

(Required) Taxes associated with the payment.

PPFault Message

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

FaultMessage Fields

Field

Description

error

common:ErrorData

(Optional) Detailed error information.

responseEnvelope

common:ResponseEnvelope

(Required) 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

xs:token

(Optional) This field is not used.

message

xs:string

A description of the error.

parameter

common:ErrorParameter

(Optional) 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

xs:string

(Optional) This field is not used.

ResponseEnvelope Fields

Field

Description

ack

common:AckCode

(Required) 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

(Required) Build number. It is used only by PayPal Merchant Technical Support.

correlationId

xs:string

(Required) 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

(Required) 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.

GetPrePaymentDisclosure Errors

Code

Message

520002 Internal error.

520003

Authentication failed. API credentials are incorrect.

550001

User is not allowed to perform this action.

569020

Feature not enabled.

580001

Invalid request: <value>

580022 Invalid request parameter: <value>

580023

The fee payer SENDER cannot be used with unilateral receiver

580027

The parameter is not supported.