Adaptive Payments / API Reference / PaymentDetails

PaymentDetails API Operation


Important: Adaptive Payments is not available for new integrations. PayPal provides this documentation to support existing integrations.

Shows information about a payment. You can identify the payment by the tracking ID, the PayPal transaction ID in an IPN message, or the pay key associated with the payment.

Note: If you are a PayPal account holder in a country with currency restrictions, see Currency Restrictions for a list of countries with restrictions, and the restriction details.

PaymentDetailsRequest Message

The PaymentDetailsRequest message contains the identifier used to retrieve information about the payment.

PaymentDetailsRequest Fields

The payKey, transactionId, and trackingId fields identify the payment.

You can supply either the payKey field or the trackingId field in your request. If you supply both fields, the payKey field will be used to identify the payment and the trackingId field will be ignored.

Field Description
payKey xs:string (Optional) The pay key that identifies the payment for which you want to retrieve details. This is the pay key returned in the PayResponse message.
requestEnvelope common:RequestEnvelope (Required) Information common to each API operation, such as the language in which an error message is returned.
transactionId xs:string (Optional) The PayPal transaction ID associated with the payment. The IPN message associated with the payment contains the transaction ID.
trackingId xs:string (Optional) The tracking ID that was specified for this payment in the PayRequest message. Maximum length: 127 characters

RequestEnvelope Fields

Field Description
detailLevel common:DetailLevelCode (Optional) Level of detail required by the client application pertaining to a particular data component. The detail level is specified as a detail level code, which has all the enumerated values of the detail level for the component. By default, the detail level code 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.

PaymentDetailsResponse Message

The PaymentDetailsResponse message contains information about the payment.

PaymentDetailsResponse Fields

Field Description
actionType xs:string Whether the Pay request is set up to create a payment request with the SetPaymentOptions request, and then fulfill the payment with the ExecutePayment request. Value is:
  • PAY — Use this option if you are not using the Pay request in combination with ExecutePayment.
  • CREATE — Use this option to set up the payment instructions with SetPaymentOptions and then execute the payment at a later time with the ExecutePayment.
  • PAY_PRIMARY — For chained payments only, specify this value to delay payments to the secondary receivers; only the payment to the primary receiver is processed.
cancelUrl xs:string The URL to which the sender's browser is redirected if the sender cancels the approval for a payment on paypal.com. Use the pay key to identify the payment as follows: payKey=${payKey}.
currencyCode xs:string The currency code. 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 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
feesPayer xs:string The payer of PayPal fees. Value is:
  • SENDER — Sender pays all fees (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)
fundingtypeList ap:FundingTypeList Specifies a list of allowed funding selections for the payment. This is a list of funding selections that can be combined in any order to allow payments to use the indicated funding type. If this Parameter is omitted, the payment can be funded by any funding type that is supported for Adaptive Payments.
ipnNotificationUrl xs:string The URL to which all IPN messages for this payment are sent.
memo xs:string A note associated with the payment.
payKey

xs:string The pay key that identifies this payment. A pay key is a token that is returned by the Pay API. This token can be used in other Adaptive Payments operations (as well as in a cancelURL or returnURL) to identify this payment.

Note: Unless overridden via the payKeyDuration field of the PayRequest message, a pay key is valid for 3 hours.
payKeyExpirationDate

xs:dateTime The date/time at which the specified payKey expires. This field is returned only if you passed the payKeyDuration field in the Pay API call that generated this pay key. Note that the payKeyExpirationDate field includes time zone information, so that the exact time can be determined.

Name-value pair example: payKeyExpirationDate=2013-06-06T13:17:22.000-07:00
paymentInfoList ap:PaymentInfoList Represents the payment attempt made to a receiver of a PayRequest. If the execution of the payment has not yet completed, there are no transaction details returned.
preapprovalKey xs:string The preapproval key that identifies the preapproval for this payment. This key can be used in other Adaptive Payment APIs to identify the preapproval.
responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgment status.
returnUrl xs:string The URL to which the sender's browser is redirected after approving a payment on paypal.com. Use the pay key to identify the payment as follows: payKey=${payKey}.
reverseAllParallelPaymentsOnError xs:string Whether to reverse parallel payments. Value is:
  • true — Each parallel payment is reversed if an error occurs
  • false — Each parallel payment is not reversed if an error occurs
sender ap:SenderIdentifer Sender's identifying information. See the ap:AccountIdentifer fields, below. This container can include an account ID value (which is the same as the Payer ID value used in the Express Checkout API). The account ID value is an encrypted PayPal account ID.
senderEmail xs:string The sender's email address.

shippingAddress

ap:ShippingAddressInfo

Container for the sender's shipping address, if any, that was specified in the SetPaymentOptions API call.

status xs:string The status of the payment. Value is:
  • CREATED — The payment request was received; funds will be transferred once the payment is approved.
  • COMPLETED — The payment was successful.
  • ERROR — The payment failed and all attempted transfers failed or all completed transfers were successfully reversed.
  • EXPIRED — The payment request has expired.
  • INCOMPLETE — For a parallel payment, some transfers succeeded and some failed. For a delayed chained payment, secondary receivers have not been paid.
  • PROCESSING — The payment is in progress.
  • PENDING — The payment is awaiting processing.
  • REVERSALERROR — One or more transfers failed when attempting to reverse a payment.
trackingId xs:string The tracking ID that was specified for this payment in the PaymentDetailsRequest message.

FundingTypeList Fields

Field Description
fundingTypeInfo ap:FundingTypeInfo Specifies a list of allowed funding selections for the payment. This is a list of funding selections that can be combined in any order to allow payments to use the indicated funding type. If this field is omitted, the payment can be funded by any funding type that is supported for Adaptive Payments.

FundingTypeInfo Fields

Field Description
fundingType Specifies a list of allowed funding selections for the payment. This is a list of funding selections that can be combined in any order to allow payments to use the indicated funding type. If this field is omitted, the payment can be funded by any funding type that is supported for Adaptive Payments. Value is:
  • ECHECK — Electronic check
  • BALANCE — PayPal account balance
  • CREDITCARD — Credit card

PaymentInfoList Fields

Fields Description
paymentInfo ap:PaymentInfo Represents the payment attempt made to a receiver of a PayRequest. If the execution of the payment has not yet completed, there are no transaction details returned.

PaymentInfo Fields

Field Description
pendingReason xs:string The reason why a payment is pending. the payment has a pending refund. Value is:
  • ADDRESS_CONFIRMATION — The payment is pending because the sender does not have a confirmed address on file and receiver's Payment Receiving Preferences is set for manually accepting payments or denying each of these payments.
  • ECHECK — The payment is pending because it was made by an eCheck that has not yet cleared.
  • INTERNATIONAL — The payment is pending because the receiver holds a non-U.S. account and does not have a withdrawal mechanism. The receiver must manually accept or deny this payment from the Account Overview.
  • MULTI_CURRENCY — The receiver does not have a balance in the currency sent, and does not have the Payment Receiving Preferences set to automatically convert and accept this payment. Receiver must manually accept or deny this payment from the Account Overview.
  • UNILATERAL — The payment is pending because it was made to an email address that is not yet registered or confirmed.
  • UPGRADE — The payment is pending because it was made via credit card and the receiver must upgrade the account to a Business account or Premier status to receive the funds. It can also mean that receiver has reached the monthly limit for transactions on the account.
  • VERIFY — The payment is pending because the receiver is not yet verified.
  • RISK — The payment is pending while it is being reviewed by PayPal for risk.
  • OTHER — The payment is pending for a reason other than those listed above. For more information, contact PayPal Customer Service.
pendingRefund xs:boolean Whether the payment has a pending refund. Value is:
  • true — The payment has a pending refund.
  • false — The payment does not have a refund pending.
receiver ap:Receiver The receiver of the payment.
refundedAmount xs:decimal The total amount refunded for this payment since the payment occurred.
senderTransactionId xs:string The transaction identification number of the sender of the payment.
senderTransactionStatus xs:string The transaction status of the payment. Value is:
  • COMPLETED — The sender's transaction has completed
  • PENDING — The transaction is awaiting further processing
  • CREATED — The payment request was received; funds will be transferred once approval is received
  • PARTIALLY_REFUNDED — Transaction was partially refunded
  • DENIED — The transaction was rejected by the receiver
  • PROCESSING — The transaction is in progress
  • REVERSED — The payment was returned to the sender
  • REFUNDED — The payment was refunded
  • FAILED — The payment failed
transactionId xs:string PayPal transaction ID for this payment to the specified receiver.
transactionStatus xs:string PayPal transaction status. Value is:
  • COMPLETED — The sender's transaction has completed
  • PENDING — The transaction is awaiting further processing
  • CREATED — The payment request was received; funds will be transferred once approval is received
  • PARTIALLY_REFUNDED — Transaction was partially refunded
  • DENIED — The transaction was rejected by the receiver
  • PROCESSING — The transaction is in progress
  • REVERSED — The payment was returned to the sender
  • REFUNDED — The payment was refunded
  • FAILED — The payment failed

Receiver Fields

Field Description
amount xs:decimal Amount to be paid to the receiver.
email xs:string Receiver's email address. Maximum length: 127 characters
accountId xs:string Account ID value (which is the same as the Payer ID value used in the Express Checkout API). The account ID value is an encrypted PayPal account ID.
invoiceId xs:string The invoice number for the payment. This data in this field shows on the Transaction Details report. Maximum length: 127 characters
paymentType xs:string The transaction type for the payment. Value is:
  • GOODS — This is a payment for non-digital goods
  • SERVICE — This is a payment for services (default)
  • PERSONAL — This is a person-to-person payment
  • CASHADVANCE — This is a person-to-person payment for a cash advance
  • DIGITALGOODS — This is a payment for digital goods
  • BANK_MANAGED_WITHDRAWAL — This is a person-to-person payment for bank withdrawals, available only with special permission.
paymentSubType xs:string The transaction subtype for the payment.
phone common:PhoneNumberType The receiver's phone number.
primary xs:boolean Whether this receiver is the primary receiver. If this field is set to true, this is a chained payment. If this field shows false, this is a simple or parallel payment. Value is:
  • true — Primary receiver (chained payment)
  • false — Secondary receiver (simple/parallel payment)

SenderIdentifier Fields

Field Description
useCredentials xs:boolean If true, credentials identify the sender; default is false.
taxIdDetails ap:TaxIdDetails Tax ID details (For Brazil only)

ShippingAddressInfo Fields

Field

Description

addresseeName

xs:string

(Optional) Person's name associated with this shipping address.

Maximum length: 128 characters

street1

xs:string

(Optional) First street address.

Maximum length: 128 characters

street2

xs:string

(Optional) Second street address.

Maximum length: 128 characters

city

xs:string

(Optional) Name of city.

Maximum length: 128 characters

state

xs:string

(Optional) State or province.

Maximum length: 128 characters

zip

xs:string

(Optional) U.S. ZIP code or other country-specific postal code.

Maximum length: 128 characters

country

xs:string

(Optional) Country code.

Maximum length: 128 characters

phone

ap:PhoneNumber

(Optional) Phone number.

PhoneNumber Fields

Field

Description

type

ap:PhoneType

(Optional) Specifies the type of phone number. Currently, only MOBILE is valid. Other Value is:

  • NONE — None of the other choices
  • HOME — Home phone
  • WORK — Work phone
  • BUSINESS — Business phone
  • MOBILE — Mobile phone
  • FAX_HOME — Fax home phone
  • FAX_BUSINESS — Fax business phone

TaxIdDetails Fields

Field Description
taxId xs:string Tax ID of the Merchant (For Brazil only)
taxIdType xs:string Type of the Tax ID. Either CPF or CNPJ (For Brazil only)

AccountIdentifier Fields

Field Description
email xs:string Sender's email address. Maximum length: 127 characters
phone common:PhoneNumberType Sender's phone number.
accountId xs:string Account ID value (which is the same as the Payer ID value used in the Express Checkout API). The account ID value is an encrypted PayPal account ID.

PhoneNumberType Response Fields

Field Description
countryCode xs:string Telephone country code.
phoneNumber xs:string Telephone number.
extension xs:string Telephone extension.

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.

PaymentDetails Examples Using NVP and CURL

These examples use NVP for the data binding and CURL to deliver the HTTP request to the PayPal sandbox endpoint. Line breaks are provided for ease of reading; each CURL command is a single line and each request and response is a string without line breaks or extra whitespace.

Using the payment key to obtain payment details

In this example, the caller of the Pay API operation specifies the payment key to obtain information about the entire payment:

Note: The sample code below uses the insecure setting to work around the certificate for testing in a sandbox environment. For actual implementations, you must specify the location of the certificate.

Request

curl https://svcs.sandbox.paypal.com/AdaptivePayments/PaymentDetails \
  -s \
  --insecure \
  -H "X-PAYPAL-SECURITY-USERID: api_username" \
  -H "X-PAYPAL-SECURITY-PASSWORD: api_password" \
  -H "X-PAYPAL-SECURITY-SIGNATURE: api_signature" \
  -H "X-PAYPAL-REQUEST-DATA-FORMAT: NV" \
  -H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV" \
  -H "X-PAYPAL-APPLICATION-ID: app_id" \
  -d payKey=AP-3TY011106S4428730 \
  -d requestEnvelope.errorLanguage=en_US

Response

responseEnvelope.timestamp=2009-08-14T09%3A00%3A37.748-07%3A00
&responseEnvelope.ack=Success
&responseEnvelope.correlationId=7967b2d03745a
&responseEnvelope.build=DEV
&cancelUrl=your_cancel_url
&currencyCode=USD
&logDefaultShippingAddress=false
&memo=Simple payment example.
&paymentInfoList.paymentInfo(0).receiver.amount=100.00
&paymentInfoList.paymentInfo(0).receiver.email=receiver@domain
&paymentInfoList.paymentInfo(0).receiver.primary=false
&returnUrl=your_return_url
&senderEmail=sender@domain
&status=CREATED
&payKey=AP-3TY011106S4428730
&actionType=PAY
&feesPayer=EACHRECEIVER

Payment Details Errors

Code Message Additional Information
500000 There is a system error
520002 Internal error
520003 User name/password is incorrect
520003 Authentication failed. API credentials are incorrect. Since 1.6.0
520006 This call is not defined in the database
540031 You do not have permission to get these payment details Since 1.6.0
579049 The payment request you are looking for was not found in our system
579051 The tracking ID is invalid
580001 Invalid request
580022 Invalid request parameter: payKey with value
580029 Invalid request
580030 This transaction cannot be processed at this time. Please try again later. Since 1.3.0
589052 The transaction ID is invalid