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:
|
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:
|
feesPayer |
xs:string The payer of PayPal fees. Value is:
|
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 |
Note: Unless overridden via the |
payKeyExpirationDate |
Name-value pair example: |
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:
|
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. |
|
Container for the sender's shipping address, if any, that was specified in the |
status |
xs:string The status of the payment. Value is:
|
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:
|
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
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:
|
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:
|
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 |
---|---|
|
(Optional) Person's name associated with this shipping address. Maximum length: 128 characters |
|
(Optional) First street address. Maximum length: 128 characters |
|
(Optional) Second street address. Maximum length: 128 characters |
|
(Optional) Name of city. Maximum length: 128 characters |
|
(Optional) State or province. Maximum length: 128 characters |
|
(Optional) U.S. ZIP code or other country-specific postal code. Maximum length: 128 characters |
|
(Optional) Country code. Maximum length: 128 characters |
|
(Optional) Phone number. |
PhoneNumber Fields
Field |
Description |
---|---|
|
(Optional) Specifies the type of phone number. Currently, only
|
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:
|
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:
|
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:
|
subdomain |
This field is not used. |
ResponseEnvelope Fields
Field | Description |
---|---|
ack |
common:AckCode Acknowledgment code. Value is:
|
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 ¤cyCode=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 |