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

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

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

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