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:
|
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; specifyreceiverList.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 thePay
request.
Additional Notes About the Pay API Operation
- In a parallel payment, a fund transfer to one receiver can occur before a fund transfer to another receiver. Therefore, set
reverseAllParallelPaymentsOnError
totrue.
In the event of an error, this setting guarantees that transfers to all receivers are reversed and all funds are returned to the sender. IfreverseAllParallelPaymentsonError
is disabled, completed transfers are not reversed and funds that have already been transferred are no longer available to the sender. - 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 thepayKey
. -
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.
- 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.
- You can specify a value for either
senderEmail
or one of theSenderIdentifier
fields. If you useSenderIdentifier
to identify the sender, you can specify eithersender.email
orsender.accountId
, or you can setsender.useCredentials
totrue
. Thesender.phone
field is reserved for future use. - Specify
senderEmail
orsender.email
(or usesender.accountId
) to set up a payment where the sender and the API caller are the same (implicit approval) or for a preapproved payment. - If
senderEmail
orsender.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:
|
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:
|
feesPayer |
xs:string (Optional) The payer of PayPal fees. Allowable values are:
|
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:
|
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 |
See the Duration Data Type section of the XSD Date and Time Data Types page for documentation of the Note: Pay key duration begins at the time a
Note: If you pass the |
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
|
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:
|
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:
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:
|
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:
Note: Note:
|
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:
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 |
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:
|
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:
|
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:
|
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:
|
transactionId |
xs:string PayPal transaction ID for this payment to the specified receiver. |
transactionStatus |
xs:string PayPal transaction status. Value is:
|
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) |
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:
|
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:.
|
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:
|
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:
|
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. |
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. |
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 |
|
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 |
|
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 |
|
Since 1.6.0 |
580022 | Your request was invalid. Check the parameter of the error to see which is invalid | |
580022 |
|
Since 1.6.0 |
580023 | Invalid request | |
580023 |
|
Since 1.6.0 |
580027 | The argument is unsupported | |
580027 |
|
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 |