Adaptive Payments Developer Guide Last updated: August 7, 2012
Adaptive Payments Developer Guide Document Number: 10097.en_US-20120807 © 2010-2012 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other trademarks and brands are the property of their respective owners. The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc. Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A.
Contents What’s New? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 1.8.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 SenderIdentifier Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 TaxIdDetails Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Chapter 1 Introducing Adaptive Payments . . . . . . . . . . . . . . . 17 Adaptive Payments Actors and Objects . . . . . . . . . . . .
Contents Chapter 2 Getting Started . . . . . . . . . . . . . . . . . . . . . . . 65 Adaptive Payments API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65 API Operations Related to Payments . . . . . . . . . . . . . . . . . . . . . . . . . . 65 API Operations Related to Preapprovals . . . . . . . . . . . . . . . . . . . . . . . . 65 Other API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66 Adaptive Payments Endpoints . . . . . . . . . . . . . . . .
Contents PhoneNumberType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85 SenderIdentifier Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 AccountIdentifier Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 RequestEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 PayResponse Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86 PayResponse Fields . . . . . . . . . .
Contents PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121 FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122 ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122 ResponseEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123 PaymentDetails Examples Using NVP and CURL . . . . . . . . . . . . . . . . . . . . . .123 Payment Details Errors . . . . . . . . .
Contents PhoneNumberType Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . .145 ResponseEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146 PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146 FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147 ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148 ResponseEnvelope Fields . . . . . . . . . .
Contents PreapprovalResponse Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170 PreapprovalResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170 ResponseEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171 PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171 FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172 ErrorData Fields . . . . . . . . . . . .
Contents CancelPreapproval Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196 Chapter 11 ConvertCurrency API Operation . . . . . . . . . . . . . . 197 ConvertCurrencyRequest Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197 ConvertCurrencyRequest Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . .197 CurrencyType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .198 CurrencyList Fields . . . . . . . . . . . . . . . . . .
Contents PhoneNumberType Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . .225 ResponseEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225 PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .226 FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227 ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227 ResponseEnvelope Fields . . . . . . . . . .
Contents FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249 ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250 ResponseEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250 GetShippingAddresses Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251 Chapter 15 Adaptive Payment Commands and Redirects . . . . . . . 253 Adaptive Payment Commands. . . . . . . . . . . . . . . . .
Contents New InvoiceItem Structure for Version 1.6.0 . . . . . . . . . . . . . . . . . . . . . .269 New SenderOptions Structure for Version 1.6.0 . . . . . . . . . . . . . . . . . . . . .269 New SenderIdentifier Structure for Version 1.6.0 . . . . . . . . . . . . . . . . . . . .270 New AccountIdentifier Structure for Version 1.6.0 . . . . . . . . . . . . . . . . . . . .270 New ReceiverOptions Structure for Version 1.6.0 . . . . . . . . . . . . . . . . . . . .
Contents Adaptive Payments Developer Guide August 7, 2012 13
Contents 14 August 7, 2012 Adaptive Payments Developer Guide
What’s New? Adaptive Payments is intended for developers implementing payment solutions with PayPal’s Adaptive Payments API. Check out what’s new in the current release. 1.8.1 Features Version 1.8.1 of the Adaptive Payments API adds a new new fields related to tax ID details for Brazil (shown below). Also a new BANK_MANAGED_WITHDRAWAL value has been added to the paymentType field. NOT E : Changes to API operations are backward-compatible.
1.8.
1 Introducing Adaptive Payments The Adaptive Payments API enables you to send money in many different scenarios, from simple to complex. For example, you might build a small send money application for a social networking site or a robust payroll system. Adaptive Payments Actors and Objects Adaptive payments handles payments between a sender of a payment and one or more receivers of the payment.
Introducing Adaptive Payments Adaptive Payments Actors and Objects You are not required to be a receiver. For example, if you own a shopping cart, you are not required to receive payments directly. You can facilitate payments between the sender and receivers that provide the actual goods.
Introducing Adaptive Payments Simple, Parallel, and Chained Payments For example, you might use this configuration in a sales commission application that transfers funds owed for commissions from your account to the accounts of your sales force. Simple, Parallel, and Chained Payments Adaptive Payments provides several kinds of payment: simple, parallel, and chained payments. You create each kind of payment with the Pay API. Simple payments enable a sender to send a single payment to a single receiver.
Introducing Adaptive Payments Simple, Parallel, and Chained Payments Simple Payments Simple payments enable a sender to send a single payment to a single receiver. This is sometimes considered a traditional payment, such as a payment from a buyer to a seller. Scenarios involving simple payments might include the following scenarios: Buyer makes a payment on a merchant’s website. Buyer makes a single payment for a cart of items from the same merchant.
Introducing Adaptive Payments Simple, Parallel, and Chained Payments NOT E : This scenario is an example only and does not take PayPal fees into account. Chained Payments A chained payment is a payment from a sender that is indirectly split among multiple receivers. It is an extension of a typical payment from a sender to a receiver, in which a receiver, known as the primary receiver, passes part of the payment to other receivers, who are called secondary receivers.
Introducing Adaptive Payments Payment Approval In this example, the primary receiver receives $100 from the sender’s perspective. The primary receiver actually receives only $10 and passes a total of $90 to secondary receivers, Receiver 2 and Receiver 3. NOT E : This scenario is an example only and does not take PayPal fees into account. Delayed Chained Payments By default, payments to all receivers in a chained payment are immediate. However, you can choose to delay a payment to a secondary receiver.
Introducing Adaptive Payments Adaptive Payments Service Permissions Preapproved payments, in which a sender logs in to PayPal and sets up preapprovals that approve future payments or set up a preapproval during the embedded payment flow. The sender logs in to paypal.com once to set up the preapproval. After the sender agrees to the preapproval, specific approval is unnecessary.
Introducing Adaptive Payments Explicit Approval Payment Flow The following diagram shows the basic flow of control for a payment (such as payment for items in a shopping cart at a web store) that requires the sender to log in to paypal.com to approve the payment: The following items correspond to the circled numbers in the diagram: 1. Your site or device sends a Pay request to PayPal on behalf of a sender. 2. PayPal responds with a key that you use when you direct the sender to PayPal. 3.
Introducing Adaptive Payments Preapproved Payments Flow Preapproved Payments Flow Preapproved payments require the sender to log in to paypal.com to set up the payment agreement with a particular vendor. You control the interaction between your application and PayPal by specifying URLs for redirection in various situations. The sender logs in to paypal.
Introducing Adaptive Payments Preapproved Payments Flow 2. PayPal responds with a key, called a preapproval key, that you use when you direct the sender to PayPal, and once the preapproval has been established, whenever you automatically complete a payment on behalf of the sender. 3. You redirect your sender’s browser to PayPal. 4. After the sender logs in to paypal.com and sets up the preapproval, PayPal redirects the sender’s browser to a location you specify.
Introducing Adaptive Payments Implicit Approval Payments Flow Implicit Approval Payments Flow Implicit approval payments are payments where the sender and the API caller are using the same account. Because PayPal draws the funds for the payment from your own account, there is no approval necessary, and as such there is no visible flow for implicit approval payments.
Introducing Adaptive Payments Embedded Payments Embedded Payment Flow Presentations PayPal provides the following kinds of visual presentations for the embedded payment flow: 28 The payment flow can be embedded as a lightbox on your web page, which gives the impression that the payment is handled completely within your website: The payment flow can appear in a minibrowser window that appears in front of your web page, which does not require an IFRAME: August 7, 2012 Adaptive Payments Developer G
Introducing Adaptive Payments Embedded Payments The payment flow can be embedded as a lightbox in an IFRAME on your web page, which gives the impression that the payment is handled completely within your website: Adaptive Payments Developer Guide August 7, 2012 29
Introducing Adaptive Payments Embedded Payments You choose your preferred visual presentation when you invoke the embedded payment flow. In some cases, PayPal may override your choice to use a lightbox; for example, when the sender is required to log into PayPal for the initial payment.
Introducing Adaptive Payments Embedded Payments IM PORT AN T : Payments for digital goods must use the embedded payment flow. You cannot associate a preapproval for future payments or enable shipping addresses in a payment for digital goods.
Introducing Adaptive Payments Embedded Payments The IFRAME also allows the sender to sign up for a PayPal account or pay as a guest without logging in. NOT E : Guest checkout only provides the visual benefits of an embedded payment. It does not reduce the payment steps. After clicking Log In, PayPal displays a Log in to your PayPal account page in the minibrowser.
Introducing Adaptive Payments Embedded Payments The checkbox controls the remember me behavior for log in. This behavior allows the sender to skip the log in step in cases where there is little risk of the account being misused. IM PORT AN T : Opting in to the remember me behavior does not guarantee that the sender will not be asked to provide log in credentials.
Introducing Adaptive Payments Embedded Payments If the sender chooses Cancel, PayPal redirects the sender’s browser to the cancel URL specified in the Pay API operation’s request message.
Introducing Adaptive Payments Embedded Payments When the sender clicks Close, PayPal redirects the sender’s browser to the return URL specified in the Pay API operation’s request message. NOT E : You are responsible for closing the minibrowser after PayPal redirects to the page specified in either the return or cancel URL. PayPal provides a JavaScript function that you call to close a PayPal minibrowser or lightbox.
Introducing Adaptive Payments Embedded Payments The lightbox containing the confirmation would appear in your page as follows: 36 August 7, 2012 Adaptive Payments Developer Guide
Introducing Adaptive Payments Embedded Payments Preapprove Future Payments Checkbox You can add a Preapprove future payments checkbox to the sender’s embedded payment experience, which enables the sender to preapprove subsequent payments.
Introducing Adaptive Payments Embedded Payments If the payment sender checks the preapproval box, the confirmation page provides details about the preapproval: 38 August 7, 2012 Adaptive Payments Developer Guide
Introducing Adaptive Payments Embedded Payments NOT E : Unless there is an error with the payment itself, PayPal transfers the money regardless of whether the preapproval for future payments was successful. Shipping Address Information You can display and collect shipping address information. PayPal displays the default shipping address when you set senderOptions.
Introducing Adaptive Payments Embedded Payments The sender of a payment can select one of the available shipping addresses or add a new shipping address by selecting Add new shipping address from the Ship to: drop-down menu: Embedded Payment Experience To the sender of a payment, the embedded payment experience appears to be built into your website.
Introducing Adaptive Payments Embedded Payments IFRAME within the sender’s browser and as a pop-up mini-browser that appears in front of your website. Typically, the sender initiates a payment by clicking a button: PayPal responds to the JavaScript that initiates the flow.
Introducing Adaptive Payments Embedded Payments The checkbox controls the remember me behavior for log in. This behavior allows the sender to skip the log in step in cases where there is little risk of the account being misused. IM PORT AN T : Opting in to the remember me behavior does not guarantee that the sender will not be asked to provide log in credentials.
Introducing Adaptive Payments Embedded Payments If the sender chooses Cancel, PayPal redirects the sender’s browser to the cancel URL specified in the Pay API operation’s request message.
Introducing Adaptive Payments Embedded Payments When the sender clicks Close, PayPal redirects the sender’s browser to the return URL specified in the Pay API operation’s request message. NOT E : You are responsible for closing the minibrowser after PayPal redirects to the page specified in either the return or cancel URL. PayPal provides a JavaScript function that you call to close a PayPal minibrowser or lightbox.
Introducing Adaptive Payments Embedded Payments The lightbox containing the confirmation would appear in your page as follows: Adaptive Payments Developer Guide August 7, 2012 45
Introducing Adaptive Payments Embedded Payments The actions you take to launch the flow and close the lightbox are the same steps you take for the minibrowser. Preapprove Future Payments Checkbox You can add a Preapprove future payments checkbox to the sender’s embedded payment experience, which enables the sender to preapprove subsequent payments.
Introducing Adaptive Payments Embedded Payments If the payment sender checks the preapproval box, the confirmation page provides details about the preapproval: Adaptive Payments Developer Guide August 7, 2012 47
Introducing Adaptive Payments Embedded Payments NOT E : Unless there is an error with the payment itself, PayPal transfers the money regardless of whether the preapproval for future payments was successful. Embedded Preapproval Experience Adaptive Payments provides a preapproval experience using a mini-browser.You can invoke the embedded preapproval flow by passing the preapproval key. Here is an example : https://www.paypal.
Introducing Adaptive Payments Embedded Payments After signing in, the user is presented with a consent form that the user must agree to: Adaptive Payments Developer Guide August 7, 2012 49
Introducing Adaptive Payments Embedded Payments If the seller has enabled PIN code entry, after consenting to the agreement, the user is prompted to enter a PIN code by the seller: 50 August 7, 2012 Adaptive Payments Developer Guide
Introducing Adaptive Payments Embedded Payments Finally, the user is presented with a confirmation screen: Adaptive Payments Developer Guide August 7, 2012 51
Introducing Adaptive Payments Embedded Payments Shipping Address Selection You can display and collect shipping address information for a transaction with the embedded payment flow. PayPal displays the default shipping address when you set senderOptions.
Introducing Adaptive Payments Embedded Payments The sender of a payment can select one of the available shipping addresses or add a new shipping address by selecting Add new shipping address from the Ship to: drop-down menu: Adaptive Payments Developer Guide August 7, 2012 53
Introducing Adaptive Payments Embedded Payments After the sender of the payment clicks Pay, PayPal displays the selected shipping address on the Thank you for using PayPal page: 54 August 7, 2012 Adaptive Payments Developer Guide
Introducing Adaptive Payments Embedded Payments You can call the GetShippingAddresses API operation to obtain the selected shipping address for the transaction using the key assoicated with the payment. Setting Up Web Pages to Invoke the Embedded Payment Flow Using a Lightbox Use the JavaScript functions in https://www.paypalobjects.com/js/external/dg.js to set up and control the embedded payment flow. This example shows how to initiate the embedded payment flow after obtaining a payment key.
Introducing Adaptive Payments Embedded Payments 1. Call the Pay API operation to obtain a valid pay key. 2. Create your form or button. – You must include the pay key and redirect to https://www.paypal.com/webapps/adaptivepayment/flow/pay. – Optionally, include a preapproval key if you want to enable the selection of Preapproval for future payments – Specify that a lightbox opens in the PayPal-created IFRAME, PPDGFrame.
Introducing Adaptive Payments Embedded Payments Setting Up Web Pages to Invoke the Embedded Payment Flow Using a Minibrowser Use the JavaScript functions in https://www.paypalobjects.com/js/external/apdg.js to set up and control the embedded payment flow. This example shows how to initiate the embedded payment flow after obtaining a payment key. This example assumes that you obtain a payment key before initiating the flow and that the key does not change or expire before the sender completes the flow.
Introducing Adaptive Payments Embedded Payments 4. Create an embedded flow object and associate it with your payment form or button. After Completing This Task: The following minibrowser return script can be used to determine whether the payment successfully completed: PAYMENTDETAILS=$(wget --no-check-certificate \ --output-document=- \ --quiet \ --header="X-PAYPAL-SERVICE-VERSION: 1.0.0" \ --header="X-PAYPAL-SECURITY-USERID
Introducing Adaptive Payments Guest Payments 3. Redirect the payment sender’s browser to the embedded payment flow at https://www.paypal.com/webapps/adaptivepayment/flow/pay?paykey=... after obtaining the pay key. 4. After returning from the flow, call the GetShippingAddresses API operation to obtain the selected shipping address. Guest Payments Adaptive payments supports guest payments, which are payments using a sender’s credit card without logging into PayPal to complete the transaction.
Introducing Adaptive Payments Fee Payment Configuration NOT E : For European Union countries, only 10 guest payments are allowed per card. Fee Payment Configuration You can set up a payment transaction so that either the sender of a payment pays the fee or the receivers of a payment pay the fee.
Introducing Adaptive Payments Fee Payment Configuration primary receiver in a chained payment pays the entire fee or whether all receivers pay a portion of the fee. You can specify who pays these fees.
Introducing Adaptive Payments Fee Payment Configuration NOT E : The scenario above is an example only and is not representative of actual PayPal fees. Receiver Pays the Fee in a Parallel Payment If the receivers pay the fee in a parallel payment, each receiver pays a portion of the fee, based on their assessment. The following example shows the receivers paying the fees: NOT E : The scenario above is an example only and is not representative of actual PayPal fees.
Introducing Adaptive Payments Fee Payment Configuration In this example, the primary receiver, identified as the merchant, pays a fee for $20 received. Each of the other receivers also pay a fee on the amount each receives. NOT E : The scenario above is an example only and is not representative of actual PayPal fees. Primary Receiver Pays the Fee in a Chained Payment If only the primary receiver pays the fee in a chained payment, other receivers pay no fees.
Introducing Adaptive Payments Fee Payment Configuration NOT E : 64 The scenario above is an example only and is not representative of actual PayPal fees.
2 Getting Started These basic scenarios get you up and running quickly with the Adaptive Payments API. The sample code shows different combinations of requests with different bindings in various programming languages. Adaptive Payments API Operations Adaptive Payments provides API operations, enabling you to build an application that handles payments, preapprovals for payments, refunds, and additional operations related to payments.
Getting Started Adaptive Payments Endpoints Other API Operations API Operation Description Refund Refunds all or part of a payment ConvertCurrency Obtains the current foreign exchange (FX) rate for a specific amount and currency GetFundingPlans Determines the funding sources that are available for a specified payment GetAllowedFundingSources Obtains the funding sources associated with a preapproval.
Getting Started HTTP Headers For SOAP, you must also include a specific SOAP protocol header (see the SOAP messages section). The following is an example of HTTP headers for NVP in Java for a web implementation: headers.put("X-PAYPAL-SECURITY-USERID", "tok261_biz_api.abc.com"); headers.put("X-PAYPAL-SECURITY-PASSWORD","1244612379"); headers.put("X-PAYPAL-SECURITY-SIGNATURE","lkfg9groingghb4uw5" headers.put("X-PAYPAL-DEVICE-IPADDRESS", "168.212.226.204"); headers.
Getting Started HTTP Headers For SOAP messages, refer to the next section. HTTP Headers for JSON, NVP, and XML Data Formats Header Description X-PAYPAL-REQUEST-DATA-FORMAT The payload format for the request. Allowable values are: NV – Name-value pairs XML – Extensible markup language JSON – JavaScript object notation X-PAYPAL-RESPONSE-DATA-FORMAT The payload format for the response.
Getting Started Making a Simple Payment (JSON) HTTP Headers for Application and Device identification Header Description X-PAYPAL-APPLICATION-ID (Required) Your application’s identification, which is issued by PayPal. N O TE : Check X.com for which application ID must be defined for working in the sandbox. X-PAYPAL-DEVICE-ID (Optional) Client’s device ID, such as a mobile device’s IMEI number or a web browser cookie. X-PAYPAL-DEVICE-IPADDRESS (Required) Client’s IP address.
Getting Started Making a Parallel Payment (NVP) In this particular scenario, the paymentExecStatus variable is set to CREATED instead of COMPLETED, which indicates that the payment has been created, but has not yet been executed. Making a Parallel Payment (NVP) A parallel payment is when a sender (whose account is debited) sends a single payment (amount and currency) up to 6 receivers. The sender can see each payment to a receiver.
Getting Started Making a Chained Payment (XML) Making a Chained Payment (XML) A chained payment is when a sender sends a payment to a PayPal-registered receiver who is the primary receiver. You send a PayRequest, enabling the primary receiver. You receive a response with a pay key. You must redirect the sender’s browser to PayPal to approve the payment. With chained payments, the sender only sees the transaction to the primary API caller.
Getting Started Making a Chained Payment (XML) Pay Response for Chained Payment 2009-10-06T17:24:03.
3 Pay API Operation Use the Pay API operation to transfer funds from a sender’s PayPal account to one or more receivers’ PayPal accounts. You can use the Pay API operation to make simple payments, chained payments, or parallel payments; these payments can be explicitly approved, preapproved, or implicitly approved. Pay Summary Create your PayRequest message by setting the common fields.
Pay API Operation Pay Summary Field Description 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 values for the fields above.
Pay API Operation Pay Summary Implicit Payments If you are the API caller and you specify your email address in the senderEmail field, PayPal implicitly approves the payment without redirecting to PayPal: Field Description senderEmail Sender’s email address 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.
Pay API Operation Pay Summary 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. With parallel payments, fund transfers to some receivers may occur before others. 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.
Pay API Operation PayRequest Message PayRequest Message The PayRequest message contains the instructions required to make a payment.
Pay API Operation PayRequest Message 78 August 7, 2012 Adaptive Payments Developer Guide
Pay API Operation PayRequest Message 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.
Pay API Operation PayRequest Message Field Description currencyCode xs:string (Required) The currency code.
Pay API Operation PayRequest Message Field Description 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.
Pay API Operation PayRequest Message Field Description senderEmail xs:string (Optional) Sender’s email address. Maximum length: 127 characters sender ap:SenderIdentifier (Optional) Sender’s identifying information. trackingId xs:string (Optional) A unique ID that you specify to track the payment. N O TE : You are responsible for ensuring that the ID is unique.
Pay API Operation PayRequest Message Field Description 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.
Pay API Operation PayRequest Message 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.
Pay API Operation PayRequest Message Field Description paymentType xs:string (Optional) The transaction type for the payment.
Pay API Operation PayResponse Message 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 phone common:PhoneNumberType (Optional) Sender’s phone number.
Pay API Operation PayResponse Message Adaptive Payments Developer Guide August 7, 2012 87
Pay API Operation PayResponse Message 88 August 7, 2012 Adaptive Payments Developer Guide
Pay API Operation PayResponse Message Adaptive Payments Developer Guide August 7, 2012 89
Pay API Operation PayResponse Message PayResponse Fields 90 Field Description payKey xs:string The pay key, which is a token you use in other Adaptive Payment APIs (such as the Refund Method) to identify this payment. The pay key is valid for 3 hours; the 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.
Pay API Operation PayResponse Message 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.
Pay API Operation PayResponse Message Field Description code xs:string The currency code for the converted amount.
Pay API Operation PayResponse Message Field Description 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.
Pay API Operation PayResponse Message 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 94 Field Description category common:ErrorCategory The location where the error occurred.
Pay API Operation PayResponse Message Receiver Fields Field Description amount xs:decimal Amount to be paid to the receiver. email xs:string Receiver’s email address. Maximum length: 127 characters invoiceId xs:string The invoice number for the payment. This data in this field shows on the Transaction Details report. Maximum length: 127 characters paymentType xs:string The transaction type for the payment.
Pay API Operation PPFault Message Field Description phoneNumber xs:string Telephone number. extension xs:string Telephone extension. ResponseEnvelope Fields Field Description ack common:AckCode Acknowledgement code. It is one of the following values: 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.
Pay API Operation PPFault Message FaultMessage Fields Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status.
Pay API Operation PPFault Message ErrorData Fields Field Description category common:ErrorCategory The location where the error occurred. Possible values are: 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.
Pay API Operation Pay Examples Using NVP and CURL Field Description correlationId xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. N O TE : timestamp You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.
Pay API Operation Pay Examples Using NVP and CURL curl -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" https://svcs.sandbox.paypal.com/AdaptivePayments/Pay -d "requestEnvelope.errorLanguage=en_US &actionType=PAY &senderEmail=sender@domain &receiverList.receiver(0).
Pay API Operation Pay Examples Using NVP and CURL Request: curl -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" https://svcs.sandbox.paypal.
Pay API Operation Pay Examples Using NVP and CURL curl -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" https://svcs.sandbox.paypal.com/AdaptivePayments/Pay "actionType=PAY &cancelUrl=http://your_cancel_url &clientDetails.applicationId=fitnesse &clientDetails.ipAddress=127.0.0.
Pay API Operation Pay Examples Using NVP and CURL curl -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" https://svcs.sandbox.paypal.
Pay API Operation Pay Errors curl -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" https://svcs.sandbox.paypal.com/AdaptivePayments/Pay "requestEnvelope.errorLanguage=en_US &actionType=PAY &receiverList.receiver(0).amount=1.
Pay API Operation Pay Errors Code Message 520005 Merchant account is locked 520006 This call is not defined in the database 529038 There was an error while making this payment 539012 The preapproval key has not been authorized yet 539041 The email account is based in a country that is not enabled to receive payments 539043 The email account is based in a country that is not enabled to send payments 540031 You don't have permission to cancel this preapproval 550001 Additional Informati
Pay API Operation Pay Errors Code Message 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 e
Pay API Operation Pay Errors Code Message 580023 Invalid request 580023 580027 580027 Additional Information The fee payer cannot be used if a primary receiver is specified The fee payer can only be used if a primary receiver is specified The fee payer must have exactly 2 receivers The reverseAllParallelPaymentOnError field can be true only if a primary receiver is not specified The fee payer cannot be used if a preapproval key is specified
Pay API Operation Pay Errors 108 August 7, 2012 Adaptive Payments Developer Guide
4 PaymentDetails API Operation Use the PaymentDetails API operation to obtain information about a payment. You can identify the payment by your tracking ID, the PayPal transaction ID in an IPN message, or the pay key associated with the payment. PaymentDetailsRequest Message The PaymentDetailsRequest message contains the identifier used to retrieve information about the payment. PaymentDetailsRequest Fields The payKey, transactionId, and trackingId fields identify the payment.
PaymentDetails API Operation PaymentDetailsResponse Message Field Description transactionId xs:string (Optional) The PayPal transaction ID associated with the payment. The IPN message associated with the payment contains the transaction ID. trackingId xs:string (Optional) The tracking ID that was specified for this payment in the PayRequest message.
PaymentDetails API Operation PaymentDetailsResponse Message Adaptive Payments Developer Guide August 7, 2012 111
PaymentDetails API Operation PaymentDetailsResponse Message 112 August 7, 2012 Adaptive Payments Developer Guide
PaymentDetails API Operation PaymentDetailsResponse Message PaymentDetailsResponse Fields Field Description actionType xs:string Whether the Pay request is set up to create a payment request with the SetPaymentOptions request, and then fulfill the payment with the ExecutePayment request. Possible values are: PAY – Use this option if you are not using the Pay request in combination with ExecutePayment.
PaymentDetails API Operation PaymentDetailsResponse Message Field Description currencyCode xs:string The currency code.
PaymentDetails API Operation PaymentDetailsResponse Message Field Description fundingtypeList ap:FundingTypeList Specifies a list of allowed funding selections for the payment. This is a list of funding selections that can be combined in any order to allow payments to use the indicated funding type. If this Parameter is omitted, the payment can be funded by any funding type that is supported for Adaptive Payments.
PaymentDetails API Operation PaymentDetailsResponse Message Field Description status xs:string The status of the payment.
PaymentDetails API Operation PaymentDetailsResponse Message PaymentInfoList Fields Fields Description paymentInfo ap:PaymentInfo Represents the payment attempt made to a receiver of a PayRequest. If the execution of the payment has not yet completed, there are no transaction details returned. PaymentInfo Fields Field Description pendingReason xs:string The reason why a payment is pending. the payment has a pending refund.
PaymentDetails API Operation PaymentDetailsResponse Message Field Description 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.
PaymentDetails API Operation PaymentDetailsResponse Message Field Description email xs:string Receiver’s email address. Maximum length: 127 characters invoiceId xs:string The invoice number for the payment. This data in this field shows on the Transaction Details report. Maximum length: 127 characters paymentType xs:string The transaction type for the payment.
PaymentDetails API Operation PaymentDetailsResponse Message TaxIdDetails Fields Field Description taxId xs:string Tax ID of the Merchant (For Brazil only) taxIdType xs:string Type of the Tax ID. Either CPF or CNPJ (For Brazil only) AccountIdentifier Fields Field Description email xs:string Sender’s email address. Maximum length: 127 characters phone common:PhoneNumberType Sender’s phone number. PhoneNumberType Response Fields Field Description countryCode xs:string Telephone country code.
PaymentDetails API Operation PPFault Message Field Description 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. N O TE : timestamp You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues.
PaymentDetails API Operation PPFault Message FaultMessage Fields Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status. ErrorData Fields 122 Field Description category common:ErrorCategory The location where the error occurred.
PaymentDetails API Operation PaymentDetails Examples Using NVP and CURL Field Description severity common:ErrorSeverity The severity of the error encountered. Possible values are: 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 Acknowledgement code. It is one of the following values: Success – The operation completed successfully.
PaymentDetails API Operation PaymentDetails Examples Using NVP and CURL is a single line and each request and response is a string without line breaks or extra whitespace. Using the payment key to obtain payment details In this example, the caller of the Pay API operation specifies the payment key to obtain information about the entire payment: NOT E : The sample code below uses the insecure setting to work around the certificate for testing in a sandbox environment.
PaymentDetails API Operation Payment Details Errors Payment Details Errors Code Message 500000 There is a system error 520002 Internal error 520003 User name/password is incorrect 520003 Authentication failed. API credentials are incorrect.
PaymentDetails API Operation Payment Details Errors 126 August 7, 2012 Adaptive Payments Developer Guide
5 ExecutePayment API Operation The ExecutePayment API operation lets you execute a payment set up with the Pay API operation with the actionType CREATE. To pay receivers identified in the Pay call, set the pay key from the PayResponse message in the ExecutePaymentRequest message. ExecutePaymentRequest Message The ExecutePaymentRequest message lets you execute a payment requested using the Pay API operation.
ExecutePayment API Operation ExecutePaymentResponse Message 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.
ExecutePayment API Operation ExecutePaymentResponse Message Adaptive Payments Developer Guide August 7, 2012 129
ExecutePayment API Operation ExecutePaymentResponse Message ExecutePaymentResponse Fields Field Description payErrorList ap:PayErrorList Information about why a payment failed. paymentExecStatus xs:string The status of the payment.
ExecutePayment API Operation ExecutePaymentResponse Message ErrorData Fields Field Description category common:ErrorCategory The location where the error occurred. Possible values are: 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.
ExecutePayment API Operation ExecutePaymentResponse Message Field Description paymentType xs:string The transaction type for the payment.
ExecutePayment API Operation PPFault Message Field Description timestamp xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.774-07:00 N O TE : 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.
ExecutePayment API Operation PPFault Message FaultMessage Fields Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status. ErrorData Fields 134 Field Description category common:ErrorCategory The location where the error occurred.
ExecutePayment API Operation ExecutePayment Errors ResponseEnvelope Fields Field Description ack common:AckCode Acknowledgement code. It is one of the following values: 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.
ExecutePayment API Operation ExecutePayment Errors 136 Code Message Additional Information 539041 The email account is based in a country that is not enabled to receive payments 539043 The email account is based in a country that is not enabled to send payments 540031 You do not have permission to execute this payment 540031 You don't have permission to cancel this preapproval 540031 You do not have permission to execute this payment Operation is not permitted because the credentials do not ma
ExecutePayment API Operation ExecutePayment Errors Code Message 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
ExecutePayment API Operation ExecutePayment Errors 138 August 7, 2012 Adaptive Payments Developer Guide
6 GetPaymentOptions API Operation You use the GetPaymentOptions API operation to retrieve the payment options passed with the SetPaymentOptionsRequest. GetPaymentOptionsRequest Message GetPaymentOptionsRequest Fields Field Description payKey xs:string (Required) The pay key that identifies the payment for which you want to get payment options. This is the pay key you used to set the payment options.
GetPaymentOptions API Operation GetPaymentOptionsResponse Message Field Description 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.
GetPaymentOptions API Operation GetPaymentOptionsResponse Message GetPaymentOptionsResponse Fields Field Description payKey xs:string The pay key that identifies the payment for which you set payment options.
GetPaymentOptions API Operation GetPaymentOptionsResponse Message Field Description displayOptions ap:DisplayOptions Specifies display items in payment flows and emails. initiatingEntitity ap:InitiatingEntity The PayPal financial partner that is initiating the payment. Financial partners must first be set up in the Admin tool before they can use the PayPal APIs. shippingAddressId xs:string Sender’s shipping address ID.
GetPaymentOptions API Operation GetPaymentOptionsResponse Message InitiatingEntity Fields Field Description institutionCustomer ap:InstitutionCustomer (Optional) Details about the party that initiated this payment. This payment is made by the API caller on behalf of the initiating party. The initiating party can be an institution or a customer of the institution. The initiating party must be set up by PayPal Merchant Services.
GetPaymentOptions API Operation GetPaymentOptionsResponse Message SenderOptions Fields Field Description requireShippingAddressSe lection xs:boolean If true, require the sender to select a shipping address during the embedded payment flow; default is false. referrerCode xs:string A code that identifies the partner associated with this transaction. Maximum length: 32 characters. ReceiverOptions Fields Field Description description xs:string A description you want to associate with the payment.
GetPaymentOptions API Operation GetPaymentOptionsResponse Message InvoiceItem Fields Field Description name xs:string Name of item. identifier xs:string External reference to item or item ID. price xs:decimal Price of item. itemPrice xs:decimal Price of an individual item. itemCount xs:int Item quantity. ReceiverIdentifier Fields Field Description email xs:string Receiver’s email address. Maximum length: 127 characters phone common:PhoneNumberType Receiver’s phone number.
GetPaymentOptions API Operation PPFault Message ResponseEnvelope Fields Field Description ack common:AckCode Acknowledgement code. It is one of the following values: 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.
GetPaymentOptions API Operation PPFault Message FaultMessage Fields Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status.
GetPaymentOptions API Operation PPFault Message ErrorData Fields Field Description category common:ErrorCategory The location where the error occurred. Possible values are: 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.
GetPaymentOptions API Operation GetPaymentOptions Errors Field Description correlationId xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. N O TE : timestamp You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.
GetPaymentOptions API Operation GetPaymentOptions Errors 150 August 7, 2012 Adaptive Payments Developer Guide
7 SetPaymentOptions API Operation You use the SetPaymentOptions API operation to specify settings for a payment of the actionType CREATE. This actionType is specified in the PayRequest message.
SetPaymentOptions API Operation SetPaymentsOptionsRequest Message SetPaymentOptionsRequest Fields 152 Field Description payKey xs:string (Required) The pay key that identifies the payment for which you want to set payment options. This is the pay key returned in the PayResponse message. displayOptions ap:DisplayOptions (Optional) Specifies display items in payment flows and emails. initiatingEntity ap:InitiatingEntity (Optional) The PayPal financial partner that is initiating the payment.
SetPaymentOptions API Operation SetPaymentsOptionsRequest Message Field Description receiverOptions ap:ReceiverOptions (Optional) Specifies information about each receiver. requestEnvelope common:requestEnvelope (Required) Information common to each API operation, such as the language in which an error message is returned. DisplayOptions Fields Field Description emailHeaderImageUrl xs:string (Optional) The URL of the image that displays in the in the header of customer emails.
SetPaymentOptions API Operation SetPaymentsOptionsRequest Message Institution Customer Fields Field Description countryCode xs:string (Required) The two-character country code of the home country of the end consumer displayName xs:string (Required) The full name of the consumer as known by the institution. Maximum length: 200 characters email xs:string (Optional) The email address of the consumer as known by the institution.
SetPaymentOptions API Operation SetPaymentsOptionsRequest Message ReceiverOptions Fields Field Description description xs:string (Optional) A description you want to associate with the payment. This overrides the value of the memo in Pay API for each receiver. If this is not specified the value in the memo will be used. Maximum length: 1000 characters customId xs:string (Optional) An external reference or identifier you want to associate with the payment.
SetPaymentOptions API Operation SetPaymentsOptionsRequest Message Field Description itemPrice xs:decimal (Optional) Price of an individual item. itemCount xs:int (Optional) Item quantity. ReceiverIdentifier Fields Field Description email xs:string (Optional) Receiver’s email address. Maximum length: 127 characters phone common:PhoneNumberType (Optional) Receiver’s phone number. PhoneNumberType Fields Field Description countryCode xs:string (Required) Telephone country code.
SetPaymentOptions API Operation SetPaymentOptionsResponse Message SetPaymentOptionsResponse Message ResponseEnvelope Fields Field Description ack common:AckCode Acknowledgement code. It is one of the following values: 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.
SetPaymentOptions API Operation PPFault Message PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs. FaultMessage Fields 158 Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status.
SetPaymentOptions API Operation PPFault Message ErrorData Fields Field Description category common:ErrorCategory The location where the error occurred. Possible values are: 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.
SetPaymentOptions API Operation SetPaymentOptions Examples Using NVP and CURL Field Description correlationId xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. N O TE : timestamp You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues.
SetPaymentOptions API Operation SetPaymentOptions Errors curl -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" https://svcs.sandbox.paypal.com/AdaptivePayments/SetPaymentOptions -d "requestEnvelope.errorLanguage=en_US&receiverOptions[0].receiver.email=test @test.com &receiverOptions[0].
SetPaymentOptions API Operation SetPaymentOptions Errors Code 580022 Message 580027 580028 162 Additional Information Invalid request parameter: Invalid Request Parameter: institutionId with value The institution id is not activated The clientDetails parameter is missing Invalid request parameter: payKey with value Invalid Phone Country Code Invalid Country Code for Receiver Invalid Receiver Phone Type
8 Preapproval API Operation Use the Preapproval API operation to set up an agreement between yourself and a sender for making payments on the sender’s behalf. You set up a preapprovals for a specific maximum amount over a specific period of time and, optionally, by any of the following constraints: the number of payments, a maximum perpayment amount, a specific day of the week or the month, and whether or not a PIN is required for each payment request.
Preapproval API Operation PreapprovalRequest Message PayPal sends an email to the sender that confirmed the approval. PayPal sends an IPN message to the URL specified in the ipnNotificationUrl field of the Preapproval request. Additional Notes About the PreApproval API Operation 1.
Preapproval API Operation PreapprovalRequest Message PreapprovalRequest Fields Field Description cancelUrl xs:string (Required) The URL to which the sender’s browser is redirected after the sender cancels the preapproval at paypal.com. Maximum length: 1024 characters clientDetails common:ClientDetailsType (Required) Information about the sender.
Preapproval API Operation PreapprovalRequest Message Field Description currencyCode xs:string (Required) The currency code.
Preapproval API Operation PreapprovalRequest Message Field Description dayOfWeek common:DayOfWeek (Optional) The day of the week that a weekly payment is to be made. Allowable values are: NO_DAY_SPECIFIED SUNDAY MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY SATURDAY endingDate xs:dateTime (Optional) Last date for which the preapproval is valid. It cannot be later than one year from the starting date.
Preapproval API Operation PreapprovalRequest Message 168 Field Description paymentPeriod xs:string (Optional) The payment period. It is one of the following values: NO_PERIOD_SPECIFIED DAILY – Each day WEEKLY – Each week BIWEEKLY – Every other week SEMIMONTHLY – Twice a month MONTHLY – Each month ANNUALLY – Each year pinType xs:string (Optional) Whether a personal identification number (PIN) is required.
Preapproval API Operation PreapprovalRequest Message Field Description feesPayer xs:string (Optional) The payer of PayPal fees.
Preapproval API Operation PreapprovalResponse Message Field Description partnerName xs:string (Optional) Your organization’s name or ID Maximum length: 127 characters RequestEnvelope Fields Field Description detailLevel common:DetailLevelCode (Optional) Level of detail required by the client application pertaining to a particular data component. The detail level is specified as a detail level code, which has all the enumerated values of the detail level for the component.
Preapproval API Operation PPFault Message Field Description responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the acknowledgement status. ResponseEnvelope Fields Field Description ack common:AckCode Acknowledgement code. It is one of the following values: Success – The operation completed successfully. Failure – The operation failed. SuccessWithWarning – The operation completed successfully; however, there is a warning message.
Preapproval API Operation PPFault Message FaultMessage Fields 172 Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status.
Preapproval API Operation PPFault Message ErrorData Fields Field Description category common:ErrorCategory The location where the error occurred. Possible values are: 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.
Preapproval API Operation Preapproval Examples Using NVP and CURL Field Description correlationId xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. N O TE : timestamp You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.
Preapproval API Operation Preapproval Errors curl -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" https://svcs.sandbox.paypal.com/AdaptivePayments/Preapproval "cancelUrl=http://your_cancel_url ¤cyCode=USD &endingDate=2009-12-13T08%3A00%3A00.000Z &maxAmountPerPayment=200.
Preapproval API Operation Preapproval Errors 176 Code Message Additional Information 580001 Invalid request 580022 Account already exists 580024 The start date must be in the future 580025 The start date must be earlier than the end date 580027 The argument is unsupported 580028 The URL is malformed 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 Since 1.
9 PreapprovalDetails API Operation Use the PreapprovalDetails API operation to obtain information about an agreement between you and a sender for making payments on the sender’s behalf. PreapprovalDetailsRequest Message The PreapprovalDetailsRequest message specifies the key of the preapproval agreement whose details you want to obtain.
PreapprovalDetails API Operation PreapprovalDetailsResponse Message 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.
PreapprovalDetails API Operation PreapprovalDetailsResponse Message Adaptive Payments Developer Guide August 7, 2012 179
PreapprovalDetails API Operation PreapprovalDetailsResponse Message PreapprovalDetailsResponse Fields 180 Field Description addresslist ap:AddressList Returns a list of billing addresses. approved Whether the preapproval request was approved. Possible values are: true – The request was approved false – The request was denied cancelUrl The URL to which the sender’s browser is redirected if the sender decides to cancel the preapproval as requested.
PreapprovalDetails API Operation PreapprovalDetailsResponse Message Field Description currencyCode The currency code represented by the following values: Australian Dollar – AUD Brazilian Real – BRL N O TE : 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 N O TE : dateOfMonth Adaptive Payments Developer Guide The Rin
PreapprovalDetails API Operation PreapprovalDetailsResponse Message Field Description dayOfWeek The day of the week that a weekly payment is to be made. Possible values are: NO_DAY_SPECIFIED SUNDAY MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY SATURDAY endingDate Last date for which the preapproval is valid. Time is currently not supported. N O TE : 182 You must specify a value unless you have specific permission from PayPal to omit this value.
PreapprovalDetails API Operation PreapprovalDetailsResponse Message Field Description senderEmail Sender’s email address. If not specified, the email address of the sender who logs in to approve the request becomes the email address associated with the preapproval key. startingDate First date for which the preapproval is valid.
PreapprovalDetails API Operation PreapprovalDetailsResponse Message Field Description baseAddress common:BaseAddress Street address. addressId xs:string The ID associated with the address. BaseAddress Fields Field Description city xs:string The city of the address. countryCode xs:string The country code of the address. line1 xs:string The first line of the address. line2 xs:string An second line of the street address. postalCode xs:string The postal code of the address.
PreapprovalDetails API Operation PPFault Message Field Description correlationId xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. N O TE : timestamp You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.
PreapprovalDetails API Operation PPFault Message FaultMessage Fields Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status. ErrorData Fields 186 Field Description category common:ErrorCategory The location where the error occurred.
PreapprovalDetails API Operation PreapprovalDetails Examples Using NVP and CURL Field Description severity common:ErrorSeverity The severity of the error encountered. Possible values are: 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 Acknowledgement code. It is one of the following values: Success – The operation completed successfully.
PreapprovalDetails API Operation PreapprovalDetails Examples Using NVP and CURL command is a single line and each request and response is a string without line breaks or extra whitespace. Obtaining information about a preapproval In this example, the caller of the PreapprovalDetails API operation specifies a preapproval key. The result shows whether or not the status has been approved, which in this case is false because the person making the approval has not completed the process on PayPal.
PreapprovalDetails API Operation Preapproval Details Errors Preapproval Details Errors Code Message 500000 There is a system error 520002 Internal error 520003 User name/password is incorrect 520003 Authentication failed. API credentials are incorrect.
PreapprovalDetails API Operation Preapproval Details Errors 190 August 7, 2012 Adaptive Payments Developer Guide
10 CancelPreapproval API Operation Use the CancelPreapproval API operation to handle the canceling of preapprovals. Preapprovals can be canceled regardless of the state they are in, such as active, expired, deactivated, and previously canceled. CancelPreapprovalRequest Message The CancelPreapprovalRequest message specifies which preapproval is to be canceled by identifying the preapproval with its the preapproval key.
CancelPreapproval API Operation CancelPreapprovalResponse Message 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.
CancelPreapproval API Operation PPFault Message ResponseEnvelope Fields Field Description ack common:AckCode Acknowledgement code. It is one of the following values: 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.
CancelPreapproval API Operation PPFault Message FaultMessage Fields 194 Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status.
CancelPreapproval API Operation PPFault Message ErrorData Fields Field Description category common:ErrorCategory The location where the error occurred. Possible values are: 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.
CancelPreapproval API Operation CancelPreapproval Errors Field Description correlationId xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. N O TE : timestamp You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.
11 ConvertCurrency API Operation Use the ConvertCurrency API operation to obtain the estimated current foreign exchange (FX) rate for a specific amount and currency. This is an estimated rate, which may be different from the FX rate used at the time of the transaction. ConvertCurrencyRequest Message The ConvertCurrencyRequest message enables you to have your application get an estimated exchange rate for a list of amounts. This API operation does not affect PayPal balances.
ConvertCurrency API Operation ConvertCurrencyRequest Message Field Description baseAmountList ap:CurrencyList (Required) A list of amounts with associated currencies to be converted. convertToCurrencyList ap:CurrencyCodeList (Required) A list of currencies to convert to.
ConvertCurrency API Operation ConvertCurrencyRequest Message Field Description code xs:string (Required) The currency code.
ConvertCurrency API Operation ConvertCurrencyRequest Message CurrencyList Fields Field Description currency ap:CurrencyType (Required) The currency code.
ConvertCurrency API Operation ConvertCurrencyRequest Message CurrencyCodeList Fields Field Description currencyCode xs:string (Required) The currency code.
ConvertCurrency API Operation ConvertCurrencyResponse Message 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.
ConvertCurrency API Operation ConvertCurrencyResponse Message ConversionCurrencyResponse Fields Field Description estimatedAmountTable ap:CurrencyConversionTable A list of the requested amounts converted to the requested currencies. responseEnvelope common:responseEnvelope Information common to each API operation, such as the language in which an error message is returned.
ConvertCurrency API Operation ConvertCurrencyResponse Message CurrencyConversionList Fields Field Description baseAmount ap:CurrencyType The base amount and currency code. currencyList ap:CurrencyList The list of amounts converted to the requested currencies, and the currency codes. CurrencyType Fields 204 Field Description amount xs:decimal The converted amount.
ConvertCurrency API Operation ConvertCurrencyResponse Message Field Description code xs:string The currency code for the converted amount.
ConvertCurrency API Operation PPFault Message ResponseEnvelope Fields Field Description ack common:AckCode Acknowledgement code. It is one of the following values: 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.
ConvertCurrency API Operation PPFault Message FaultMessage Fields Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status.
ConvertCurrency API Operation PPFault Message ErrorData Fields Field Description category common:ErrorCategory The location where the error occurred. Possible values are: 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.
ConvertCurrency API Operation ConvertCurrency Errors Field Description correlationId xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. N O TE : timestamp You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.
ConvertCurrency API Operation ConvertCurrency Errors 210 August 7, 2012 Adaptive Payments Developer Guide
12 Refund API Operation Use the Refund API operation to refund all or part of a payment. You can specify the amount of the refund and identify the accounts to receive the refund by the payment key or tracking ID, and optionally, by transaction ID or the receivers of the original payment. Refund API Overview PayPal supports refunds made manually, via the PayPal account interface, or by means of the RefundTransaction API.
Refund API Operation Refund API Overview Common fields for all refunds Field Description currencyCode The currency code. You must specify the currency code that matches the currency code of the original payment unless you also specify the payment key. requestEnvelope.
Refund API Operation Refund API Overview Refunds that apply to a PayPal transaction associated with the payment Field Description transactionId A PayPal transaction ID associated with the receiver whose payment you want to refund to the sender. Use field name characters exactly as shown. Refund Notifications Notifications are sent after the refund is complete: PayPal sends an email to all PayPal account holders affected by the refund.
Refund API Operation RefundRequest Message 6. If the refund involves chained payments, PayPal first moves the money from the secondary receiver to the primary, refunding the secondary's share back to the primary. PayPal then attempts to refund the full amount from primary to buyer. At this point, if the primary receiver’s account still does not have sufficient funds to cover the refund, PayPal initiates a draft from the Primary's bank account to get enough money to complete the refund.
Refund API Operation RefundRequest Message RefundRequest Fields You must specify a value for only one of the following fields to identify the part of the payment to refund: payKey, transactionId, or trackingId.
Refund API Operation RefundRequest Message Field Description currencyCode (Required) The currency code. You must specify the currency code used for the original payment. You do not need to specify this field if you use a payKey to refund a complete transaction.
Refund API Operation RefundRequest Message Field Description receiverList ap:ReceiverList (Optional) Information about the receivers of the payment that you want to refund; the payment is identified by payment key, tracking ID, or transaction ID. Specify each receiver to whom you want to issue a refund. You can specify the refund amount for specific receivers.
Refund API Operation RefundRequest Message Field Description paymentSubType xs:string (Optional) This field is not used. phone common:PhoneNumberType (Optional) 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 this a refund for a chained payment. You can specify at most one primary receiver.
Refund API Operation Refund Response Message Refund Response Message The refundResponse message contains status information about a refund request.
Refund API Operation Refund Response Message 220 August 7, 2012 Adaptive Payments Developer Guide
Refund API Operation Refund Response Message RefundResponse Fields Field Description currencyCode The currency code represented by one of the following values: Australian Dollar – AUD Brazilian Real – BRL N O TE : 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 N O TE : The Ringgit is supported as a payment currency an
Refund API Operation Refund Response Message RefundInfoList Fields Field Description refundInfo ap:RefundInfo Represents the refund attempt made to a receiver of a PayRequest. RefundInfo Fields Field Description encryptedRefundTransacti onId xs:string The PayPal transaction ID for this refund. N O TE : errorList ap:ErrorList Information about why a refund failed. receiver ap:Receiver Information about the receiver of the refund.
Refund API Operation Refund Response Message Field Description refundStatus xs:string Status of the refund. It is one of the following values: REFUNDED – Refund successfully completed REFUNDED_PENDING – Refund awaiting transfer of funds; for example, a refund paid by eCheck. NOT_PAID – Payment was never made; therefore, it cannot be refunded. ALREADY_REVERSED_OR_REFUNDED – Request rejected because the refund was already made, or the payment was reversed prior to this request.
Refund API Operation Refund Response Message ErrorData Fields Field Description category common:ErrorCategory The location where the error occurred. Possible values are: 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.
Refund API Operation Refund Response Message Field Description paymentSubType xs:string This field is not used. phone common:PhoneNumberType The receiver’s phone number. primary xs:boolean Whether this receiver is the primary receiver, which makes this a refund for a chained payment. If this field is set to false, this is a refund for a simple or parallel payment.
Refund API Operation PPFault Message Field Description correlationId xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. N O TE : timestamp You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.
Refund API Operation PPFault Message FaultMessage Fields Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status. ErrorData Fields Field Description category common:ErrorCategory The location where the error occurred.
Refund API Operation PPFault Message Field Description severity common:ErrorSeverity The severity of the error encountered. Possible values are: 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 Acknowledgement code. It is one of the following values: Success – The operation completed successfully. Failure – The operation failed.
Refund API Operation Refund Examples Using NVP and CURL Refund Examples Using NVP and CURL These examples all use NVP for the data binding and CURL to deliver the HTTP request to the PayPal sandbox endpoint. Line breaks are provided for ease of reading; each CURL command is a single line and each request and response is a string without line breaks or extra whitespace. Using the payment key to refund an entire payment In this example, the caller of the Refund API operation specifies a payment key.
Refund API Operation Refund Errors responseEnvelope.timestamp=2009-08-14T09%3A00%3A37.748-07%3A00 &responseEnvelope.ack=Success &responseEnvelope.correlationId=7967b2d03745a &responseEnvelope.build=DEV ¤cyCode=USD &refundInfoList.refundInfo(0).receiver.amount=3.15 &refundInfoList.refundInfo(0).receiver.email=receiver1@domain &refundInfoList.refundInfo(0).refundStatus=REFUNDED &refundInfoList.refundInfo(0).refundNetAmount=2.81 &refundInfoList.refundInfo(0).refundFeeAmount=0.34 &refundInfoList.
Refund API Operation Refund Errors Code Message 560018 You cannot refund this type of transaction 570012 Cannot do a full refund after a partial refund 570013 The partial refund amount must be less than or equal to the original transaction amount 570014 The partial refund amount must be less than or equal to the remaining amount 570015 This transaction has already been fully refunded 570017 You are over the time limit to perform a refund on this transaction 579051 The tracking ID is invalid
Refund API Operation Refund Errors 232 August 7, 2012 Adaptive Payments Developer Guide
13 GetFundingPlans API Operation Use the GetFundingPlans API operation to determine the funding sources that are available for a specified payment, identified by its key, which takes into account the preferences and country of the receiver as well as the payment amount. You must be both the sender of the payment and the caller of this API operation.
GetFundingPlans API Operation GetFundingPlansResponse Message GetFundingPlansRequest Fields Field Description payKey xs:string (Required) The key used to create the payment whose funding sources you want to determine. requestEnvelope common:requestEnvelope (Required) Information common to each API operation, such as the language in which an error message is returned.
GetFundingPlans API Operation GetFundingPlansResponse Message Adaptive Payments Developer Guide August 7, 2012 235
GetFundingPlans API Operation GetFundingPlansResponse Message GetFundingPlansResponse Fields Field Description FundingPlan ap:FundingPlan One or more available funding sources for this payment. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status. FundingPlan Fields 236 Field Description fundingPlanId xs:string ID for this funding plan. fundingAmount common:CurrencyType Amount of available funding.
GetFundingPlans API Operation GetFundingPlansResponse Message Field Description 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.
GetFundingPlans API Operation GetFundingPlansResponse Message Field Description code xs:string The currency code for the converted amount.
GetFundingPlans API Operation GetFundingPlansResponse Message Field Description 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.
GetFundingPlans API Operation PPFault Message Field Description 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. N O TE : timestamp You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues.
GetFundingPlans API Operation PPFault Message FaultMessage Fields Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status. ErrorData Fields Field Description category common:ErrorCategory The location where the error occurred.
GetFundingPlans API Operation GetFundingPlan Errors Field Description severity common:ErrorSeverity The severity of the error encountered. Possible values are: 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 Acknowledgement code. It is one of the following values: Success – The operation completed successfully. Failure – The operation failed.
GetFundingPlans API Operation GetFundingPlan Errors Code Message Additional Information 520003 Authentication failed. API credentials are incorrect. Since 1.6.0 540031 Operation is not permitted because the credentials do not match those of the initial operation Since 1.6.0 User is not allowed to perform this action. You are not allowed to get the funding plans for this key You do not have permission to get these funding plan details Since 1.6.
GetFundingPlans API Operation GetFundingPlan Errors 244 August 7, 2012 Adaptive Payments Developer Guide
14 GetShippingAddresses API Operation Use the GetShippingAddresses API operation to obtain the selected shipping address. You must have created the payment payKey that identifies the account holder whose shipping address you want to obtain, or be the primary receiver of the payment or one of the parallel receivers of the payment. The shipping address is available only if it was provided during the embedded payment flow.
GetShippingAddresses API Operation GetShippingAddressesResponse Message 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.
GetShippingAddresses API Operation GetShippingAddressesResponse Message GetShippingAddressesResponse Fields Field Description selectedAddress ap:Address Any number of available shipping addresses. The first address selected in the embedded payment flow. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status. Address Fields Field Description addresseeName xs:string The name associated with the address.
GetShippingAddresses API Operation PPFault Message Field Description type xs:string. The type of address. ResponseEnvelope Fields Field Description ack common:AckCode Acknowledgement code. It is one of the following values: 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.
GetShippingAddresses API Operation PPFault Message FaultMessage Fields Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status.
GetShippingAddresses API Operation PPFault Message ErrorData Fields Field Description category common:ErrorCategory The location where the error occurred. Possible values are: 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.
GetShippingAddresses API Operation GetShippingAddresses Errors Field Description correlationId xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. N O TE : timestamp You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.
GetShippingAddresses API Operation GetShippingAddresses Errors 252 August 7, 2012 Adaptive Payments Developer Guide
15 Adaptive Payment Commands and Redirects The web flows associated with Adaptive Payments may require you to redirect a sender’s browser to PayPal. When you redirect to the webscr endpoint, you must send a command that identifies the flow and associated parameters, or in the case of the embedded payment flow, you must redirect to a specific endpoint for the flow. Adaptive Payment Commands When redirecting to https://www.paypal.com/webscr, you must specify a command that identifies the flow.
Adaptive Payment Commands and Redirects Embedded Payment Flow Redirect _ap-preapproval Command The sender can log in to paypal.com and approve a preapproval request when you redirect the sender’s browser to PayPal using the _ap-preapproval command. Redirect to PayPal using the _ap-preapproval command https://www.paypal.
Adaptive Payment Commands and Redirects Embedded Payment Flow Redirect JavaScript Functions for Embedded Payments You must include https://www.paypalobjects.com/js/external/dg.js for a lightbox or https://www.paypalobjects.com/js/external/apdg.js for a minibrowser on any page that invokes or terminates the embedded payment flow. The JavaScript functions in dg.js and apdg.js set up and control the PayPal login and payment experience. Function and Signature Description PAYPAL.apps.
Adaptive Payment Commands and Redirects Embedded Payment Flow Redirect 256 August 7, 2012 Adaptive Payments Developer Guide
16 Instant Payment Notifications PayPal sends an IPN message in response to a payment, a refund, creation of a preapproval, and cancellation of a preapproval. Your IPN message handler must be set up in the way described in the Instant Payment Notification Guide. Specifically, it must guard against spoofing and it must be able to handle duplicate messages, which can occur, for example, if your application is both the caller of the Pay API and a receiver of the payment.
Instant Payment Notifications Pay Message Variables 258 Variable Description status The status of the payment.
Instant Payment Notifications Pay Message Variables Variable Description transaction[n].status_fo r _sender_txn The transaction status, where [n] is a number from 0 to 5. For simple singlereceiver payments, this number will be 0. Numbers larger than 0 indicate the payment to a particular receiver in chained and parallel payments.
Instant Payment Notifications Preapproval Message Variables Variable Description fees_payer The payer of PayPal fees.
Instant Payment Notifications Preapproval Message Variables Variable Description current_total_amount_of_ all_payments The current total of payments made for this preapproval. current_period_attempts The current number of attempts this period for this preapproval. currencyCode The currency code.
Instant Payment Notifications Preapproval Message Variables 262 Variable Description day_of_week The day of the week that a weekly payment is to be made. Possible values are: NO_DAY_SPECIFIED SUNDAY MONDAY TUESDAY WEDNESDAY THURSDAY FRIDAY SATURDAY starting_date First date for which the preapproval is valid. ending_date Last date for which the preapproval is valid. Time is currently not supported.
Older Versions of the Adaptive Payments API Older versions of the Adaptive Payments API can still be used; however, PayPal recommends using the latest version whenever possible. Unless specifically specified, API operations default to the latest version. 1.8.0 Features Version 1.8.0 of the Adaptive Payments API introduces new API operation fields for Convert Currency and changes to JavaScript functions. NOT E : Changes to API operations are backward-compatible.
1.8.0 Features Changes to ConvertCurrencyRequest Fields for Version 1.8.0 Field Description conversionType xs:string (Optional) The conversion type allows you to determine the converted amounts for a PayPal user in different currency conversion scenarios. Possible values are: SENDER_SIDE – Pass this conversion type when you convert amounts for a PayPal user who is sending a payment in a different currency from what he/she holds in PayPal.
1.7.0 Features Minibrowser code
1.6.0 Features API Operation Description ConfirmPreapproval Confirms the specified preapproval Changes to PayRequest Fields for Version 1.6.0 Field Description sender New field: ap:SenderIdentifier (Optional) Sender’s identifying information. Changes to PayResponse Fields for Version 1.6.0 Field Description defaultFundingPlan New field: ap:FundingPlan Default funding plan. Changes to ExecutePaymentRequest Fields for Version 1.6.
1.6.0 Features Changes to SetPaymentOptionsRequest Fields for Version 1.6.0 Field Description shippingAddressId New field: xs:string (Optional) Sender’s shipping address ID. Changes to PreapprovalRequest Fields for Version 1.6.0 Field Description endingDate xs:dateTime (Optional) Last date for which the preapproval is valid. It cannot be later than one year from the starting date. You must specify a value unless you have specific permission from PayPal.
1.6.0 Features New CurrencyConversion Structure for Version 1.6.0 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. New InvoiceData Structure for Version 1.6.0 Field Description item ap:InvoiceItem (Optional) Any number of items associated with the payment. totalTax xs:decimal (Optional) Total tax associated with the payment.
1.6.0 Features New SenderIdentifier Structure for Version 1.6.0 Field Description useCredentials xs:boolean (Optional) If true, use credentials to identify the sender; default is false. New AccountIdentifier Structure for Version 1.6.0 Field Description email xs:string (Optional) Sender’s email address. Maximum length: 127 characters phone common:PhoneNumberType (Optional) Sender’s phone number. New ReceiverOptions Structure for Version 1.6.
1.6.0 Features Additional Error Messages for Version 1.6.0 Code Message 520003 Authentication failed. API credentials are incorrect. 520003 The caller’s credential doesn't have permission for the fee payer The caller's credential doesn't have permission for the payment type Authentication failed. API credentials are incorrect.
1.6.
1.5.
1.4.0 Features PaymentDetails Pending Reason Feature in Version 1.5.0 The PaymentDetailsResponse now returns the new pendingReason parameter. This parameter returns a string describing the reason why a transaction is pending. Possible values are: ADDRESS_CONFIRMATION – The payment is pending because the sender does not have a confirmed address on file and receiver's Payment Receiving Preferences is set for manually accepting payments or denying each of these payments.
1.4.0 Features New API Operation Description GetPaymentOptions Retrieve payment settings specified with the SetPaymentOptions API operation. SetPaymentOptions Set payment options to be executed with the ExecutePayment API operation.
1.4.0 Features Changes to the Pay API Operation Changes to PayRequest and PayResponse Message Field Description actionType New CREATE value: PAY – Use this option if you are not using the Pay request in combinations with the ExecutePayment request. CREATE – Use this option to set up the payment instructions with the Pay request and then execute the payment at a later time with the ExecutePayment request. paymentType New person-to-person values PERSONAL and CASHADVANCE.
1.4.0 Features Field Description paymentType New person-to-person values PERSONAL and CASHADVANCE.
1.4.0 Features Changes to the PreapprovalDetails API Operation Changes to PreapprovalDetailsRequest Message Field Description getBillingAddress New field: xs:boolean (Optional) An option that lets you retrieve a list of billing addresses for the sender. Allowable values are: true – Includes the billing address in the response false – Omits the billing address from the response (default) N O TE : This field is available only to API callers with advanced permission levels.
1.3.0 Features Field Description BaseAddress.state xs:string The state for the billing address BaseAddress.type xs:string The type of billing address. Possible values are: BILLING – This is a billing address Changes to the Refund API Operation Changes to RefundRequest and RefundResponse Message Field Description Receiver.PhoneNumberType New field: common:PhoneNumberType Allows you to pass a receiver’s phone number, including the country code and extension.
1.3.0 Features current Foreign Exchange rate. For more information, refer to the ConvertCurrenty API Operation section. Payments to unregistered PayPal email addresses With the Adaptive Payments Pay API operation, you can make payments to a person who does not have a PayPal account. In essence, you can send a payment request that includes an email address for a receiver in which the receiver’s email address is not linked to a registered PayPal account.
1.3.0 Features Changes to the Pay API Operation for Version 1.3.0 Changes to PayRequest Message Field Description ClientDetails.applicationId This field is no longer required. The application ID is passed in a new HTTP header. For information, refer to the Specifying Application and Device Information section. ClientDetails.ipAddress This field is no longer required. fundingConstraint New field: ap:FundingConstraint Specifies a list of allowed funding types for the payment.
1.3.0 Features 282 Field Description Receiver.email xs:string In this release, the receiver’s email address does not need to be registered with paypal.com. If so, the receiver cannot claim the payment until a PayPal account has been created for the email address. senderEmail xs:string In previous releases, this field required the email address to be registered with paypal.com. In the 1.3.0 release, you have the option to omit the field from the payment request.
1.3.0 Features Changes to the PaymentDetails API Operation for Version 1.3.0 Changes to PaymentDetailsResponse messages Field Description fundingConstraint New field: ap:FundingConstraint Specifies a list of allowed funding types for the payment. This list can be in any order. If this field is omitted, the payment can be funded by any funding type that is supported by Adaptive Payments. N O TE : FundingTypeList.
1.2.0 Features Field Description PaymentInfo.senderTransactionStatus xs:string The status of the sender of the payment. For previous releases, the response included only information about the receiver portion of the transaction. With 1.3.0, the response includes information about the sender portion of the transaction. This feature accommodates payments to a receiver’s email address that is not linked to a registered PayPal account. 1.2.0 Features Version 1.2.
1.2.0 Features Changes to the Pay API Operation for Version 1.2.0 Changes to PayRequest messages Field Description ClientDetails.deviceID This field is now optional; it is no longer required. Receiver.invoiceId New field: xs:string (Optional) The invoice number for the payment Changes to PayResponse message Field Description Receiver.invoiceID New field: xs:string The invoice number for the payment Changes to the Payment Details API Operation for Version 1.2.
1.1.0 Features Changes to Preapproval API Operation for Version 1.2.0 Changes to PreapprovalRequest messages Field Description ipnNotificationUrl New field: xs:string (Optional) The URL to which you want all IPN messages for this preapproval to be sent. This URL supersedes the IPN notification URL in your profile. memo New field: xs:string (Required) A note about the preapproval. ClientDetails.deviceID This field is now optional; it is no longer required.
1.1.0 Features Changes to the Pay API Operation for Version 1.1.0 Changes to PayRequest message Field Description logDefaultShippingAddres s New field: xs:boolean (Optional) Whether or not to associate the receiver's default shipping address with the transaction. clientDetails.deviceId This field is now optional; it is no longer required. Changes to PayResponse message Field Description payErrorList New field: ap:PayErrorList Information about why a payment failed.
1.1.
1.1.0 Features Changes to Preapproval API Operation for Version 1.1.0 Changes to PreapprovalRequest message Field Description maxNumberOfPayments This field is now optional; it is no longer required. senderEmail This field is now optional; it is no longer required. If not specified, the email address of the sender who logs in to approve the request becomes the email address associated with the preapproval key. clientDetails.deviceId This field is now optional; it is no longer required.
1.1.0 Features Changes to RefundResponse message Field Description refundInfoList.refundInf o.errorList New field: xs:string Information about why a refund failed.
Revision History The revision history identifies changes to Adaptive Payments documentation at a high level. Date Description 08/07/2012 Added new fields related to Brazil tax ID to SenderIdentifer. Added new BANK_MANAGED_WITHDRAWAL value to paymentType field. 05/02/2012 Maintenance release. Added information about Embedded Preapproval Experience. 02/07/2012 Added reffererCode to SenderOptions. 11/16/2011 Revised draft for version 1.8.0.
August 7, 2012 Adaptive Payments Developer Guide
Index Symbols _ap-payment flow command 253 _ap-preapproval flow command 254 A ack response field 96, 98, 120, 123, 132, 135, 146, 148, 157, 159, 171, 173, 184, 187, 193, 195, 206, 208, 225, 228, 239, 242, 248, 250 action_type IPN variable 258 actionType request field 79 actionType response field 113 Address response fields 183, 247 addresseeName response field 183, 247 addressId response field 184, 247 AddressList response field 183 addresslist response field 180 AddressList response fields 183 allowed re
Index currencyConversionList response field 203 CurrencyConversionList response fields 204 CurrencyConversionTable response fields 203 CurrencyList request fields 200 currencyList response field 204 CurrencyList response fields 205 CurrencyType request fields 198 CurrencyType response fields 91, 204, 237 current_number_of_payments IPN variable 260 current_period_attempts IPN variable 261 current_total_amount_of_all_payments IPN variable 261 customId request field 155 customId response field 144 D dateOfMo
Index FundingTypeInfo request fields 84 fundingTypeInfo response field 116 FundingTypeInfo response fields 116 FundingTypeList request fields 83 fundingtypeList response field 115 FundingTypeList response fields 116 G getBillingAddress request field 177 GetFundingPlans API operation 233 GetFundingPlansRequest fields 234 GetFundingPlansRequest message 233 GetFundingPlansResponse fields 236 GetFundingPlansResponse message 234 GetPaymentOptions API operation 139 GetPaymentOptionsRequest fields 139 GetPayment
Index N name request field 155 name response field 145 P parameter field 94, 98, 122, 131, 134, 148, 159, 173, 186, 195, 208, 224, 227, 241, 250 Pay API operation 73 Pay Message variables 257 pay_key IPN variable 259 payError response field 91, 130 PayError response fields 94, 130 payErrorList response field 90, 130 PayErrorList response fields 91, 130 payKey request field 127, 139, 152, 216, 234 payKey response field 90, 115, 141 payment_request_date IPN variable 258 PaymentDetails API operation 109 Paym
Index refundTransactionStatus response field 223 req uestenvelope request field 81 requestEnvelope request field 127, 139, 153, 177, 191, 198, 217, 234, 245 RequestEnvelope request fields 86, 110, 128, 139, 156, 170, 178, 192, 202, 218, 234, 246 requestEnvelope request fields 168 requestEnvelope response field 142 requireShippingAddressSelection request field 154, 263 requireShippingAddressSelection response field 144 responseEnvelope PPFault field 97, 122, 134, 147, 158, 172, 186, 194, 207, 227, 241, 249
Index U useCredentials request field 86 useCredentials response field 15, 119, 120 298 August 7, 2012 Adaptive Payments Developer Guide
