Adaptive Payments / API Reference / ExecutePayment

ExecutePayment API Operation

APIDeprecated


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

Executes a payment set up with the Pay API operation with the actionType CREATE. To pay receivers identified in the Pay call, pass the pay key you received from the PayResponse message in the ExecutePaymentRequest message.

ExecutePaymentRequest Message

The ExecutePaymentRequest message enables you to execute a payment requested using the Pay API operation.

ExecutePaymentRequest Fields

Field Description
payKey xs:string

(Optional) The pay key that identifies the payment to be executed. This is the pay key returned in the PayResponse message.
actionType xs:string

(Optional) Describes the action that is performed.

fundingPlanId xs:string

(Optional) The ID of the funding plan from which to make this payment.
requestEnvelope common:requestEnvelope

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

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.

ExecutePaymentResponse Message

ExecutePaymentResponse Fields

Field Description
payErrorList ap:PayErrorList Information about why a payment failed.
paymentExecStatus 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
  • INCOMPLETE — Some transfers succeeded and some failed for a parallel payment
  • ERROR — The payment failed and all attempted transfers failed or all completed transfers were successfully reversed
  • REVERSALERROR — One or more transfers failed when attempting to reverse a payment
Important: You must test the value of paymentExecStatus for an error even if responseEnvelope.ack is Success. If the PaymentExecStatus is ERROR, the Pay Key can no longer be used.
postPaymentDisclosureList ap:PostPaymentDisclosureList Common response information, including a timestamp and the response acknowledgment status.
responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgment status.

PayErrorList Fields

Field Description
payError PayError indicates the error, if any, that resulted on an attempted payment to a receiver.

PostPaymentDisclosureList Fields

Field Description
postPaymentDisclosure

ap:PostPaymentDisclosure

(Required) Contains information related to the post payment disclosure.

PostPaymentDisclosure Fields

Field Description
accountIdentifier common:AccountIdentifier

(Required) Identifies the payment receiver.

fundsAvailabilityDate xs:date

(Optional) The date on which the funds are available.

fundsAvailabilityDateDisclaimerText xs:string

(Optional) Text of the disclosure message.

stateRegulatoryAgencyInfo ap:StateRegulatoryAgencyInfo

(Optional) Contains information related to State Regulatory Agency Information of the Sender's country for Remittance Transfer Rule (RTR) transactions. This contains the following info:

  1. Agency Name
  2. Phone Number
  3. Website
Note: RTR is a rule published by the Consumer Financial Protection Bureau. It applies to companies processing remittance transfers of more than $15 USD (in the funded currency) from a US-based consumer (Sender) to a foreign-based receiver (Recipient).

StateRegulatoryAgencyInfo Fields

Contains information related to State Regulatory Agency Information of the Sender's country for Remittance Transfer Rule (RTR) transactions.

Field Description
Name xs:string

(Optional) The name of the State Regulatory Agency.

PhoneNo xs:string

(Optional) The phone number of the State Regulatory Agency.

Website xs:string

(Optional) The website URL of the State Regulatory Agency.

PayError Fields

Field Description
error Detailed error information.
receiver ap:Receiver Receiver is the party where funds are transferred to. A primary receiver receives a payment directly from the sender in a chained split payment. A primary receiver should not be specified when making a single or parallel split payment.

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.

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

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.

ExecutePayment 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
520005 Merchant account is locked  
520006 This call is not defined in the database  
529038 There was an error while making this payment  
539012 The preapproval key has not been authorized yet  
539041 The email account is based in a country that is not enabled to receive payments  
539043 The email account is based in a country that is not enabled to send payments  
540031 You do not have permission to execute this payment
540031 You don't have permission to cancel this preapproval  
540031 You do not have permission to execute this payment operation is not permitted because the credentials do not match those of the initial operation Since 1.6.0
550001 User is not allowed to perform this action  
550001 This payment request must be authorized by the sender  
550001 You do not have permission to execute this payment implicitly Since 1.6.0
559044 Account setting on the receiver prohibited the payment  
560027 The argument value is unsupported  
569000 Split payments are not supported at this time  
569013 The preapproval key has been canceled  
569016 Preapproval PIN functionality is not enabled  
569017 The preapproval key has been suspended  
569018 Preapproved payments have been disabled  
569019 The preapproval has been suspended due to too many PIN failures  
569042 The email account is not confirmed by PayPal  
579007 The maximum number of receivers is <number>  
579010 If a preapproval key is specified, the sender's email address must be, too  
579014 The preapproval key specifies a different sender than the payment request  
579017 The amount for the primary receiver must be greater than or equal to the total of other chained receiver amounts  
579024 The preapproval key cannot be used before the start date or after the end date  
579025 The preapproval key cannot be used on this weekday  
579026 The preapproval key cannot be used on this day of the month  
579027 The preapproval key specifies a different currency than the payment request  
579028 The payment amount exceeds the maximum amount per payment  
579030 The number of payments made this period exceeds the maximum number of payments per period  
579031 The total amount of all payments exceeds the maximum total amount for all payments  
579033 The sender and each receiver must have different accounts  
579040 The receivers cannot belong to the same PayPal account  
579042 The tracking ID already exists and cannot be duplicated  
579045 The email account exceeds the receiving limit  
579047 The email account exceeds the purse limit  
579048 The email account exceeds the sending limit  
580001 Invalid request  
580022 Your request was invalid. Check the parameter of the error to see which is invalid  
580022
  • Invalid request parameter: payKey with value <value>
  • payKey <value> has already been used to make a payment
580022 The funding plan data is not present Since 1.6.0. Tried to pass in a non-zero funding plan and there are no funding plans present
580023 Invalid request  
580027 The argument is unsupported  
580028 The URL <value> is malformed  
580029 Invalid request  
580029 A pay key, transaction ID, or tracking ID is missing Since 1.6.0
580030 This transaction cannot be processed at this time. Please try again later. Since 1.3.0
589009 This payment cannot be processed because no payment source is available  
589023 If a fractional amount is rounded due to currency conversion, funds could be lost  
589039 The email address is invalid. It may not be registered in PayPal's system yet