Older Versions of the Adaptive Payments API

Important: Adaptive Payments is now a limited release product. It is restricted to select partners for approved use cases and should not be used for new integrations without guidance from PayPal.

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.

Contents

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.

Note: Changes to API operations are backward-compatible.

Changes to SenderOptions

The change to SenderOptions request fields corresponds to version 85.0 of the PayPal API:

Field Description
referrerCode New field. xs:string (Optional) A code that identifies the partner associated with this transaction. Maximum length: 32 characters.

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. Value is:
  • 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.
  • RECEIVER_SIDE — Pass this conversion type when you when you convert amounts for a PayPal user who is accepting a payment in a currency that he/she does not hold and who wants to convert the received payment.
  • BALANCE_TRANSFER — Pass this conversion type when you convert amounts for a PayPal user who is converting a balance in one currency to a balance in a different currency on his/her profile.
countryCode xs:string (Optional)The two-character ISO code for the country where the function is supposed to happen. The default value is US.

Changes to 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 mini-browser, on any page that invokes or terminates the embedded payment flow.

For information about how to use the lightbox and mini-browser options, see How to Create an Embedded Payment Flow Using Adaptive Payments.

New JavaScript Function for Version 1.8.0: AutoRedirectOnDone

After the payment sender using a Merchant site completes a transaction, the Thank you for using PayPal page appears, also known as the "Done" page. Previously, from within this page, the Merchant allowed the sender to close the page or to navigate back to a Merchant-specified URL by clicking a button. Now, by using the AutoRedirectOnDone option, the Merchant can automatically redirect the sender from the Thank you for using PayPal page to a specified URL, which opens after a waiting period of about five seconds. The following code sample shows how this optional function would be implemented in a mini-browser, a lightbox, or an iframe.

Note: Do not supply a value for autoredirectondone. You do not necessarily have to use the button images provided in the sample code.

mini-browser code

<form id="mini-form" action="https://www.paypal.com/webapps/adaptivepayment/flow/pay" target="PPDGFrame">
  <fieldset>
    <legend>Pay - Mini Browser</legend>
    <input type="hidden" name="expType" value="mini">
    <input type="hidden" name="autoredirectondone">
    <label for="paykey">PayKey</label>
    <input type="text" id="paykey" name="payKey" size="25">
    <input type="image" id="mini-browserBtn" value="Pay with PayPal mini" src="https://www.paypal.com/en_US/i/btn/x-click-but06.gif">
  </fieldset>
</form>
<form id="lightbox-form" action="https://www.paypal.com/webapps/adaptivepayment/flow/pay" target="PPDGFrame">
  <fieldset>
    <legend>Pay - Lightbox</legend>
    <input type="hidden" name="expType" value="lightbox">
    <input type="hidden" name="autoredirectondone">
    <label for="paykey">PayKey</label>
    <input type="text" id="paykey" name="payKey" size="25">
    <input type="submit" id="submitBtn" value="Pay with light" src="https://www.paypal.com/en_US/i/btn/x-click-but06.gif">
  </fieldset>
</form>

iFrame Code

<iframe id="PPDGFrame" name="PPDGFrame" scrolling="no" frameborder="0" allowtransparency="true" src="https://www.paypal.com/webapps/adaptivepayment/flow/pay?expType=light&amp;paykey=<AP-SAMPLEPAYKEY>&amp;
autoredirectondone=">
</iframe>

1.7.0 Features

Version 1.7.0 of the Adaptive Payments API introduces a new API operation and changes several Adaptive Payments API operations for mobile providers.

Note: Changes to API operations are backward-compatible.

New API Operations for Version 1.7.0

API Operation Description
GetAllowedFundingSources Determines the funding sources associated with a preapproval.

Changes to ConfirmPreapprovalRequest Fields for Version 1.7.0

Field Description
fundingSourceId New field: xs:string (Optional) Funding source ID.

Changes to 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 mini-browser, on any page that invokes or terminates the embedded payment flow.

For information about how to use the lightbox and mini-browser options, see How to Create an Embedded Payment Flow Using Adaptive Payments.

1.6.0 Features

Version 1.6.0 of the Adaptive Payments API introduces new API operations, as well as changes to several Adaptive Payments API operations and additional error messages.

Note: Changes to API operations are backward-compatible.

New API Operations for Version 1.6.0

API Operation Description
GetFundingPlans Determines the funding sources that are available for a specified payment
GetShippingAddresses Obtains the selected shipping address
GetAvailableShippingAddresses Obtains available shipping addresses
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.0

Field Description
fundingPlanId New field: xs:string (Optional) The ID of the funding plan from which to make this payment.

Changes to GetPaymentOptionsResponse Fields for Version 1.6.0

Field Description
shippingAddressId New field: xs:string Sender's shipping address ID.

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.
maxNumberOfPaymentsPerPeriod xs:int (Optional) The preapproved maximum number of all payments per period. You must specify a value unless you have specific permission from PayPal.

Changes to Address Structure for Version 1.6.0

Field Description
addressId New field: xs:string The ID associated with the address.

Changes to DisplayOptions Structure for Version 1.6.0

Field Description
headerImageUrl New field: xs:string (Optional) The URL of the image that displays in the header of a payment page. If set, it overrides the header image URL specified in your account's Profile. The image dimensions are 750 pixels high x 90 pixels wide.
businessName New field: xs:string (Optional) The business name to display.

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.
totalShipping xs:decimal (Optional) Total shipping charge associated with the payment.

New InvoiceItem Structure for Version 1.6.0

Field Description
name xs:string (Optional) Name of item.
identifier xs:string (Optional) External reference to item or item ID.
price xs:decimal (Optional) Price of item.

New SenderOptions Structure for Version 1.6.0

Field Description
requireShippingAddressSelection xs:boolean (Optional) If true, require the sender to select a shipping address during the payment flow; default is false.

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.0

Field Description
description xs:string (Optional) A description you want to associate with the payment.
customId xs:string (Optional) An external reference or identifier you want to associate with the payment.
invoiceData ap:InvoiceData (Optional) Item information for the payment, which could appear on an invoice.
receiver ap:ReceiverIdentifier (Optional) Receiver ID associated with these options.

New ReceiverIdentifier Structure for Version 1.6.0

Field Description
base common:AccountIdentifier Account identifier.

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 <value>
  • The caller's credential doesn't have permission for the payment type <value>
  • Authentication failed. API credentials are incorrect.
540031 You do not have permission to execute this payment Operation is not permitted because the credentials do not match those of the initial operation
540031 You do not have permission to get these preapproval details
540031 You do not have permission to get these payment options Operation is not permitted because the credentials do not match those of the initial operation
540031 You do not have permission to set these payment options Operation is not permitted because the credentials do not match those of the initial operation
540031 Operation is not permitted because the credentials do not match those of the initial operation
540031 You do not have permission to get these payment details
550001
  • You are not allowed to confirm the preapproval for this key
  • User is not allowed to perform this action.
550001 You do not have permission to execute this payment implicitly
550001
  • 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
550001
  • User is not allowed to perform this action.
  • You are not allowed to get the addresses for this key
580001
  • Invalid request: both email and phone cannot be set <value> <value> <value>
  • Invalid request: neither email nor phone is set <value>
  • To use currency <value>, currency must be held by sender and all receivers
  • Invalid request: More than one field cannot be used to specify a sender
  • Invalid request: <value>
580001 Invalid request: <value>
580022
  • Invalid request parameter: <value>
  • The clientDetails parameter is missing
  • The PIN is invalid
580022
  • Invalid request parameter: <value>
  • The clientDetails parameter is missing
  • Invalid request parameter: payKey with value <value>
  • payKey <value> is expired
  • Invalid request parameter: <value> with <value>
  • No sender is associated with this key
  • The funding plan data is not present
  • payKey <value> has already been used to make a payment
580022
  • Invalid request parameter: <value>
  • Invalid Request Parameter: institutionId with value <value>
  • The institution id <value> is not activated
  • The clientDetails parameter is missing
  • Invalid request parameter: payKey with value <value>
  • Invalid Phone Country Code <value>
  • Invalid Country Code <value> for Receiver
  • Invalid Receiver Phone Type <value> <value> <value>
  • Invalid Phone Format <value> <value>
  • Invalid Phone Number <value> <value>
  • Invalid Receiver Phone Number <value> <value>
  • Invalid Area or Exchange Code <value> <value>
  • <value> has already been set and cannot be set multiple times
  • Invalid request parameter: <value> with value <value>
  • Invalid request parameter: <value> <value> is invalid
  • Invalid request parameter: <value> <value> is duplicated
  • Invalid request parameter: <value> <value> cannot be negative or zero
580022
  • Invalid request parameter: <value>
  • Invalid request parameter: payKey with value <value>
580022
  • Invalid request parameter: <value>
  • Invalid request parameter: payKey with value <value>
  • No sender is associated with this key
580022 The funding plan data is not present
580023
  • The fee payer <value> cannot be used if a primary receiver is specified
  • The fee payer <value> can only be used if a primary receiver is specified
  • The fee payer <value> must have exactly 2 receivers
  • The reverseAllParallelPaymentOnError field can be true only if a primary receiver is not specified
  • The fee payer <value> cannot be used if a preapproval key is specified
  • Invalid request: FundingType cannot be specified when PaymentSubType is specified
  • Your Application is not approved to use the PaymentSubType: <value>
  • Your Application is not approved to use the PaymentType: <value>
  • Invalid request parameter: PaymentType should be the same for all receivers <value>
  • Inconsistent request parameter for digitalgoods
  • Invalid request parameter: PaymentSubType should be the same for all receivers <value>
  • Invalid Request: RECEIVABLE cannot be used with other funding types
  • For chained payments, receivers must have premier or business accounts
580027
  • Currently the system does not accept the currency <value>
  • Unsupported country code <value>
  • Currently the system does not accept the currency <value>
  • The parameter is not supported
580027 This parameter is not supported
580029 A pin is required to confirm this preapproval Missing required request parameter: <value>
580029 Missing required request parameter: <value>
580029 A pay key, transaction ID, or tracking ID is missing
589018 The pay key <value> is invalid
589019 The preapproval key <value> is invalid
589061 The receiver <value> is invalid for this refund

1.5.0 Features

Adaptive Payments version 1.5.0 provides the new features for the APIs, such as the ability to delay a chained payment and to obtain the reason a payment is pending.

In addition to API changes, version 1.5.0 also offers new features that do not affect the APIs, such as guest payments, and ELV support.

Ability to Delay a Chained Payment Feature in Version 1.5.0

You can now set up chained payments to process the transaction leg to the primary receiver, and delay the payment to the secondary receivers. To do this, you use the Pay or ExecutePayment call and pass the new parameter actionType with PAY_PRIMARY

.

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. Value is:

  • 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.
  • ECHECK – The payment is pending because it was made by an eCheck that has not yet cleared.
  • INTERNATIONAL – The payment is pending because the receiver holds a non-U.S. account and does not have a withdrawal mechanism. The receiver must manually accept or deny this payment from the Account Overview.
  • MULTI_CURRENCY – The receiver does not have a balance in the currency sent, and does not have the Payment Receiving Preferences set to automatically convert and accept this payment. Receiver must manually accept or deny this payment from the Account Overview.
  • UNILATERAL – The payment is pending because it was made to an email address that is not yet registered or confirmed.
  • UPGRADE – The payment is pending because it was made via credit card and the receiver must upgrade the account to a Business account or Premier status to receive the funds. It can also mean that receiver has reached the monthly limit for transactions on the account.
  • VERIFY – The payment is pending because the receiver is not yet verified.
  • RISK – The payment is pending while it is being reviewed by PayPal for risk.
  • OTHER – The payment is pending for a reason other than those listed above. For more information, contact PayPal Customer Service.

1.4.0 Features

Release 1.4.0 provides the new API operations: ExecutePayment, GetPaymentOptions, and SetPaymentOptions. The new API operations work with the actiontype CREATE in the Pay API operation.

New API Operations for Version 1.4.0

New API Operation Description
ExecutePayment Execute a payment created with a PayRequest that had the actionType set to CREATE.
GetPaymentOptions Retrieve payment settings specified with the SetPaymentOptions API operation.
SetPaymentOptions Set payment options to be executed with the ExecutePayment API operation.

Changes to the Pay API Operation

Table 1. 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. Person-to-person payments can only be made under the following conditions:
  • simple and parallel payments (not chained)
  • all transactions within the single Pay request must be person-to-person
  • feesPayer field set to EACHRECEIVER or SENDER.
  • this feature requires the appropriate permission level from PayPal
Receiver.PhoneNumberType New field: common:PhoneNumberType Allows you to pass a receiver's mobile phone number, including the country code and extension.
Note: This feature is available for applications with special permission level.

Changes to the PaymentDetails API Operation

Table 2. Changes to PaymentDetails response messages
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. Allowable values are:
  • GOODS — This is a payment for goods
  • SERVICE — This is a payment for services (default)
  • PERSONAL — This is a person-to-person payment
  • CASHADVANCE — This is a person-to-person payment for a cash advance
Person-to-person payments can only be made under the following conditions:
  • simple and parallel payments (not chained)
  • all transactions within the single Pay request must be person-to-person
  • feesPayer field set to EACHRECEIVER or SENDER.
  • this feature requires the appropriate permission level from PayPal
Receiver.PhoneNumberType New field: common:PhoneNumberType Allows you to pass a receiver's mobile phone number, including the country code and extension.
Note: This feature requires the appropriate permission level from PayPal.

Changes to the PreapprovalDetails API Operation

Table 3. 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)
Note: This field is available only to API callers with advanced permission levels. For information, refer to the section Adaptive Payments Service Permissions.

Changes to the PreapprovalDetails API Operation

Table 4. Changes to PreapprovalDetailsResponse message
Field Description
addresslist New field: ap:AddressList Returns a list of billing addresses.
AddressList New field: ap:Address
Address.addresseeName xs:string The name of the person that is billed.
Address.baseAddress New field: common:BaseAddress
BaseAddress.city xs:string The city of the billing address
BaseAddress.countryCode xs:string The country code for the billing address
BaseAddress.line1 xs:string The streetname for the billing address
BaseAddress.line2 xs:string An extra line for the street address
BaseAddress.postalCode xs:string The postal code of the billing address
BaseAddress.state xs:string The state for the billing address
BaseAddress.type xs:string The type of billing address. Value is:
  • BILLING — This is a billing address

Changes to the Refund API Operation

Table 5. 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.
Note: This feature is available for applications with special permission level.

1.3.0 Features

Version 1.3.0 includes changes to existing APIs as well new APIs: ConvertCurrency, CancelPreapproval. It also includes the new PPFaultMessage.

Overview of Changes for Version 1.3.0

These are the main changes for version 1.3.0:

  • Consumer signups for new PayPal accounts Consumers can now sign up for a PayPal account during the payment preapproval web flow. Consumers can also sign up for a PayPal account during a payment web flow and then complete the payment in the same session.
  • Preapproval cancellations This release includes a new API operation to allow consumers to cancel preapprovals: the CancelPreapproval API operation. In past releases, consumers could only cancel preapprovals through paypal.com. For more information, refer to the CancelPreapproval API Operation section.
  • Getting Foreign Exchange rates for a list of payment amounts This release provides a new API Operation, ConvertCurrency, that lets you convert a given amount in one currency to an equivalent amount in another currency based on the 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. PayPal notifies the receiver at this email address to create an account and claim the payment. Supporting features include email notifications and IPN messages to the sender, receiver, and API caller, plus the ability to cancel unclaimed payments.

HTTP Header Changes

In previous versions, the application ID was passed in the ClientDetails element applicationId. Version 1.3.0 requires a new header to be passed to identify the application ID. The ClientDetails.applicationId element is no longer necessary.

Changes to the Pay API Operation for Version 1.3.0

Table 6. 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. 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.
Note: This feature is available for applications with special permission level.
FundingTypeList.fundingTypeInfo New field: ap:FundingTypeInfo 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.
Note: This feature is available for applications with special permission level.
fundingType New field: xs:string Specifies the allowed funding types that can be used as funding sources for the payment. Allowable values are:
  • ECHECK — Electronic check
  • BALANCE — PayPal account balance
  • CREDITCARD — Credit card
Note: This feature is available for applications with special permission level.
logdefaultShippingAddress This field has been removed. Pay requests that use this field are executed, but the logdefaultShippingAddress is ignored.
Receiver.paymentType New field: xs:string The transaction subtype for the payment. Allowable values are:
  • GOODS — This is a payment for goods
  • SERVICE — This is a payment for services (default)
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. The consumer can either log in using an existing PayPal account (that is not associated with a receiver) or create a new account during the payment flow.

Changes to the PaymentDetails API Operation for Version 1.3.0

Table 7. 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.
Note: This feature is available for applications with a special permission level.
FundingTypeList.fundingTypeInfo New field: ap:FundingTypeInfo 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.
Note: This feature is available for applications with a special permission level.
fundingType New field: xs:string Specifies the allowed funding type that can be used as the funding source for the payment. Value is:
  • ECHECK — Electronic check
  • BALANCE — PayPal account balance
  • CREDITCARD — Credit card
Note: This feature is available for applications with a special permission level.
PaymentInfo.senderTransactionID xs:string The identification number 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.
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.0 of the Adaptive Payments API introduces changes to several Adaptive Payments API operations. These changes include backward-compatible changes to request and response messages as well as additional error messages.

Changes to the Pay API Operation for Version 1.2.0

Table 8. 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

Table 9. 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.0

Table 10. Changes to PaymentDetailsReponse message
Field Description
Receiver.invoiceID New field: xs:string The invoice number for the payment

Changes to Preapproval API Operation for Version 1.2.0

Table 11. 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.

Changes to Preapproval Details API Operation for Version 1.2.0

Table 12. Changes to PreapprovalDetailsResponse message
Field Description
ipnNotificationUrl New field: xs:string The URL to which all IPN messages for this preapproval are sent.
memo New field: xs:string A note about the preapproval.

1.1.0 Features

Version 1.1.0 of the Adaptive Accounts API introduces changes to all Adaptive Payments API operations. These changes include backward compatible changes to request and response messages as well as additional error messages.

Changes to the Pay API Operation for Version 1.1.0

Table 13. Changes to PayRequest message
Field Description
logDefaultShippingAddress 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.

Table 14. Changes to PayResponse message
Field Description
payErrorList New field: ap:PayErrorList Information about why a payment failed.

Table 15. New Pay error messages
Code Message Additional Information
580022 Invalid request: ~1 Invalid request parameter; for example an invalid application ID or language code
580026 The invoice id (~1) already exists for receiver ~2 and cannot be duplicated
580027 Payment is not allowed to be pending
580029 Invalid request: ~1 Missing request parameter

Changes to PaymentDetails API Operation for Version 1.1.0

Table 16. Changes to PaymentDetailsResponse
Field Description
logDefaultShippingAddress New field: xs:string Indicates when the Pay operation was called for this payKey.
trackingId Empty fields are not returned; this is now enforced for trackingID.

Table 17. New PaymentDetails error messages
Code Message Additional Information
540031 You do not have permission to get the details of this Payment PaymentDetails
580022 Invalid request: ~1 Invalid request parameter; for example an invalid application ID or language code
580029 Invalid request: ~1 Missing request parameter

Changes to Preapproval API Operation for Version 1.1.0

Table 18. 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.

Table 19. New Preapproval error messages
Code Message Additional Information
580022 Invalid request: ~1 Invalid request parameter; for example an invalid application ID or language code
580029 Invalid request: ~1 Missing request parameter

Changes to PreapprovalDetails API Operation for Version 1.1.0

Table 20. Changes to PreapprovalDetailsResponse message
Field Description
senderEmail The sender's email address is only available when you explicitly set the email address in the PreapprovalRequest message.
maxNumberOfPayments The preapproved maximum number of payments is only available when you explicitly set the email address in the PreapprovalRequest message.

Table 21. New PreapprovalDetails error messages
Code Message Additional Information
540031 You do not have permission to get the details of this Preapproval
580022 Invalid request: ~1 Invalid request parameter; for example an invalid application ID or language code
580029 Invalid request: ~1 Missing request parameter

Changes to Refund API Operation for Version 1.1.0

Table 22. Changes to RefundResponse message
Field Description
refundInfoList.refundInfo.errorList New field: xs:string Information about why a refund failed.

Table 23. New Refund error messages
Code Message Additional Information
540031 You do not have permission to get the details of this Refund
580022 Invalid request: ~1 Invalid request parameter; for example an invalid application ID or language code
580029 Invalid request: ~1 Missing request parameter