Adaptive Payments / API Reference / Pay

Pay API Operation


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

Transfers funds from a sender's PayPal account to one or more receivers' PayPal accounts.

You can use the Pay API for simple payments, chained payments, and parallel payments. Payments can be explicitly approved, preapproved, or implicitly approved.

Summary

A PayRequest must have the common fields below.

For use cases other than a simple payment, fields are added. Use cases include parallel payments, chained payments, implicit payments, and preapproved payments.

Common Fields for All Payments

For each kind of payment, you must specify values for the fields listed below.

Please read the Description column for alternatives:

Field Description
actionType The action for this 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.
receiverList.receiver(0).email A receiver's email address.
Alternatively, you can use receiverList.receiver(0).accountId.
The accountId field contains 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. This account ID value can be specified instead of a PayPal email address.
receiverList.receiver(0).amount Amount to be credited to the receiver's account
currencyCode The code for the currency in which the payment is made; you can specify only one currency, regardless of the number of receivers
cancelUrl URL to redirect the sender's browser to after canceling the approval for a payment; it is always required but only used for payments that require approval (explicit payments)
returnUrl URL to redirect the sender's browser to after the sender has logged into PayPal and approved a payment; it is always required but only used if a payment requires explicit approval
requestEnvelope.errorLanguage The code for the language in which errors are returned, which must be en_US.

Parallel Payments

For a simple payment, you must specify the fields above. For a parallel payment, you must specify the fields listed above as well as the fields listed below.

Please read the Description column for alternatives:

Field Description
receiverList.receiver(n).email The receiver's email address, where n is between 0 and 5 for a maximum of 6 receivers.
Alternatively, you can use receiverList.receiver(n).accountId.
receiverList.receiver(n).amount Amount to send to each corresponding receiver

Chained Payments

For a chained payment, you must specify all required fields for a parallel payment and you must also specify the primary receiver.

Please read the Description column for alternatives:

Field Description
receiverList.receiver(n).email The receivers' email addresses, where n is between 0 and 5 for a total of one primary receiver and between one and 5 secondary receivers.
Alternatively, you can use receiverList.receiver(n).accountId.
receiverList.receiver(n).amount Amount to send to each corresponding receiver
receiverList.receiver(n).primary Set to true to indicate a chained payment; only one receiver can be a primary receiver. Omit this field, or set it to false for simple and parallel payments.

By default, a payment requires explicit approval, in which the sender must log in to PayPal. In that case, you are not required to specify the sender's email address. To initiate the approval process, you must redirect the sender to an authorization URL. For example:

https://www.paypal.com/cgi-bin/webscr?cmd=_ap-payment&paykey=value

The command is _ap-payment. You obtain the value of the paykey parameter from the payKey field in the Pay API response.

Note: For a pre-approval, the authorization redirect would be to:

https://www.sandbox.paypal.com/cgi-bin/webscr?cmd=_ap-preapproval&preapprovalkey=Your-preapproval-key

Implicit Payments

If you are the API caller and you specify your email address in the senderEmail field, PayPal sets the payment to be implicitly approved, without redirection to PayPal. (Alternatively, you can use sender.accountId.)

Field Description
senderEmail Sender's email address
sender.accountId 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.

Preapproved Payments

If the sender has set up a preapproval, you can use the preapproval to avoid explicit approval. In that case, you must specify values for the fields below.

Field Description
preapprovalKey Preapproval key for the approval set up between you and the sender
pin Sender's personal identification number, if one was specified when the sender agreed to the approval

Payments for Digital Goods

You handle payments for digital goods in the same way you handle payments for other goods and services, with the following exceptions:

  • To specify a payment for digital goods, you must specify DIGITALGOODS for each receiver in your receiver list; specify receiverList.receiver(n).paymentType=DIGITALGOODS for each receiver, where n identifies the receiver, starting with 0.
  • If you specify a payment for digital goods, you cannot specify a senderEmail address or include a funding constraint.
  • You must redirect the sender to the following PayPal URL to complete the payment for digital goods: https://www.paypal.com/webapps/adaptivepayment/flow/pay?paykey=...

Payment Notifications

Notifications are sent after a payment is executed, which follows approval of the payment by the sender if required:

  • PayPal sends an email to the sender and all receivers associated with a payment when the transfer is complete; you receive an email only if you are also the payment sender or receiver.
  • When the payment is complete, PayPal sends an IPN message to the URL specified in the ipnNotificationUrl field of the Pay request.

Additional Notes About the Pay API Operation

  1. In a parallel payment, a fund transfer to one receiver can occur before a fund transfer to another receiver. Therefore, set reverseAllParallelPaymentsOnError to true. In the event of an error, this setting guarantees that transfers to all receivers are reversed and all funds are returned to the sender. If reverseAllParallelPaymentsonError is disabled, completed transfers are not reversed and funds that have already been transferred are no longer available to the sender.
  2. You can specify your unique tracking ID in the trackingID field and use this value to obtain information about a payment or to request a refund. The tracking ID is provided for cases when you already maintain an ID that you want to associate with a payment. You can also track payments using the payKey.

  3. You can use the Pay API to make unilateral payments under limited circumstances. A unilateral payment is a payment that is made to a receiver who does not have a PayPal account. Unilateral payments can be used with simple or parallel payments that are implicit or preapproved. Unilateral payments are not designed to be used with chained payments or payments that require manual approval through the web flow.

    When you send a unilateral payment, you send a payment request that includes an email address for a receiver, and this email address is not linked to a registered PayPal account. The receiver receives an email notifying the receiver to create an account and claim the payment.

    PayPal holds a payment to a receiver whose email address is not yet registered or confirmed until the receiver creates a PayPal account and confirms the email address. If a refund specifies a receiver whose email address is not yet registered or confirmed, the payment to the receiver is canceled.

  4. For a guest payment, do not set the sender's email address or the preapproval key. Specifying the sender's email address prevents the sender from choosing the guest payment option. Implicit approval and preapproval options are not allowed. Each receiver of a guest payment must be a verified PayPal business or premier account holder.
  5. You can specify a value for either senderEmail or one of the SenderIdentifier fields. If you use SenderIdentifier to identify the sender, you can specify either sender.email or sender.accountId, or you can set sender.useCredentials to true. The sender.phone field is reserved for future use.
  6. Specify senderEmail or sender.email (or use sender.accountId) to set up a payment where the sender and the API caller are the same (implicit approval) or for a preapproved payment.
  7. If senderEmail or sender.email is specified in the request, the email address must be registered with paypal.com. If you do not include one of these fields in the payment request, the sender can either log in using an existing account that is not associated with a receiver or create a new account during the payment flow.

PayRequest Message

The PayRequest message contains the instructions required to make a payment.

PayRequest Fields

Field Description
actionType xs:string (Required) Whether the Pay request pays the receiver or whether the Pay request is set up to create a payment request, but not fulfill the payment until the ExecutePayment is called. Allowable values are:
  • 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 (Required) The URL to which the sender's browser is redirected if the sender cancels the approval for the payment after logging in to paypal.com to approve the payment. Specify the URL with the HTTP or HTTPS. Maximum length: 1024 characters
clientDetails common:ClientDetailsType (Optional) Information about the sender.
currencyCode xs:string (Required) The currency code. Allowable values are:
  • 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 (Optional) The payer of PayPal fees. Allowable values are:
  • 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)
fundingConstraint ap:FundingConstraint (Optional) Specifies a list of allowed funding types 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.
Note: FundingConstraint is unavailable to API callers with standard permission levels; for more information, refer to the section Adaptive Payments Service Permissions.
ipnNotificationUrl xs:string (Optional) The URL to which you want all IPN messages for this payment to be sent. Maximum length: 1024 characters
memo xs:string (Optional) A note associated with the payment (text, not HTML). Maximum length: 1000 characters, including newline characters
payKeyDuration

xs:duration (Optional) The duration for which the pay key returned by this request is valid. After this period, the pay key expires. If no pay key duration is supplied, it defaults to 3 hours. Valid values for this field are from 5 minutes to 30 days.

See the Duration Data Type section of the XSD Date and Time Data Types page for documentation of the xs:duration date type.

Note: Pay key duration begins at the time a PayRequest message is sent. Further, payment must be approved before the pay key expires.
Note: If you pass the payKeyDuration field and subsequently pass the returned pay key in a PaymentDetailsRequest message, the PaymentDetailsResponse message includes a field named payKeyExpirationDate. This value of this field is determined by the value passed in payKeyDuration.
pin xs:string (Optional) The sender's personal identification number, which was specified when the sender signed up for a preapproval.
preapprovalKey xs:string (Optional) The key associated with a preapproval for this payment. The preapproval key is required if this is a preapproved payment.
Note: The Preapproval API is unavailable to API callers with Standard permission levels.
receiverList ap:ReceiverList (Required) Information about the receivers of the payment.
requestenvelope common:RequestEnvelope (Required) Information common to each Method, such as the language in which an error message is returned.
returnUrl xs:string (Required) The URL to which the sender's browser is redirected after approving a payment on paypal.com. Specify the URL with the HTTP or HTTPS designator. Maximum length: 1024 characters
reverseAllParallelPaymentsOnError xs:boolean (Optional) Whether to reverse parallel payments if an error occurs with a payment. Allowable values are:
  • true — Each parallel payment is reversed if an error occurs
  • false — Only incomplete payments are reversed (default)
senderEmail xs:string (Optional) Sender's email address. Maximum length: 127 characters
sender ap:SenderIdentifier (Optional) Sender's identifying information; see sender.accountId, below.
sender.accountId xs:string (Optional) 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. You can specify a value for either senderEmail or one of the SenderIdentifier fields. If you use SenderIdentifier to identify the sender, you can specify either sender.email or sender.accountId, or you can set sender.useCredentials to true.
trackingId xs:string (Optional) A unique ID that you specify to track the payment.
Note: You are responsible for ensuring that the ID is unique. Maximum length: 127 characters

ClientDetails Fields

Field Description
applicationId xs:string (Optional) Your application's identification, such as the name of your application
customerId xs:string (Optional) Your ID for this sender Maximum length: 127 characters
customerType xs:string (Optional) Your identification of the type of customer Maximum length: 127 characters
deviceId xs:string (Optional) Sender's device ID, such as a mobile device's IMEI number or a web browser cookie. If a device ID was passed with the PayRequest, use the same ID here. Maximum length: 127 characters
geoLocation xs:string (Optional) Sender's geographic location Maximum length: 127 characters
ipAddress xs:string (Optional) Sender's IP address. If an IP addressed was passed with the PayRequest, use the same ID here.
model xs:string (Optional) A sub-identification of the application Maximum length: 127 characters
partnerName xs:string (Optional) Your organization's name or ID Maximum length: 127 characters

FundingConstraint Fields

Field Description
allowedFundingType ap:FundingTypeList (Optional) 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.
Note: FundingConstraint is unavailable to API callers with standard permission levels; for more information, refer to the section Adaptive Payments Service Permissions.
Note: To use iACH, omit this field and do not specify a funding source for the payment.

FundingTypeList Fields

Field Description
fundingTypeInfo ap:FundingTypeInfo (Optional) 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.
Note: FundingConstraint is unavailable to API callers with standard permission levels; for more information, refer to the section Adaptive Payments Service Permissions.

FundingTypeInfo Fields

Field Description
fundingType xs:string (Required) 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. Allowable values are:
  • ECHECK — Electronic check
  • BALANCE — PayPal account balance
  • CREDITCARD — Credit card
Note: ECHECK and CREDITCARD include BALANCE implicitly.
Note: FundingConstraint is unavailable to API callers with standard permission levels; for more information, refer to the section Adaptive Payments Service Permissions.

ReceiverList Fields

Field Description
receiver ap:Receiver (Required) Receiver is the party whose account is credited.

Receiver Fields

Field Description
amount xs:decimal (Required) Amount to be paid to the receiver.
email xs:string (Optional) Receiver's email address. This address can be unregistered with paypal.com. If so, a receiver cannot claim the payment until a PayPal account is linked to the email address. You can specify a value for an email address, for a phone number, or for an account ID. Maximum length: 127 characters
accountId xs:string (Optional) Contains 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.
invoiceId xs:string (Optional) The invoice number for the payment. This data in this field shows on the Transaction Details report. Maximum length: 127 characters
paymentType xs:string (Optional) The transaction type for the payment. Allowable values are:
  • 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.
Important: Personal payments are no longer available for new Adaptive Payments applications. In pre-existing Adaptive Payments applications, person-to-person payments are valid only for parallel payments that have the feesPayer field set to EACHRECEIVER or SENDER.
paymentSubType xs:string (Optional) The transaction subtype for the payment.
phone common:PhoneNumberType A type to specify the receiver's phone number. The PayRequest must pass either an email address or a phone number as the payment receiver.
primary xs:boolean (Optional) Whether this receiver is the primary receiver, which makes the payment a chained payment. You can specify at most one primary receiver. Omit this field for simple and parallel payments. Allowable values are:
  • true — Primary receiver
  • false — Secondary receiver (default)

PhoneNumberType Fields

Field Description
countryCode xs:string (Required) Telephone country code.
phoneNumber xs:string (Required) Telephone number.
extension xs:string (Optional) Telephone extension.

SenderIdentifier Fields

Field Description
useCredentials xs:boolean (Optional) If true, use credentials to identify the sender; default is false.

AccountIdentifier Fields

Field Description
email xs:string (Optional) Sender's email address. Maximum length: 127 characters
accountId xs:string (Optional) Contains 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. This account ID value can be specified instead of a PayPal email address. The character length (and limit) of the account ID value is 13 single-byte alphanumeric characters. For an example of how to specify the account ID value, see "Pay Examples Using NVP and CURL," below.
phone common:PhoneNumberType (Optional) Sender's phone number.

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.

PayResponse Message

The Pay response includes a key for identifying the payment. The Pay response also includes the status of the payment.

If a payment is complete, the Pay response includes transaction data, along with some data from the request, e.g. data about the sender. Examples of use cases in which a payment is complete are implicit payments and preapproved payments.

PayResponse Fields

Field Description
payKey xs:string Pay key token. Use this token in other Adaptive Payment APIs (such as the Refund method) to identify this payment. Note that unless you overrode the default duration via the payKeyDuration request parameter, the pay key is valid for 3 hours. Payment must be approved while the pay key is valid.
payErrorList xs:string 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 or, for a delayed chained payment, secondary receivers have not been paid
  • 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
  • PROCESSING — The payment is in progress
  • PENDING — The payment is awaiting processing
paymentInfoList ap:PaymentInfoList Contains transaction data for the payment. If a payment is complete, the Pay response includes transaction data, along with some data from the request, e.g. data about the sender. Examples of use cases in which a payment is complete are implicit payments and preapproved payments. If the execution of the payment has not yet completed, there are no transaction details returned.
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.
defaultFundingPlan ap:FundingPlan Default funding plan.
responseEnvelope common:responseEnvelope Common response information, including a timestamp and the response acknowledgment status.
warningDataList ap:WarningDataList Warning ID and message related to payments that may be in the pending state.

PaymentInfoList Fields

Fields Description
paymentInfo ap:PaymentInfo If the value in the paymentExecStatus output field is COMPLETED, the paymentInfo container includes transaction data, along with some data from the request, e.g. sender data that was specified in the Pay request. Examples of use cases in which a payment is complete are implicit payments and preapproved payments. If the value in the paymentExecStatus output field is other than COMPLETED, there are no transaction details returned.

PaymentInfo Fields

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

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.

PayErrorList Fields

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

FundingPlan Fields

Field Description
fundingPlanId xs:string ID for this funding plan.
fundingAmount common:CurrencyType Amount of available funding.
backupFundingSource ap:FundingSource Backup funding source.
senderFees common:CurrencyType Fees to be paid by the sender.
currencyConversion ap:CurrencyConversion The currency conversion associated with the funding plan.
charge ap:FundingPlanCharge The amount to be charged to this funding plan.

CurrencyType Fields

Field Description
amount xs:decimal The converted amount.
code xs:string The currency code for the converted amount. 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

FundingSource Fields

Field Description
lastFourOfAccountNumber xs:string Last 4 digits or characters in account number.
type xs:string Type of funding source, which is one of the following values:.
  • UNDEFINED
  • BALANCE
  • BANK_INSTANT
  • BANK_DELAYED
  • CREDITCARD
  • DEBITCARD
  • ACCOUNTS_RECEIVABLE
displayName xs:string Display name of funding source.
fundingSourceId xs:string Funding source ID.
allowed xs:boolean Whether the funding source is allowed for this payment:
  • true — You can use this funding source for the payment
  • false — You cannot use this funding source (default)

CurrencyConversion Fields

Field Description
from ap:CurrencyType The currency to be converted.
to ap:CurrencyType The currency resulting from the conversion.
exchangeRate xs:decimal The exchange rate for the from currency to the to currency.

FundingPlanCharge Fields

Field Description
charge common:CurrencyType Amount charged to funding source.
fundingSource ap:FundingSource Funding source being charged.

WarningDataLists Fields

Field Description
warningId xs:long ID corresponding to a service operation warning.
message xs:string Message corresponding to a service operation warning.

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.

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.

Pay Examples Using NVP and CURL

These examples all use the NVP format and with CURL calls to deliver an HTTP request to the PayPal sandbox endpoint.

Line breaks are provided for ease of reading. In practice, each CURL command is a single line; each request and response is a string without line breaks or extra whitespace.

Simple payment example

In this example, the sender pays $100 to a PayPal-registered receiver.

If the owner of the API credentials (that is, of X-PAYPAL-SECURITY-USERID, etc.) is the payment sender, the approval is implicit. Otherwise, a sender must explicitly approve the payment.

The payment status, identified in the paymentExecStatus output field, differs based on the type of approval required. In an implicit approval, the request is completed immediately. In an explicit approval, the request is created, but is completed only after the payment is approved.

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/Pay \
  -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 actionType=PAY \
  -d senderEmail=sender@domain \
  -d cancelUrl=https://example.com \
  -d currencyCode=USD \
  -d receiverList.receiver(0).email=receiver@domain \
  -d receiverList.receiver(0).amount=100.00 \
  -d requestEnvelope.errorLanguage=en_US \
  -d returnUrl=https://example.com

Response for an implicitly approved payment:

responseEnvelope.timestamp=2013-04-24T14%3A39%3A26.000-07%3A00
&responseEnvelope.ack=Success
&responseEnvelope.correlationId=34e44c0bdbed6
&responseEnvelope.build=5710123
&payKey=AP-54224401WG0931234
&paymentExecStatus=COMPLETED
&paymentInfoList.paymentInfo(0).transactionId=1F809595PU5211234
&paymentInfoList.paymentInfo(0).transactionStatus=COMPLETED
&paymentInfoList.paymentInfo(0).receiver.amount=100.00
&paymentInfoList.paymentInfo(0).receiver.email=receiver@domain
&paymentInfoList.paymentInfo(0).receiver.primary=false
&paymentInfoList.paymentInfo(0).receiver.accountId=7X2XKABC5Z1234
&paymentInfoList.paymentInfo(0).pendingRefund=false
&paymentInfoList.paymentInfo(0).senderTransactionId=5VA331617X3361234
&paymentInfoList.paymentInfo(0).senderTransactionStatus=COMPLETED
&sender.accountId=6VJKLRUABCDEF

Response for an explicitly approved payment:

responseEnvelope.timestamp=2013-04-25T14%3A39%3A26.000-07%3A00
&responseEnvelope.ack=Success
&responseEnvelope.correlationId=d615a365bed61
&responseEnvelope.build=5710123
&payKey=AP-3TY011106S4428730
&paymentExecStatus=CREATED

Note: You must redirect the sender to PayPal to complete the payment.

Example of specifying a sender's account ID

The accountId field contains 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. This account ID value can be specified instead of a PayPal email address.

Request

curl https://svcs.sandbox.paypal.com/AdaptivePayments/Pay \
  -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 actionType=PAY_PRIMARY \
  -d cancelUrl=https://example.com \
  -d returnUrl=https://example.com \
  -d currencyCode=USD \
  -d sender.accountId=JBG2L1234ABCD \
  -d receiverList.receiver(0).email=emailzero@site.com \
  -d receiverList.receiver(0).amount=10.00 \
  -d receiverList.receiver(0).primary=true \
  -d receiverList.receiver(1).email=email@site.com \
  -d receiverList.receiver(1).amount=1.00 \
  -d receiverList.receiver(1).primary=false \
  -d memo=example \
  -d requestEnvelope.errorLanguage=en_US \
  -d clientDetails.ipAddress=127.0.0.1 \
  -d clientDetails.deviceId=mydevice \
  -d clientDetails.applicationId=APP-1AB12310112341234

Parallel payment example

In this example, the sender makes a payment of $100 to a PayPal-registered receiver and $50 to another PayPal-registered receiver. If an error occurs, all funds are returned to the sender whether or not the funds were transferred to a receiver.

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/Pay \
  -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 actionType=PAY \
  -d cancelUrl=https://example.com \
  -d currencyCode=USD \
  -d feesPayer=EACHRECEIVER \
  -d memo=Parallel-payment-example \
  -d receiverList.receiver(0).amount=100.00 \
  -d receiverList.receiver(0).email=receiver1@domain \
  -d receiverList.receiver(0).primary=false \
  -d receiverList.receiver(1).amount=50.00 \
  -d receiverList.receiver(1).email=receiver2@domain \
  -d receiverList.receiver(1).primary=false \
  -d requestEnvelope.errorLanguage=en_US \
  -d returnUrl=https://example.com \
  -d reverseAllParallelPaymentsOnError=true \
  -d senderEmail=sender@domain

Response

responseEnvelope.timestamp=2009-07-13T12%3A34%3A29.316-07%3A00
&responseEnvelope.ack=Success
&responseEnvelope.correlationId=d615a365bed61
&responseEnvelope.build=DEV&payKey=AP-1CB41255YH2406602
&paymentExecStatus=CREATED

Chained payment example

In this example, the sender makes a payment of $100 to a PayPal-registered receiver who is identified as the primary receiver. This receiver sends $50 of the $100 to another PayPal-registered receiver.

Request

curl https://svcs.sandbox.paypal.com/AdaptivePayments/Pay \
  -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 actionType=PAY \
  -d cancelUrl=https://example.com \
  -d clientDetails.applicationId=fitnesse \
  -d clientDetails.ipAddress=127.0.0.1 \
  -d currencyCode=USD \
  -d feesPayer=EACHRECEIVER \
  -d memo=Parallel-payment-example \
  -d receiverList.receiver(0).amount=100.00 \
  -d receiverList.receiver(0).email=receiver1@domain \
  -d receiverList.receiver(0).primary=true \
  -d receiverList.receiver(1).amount=50.00 \
  -d receiverList.receiver(1).email=receiver2@domain \
  -d receiverList.receiver(1).primary=false \
  -d requestEnvelope.errorLanguage=en_US \
  -d returnUrl=https://example.com \
  -d senderEmail=sender@domain

Response

responseEnvelope.timestamp=2009-07-13T12%3A34%3A29.316-07%3A00
&responseEnvelope.ack=Success
&responseEnvelope.correlationId=d615a365bed61
&responseEnvelope.build=DEV
&payKey=AP-7AF63289GN043650D
&paymentExecStatus=CREATED

Preapproved payment example

In this example, the sender has a valid preapproval agreement with you and makes a payment of $100 to a PayPal-registered receiver and $50 to another PayPal-registered receiver. The payment is completed without the sender logging in to paypal.com.

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/Pay \
  -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 actionType=PAY \
  -d cancelUrl=https://example.com \
  -d currencyCode=USD \
  -d feesPayer=EACHRECEIVER \
  -d memo=Preapproval-payment-example \
  -d preapprovalKey=PA-9JR04288NR0519129 \
  -d receiverList.receiver(0).amount=100.00 \
  -d receiverList.receiver(0).email=receiver1@domain \
  -d receiverList.receiver(0).primary=false \
  -d receiverList.receiver(1).amount=50.00 \
  -d receiverList.receiver(1).email=receiver2@domain/em> \
  -d receiverList.receiver(1).primary=false \
  -d requestEnvelope.errorLanguage=en_US \
  -d returnUrl=https://example.com \
  -d reverseAllParallelPaymentsOnError=true \
  -d senderEmail=sender@domain

Response

responseEnvelope.timestamp=2009-07-13T12%3A34%3A29.316-07%3A00
&responseEnvelope.ack=Success
&responseEnvelope.correlationId=d615a365bed61
&responseEnvelope.build=DEV
&payKey=AP-42706441J12795911
&paymentExecStatus=COMPLETED

Digital goods payment

In this example, the sender makes a payment of $1 to a PayPal-registered receiver. The sender must explicitly approve the 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/Pay \
  -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 requestEnvelope.errorLanguage=en_US \
  -d actionType=PAY \
  -d receiverList.receiver(0).amount=1.00 \
  -d currencyCode=USD \
  -d feesPayer=EACHRECEIVER \
  -d memo=Simple payment example. \
  -d cancelUrl=https://example.com \
  -d returnUrl=https://example.com \
  -d ipnNotificationUrl=https://example.com/ipn \
  -d receiverList.receiver(0).paymentType=DIGITALGOODS

Response to a payment for digital goods:

responseEnvelope.timestamp=2009-07-13T12%3A34%3A29.316-07%3A00
&responseEnvelope.ack=Success
&responseEnvelope.correlationId=d615a365bed61
&responseEnvelope.build=DEV
&payKey=AP-3TY011106S4428730
&paymentExecStatus=CREATED

Note: You must redirect the sender to the following PayPal URL to complete the payment for digital goods: https://www.paypal.com/webapps/adaptivepayment/flow/pay? paykey=....

Pay Errors

Code Message Additional Information
500000 There is a system error  
520002 Internal error  
520003 User name/password is incorrect  
520003
  • The caller's credentials don't have permission for the fee payer <value>
  • The caller's credentials don't have permission for the payment type <value>
  • Authentication failed. API credentials are incorrect.
Since 1.6.0
520005 Merchant account is locked  
520006 This call is not defined in the database  
520009 The transaction cannot be completed as the sender has some important information missing on file.  
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 don't have permission to cancel this preapproval  
550001
  • You are not allowed to confirm the preapproval for this key
  • User is not allowed to perform this action.
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  
580001
  • Invalid request: both email and phone cannot be set <value> <value> <value>
  • Invalid request: neither email nor phone is set <value>
  • To use currency <value>, currency must be held by sender and all receivers
  • Invalid request: More than one field cannot be used to specify a sender
  • Invalid request: <value>
Since 1.6.0
580022 Your request was invalid. Check the parameter of the error to see which is invalid  
580022
  • Invalid request parameter: <value>
  • Invalid Request Parameter: institutionId with value <value>
  • The institution id <value> is not activated
  • The clientDetails parameter is missing
  • Invalid request parameter: payKey with value <value>
  • Invalid Phone Country Code <value>
  • Invalid Country Code <value> for Receiver
  • Invalid Receiver Phone Type <value> <value> <value>
  • Invalid Phone Format <value> <value>
  • Invalid Phone Number <value> <value>
  • Invalid Receiver Phone Number <value> <value>
  • Invalid Area or Exchange Code <value> <value>
  • <value> has already been set and cannot be set multiple times
  • Invalid request parameter: <value> with value <value>
  • Invalid request parameter: <value> <value> is invalid
  • Invalid request parameter: <value> <value> is duplicated
  • Invalid request parameter: <value> <value> cannot be negative or zero
  • Invalid request parameter: PayKeyDuration must be in the range 5 minutes through 30 days
 Since 1.6.0
580023 Invalid request  
580023
  • The fee payer <value> cannot be used if a primary receiver is specified
  • The fee payer <value> can only be used if a primary receiver is specified
  • The fee payer <value> must have exactly 2 receivers
  • The reverseAllParallelPaymentOnError field can be true only if a primary receiver is not specified
  • The fee payer <value> cannot be used if a preapproval key is specified
  • Invalid request: FundingType cannot be specified when PaymentSubType is specified
  • Your Application is not approved to use the PaymentSubType: <value>
  • Your Application is not approved to use the PaymentType: <value>
  • Invalid request parameter: PaymentType should be the same for all receivers <value>
  • Inconsistent request parameter for digital goods
  • Invalid request parameter: PaymentSubType should be the same for all receivers <value>
  • Invalid Request: RECEIVABLE cannot be used with other funding types
  • For chained payments, receivers must have premier or business accounts
Since 1.6.0
580027 The argument is unsupported  
580027
  • Currently the system does not accept the currency <value>
  • Unsupported country code <value>
  • Currently the system does not accept the currency <value>
  • The parameter is not supported
Since 1.6.0
580028 The URL <value> is malformed  
580029 Invalid request  
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  
589019 The preapproval key is invalid  
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