Home

PayPal Adaptive Payments - 2012 Developer's Guide

1. Gary McCue epus PayPal You are about to pay Receiver Amount PicMart 10 50 10 50 USD Pay with My PayPal Balance View PayPal policies 0 50 USD My PayPal Balance Pay Cancel PayPal protects your privacy and security e 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 Innovate 2010 Gary McCue Notyou Log out PayPal ja You are about to pay Receiver Amount PicMart 0 50 Total 0 50 USD Pay with My PayPal Balance View PayPal policies 0 50 USD My PayPal Balance Y Pay Cancel PayPal protects your privacy and security H Ji 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 Kinds of Embedded Payments Embedded payments can include e simple payments e parallel payments e chained payments You can also enable preapprovals for future payments or enable shipping addresses to be associated with embedded payments 30 August 7 2012 Adaptive Payments Developer Guide Introducing Adaptive Payments Embedded Payments IMPORTANT Payments for digital goods m
2. currencyList 1 1 CurrencyList CurrencyType e code 1 1 string e amount 1 1 decimal e code 1 1 string e amount 1 1 decimal 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 CurrencyConversionTable Fields Field Description currencyConversionList ap CurrencyConversionList The list of converted currencies Adaptive Payments Developer Guide August 7 2012 203 al 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 Field Description amount xs decimal The converted amount 204 August 7 2012 Adaptive Payments Developer Guide ConvertCurrency API Operation ConvertCurrency Response Message Field Description code xs string The currency code for the converted amount Possible values are e Australian Dollar AUD e Brazilian Real BRL NOTE The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts
3. 0 1 string severity ErrorSeverity category ErrorCategory message string e exceptionId 0 1 token e parameter 0 ErrorParameter ErrorData E Errorseverity e errorId long e domain string EJ ErrorCategory e subdomain 0 1 string severity ErrorSeverity i ErrorParameter name string category ErrorCategory message string e exceptionId 0 1 token e parameter 0 ErrorParameter Adaptive Payments Developer Guide August 7 2012 133 SS 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 Field category domain errorId exceptionID message parameter severity subdomain Description common ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect xs string The domain to which this service belongs xs long A 6 digit number that uniquely identifies a particular error This field is not used xs string A description of the error common ErrorParameter Represents contextual in
4. E responseEnvelope 1 1 ResponseEnvelope e timestamp 1 1 dateTime f fundingPlan 0 FundingPlan e ack 1 1 AckCode FE any 0 e correlationId 1 1 string build 1 1 string fl any 0 E FundingPlan e FundingPlanId 1 1 string e FundingAmount 1 1 CurrencyType e backupFundingSource 0 1 FundingSource e senderFees 0 1 CurrencyType e currencyConversion 0 1 CurrencyConversion e charge 1 FundingPlanCharge FE any 0 E FundingPlan E CurrencyType e FundingPlanId 1 1 string e code 1 1 string e FundingAmount 1 1 CurrencyType e amount 1 1 decimal e backupFundingSource 0 1 FundingSource ss e senderFees 0 1 CurrencyType Ej FundingSource e currencyConversion 0 1 CurrencyConversion e lastFourOfAccountNumber 0 1 string e charge 1 FundingPlanCharge e type 1 1 string FE any 0 e displayName 0 1 string Ef FundingSourceld 0 1 string e alowed 0 1 boolean F any 0 E CurrencyConversion e from 1 1 CurrencyType e to 1 1 CurrencyType e exchangeRate 1 1 decimal Fany o E FundingPlanCharge e charge 1 1 CurrencyType e fundingSource 1 1 FundingSource F any 0 Adaptive Payments Developer Guide August 7 2012 235 am GetFundingPlans API Operation GetFundingPlansResponse Message E CurrencyConversion CurrencyType e from
5. Field Description ack common AckCode Acknowledgement code It is one of the following values e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message build xs string Build number It is used only by PayPal Merchant Technical Support correlationId xs string Correlation identifier It is a 13 character alphanumeric string for example db87c705a910e that is used only by PayPal Merchant Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs Adaptive Payments Developer Guide August 7 2012 193 isa CancelPreapproval API Operation PPFault Message E FaultMessage i ResponseEnvelope e responseEnvelope 1 1 ResponseEnvelope e timestamp 1 1 dateTime e error 0 ErrorData ack 1 1 AckCode e correlation
6. PLN Pound Sterling GBP Singapore Dollar SGD Swedish Krona SEK Swiss Franc CHF Taiwan New Dollar TWD Thai Baht THB Turkish Lira TRY NOTE The Turkish Lira is supported as a payment currency and currency balance only for Turkish PayPal accounts U S Dollar USD FundingSource Fields Field Description lastFourOfAccountNumber xs string Last 4 digits or characters in account number 92 August 7 2012 Adaptive Payments Developer Guide Pay API Operation PayResponse Message Field Description type xs string Type of funding source which is one of the following values e UNDEFINED BALANCE BANK INSTANT BANK DELAYED CREDITCARD DEBITCARD ACCOUNTS RECEIVABLE displayName xs string Display name of funding source fundingSourceld xs string Funding source ID allowed xs boolean Whether the funding source is allowed for this payment e true You can use this funding source for the payment e false You cannot use this funding source default CurrencyConversion Fields Field Description from ap CurrencyType The currency to be converted to ap CurrencyType The currency resulting from the conversion exchangeRate xs decimal The exchange rate for the from currency to the to currency FundingPlanCharge Fields Field Description charge common CurrencyType Amount charged to funding source fundingSource ap FundingSource F
7. phoneNumber 1 1 string 1 1 extension 0 1 string August 7 2012 Adaptive Payments Developer Guide Pay API Operation BN 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 e PAY Use this option if you are not using the Pay request in combination with ExecutePayment e CREATE Use this option to set up the payment instructions with SetPaymentOptions and then execute the payment at a later time with the ExecutePayment e PAY PRIMARY For chained payments only specify this value to delay payments to the secondary receivers only the payment to the primary receiver is processed cancelUrl xs string Required The URL to which the sender s browser is redirected if the sender cancels the approval for the payment after logging in to paypal com to approve the payment Specify the URL with the HTTP or HTTPS Maximum length 1024 characters clientDetails common ClientDetailsType Optional Information about the sender Adaptive Payments Developer Guide August 7 2012 79 sas Pay API Operation PayRequest Message Field Description currencyCode feesPayer xs string Required The currency code Allowable values are e Australian Dollar
8. xs long A 6 digit number that uniquely identifies a particular error This field is not used xs string A description of the error common ErrorParameter Represents contextual information about the error August 7 2012 Adaptive Payments Developer Guide PreapprovalDetails API Operation NX PreapprovalDetails Examples Using NVP and CURL Field Description severity common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request was interrupted e 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 e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message build xs string Build number It is used only by PayPal Merchant Technical Support correlationId xs string Correlation identifier It is a 13 character alphanumeric string for example db87c705a910e that is used only by PayPal Merchant Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp xs datetime Date on which the res
9. CREATED The response includes a pay key which is a token you use in subsequent calls to Adaptive Payments APIs to identify this particular payment Adaptive Payments Developer Guide August 7 2012 69 70 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 e You send a PayRequest specifying an amount to be paid for each receiver e You receive a response with a pay key e You must redirect the sender s browser to PayPal to approve the payment In the example below Paul makes a single payment of 14 which is split into a 9 payment to Andrea and a 5 payment to Linda The following event sequence takes place Pay Request for Parallel Payment amp actionType PAY amp cancelUrl http example com cancel htm amp currencyCode USD amp receiverList receiver 0 amount 9 00 amp receiverList receiver 0 email andrea example com amp receiverList receiver 1 amount 5 00 amp receiverList receiver 1 email linda example com amp requestEnvelope errorLanguage en_US amp returnUrl http example com return htm Pay Response for Par
10. Canadian Dollar CAD Czech Koruna CZK Danish Krone DKK Euro EUR Hong Kong Dollar HKD Hungarian Forint HUF Israeli New Sheqel ILS Japanese Yen JPY Malaysian Ringgit MYR NOTE The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts Mexican Peso MXN Norwegian Krone NOK New Zealand Dollar NZD Philippine Peso PHP Polish Zloty PLN Pound Sterling GBP Singapore Dollar SGD Swedish Krona SEK Swiss Franc CHF Taiwan New Dollar TWD Thai Baht THB Turkish Lira TRY NOTE The Turkish Lira is supported as a payment currency and currency balance only for Turkish PayPal accounts e U S Dollar USD CurrencyList Fields Field Description currency ap CurrencyType The list of converted amounts with their target currency codes Adaptive Payments Developer Guide August 7 2012 205 al ConvertCurrency API Operation PPFault Message ResponseEnvelope Fields Field Description ack common AckCode Acknowledgement code It is one of the following values e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message build xs string Build number It is used only by PayPal Merchant Technical S
11. 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 Some kinds of payments and operations require specific permission to use API Operations Related to Payments API Operation Description Pay Transfers funds from a sender s PayPal account to one or more receivers PayPal accounts up to 6 receivers PaymentDetails Obtains information about a payment created with the Pay API operation ExecutePayment Executes a payment Get PaymentOptions Obtain the settings specified with the Set PaymentOptions API operation Set PaymentOptions Sets payment options API Operations Related to Preapprovals API Operation Description Preapproval Sets up preapprovals which is an approval to make future payments on the sender s behalf PreapprovalDetails Obtains information about a preapproval CancelPreapproval Cancels a preapproval ConfirmPreapproval Confirms that you can use the specified preapproval to make payments Adaptive Payments Developer Guide August 7 2012 65 66 Getting Started Adaptive Payments Endpoints Other API Operations API Opera
12. subdomain common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request was interrupted e Warning Processing of the request was completed This field is not used ResponseEnvelope Fields Field Description ack build correlationId timestamp common AckCode Acknowledgement code It is one of the following values e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message xs string Build number It is used only by PayPal Merchant Technical Support xs string Correlation identifier It is a 13 character alphanumeric string for example db87c705a910e that is used only by PayPal Merchant Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues 228 August 7 2012 Adaptive Payments Developer Guide Refund API Operation Refund Examples Using NVP and CURL Refund Examples Using NVP and CURL
13. E cance about the preapproval Adaptive Payments Developer Guide August 7 2012 Embedded Payments 47 al Introducing Adaptive Payments Embedded Payments Thank you for using PayPal Windows Internet Ex a ed Google 11 Jos Ramirez Hi Log out Receiver Rapid Action Towing 5 00 5 00 USD El Order Details e You paid with My PayPal Balance e Your order information has been sentto pbehara usbuyer paypal com Preapproval Details e Your preapproval agreement has been successfully created The reference number for this agreement is PA 8US9675113297773C i PayPal protects your privacy and security NOTE 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 com webapps adaptivepayment flow preapproval prea pprovalKey PA xxxxxxxxxxxx amp expType mini PayPal first asks the user to log into their PayPal account 48 August 7 2012 Adaptive Payments Developer Guide Introducing Adaptive Payments f English PayPal amp Log in to your PayPal account Email address PayPal password Problem with login New to PayPal Sign up and buy in a few eas
14. PLN Pound Sterling GBP Singapore Dollar SGD Swedish Krona SEK Swiss Franc CHF Taiwan New Dollar TWD Thai Baht THB Turkish Lira TRY NOTE The Turkish Lira is supported as a payment currency and currency balance only for Turkish PayPal accounts e U S Dollar USD Adaptive Payments Developer Guide August 7 2012 201 al ConvertCurrency API Operation ConvertCurrencyResponse Message RequestEnvelope Fields Field Description detailLevel errorLanguage 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 ReturnA11 which provides the maximum level of detail 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 ConversionType Fields The table below describes the ConversionType field 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 e 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 h
15. PayPal Technical Support uses the information to assist with reported issues CancelPreapproval Errors Code Message Additional Information 520002 Internal error 540031 You don t have permission to cancel this preapproval 589019 The preapproval key is invalid 196 August 7 2012 Adaptive Payments Developer Guide 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 e ConvertCurrencyRequest E ConvertCurrencyRequest fj ConvertCurrencyRequest ef requestEnvelope 1 1 RequestEnvelope requestEnvelope 1 1 RequestEnvelope Ef baseAmountList 1 1 CurrencyList convertToCurrencyList 1 1 CurrencyCodeList countryCode 0 1 string Gi conversionType 0 string E CurrencyList seol currency 1 CurrencyType e code 1 1 string e amount 1 1 decimal E Currency Conversion CurrencyType e from 1 1 CurrencyType e code 1 1 string e to 1 1 CurrencyType e amount 1 1 decimal e exchangeRate 1 1 decimal Ej any 0 C
16. ResponseEnvelope Fields PaymentDetails Examples Using NVP and CURL Payment Details Errors Chapter 5 ExecutePayment API Operation ExecutePaymentRequest Message ExecutePaymentRequest Fields RequestEnvelope Fields ExecutePaymentResponse Message ExecutePaymentResponse Fields PayErrorList Fields PayError Fields o ErrorData Fields ll Receiver Fields ResponseEnvelope Fields PPFault Message e lens FaultMessage Fields ErrorData Fields ll ResponseEnvelope Fields ExecutePayment Errors lll sn Chapter 6 GetPaymentOptions API Operation GetPaymentOptionsRequest Message GetPaymentOptionsRequest Fields RequestEnvelope Fields GetPaymentOptionsResponse Message GetPaymentOptionsResponse Fields DisplayOptions Fields InitiatingEntity Fields lcs Institution Customer Fields SenderOptions Fields ReceiverOptions Fields InvoiceData Fields Invoicellem Fields lll sn Receiverldentifier Fields 6 August 7 2012 Adaptive Payme
17. e exceptionId 0 1 token e 0 ErrorParameter 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 category domain errorId exceptionID message parameter Description common ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect xs string The domain to which this service belongs xs long A 6 digit number that uniquely identifies a particular error This field is not used xs string A description of the error common ErrorParameter Represents contextual information about the error Adaptive Payments Developer Guide August 7 2012 241 am GetFundingPlans API Operation GetFundingPlan Errors Field Description severity common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request was interrupted e 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 e Success The operation completed successfu
18. e COMPLETED The payment was successful e INCOMPLETE Some transfers succeeded and some failed for a parallel payment or for a delayed chained payment secondary receivers have not been paid e ERROR The payment failed and all attempted transfers failed or all completed transfers were successfully reversed e REVERSALERROR One or more transfers failed when attempting to reverse a payment e PROCESSING The payment is in progress e PENDING The payment is awaiting processing Sender s email address Whether the Pay API is used with or without the SetPaymentOptions and ExecutePayment API operations Possible values are e PAY If you are not using the SetPaymentOptions and ExecutePayment API operations e CREATE If you are using the SetPaymentOptions and ExecutePayment API operations The date on which the payment request was initiated Whether the payment request specified to reverse parallel payments if an error occurs Possible values are e true Each parallel payment is reversed if an error occurs e false Only incomplete payments are reversed default The transaction ID where n is a number from 0 to 5 For simple single receiver payments this number will be 0 Numbers larger than 0 indicate the payment to a particular receiver in chained and parallel payments The transaction status where n is a number from 0 to 5 For simple single receiver payments this number will be 0 Numbers larger than 0 indica
19. severity ErrorSeverity name string category ErrorCategory e message string e exceptionId 0 1 token e parameter 0 ErrorParameter FaultMessage Fields Field Description error common ErrorData Detailed error information responseEnvelope common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status 172 August 7 2012 Adaptive Payments Developer Guide Preapproval API Operation E PPFault Message ErrorData Fields Field Description category common ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect domain xs string The domain to which this service belongs errorld xs long A 6 digit number that uniquely identifies a particular error exceptionID This field is not used message xs string A description of the error parameter common ErrorParameter Represents contextual information about the error severlty common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request was interrupted e Warning Processing of the request was completed subdomain This field is not used ResponseEnvelope Fields Field Description ack common AckCode Acknowledgement code It i
20. zo f error 1 1 ErrorData email 1 string FE any 0 Ef phone 1 PhoneNumberType primary 41 boolean Ef invoiceld 1 string Gi paymentType n string Gi paymentsubType T string T l any E ErrorData e errorId long e domain string e subdomain 0 1 string e severity ErrorSeverity e category ErrorCategory e message string e exceptionId 0 1 token e parameter 0 ErrorParameter ES Receiver E PhoneNumberType Ef amount 1 1 decimal e countryCode 1 1 string email 0 1 string e phoneNumber 1 1 string Ef phone 1 PhoneNumberType e extension 0 1 string primary 1 boolean invoiceld 1 string Ef paymentType 1 string paymentSubType 1 string Pany i ErrorData E Errorseverity e errorId long domain string E ErrorCategory e subdomain 0 1 string E ErrorParameter severity ErrorSeverity name string category ErrorCategory message string e exceptionId 0 1 token e parameter 0 ErrorParameter Adaptive Payments Developer Guide August 7 2012 89 uz Pay API Operation PayResponse Message E Receiver PhoneNumberType Ef amount 1 decimal e countryCode 1 1 string email 1 string s e phoneNumber 1 1 string phone 1 PhoneNumberType i e extension 0 1 string e primary 1 boolean invoiceld 1 string Ef paymentTyp
21. 0 Ej ReceiverIdentifier Ef email 0 1 string ses f phone 0 1 PheneNumberType F lany 0 GetPaymentOptionsResponse Fields GetPaymentOptions API Operation GetPaymentOptionsResponse Message E InstitutionCustomer e institutionId 41 string Ef FirstName 1 string lastName 1 string Gi displayName v1 string fe institutionCustomerId m string countryCode 41 string Gi email 41 string 7j any E InvoiceData e item 0 Invoiceltem e totalTax 0 1 decimal e totalShipping 0 1 decimal El any 0 E ReceiverIdentifier Ef email 0 1 string Gi phone 0 1 PhoneNumberType F lany 0 E InvoiceItem Gi name 0 1 string Ef identifier 0 1 string e price 0 1 decimal Ef itemPrice 0 1 decimal Ef itemCount 0 1 int fl any 0 E PhoneNumberType e countryCode 1 1 string e phoneNumber 1 1 string e extension 0 1 string Field Description payKey xs string The pay key that identifies the payment for which you set payment options Adaptive Payments Developer Guide August 7 2012 141 142 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
22. 1 dateTime e error 0 ErrorData e ack 1 1 AckCode e correlationId 1 1 string e build 1 1 string cd any 0 ErrorData errorId long domain string e subdomain 0 1 string severity ErrorSeverity category ErrorCategory message string e exceptionId 0 1 token e parameter 0 ErrorParameter Adaptive Payments Developer Guide August 7 2012 185 186 PreapprovalDetails API Operation PPFault Message le le le le le le le le ErrorData E ErrorSeverity errorId long domain string iE ErrorCategory subdomain 0 1 string severity ErrorSeverity E ErrorParameter category ErrorCategory message string exceptionId 0 1 token parameter 0 ErrorParameter 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 category domain errorId exceptionID message parameter Description common ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect xs string The domain to which this service belongs
23. BaseAddress request fields 184 247 baseAddress response field 184 247 baseAmount response field 204 baseAmountList request field 198 build response field 96 98 121 123 132 135 146 148 157 159 171 173 184 187 193 195 206 208 225 228 240 242 248 250 businessName request field 153 businessName response field 142 C cancel url IPN variable 259 260 Adaptive Payments Developer Guide CancelPreapproval API operation 191 CancelPreapprovalRequest fields 191 CancelPreapprovalRequest message 191 CancelPreapprovalResponse fields 192 CancelPreapprovalResponse message 192 cancelUrl request field 79 cancelUrl request fields 165 cancelUrl response field 113 180 category field 94 98 122 131 134 148 159 173 186 195 208 224 227 241 250 charge response field 91 93 237 city response field 184 247 clientDetails request field 79 clientDetails request fields 165 closeFlow JavaScript function 255 code request field 199 code response field 92 205 238 ConversionCurrencyResponse fields 202 203 264 conversionType request field 198 ConvertCurrency API operation 197 ConvertCurrencyRequest fields 198 ConvertCurrencyRequest message 197 ConvertCurrencyResponse message 202 convertToCurrencyList request field 198 correlationId response field 96 99 121 123 132 135 146 149 157 160 171 174 185 187 193 196 206 209 226 228 240 242 248 251 countryCode request field 85 156 198 218
24. Code Message Additional Information 500000 There is a system error 520002 Internal error 520003 User name password is incorrect 520003 Authentication failed API credentials are incorrect Since 1 6 0 520005 Merchant account is locked 520006 This call is not defined in the database 529038 There was an error while making this payment 539012 The preapproval key has not been authorized yet Adaptive Payments Developer Guide August 7 2012 135 136 ExecutePayment API Operation ExecutePayment Errors 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 Since 1 6 0 Operation is not permitted because the credentials do not match those of the initial operation 550001 User is not allowed to perform this action 550001 This payment request must be authorized by the sender 550001 You do not have permission to execute this payment implicitly Since 1 6 0 559044 Account setting on the receiver prohibited the payment 560027 The argument value is unsupported 569000 Split payments are not supported at this time 569013 The preapproval key has been canceled 569016 Preapproval PIN functionality is not enabled 569
25. E GetFundingPlansRequest Is RequestEnvelope Ef requestEnvelope 1 1 RequestEnvelope e detailLevel 0 1 DetailLevelCode Ef payKey 1 1 string ves e errorLanguage 1 1 string f any 0 F any 0 Adaptive Payments Developer Guide August 7 2012 233 234 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 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 ReturnA11 which provides the maximum level of detail errorLanguage xs string Required RFC 3066 language in which error messages are returned by default it is en_US which is the only language currently supported GetFundingPlansResponse Message August 7 2012 Adaptive Payments Developer Guide GetFundingPlans API Operation E GetFundingPlansResponse Message E ResponseEnvelope E GetFundingPlansResponse
26. PhoneNumberType e extension 0 1 string primary 41 boolean invoiceld 1 string paymentType 41 string Ef paymentSubType 0 1 string T l any on E ErrorData E Errorseverity e errorId long domain string E ErrorCategory e subdomain 0 1 string ErrorParameter severity ErrorSeverity name string e category ErrorCategory message string e exceptionId 0 1 token e parameter 0 ErrorParameter 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 e Australian Dollar AUD e Brazilian Real BRL NOTE The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts Canadian Dollar CAD Czech Koruna CZK Danish Krone DKK Euro EUR Hong Kong Dollar HKD Hungarian Forint HUF Israeli New Sheqel ILS Japanese Yen JPY Malaysian Ringgit MYR NOTE The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts Mexican Peso MXN Norwegian Krone NOK New Zealand Dollar NZD Philippine Peso PHP Polish Zloty PLN Pound Sterling GBP Singapore Dollar SGD Swedish Krona SEK Swiss Franc CHF Taiwan New Dollar TWD Thai Baht
27. 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 The total amount from each receiver is refunded to the sender NOTE The sample code below uses the insecure setting to work around the certificate for testing in a sandbox environment For actual implementations you must specify the location of the certificate Request curl 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 your app id https svcs sandbox paypal com AdaptivePayments Refund d requestEnvelope errorLanguage en US amp payKey AP 95V43510SV018561T Response Adaptive Payments Developer Guide August 7 2012 229 230 Refund API Operation Refund Errors responseEnvelope timestamp 2009 08 14T09 3A00 3A37 748 07 3A00 amp responseEnvelope ack Success amp responseEnvelope correlat ionId 7967b2d03745a amp responseEnvelope build DEV amp currencyCode USD amp refundInfoList
28. e timestamp 1 1 dateTime paymentExecStatus 1 1 string e payErrorList 0 1 PayErrorList FE any 0 e build 1 1 string fl any 0 E PayErrorList se f payError 1 PayError Ej PayErrorList PayError ses f payError 1 PayError Ef receiver 1 1 Receiver seo Ef error 1 1 ErrorData F lany 0 128 August 7 2012 Adaptive Payments Developer Guide Ea PayError E receiver 1 1 Receiver seo f error 1 1 ErrorData fjnv o E Receiver amount Eii email 0 1 phone 1 e primary 1 invoiceld wl fe paymentType 1 Gi paymentsubType 0 1 Pany decimal string PhoneNumberType boolean string string string i ErrorData e errorId e domain e subdomain e severity e category e message e exceptionId e parameter Adaptive Payments Developer Guide long string 0 1 string ErrorSeverity ErrorCategory string 0 1 token 0 ErrorParameter ExecutePayment API Operation NER ExecutePaymentHesponse Message E Receiver Gi amount 1 decimal Gi email 1 string Gi phone 1 PhoneNumberType e primary 1 boolean Ef invoiceld 1 string Gi paymentType n string Gi paymentsubType T string T l any E ErrorData e errorId long e domain string e subdomain 0 1 string e severity ErrorSeverity e category ErrorCategory e message
29. errorlanguage 1 1 string E actionType 0 1 string 7 any 0 Gi FundingPlanId 0 1 string Ej any 0 ExecutePaymentRequest Fields Field Description payKey xs string Optional The pay key that identifies the payment to be executed This is the pay key returned in the PayResponse message fundingPlanId xs string Optional The ID of the funding plan from which to make this payment requestEnvelope common requestEnvelope Information common to each API operation such as the language in which an error message is returned Adaptive Payments Developer Guide August 7 2012 127 S 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 ReturnA11 which provides the maximum level of detail errorLanguage xs string Required RFC 3066 language in which error messages are returned by default it is en_US which is the only language currently supported ExecutePaymentResponse Message ResponseEnvelope E ExecutePaymentResponse e ack 1 1 AckCode e correlationId 1 1 string Ef responseEnvelope 1 1 ResponseEnvelope
30. lt value gt lt value gt is duplicated Invalid request parameter lt value gt lt value gt cannot be negative or zero 580027 e Currently the system does not accept the currency lt value gt Since 1 6 0 e Unsupported country code lt value gt e Currently the system does not accept the currency lt value gt e The parameter is not supported 580028 The URL lt value gt is malformed 162 August 7 2012 Adaptive Payments Developer Guide 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 per payment amount a specific day of the week or the month and whether or not a PIN is required for each payment request Preapproval Overview To set up a preapproval request you must specify values for the following fields Required preapproval fields Field Description endingDate Last date for which the preapproval is valid It cannot be later than one year from the starting date Contact PayPal if you do not want to specify an ending date startingDate First date for which the preapproval is valid It cannot be before today s date or after the ending date maxTotalAmountOfAllPayments The preapproved maximum total amount of all payments
31. receiver string string InvoiceData Receiverldentifier string 151 152 E InitiatingEntity fe institutionCustomer 0 1 InstitutionCustomer 7j any aaa Gi item Ef totalTax Fany Ef email Fany E InvoiceData 0 Invoiceltem 0 1 decimal Ef totalShipping 0 1 decimal 0 E ReceiverIdentifier 0 1 string s ef phone 0 1 PhoneNumberType SetPaymentOptions API Operation SetPaymentsOptionsRequest Message E InstitutionCustomer Gi institutionId 1 string Gi firstName 1 string Gi lastName 41 string Gi displayName v1 string Gi institutionCustomerId E string countryCode 41 string Gi email 41 string 7j any E InvoiceItem Gi name 0 1 string f identifier 0 1 string price 0 1 decimal E itemPrice 0 1 decimal Gi itemCount 0 1 int 7 any 0 PhoneNumberType e countryCode 1 1 string e phoneNumber 1 1 string 0 1 string extension SetPaymentOptionsRequest Fields Field payKey displayOptions initiatingEntity shippingAddressId senderOptions Description 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 ap DisplayOptions Optional Specifies display items in payment flows and emails ap InitiatingEntity Optional The PayPal financial partner
32. 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 minibrowser a lightbox or an iframe NOTE Do not supply a value for autoredirectondone Be aware that you do not necessarily have to use the button images provided in the sample code 264 August 7 2012 Adaptive Payments Developer Guide 1 7 0 Features EE Minibrowser code form id mini form action https www paypal com webapps adaptivepayment flow pay target PPDGFrame gt lt br gt lt fieldset gt lt b gt lt legend gt Pay Mini Browser lt legend gt lt b gt lt input id type name expType value mini type hidden gt lt input id type name autoredirectondone type hidden gt label for paykey gt PayKey lt label gt lt input id paykey name payKey size 25 type text gt lt input type image id miniBrowserBtn value Pay with PayPal mini src https www paypal com en_US i btn x click but06 gif gt lt fieldset gt lt form gt Lightbox code form id lightbox form action https www paypal com webapps adaptivepayment flow pay target PPDGFrame gt lt fieldset gt
33. 1 token e parameter 0 ErrorParameter 226 August 7 2012 Adaptive Payments Developer Guide ErrorData Refund API Operation iE ErrorSeverity PPFault Message parameter FaultMessage Fields e errorId long e domain string E ErrorCategory e subdomain 0 1 string severity ErrorSeverity e category ErrorCategory e message string e exceptionId 0 1 token e 0 ErrorParameter 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 category domain errorId exceptionID message parameter Description common ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect xs string The domain to which this service belongs xs long A 6 digit number that uniquely identifies a particular error This field is not used xs string A description of the error common ErrorParameter Represents contextual information about the error Adaptive Payments Developer Guide August 7 2012 227 S Refund API Operation PPFault Message Field Description severity
34. 127 characters xs string Optional Your identification of the type of customer Maximum length 127 characters xs string Optional Sender s device ID such as a mobile device s IMEI number or a web browser cookie If a device ID was passed with the PayRequest use the same ID here Maximum length 127 characters xs string Optional Sender s geographic location Maximum length 127 characters xs string Optional Sender s IP address If an IP addressed was passed with the PayRequest use the same ID here xs string Optional A sub identification of the application Maximum length 127 characters Adaptive Payments Developer Guide August 7 2012 169 SS 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 By default the detail level code is ReturnA11 which provides the maximum level of detail errorLanguage xs string Required RFC 3066 language in which error messages are returned by default it is en_US which is the only language currently supported
35. 2009 07 13T12 3A34 3A29 316 07 3A00 amp responseEnvelope ack Success amp responseEnvelope correlationId d615a365bed61 amp responseEnvelope build DEV amp payKey AP 7AF63289GN043650D amp paymentExecStatus CREATED Preapproved payment example In this example the sender has a valid preapproval agreement with you and makes a payment of 100 to a PayPal registered receiver and 50 to another PayPal registered receiver The payment is completed without the sender logging in to paypal com NOTE The sample code below uses the insecure setting to work around the certificate for testing in a sandbox environment For actual implementations you must specify the location of the certificate Request August 7 2012 Adaptive Payments Developer Guide 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 actionType PAY amp cancelUrl http your cancel url amp currencyCode USD amp feesPayer EACHRECEIVER amp memo Preapproval payment example amp preapprovalKey PA 9JR04288NR0519129 amp receiverList receiver 0 amount 100 00 amp receiverList receiver 0 email receiver domain amp receiverList receiv
36. 265 New API Operations for Version 1 7 0 0 000 266 Changes to ConfirmPreapprovalRequest Fields for Version 1 7 0 266 Changes to JavaScript Functions for Embedded Payments 266 1 00 FE QUES C doe BOGS RR A e we e a do a da 266 New API Operations for Version 1 6 0 o 266 Changes to PayRequest Fields for Version 1 6 0 267 Changes to PayResponse Fields for Version 1 6 0 04 267 Changes to ExecutePaymentRequest Fields for Version 1 6 0 267 Changes to GetPaymentOptionsResponse Fields for Version 1 6 0 267 Changes to SetPaymentOptionsRequest Fields for Version 1 6 0 268 Changes to PreapprovalRequest Fields for Version 1 6 0 268 Changes to Address Structure for Version 1 6 0 aaa 268 Changes to DisplayOptions Structure for Version 1 6 0 268 New CurrencyConversion Structure for Version 1 6 0 ls 269 New InvoiceData Structure for Version 1 6 0 o ll 269 Adaptive Payments Developer Guide August 7 2012 11 EN Contents New Invoiceltem Structure for Version 1 6 0 0 200002 eee 269 New SenderOptions Structure for Version 1 6 0 a a a lll 269 New Senderldentifier Structure for Version 1 6 0 lll 270 New Accountldentifier Structure for Version 1 6 0 l l 270 New Rec
37. August 7 2012 115 E PaymentDetails API Operation PaymentDetailsResponse Message Field Description status trackingld xs string The status of the payment Possible values are e CREATED The payment request was received funds will be transferred once the payment is approved COMPLETED The payment was successful e INCOMPLETE Some transfers succeeded and some failed for a parallel payment or for a delayed chained payment secondary receivers have not been paid e ERROR The payment failed and all attempted transfers failed or all completed transfers were successfully reversed e REVERSALERROR One or more transfers failed when attempting to reverse a payment e PROCESSING The payment is in progress e PENDING The payment is awaiting processing xs string The tracking ID that was specified for this payment in the PaymentDetailsRequest message FundingTypeList Fields Field Description fundingTypeInfo ap FundingTypeInfo 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 FundingTypelnfo Fields Field Description fundingType Specifies a list of allowed funding selections for the payment This is a list of funding selection
38. 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 e GOODS This is a payment for goods e SERVICE This is a payment for services default Adaptive Payments Developer Guide August 7 2012 281 al 1 3 0 Features 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 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 282 August 7 2012 Adaptive Payments Developer Guide 1 3 0 Features EE 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 type
39. Collecting Shipping Addresses 58 Guest Payments lll ea sss ross 59 Fee Payment Configuration 60 Sender Pays the Fee s 61 Receiver Pays the Fee in a Parallel Payment aao a 62 Each Receiver Pays the Fee in a Chained Payment 62 Primary Receiver Pays the Fee in a Chained Payment 63 EN Contents Chapter 2 Getting Started 65 Adaptive Payments API Operations a aooaa a 65 API Operations Related to Payments eee ee 65 API Operations Related to Preapprovals ln 65 Other API Operations 2 oaa 66 Adaptive Payments Endpoints 2n 66 HTTP Headers 4 acs as db oda a A A A A A d 66 Authentication ag oan eRe Re eom e A ROC ae dB da 67 Specifying JSON NVP or XML Data Formats 67 SOAP Messages i as sa a a a a Ee RO 68 Specifying Application and Device Information 68 Making a Simple Payment JSON 22s 69 Pay Request for Simple Payment a 69 Pay Response for Simple Payment 2l 69 Making a Parallel Payment NVP 2222s 70 Pay Request for Parallel Payment 222r 70 Pay Response for Parallel Payment 22er 70 Making a Chained Payment XML lll 71 Pay Request for Chained Payment aa 71 Pay Response for Chained Payment eee 72 Chapter 3 Pay API Operatio
40. Create a PIN You re almost done For your security Pretty Flower Florist requires you to create a PIN Choose a PIN 4 8 numbers Re enter PIN PayPal protects your privacy and security Finally the user is presented with a confirmation screen Adaptive Payments Developer Guide August 7 2012 51 52 Introducing Adaptive Payments Embedded Payments Jos Ramirez PayPal e Log out Thank you for signing up You just signed up for future payments with Pretty Flower Florist We ll send a confirmation email to pbehara usbuyer paypal com To see more details of this agreement go to My pre approved payments in your PayPal Profile PayPal protects your privacy and security 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 requireShippingAddressSelection to true in your request to SetPaymentOptions August 7 2012 Adaptive Payments Developer Guide Introducing Adaptive Payments aa Embedded Payments Review Your Purchase PayPal Mozilla Firefox DE https fflocalhost paypel com 9443 webapps adaptivepaymen Y Raymond Adams 11 Log out You are about to pay Receiver Amount Rapid Action Towing 1 75 1 75 USD Pay with American Express XXxx 9275 w 11 Ship to 12893069 W 15th Street Ventura F 2
41. Fields 000 eee ee ee 225 PPFault Message eee eer ns 226 FaultMessage Fields 2222s 227 ErrorData Fields o a aaa a 227 ResponseEnvelope Fields a aoaaa 22s 228 Refund Examples Using NVP and CURL leen 228 Refund Errors a0 2 sa ae ba wee A mai RA a A XOR m RE a m 230 13 GetFundingPlans API Operation 233 GetFundingPlans Overview oaoa a ss 233 Additional Notes About the Pay API Operation aooo aa 233 GetFundingPlansRequest Message eo 233 GetFundingPlansRequest Fields 0 000 lll 234 RequestEnvelope Fields a a 234 GetFundingPlansResponse Message a 234 GetFundingPlansResponse Fields 236 FundingPlan Fields o 236 Currency Type Fields s gt soe ek ege as da aa es 237 FundingSource Fields o ssa s aa 2222s 238 CurrencyConversion Fields 2222s 239 ResponseEnvelope Fields 22e 239 PPFault Message 2l llle ee 240 FaultMessage Fields 2 a 241 EmorDataFields 2222s 241 ResponseEnvelope Fields aaa a 242 GetFundingPlan Errors oma 2l TE A a E sss 242 14 GetShippingAddresses API Operation 245 GetShippingAddressesRequest Message ee 245 GetShippingAddressesRequest Fields 245 RequestEnvelope Fields a 246 GetShippingAddressesResponse Message 2 ee 24
42. PayPal accounts Mexican Peso MXN Norwegian Krone NOK New Zealand Dollar NZD Philippine Peso PHP Polish Zloty PLN Pound Sterling GBP Singapore Dollar SGD Swedish Krona SEK Swiss Franc CHF Taiwan New Dollar TWD Thai Baht THB Turkish Lira TRY NOTE The Turkish Lira is supported as a payment currency and currency balance only for Turkish PayPal accounts e U S Dollar USD feesPayer xs string The payer of PayPal fees Possible values are e SENDER Sender pays all fees for personal implicit simple parallel payments do not use for chained or unilateral payments e PRIMARYRECEIVER Primary receiver pays all fees chained payments only e EACHRECEIVER Each receiver pays their own fee default personal and unilateral payments e SECONDARYONLY Secondary receivers pay all fees use only for chained payments with one secondary receiver 114 August 7 2012 Adaptive Payments Developer Guide 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 ipnNotificationUrl xs string The URL to which all IPN messages for
43. Person on a social networking site makes a payment for a purchase to the receiver For example a sender sends money to pay for lunch at a restaurant In these cases the sender sends a payment to a single receiver The following example shows a sender making a simple payment Simple Payment m im Sender Receiver Parallel Payments A parallel payment is a payment from a sender that is split directly among 2 6 receivers Technically a parallel payment is a set of multiple payments made in a single Pay request Parallel payments are useful in cases when a buyer intends to make a single payment for items from multiple sellers Examples include the following scenarios e asingle payment for multiple items from different merchants such as a combination of items in your inventory and items that partners drop ship for you e purchases of items related to an event such as a trip that requires airfare car rental and a hotel booking In these cases the sender knows the receivers and the amount paid to each one The following example shows a sender paying 3 receivers in a single parallel payment August 7 2012 Adaptive Payments Developer Guide Introducing Adaptive Payments E Simple Parallel and Chained Payments Parallel Payment Receiver 1 10 a Sender Receiver 2 100 45 Receiver 3 45 NOTE This scenario is an example only and does not take PayPal fees into account Chained Payments A chained
44. PreapprovalResponse Message The PreapprovalResponse message contains a preapproval key This key uniquely identifies the preapproval for this request and can be used in other Adaptive Payment APIs to identify this specific preapproval E PreapprovalResponse ResponseEnvelope e timestamp 1 1 dateTime ack 1 1 AckCode Gi responseEnvelope 1 1 ResponseEnvelope ona Ef preapprovalkey 1 1 string FE any 0 e correlationId 1 1 string build 1 1 string FE any 0 PreapprovalResponse Fields Field Description preapprovalKey xs string A preapproval key that identifies the preapproval requested You can use this key in other Adaptive Payment requests to identify this preapproval 170 August 7 2012 Adaptive Payments Developer Guide Preapproval API Operation NE 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 e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message build xs string Build number It is used only by PayPal Merchant Technical
45. THB Turkish Lira TRY NOTE The Turkish Lira is supported as a payment currency and currency balance only for Turkish PayPal accounts e U S Dollar USD refundInfoList ap RefundInfoList List of refunds associated with the payment responseEnvelope common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status Adaptive Payments Developer Guide August 7 2012 221 SS 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 onld errorList receiver refundFeeAmount refundGrossAmount refundHasBecomeFull refundNetAmount xs string The PayPal transaction ID for this refund NOTE This ID is different than the transaction ID for the original payment ap ErrorList Information about why a refund failed ap Receiver Information about the receiver of the refund xs decimal Amount of fees that have been refunded xs decimal Gross amount of the refund including the total amount from this receiver and fees xs boolean Whether you have refunded the total amount of the payment Possible values are e true Entire amount of the payment has been refunded e false Entire amount of the payment has not been refunded NOTE This field i
46. The account for the counter party is locked or inactive 560011 Because a complaint case exists on this transaction only a refund of the full or full remaining amount of the transaction can be issued 560016 You cannot do a partial refund on this transaction August 7 2012 Adaptive Payments Developer Guide Refund API Operation Refund Errors Code Message Additional Information 560018 570012 570013 570014 570015 570017 579051 580001 580022 580027 589018 589023 580029 580030 589036 589037 589038 589041 589052 589061 You cannot refund this type of transaction Cannot do a full refund after a partial refund The partial refund amount must be less than or equal to the original transaction amount The partial refund amount must be less than or equal to the remaining amount This transaction has already been fully refunded You are over the time limit to perform a refund on this transaction The tracking ID is invalid Invalid request Invalid request parameter payKey with value lt value gt The argument is unsupported The pay key is valid If a fractional amount is rounded due to currency conversion funds could be lost A pay key transaction ID or tracking ID is missing This transaction cannot be processed at this time Please try again later The currency code is missing or does not match the code in the payment request The refund s receiver was not part of the payment
47. advance personal payment or unilateral payment Additional fields for refunds of specific amounts to specific receivers Field Description receiverList receiver n email receiverList receiver n amount The receiver s email address where n is between 0 and 5 for a maximum of 6 receivers Amount to refund from the receiver identified by email address A payment can also be identified as a set of PayPal transactions between the sender and each specific receiver You can refund the amount of the transaction by specifying the transaction ID August 7 2012 Adaptive Payments Developer Guide Refund API Operation E Refund API Overview Refunds that apply to a PayPal transaction associated with the payment Field Description transactionld 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 e PayPal sends an email to all PayPal account holders affected by the refund e PayPal sends an IPN message to the URL specified in the ipnNotificationUrl field of the Pay request Additional Notes About the Refund API Operation 1 Payments made using the Pay API operation cannot be refunded using the RefundTransaction API operation You must use the Refund API operation or log in to PayPal to issue the refund 2 A personal account holder canno
48. also have permission from PayPal to use the advanced service For example if an application supports chained payments both you and the third party must have permission to use the service Explicit Approval Payment Flow Explicit approval payments require the sender to log in to paypal com to approve the payment You control the interaction between your application and PayPal by specifying URLs for redirection in various situations Adaptive Payments Developer Guide August 7 2012 23 j 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 Legend gt Web Flow gt API Call O Pay Key D Pay request t M l8l PayPal API Server Pay 2 Pay key O Send money 3 HTTP redirect o 4 HTTP redirect to return URL Your site 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 You redirect your sender s browser to paypal com 4 After the sender authorizes the transfer of funds PayPal redirects your sender s browser to the location you specify NOTE The cancel operation is not shown in the diagram Cancellation
49. and are based on criteria such as the transaction volume of the receiver In the examples that follow the fees shown are representative only and not actual fees Sender Pays the Fee The sender can pay a fee for a simple payment parallel payment or a chained payment The following example shows fees being paid by the sender of a parallel payment based on the assessment for each receiver Receiver 1 200 No fees a Ca Sender Receiver 2 500 170 Fees No fees 5 10 2 70 3 03 Receiver 3 130 No fees In this example the sender pays a total of 510 83 which includes all fees Adaptive Payments Developer Guide August 7 2012 61 al Introducing Adaptive Payments Fee Payment Configuration NOTE 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 a rms Receiver 1 200 Fees 5 10 DO Sender Receiver 2 500 170 Fees a 3 03 Receiver 3 130 Fees 2 70 NOTE The scenario above is an example only and is not representative of actual PayPal fees Each Receiver Pays the Fee in a Chained Payment If the receivers pay the fee in a chained payment each receiver pays a portion of the fee based on th
50. backupFundingSource 0 1 se e senderFees e currencyConversion e charge 0 1 0 1 1 string Currency Type FundingSource CurrencyType CurrencyConversion FundingPlanCharge F any 0 E CurrencyConversion e from e to 1 1 CurrencyType 1 1 CurrencyType e exchangeRate 1 1 decimal T l any 0 E FundingPlanCharge e charge 1 1 Currency Type ees e fundingSource 1 1 FundingSource Ej any 0 August 7 2012 E CurrencyType e code 1 1 string e amount 1 1 decimal E FundingSource e lastFourOfAccountNumber 0 1 string type 1 1 string displayName 0 1 string Ef FundingSourceld 0 1 string e allowed 0 1 boolean F any 0 E CurrencyConversion e from 1 1 CurrencyType e to 1 1 CurrencyType e exchangeRate 1 1 decimal El any o E FundingPlanCharge e charge 1 1 CurrencyType e fundingSource 1 1 FundingSource F any 0 E CurrencyType e code 1 1 string e amount 1 1 decimal E CurrencyType e code 1 1 string e amount 1 1 decimal E FundingSource e lastFourOfAccountNumber 0 1 string e type 1 1 string e displayName 0 1 string Fl any 0 Adaptive Payments Developer Guide Pay API Operation m PayResponse Message Ea PayError Ej Receiver Ef receiver 1 1 Receiver Ef amount 1 decimal
51. code Allowable values are e Australian Dollar AUD e Brazilian Real BRL NOTE The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts Canadian Dollar CAD Czech Koruna CZK Danish Krone DKK Euro EUR Hong Kong Dollar HKD Hungarian Forint HUF Israeli New Sheqel ILS Japanese Yen JPY Malaysian Ringgit MYR NOTE The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts Mexican Peso MXN Norwegian Krone NOK New Zealand Dollar NZD Philippine Peso PHP Polish Zloty PLN Pound Sterling GBP Singapore Dollar SGD Swedish Krona SEK Swiss Franc CHF Taiwan New Dollar TWD Thai Baht THB Turkish Lira TRY NOTE The Turkish Lira is supported as a payment currency and currency balance only for Turkish PayPal accounts e U S Dollar USD Adaptive Payments Developer Guide August 7 2012 199 ConvertCurrencyRequest Message CurrencyList Fields ConvertCurrency API Operation Field Description currency ap CurrencyType Required The currency code Allowable values are Australian Dollar AUD Brazilian Real BRL NOTE The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts Canadian Dollar CAD Czech Koruna CZK Danish Krone DKK Euro EUR Hong Kong Dollar HKD Hungari
52. completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message xs string Build number It is used only by PayPal Merchant Technical Support xs string Correlation identifier It is a 13 character alphanumeric string for example db87c705a910e that is used only by PayPal Merchant Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues 132 August 7 2012 Adaptive Payments Developer Guide ExecutePayment API Operation NER PPFault Message Field Description timestamp xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs FaultMessage E ResponseEnvelope e responseEnvelope 1 1 ResponseEnvelope e timestamp 1 1 dateTime e error 0 ErrorData ack 1 1 AckCode e correlationId 1 1 string build 1 1 string T any 0 ErrorData errorId long domain string e subdomain
53. display NOTE The headerImageUrl and businessName parameters are mutually exclusive only one of these fields can be used If you specify both the image will take precedence over the business name August 7 2012 Adaptive Payments Developer Guide GetPaymentOptions API Operation NER 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 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 Maximum length 127 characters firstName xs string Required The first name of the consumer as known by the institution Maximum length 64 characters institutionCustomerId xs string Required The unique identifier assigned to the consumer by the institution Maximum length 64 characters institutionId xs string Required The unique identifier assigned to the in
54. e all transactions within the single Pay request must be person to person e feesPayer field set to EACHRECEIVER or SENDER e 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 Adaptive Payments Developer Guide August 7 2012 277 ES 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 e true Includes the billing address in the response e 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 Permission Levels Changes to the PreapprovalDetails API Operation 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 Th
55. field 93 143 154 239 displayOptions request field 152 DisplayOptions request fields 153 displayOptions response field 142 DisplayOptions response fields 142 domain field 94 98 122 131 134 148 159 173 186 195 208 224 227 241 250 E email request field 86 156 email response field 120 143 145 154 emailHeaderImageUrl request field 153 emailHeaderImageUrl response field 142 emailMarketinglmageUrl request field 153 emailMarketingImageUrl response field 142 embedded payment flow command 254 encryptedRefundTransactionId response field 222 endingDate request fields 167 August 7 2012 endingDate response field 182 environments production sandbox beta sandbox 66 error PPFault field 97 122 134 147 158 172 186 194 207 227 241 249 error response field 94 130 ErrorData fields 94 98 122 131 134 148 159 173 186 195 208 224 227 241 250 errorId field 94 98 122 131 134 148 159 173 186 195 208 224 227 241 250 errorLanguage request field 86 110 128 140 156 170 178 192 202 218 234 246 errorList response field 222 estimatedAmountTable response field 203 exceptionID field 94 98 122 131 134 148 159 173 186 195 208 224 227 241 250 exchangeRate response field 93 239 ExecutePayment API operation 127 ExecutePaymentRequest message 127 ExecutePaymentRequest request fields 127 ExecutePaymentResponse fields 130 ExecutePaymentResponse message 128 extension re
56. gt Since 1 6 0 580022 e Invalid request parameter payKey with value lt value gt e payKey lt value gt has already been used to make a payment e displayOptions has already been set and cannot be set multiple times e initiationEntity has already been set and cannot be set multiple times e Invalid Request Parameter institutionId with value lt value gt e The instituion ID lt value gt is not activated Adaptive Payments Developer Guide August 7 2012 161 al SetPaymentOptions API Operation SetPaymentOptions Errors Code Message Additional Information 580022 Invalid request parameter lt value gt Since 1 6 0 Invalid Request Parameter institutionId with value lt value gt The institution id lt value gt is not activated The clientDetails parameter is missing Invalid request parameter payKey with value lt value gt Invalid Phone Country Code lt value gt Invalid Country Code lt value gt for Receiver Invalid Receiver Phone Type lt value gt lt value gt lt value gt Invalid Phone Format lt value gt lt value gt Invalid Phone Number lt value gt lt value gt Invalid Receiver Phone Number lt value gt lt value gt Invalid Area or Exchange Code lt value gt lt value gt lt value gt has already been set and cannot be set multiple times Invalid request parameter lt value gt with value lt value gt Invalid request parameter lt value gt lt value gt is invalid Invalid request parameter
57. has been successfully created The reference number for this agreementis PA 8US9675113297773C PayPal protects your privacy and security Tn v ee RIO NI PON A NOOO IO NN NOS NIE ROO RR RR A NU AA NOTE 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 requireShippingAddressSelection to true in your request to SetPaymentOptions Adaptive Payments Developer Guide August 7 2012 39 al Introducing Adaptive Payments Embedded Payments Raymond Adams Log out Receiver Amount Rapid Action Towing 1 75 1 75 USD j Pay with American Express 300049275 1 75 USD Ship to 2693069 W 15th Street Ventura Y t 2693069 WW 15th Street Ventura CA Add new shipping address PayPal protects your privacy and security I H Hi t i H i i i i H H i H t i t t t i i E Hi t i t t t i E t i H t i Hi T t t t i t i H i t Hi t i i i t Li t Hi t i i H H i H t i t t B The sender of a payment can select one of the available shipping addresses or add a new shipping address by selecting Ad
58. invoiceId xs decimal Required Amount to be paid to the receiver xs string Receiver s email address This address can be unregistered with paypal com If so a receiver cannot claim the payment until a PayPal account is linked to the email address The PayRequest must pass either an email address or a phone number Maximum length 127 characters xs string Optional The invoice number for the payment This data in this field shows on the Transaction Details report Maximum length 127 characters 84 August 7 2012 Adaptive Payments Developer Guide Pay API Operation BN PayRequest Message Field Description paymentType xs string Optional The transaction type for the payment Allowable values are GOODS This is a payment for non digital goods SERVICE This is a payment for services default PERSONAL This is a person to person payment CASHADVANCE This is a person to person payment for a cash advance DIGITALGOODS This is a payment for digital goods BANK MANAGED WITHDRAWAL This is a person to person payment for bank withdrawals available only with special permission NOTE Person to person payments are valid only for parallel payments that have the feesPayer field set to EACHRECEIVER or SENDER paymentSubType xs string Optional The transaction subtype for the payment phone common PhoneNumberType A type to specify the receiver s phone number The PayRequest must pass either an emai
59. is en_US which is the only language currently supported 156 August 7 2012 Adaptive Payments Developer Guide SetPaymentOptions API Operation E SetPaymentOptionsResponse Message SetPaymentOptionsResponse Message E SetPaymentOptionsResponse ResponseEnvelope e timestamp 1 1 dateTime e ack 1 1 AckCode e correlationId 1 1 string build 1 1 string 7 any 0 Gi responseEnvelope 1 1 ResponseEnvelope Ej any 0 nes ResponseEnvelope Fields Field Description ack common AckCode Acknowledgement code It is one of the following values e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message build xs string Build number It is used only by PayPal Merchant Technical Support correlationId xs string Correlation identifier It is a 13 character alphanumeric string for example db87c705a910e that is used only by PayPal Merchant Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Tec
60. lt b gt lt legend gt Pay Lightbox lt legend gt lt b gt lt input id type name expType value lightbox type hidden gt lt input id type name autoredirectondone type hidden gt label for paykey gt PayKey lt label gt lt input id paykey name payKey size 25 type text gt lt input type submit id submitBtn value Pay with light src https www paypal com en_US i btn x click but06 gif gt lt fieldset gt lt form gt iFrame Code lt iframe id PPDGFrame name PPDGFrame src https w paypal com webapps adapt ivepayment flow pay expType light amp paykey AP SAMPLEPAYKEY amp autoredirectondone scrolling no frameborder 0 style border none height 550px width 385px allowtransparency true gt 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 Adaptive Payments Developer Guide August 7 2012 265 a 1 6 0 Features 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 fundingSourceld New field xs string Optional Funding source ID Changes to JavaScript Functions for Embedded Payments You mus
61. merchants with one payment Your shopping cart allocates the payment to merchants that actually provided the items PayPal then deducts money from the sender s account and deposits it in the receivers accounts e Chained payments enable a sender to send a single payment to a primary receiver The primary receiver keeps part of the payment and pays secondary receivers the remainder For example your application could be an online travel agency that handles bookings for airfare hotel reservations and car rentals The sender sees only you as the primary receiver You allocate the payment for your commission and the actual cost of services provided by other receivers PayPal then deducts money from the sender s account and deposits it in both your account and the secondary receivers accounts NOTE Chained payments also include delayed chained payments in which payments to secondary receivers can be delayed for up to 90 days Adaptive Payments Developer Guide August 7 2012 19 20 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 e Buyer makes a payment on a merchant s website e Buyer makes a single payment for a cart of items from the same merchant e
62. only be made under the following conditions e simple and parallel payments not chained e all transactions within the single Pay request must be person to person e feesPayer field set to EACHRECEIVER or SENDER e this feature requires the appropriate permission level from PayPal 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 Changes to PaymentDetails response messages Field Description actionType New CREATE value e PAY Use this option if you are not using the Pay request in combinations with the ExecutePayment request e 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 276 August 7 2012 Adaptive Payments Developer Guide 1 4 0 Features ERE Field Description paymentType New person to person values PERSONAL and CASHADVANCE Allowable values are e GOODS This is a payment for goods e SERVICE This is a payment for services default e PERSONAL This is a person to person payment e CASHADVANCE This is a person to person payment for a cash advance Person to person payments can only be made under the following conditions e simple and parallel payments not chained
63. 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 NoTE The API caller must get permission from PayPal to use chained payments You can have at most one primary receiver and 1 5 secondary receivers Chained payments are useful in cases when the primary receiver acts as an agent for other receivers The sender deals only with the primary receiver and does not know about the secondary receivers including how a payment is split among receivers The following example shows a sender making a payment of 100 Adaptive Payments Developer Guide August 7 2012 21 22 Introducing Adaptive Payments Payment Approval Chained Payment a Receiver 2 naa 45 wmm Eus Sender Primary receiver M 100 10 Receiver 3 45 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 NOTE 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 For exam
64. payment key before initiating the flow and that the key does not change or expire before the sender completes the flow To set up a web page to invoke the embedded payment flow 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 Set the expType parameter to mini to indicate your preference for the context in which the PayPal payment flow is displayed lt form action https www paypal com webapps adapt ivepayment flow pay target PPDGFrame gt lt input id type type hidden name expType value mini gt lt input id paykey type hidden name paykey value AP gt lt input id preapprovalkey type hidden name preapprovalkey value PA gt lt input type submit id submitBtn value Pay with PayPal gt lt form gt NOTE To modify an existing application to use the embedded payment flow change the redirect from https www paypal com webscr cmd _ap payment amp paykey to https www paypal com webapps adaptivepayment flow pay paykey after obtaining the pay key 3 Include the PayPal JavaScript functions from apdg js lt script src https www paypalobjects com js external apdg js gt lt script gt Adaptive Payments Devel
65. receiver receives an email notifying the receiver to create an account and claim the payment PayPal holds a payment to a receiver whose email address is not yet registered or confirmed until the receiver creates a PayPal account and confirms the email address If a refund specifies a receiver whose email address is not yet registered or confirmed the payment to the receiver is canceled For a guest payment do not set the sender s email address or the preapproval key Specifying the sender s email address prevents the sender from choosing the guest payment option Implicit approval and preapproval options are not allowed Each receiver of a guest payment must be a verified PayPal business or premier account holder You can specify a value for either senderEmail or one of the SenderIdentifier fields If you use SenderIdentifier to identify the sender you can only specify sender email or set sender useCredentials to true but not both sender phone is reserved for future use Specify senderEmail or sender email to set up a payment where the sender and the API caller are the same implicit approval or for a preapproved payment If senderEmail or sender email is specified in the request the email address must be registered with paypal com If you do not include one of these fields in the payment request the sender can either log in using an existing account that is not associated with a receiver or create a new account during t
66. request The refund has to be both less than or equal to the original payment request and greater than zero All receivers must give full refunds for this type of chained payment The transaction ID is invalid The receiver lt value gt is invalid for this refund Since 1 6 0 Since 1 3 0 Since 1 6 0 Adaptive Payments Developer Guide August 7 2012 231 EA Refund API Operation Refund Errors 232 August 7 2012 Adaptive Payments Developer Guide 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 Overview To obtain the funding plans for a payment specify values for the following fields Required fields Field Description payKey The key used to create the payment whose funding sources you want to determine requestEnvelope errorLanguage The code for the language in which errors are returned which must be en US Additional Notes About the Pay API Operation 1 The GetFundingPlans API operation is only avail a be for implicitly approved payments meaning you must be both the sender and the caller of the Pay API operation identified by the pay key GetFundingPlansRequest Message
67. set up to create a payment request with the SetPaymentOptions request and then fulfill the payment with the ExecutePayment request Possible values are e PAY Use this option if you are not using the Pay request in combination with ExecutePayment e CREATE Use this option to set up the payment instructions with SetPaymentOptions and then execute the payment at a later time with the ExecutePayment e PAY PRIMARY For chained payments only specify this value to delay payments to the secondary receivers only the payment to the primary receiver is processed cancelUrl xs string The URL to which the sender s browser is redirected if the sender cancels the approval for a payment on paypal com Use the pay key to identify the payment as follows payKey payKey Adaptive Payments Developer Guide August 7 2012 113 ss PaymentDetails API Operation PaymentDetailsResponse Message Field Description currencyCode xs string The currency code Possible values are e Australian Dollar AUD e Brazilian Real BRL NOTE The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts Canadian Dollar CAD Czech Koruna CZK Danish Krone DKK Euro EUR Hong Kong Dollar HKD Hungarian Forint HUF Israeli New Sheqel ILS Japanese Yen JPY Malaysian Ringgit MYR NOTE The Ringgit is supported as a payment currency and currency balance only for Malaysian
68. string Field Description error common ErrorData Detailed error information responseEnvelope common ResponseEnvelope Common response information acknowledgement status including a timestamp and the response Adaptive Payments Developer Guide August 7 2012 147 148 GetPaymentOptions API Operation PPFault Message ErrorData Fields Field Description category common ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect domain xs string The domain to which this service belongs errorld xs long A 6 digit number that uniquely identifies a particular error exceptionID This field is not used message xs string A description of the error parameter common ErrorParameter Represents contextual information about the error severlty common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request was interrupted e 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 e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully howeve
69. string e exceptionId 0 1 token e parameter 0 ErrorParameter E PhoneNumberType e countryCode 1 1 string e phoneNumber 1 1 string extension 0 1 string 5 ErrorSeverity E ErrorCategory E ErrorParameter name string August 7 2012 129 SS ExecutePayment API Operation ExecutePaymentResponse Message ExecutePaymentResponse Fields Field Description payErrorList paymentExecStatus responseEnvelope ap PayErrorList Information about why a payment failed xs string The status of the payment Possible values are e CREATED The payment request was received funds will be transferred once the payment is approved e COMPLETED The payment was successful e INCOMPLETE Some transfers succeeded and some failed for a parallel payment e ERROR The payment failed and all attempted transfers failed or all completed transfers were successfully reversed e REVERSALERROR One or more transfers failed when attempting to reverse a payment IMPORTANT You must test the value of paymentExecStatus for an error even if responseEnvelope ackis Success If the PaymentExecStatus is ERROR the Pay Key can no longer be used common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status PayErrorList Fields Field Description payError PayError indicates the error if any that resulted on an attempted paym
70. this payment are sent memo xs string A note associated with the payment payKey xs string The pay key that identifies this payment This is a token that is assigned by the Pay API after a PayRequest message is received and can be used in other Adaptive Payments Methods as well as the cancelURL and returnURL to identify this payment The pay key is valid for 3 hours payment InfoList ap Payment InfoList 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 preapprovalKey xs string The preapproval key that identifies the preapproval for this payment This key can be used in other Adaptive Payment APIs to identify the preapproval responseEnvelope common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status returnUrl xs string reverseAllParallelPaymen tsOnError sender senderEmail The URL to which the sender s browser is redirected after approving a payment on paypal com Use the pay key to identify the payment as follows payKey payKey xs string Whether to reverse parallel payments Possible values are e true Each parallel payment is reversed if an error occurs e false Each parallel payment is not reversed if an error occurs ap SenderIdentifer Sender information xs string The sender s email address Adaptive Payments Developer Guide
71. with My PayPal Balance e Your order information has been sentto pbehara usbuyer paypal com PayPal protects your privacy and security 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 If you specify both a payment key and a preapproval key when you call the Pay API operation PayPal displays the checkbox on the payment page in the minibrowser Adaptive Payments Developer Guide August 7 2012 37 j Introducing Adaptive Payments Embedded Payments Review Your Purchase PayPal Windows Internet E jo Jos Ramirez Log out Receiver Amount Rapid Action Towing 5 00 5 00 USD My PayPal Balance View PayPal policies 5 00 USD My PayPal Balance y Memo Payment Preapprove future payments to Pretty Flower Florist Pay Cancel PayPal protects your privacy and security If the payment sender ieee the EOE box the confirmation page provides details about the preapproval 38 August 7 2012 Adaptive Payments Developer Guide Introducing Adaptive Payments Embedded Payments E Jos R mirez Log out Thank you for using PayPal Receiver Amount Rapid Action Towing 5 00 5 00 USD Order Details e You paid with My PayPal Balance e Your order information has been sentto pbehara usbuyer paypal com Preapproval Details e Your preapproval agreement
72. 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 NOTE The cancel operation is not shown in the above diagram Cancellation is handled by a separate cancellation URL to which PayPal redirects the sender s browser any time the sender cancels while on paypal com In addition to the steps shown above PayPal sends an email notifying you and the sender that the preapproval has been created After the sender sets up the approval you can make payments on the sender s behalf directly The sender is no longer required to log in to PayPal to complete the payment The following diagram shows the basic flow of control during a Pay operation Legend ww API Call O Pay Key D Pay request PayPal API Server Pay 2 Pay key O 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 You can require the sender to provide a personal identification number PIN however logging in to paypal com is no longer required NOTE You must provide a preapproval key that identifies the agreement 2 PayPal still responds with a
73. 017 The preapproval key has been suspended 569018 Preapproved payments have been disabled 569019 The preapproval has been suspended due to too many PIN failures 569042 The email account is not confirmed by PayPal 579007 The maximum number of receivers is lt number gt 579010 If a preapproval key is specified the sender s email address must be too 579014 The preapproval key specifies a different sender than the payment request 579017 The amount for the primary receiver must be greater than or equal to the total of other chained receiver amounts 579024 The preapproval key cannot be used before the start date or after the end date 579025 The preapproval key cannot be used on this weekday 579026 The preapproval key cannot be used on this day of the month August 7 2012 Adaptive Payments Developer Guide ExecutePayment API Operation ExecutePayment Errors Code Message Additional Information 579027 579028 579030 579031 579033 579040 579042 579045 579047 579048 580001 580022 580022 580022 580023 580027 580028 580029 580029 580030 589009 589023 589039 The preapproval key specifies a different currency than the payment request The payment amount exceeds the maximum amount per payment The number of payments made this period exceeds the maximum number of payments per period The total amount of all payments exceeds the maximum total amount for all payments The sender
74. 1 1 CurrencyType e code 1 1 string to 1 1 CurrencyType e amount 1 1 decimal e exchangeRate 1 1 decimal FE any 0 E FundingPlanCharge CurrencyType e charge 1 1 CurrencyType e code 1 1 string ees e fundingSource 1 1 FundingSource e amount 1 1 decimal F any 0 E FundingSource e lastFourOfAccountNumber 0 1 string e type 1 1 string e displayName 0 1 string FE any 0 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 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 236 August 7 2012 Adaptive Payments Developer Guide GetFundingPlans API Operation GetFundingPlansResponse Message Field Description currencyConversion charge ap CurrencyConversion The currency conversion associated with the funding plan ap FundingPlanCharge The amount to be charged to this funding plan CurrencyType Fields Field amount Description xs decimal The con
75. 1 Invalid request value 580022 e Invalid request parameter value e The clientDetails parameter is missing e The PIN is invalid Adaptive Payments Developer Guide August 7 2012 271 al 1 6 0 Features Code Message 580022 Invalid request parameter lt value gt The clientDetails parameter is missing Invalid request parameter payKey with value lt value gt payKey lt value gt is expired Invalid request parameter lt value gt with lt value gt No sender is associated with this key The funding plan data is not present payKey lt value gt has already been used to make a payment 580022 Invalid request parameter lt value gt Invalid Request Parameter institutionId with value lt value gt The institution id lt value gt is not activated The clientDetails parameter is missing Invalid request parameter payKey with value lt value gt Invalid Phone Country Code lt value gt Invalid Country Code lt value gt for Receiver Invalid Receiver Phone Type lt value gt lt value gt lt value gt Invalid Phone Format lt value gt lt value gt Invalid Phone Number lt value gt lt value gt Invalid Receiver Phone Number lt value gt lt value gt Invalid Area or Exchange Code lt value gt lt value gt lt value gt has already been set and cannot be set multiple times Invalid request parameter lt value gt with value lt value gt Invalid request parameter lt value gt lt value gt is invalid In
76. 264 countryCode response field 95 120 143 145 154 184 225 247 curPayments response field 180 curPaymentsAmount response field 180 curPeriodAttempts response field 180 curPeriodEndingDate response field 180 currency request field 200 currency response field 205 currencyCode request field 80 201 216 currencyCode request fields 166 currencyCode response field 114 181 221 CurrencyCodeList request fields 201 currencyConversion response field 91 237 CurrencyConversion response fields 93 239 August 7 2012 293 294 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 customld request field 155 customld response field 144 D dateOfMonth request fields 166 dateOfMonth response field 181 dayOfWeek request fields 167 dayOfWeek response field 182 defaultFundingPlan response field 90 description request field 155 description response field 144 detailLevel request field 86 110 128 139 156 170 178 192 202 218 234 246 displayMaxTotalA mount request field 168 displayMaxTotalA mount response field 183 displayName response
77. 3 CurrencyConversionTable Fields 0 4 203 CurrencyConversionList Fields sn 204 Currency Type Fields ser sa a a Oa araok a a a RARUS a 204 CurrencyList Fields 2l lll 205 ResponseEnvelope Fields 2er 206 PPFault Message 2l les ee 206 FaultMessage Fields 2222s 207 ErrorData Fields a 208 ResponseEnvelope Fields o o eo 208 ConvertCurrency Errors lll sns 209 Chapter 12 Refund API Operation 211 Refund API Overview 2 6 aa a a a 211 Refund Notifications a lll les 213 Additional Notes About the Refund API Operation 213 RefundRequest Message a 214 RefundRequest Fields a aoaaa a a 215 ReceiverList Fields oaoa aaa a 217 Receiver Fieldsi ens lia ca tia as 217 PhoneNumberType Fields lees 218 RequestEnvelope Fields 22e 218 Refund Response Message ers 219 RefundResponse Fields lens 221 RefundlnfoList Fields o cnn 222 Refundinfo Fields 22e 222 EmorDataFields 22h 224 Receiver Fields s s s veu 204 vod uox ede ode Xo8 x POE X x X Wi domus 224 Adaptive Payments Developer Guide August 7 2012 9 EN Contents Chapter Chapter PhoneNumberType Response Fields e 225 ResponseEnvelope
78. 6 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 ClientDetails deviceID xs string Required A note about the preapproval This field is now optional it is no longer required Changes to Preapproval Details API Operation for Version 1 2 0 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 August 7 2012 Adaptive Payments Developer Guide 1 1 0 Features EE Changes to the Pay API Operation for Version 1 1 0 Changes to PayRequest message Field Description logDefaultShippingAddres New field S xs boolean Optional Whether or not to associate the receiver s default shipping address with the transaction clientDetails deviceld This field is now optional it is no longer required Changes to PayResponse message Field Description payErrorList New fie
79. 6 GetShippingAddressesResponse Fields 247 Address Fields acsi sa cR xo RUE RRR RE ew e RR e dE Dd 247 BaseAddress Fields aaa lll 247 ResponseEnvelope Fields 2 2 000 a 248 PPFault Message aaa aaa a 248 August 7 2012 Adaptive Payments Developer Guide Contents E FaultMessage Fields 2 22e 249 ErrorData Fields 2 ra e a a a aa Aa E aA a D a a a e ala 250 ResponseEnvelope Fields oaoa a a aa a 250 GetShippingAddresses Errors 2 2 1 a 251 Chapter 15 Adaptive Payment Commands and Redirects 253 Adaptive Payment Commands 2222s 253 _ap payment Command 2l ll sss 253 ap preapproval Command 2l ees 254 Embedded Payment Flow Redirect 0 00002 eee eee eee 254 JavaScript Functions for Embedded Payments lll 255 Chapter 16 Instant Payment Notifications 257 Pay Message Variables 22s 257 Preapproval Message Variables 222r 260 Older Versions of the Adaptive Payments API 263 1 8 0 Features a a a a a a a ie 263 Changes to SenderOptions e 263 Changes to ConvertCurrencyRequest Fields for Version 1 8 0 264 Changes to JavaScript Functions for Embedded Payments 264 New JavaScript Function for Version 1 8 0 AutoRedirectOnDone 264 1 7 0 Features 4 ede eo a e a a e de Res e ke A
80. 693069 W 15th Street Ventura CA Add new shipping address PayPal protects your privacy and security 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 54 Introducing Adaptive Payments Embedded Payments Add Shipping Address PayPal Mozilla Firefox Ek E https flocalhost paypal com 8443 webapps adaptivepaymen Y Raymond Adams EE Add Shipping Address Your Country or Region United States Y First name Middle name Last name Address 1 Address 2 optional ZIP Code PayPal protects your privacy and security the Thank you for using PayPal page August 7 2012 Adaptive Payments Developer Guide Introducing Adaptive Payments aa Embedded Payments 1 Raymond Adams i Log out Thank vou for using PayPal Receiver Amount Rapid Action Towing 1 75 Total 1 75 USD f El Order Details You paid with American Express XXxK 9275 Your order information has been sent to josilva STAGE 2VM5199 US 20101111151156140860307 paypal com Shipping Address 2693069 W 15th Street Ventura CA f PayPal protects your privacy and security ax You can call the GetShippingAddresses API operation to obtain the selected shipping address for the transaction using the key assoicated with the payment Setting U
81. 7 2012 Adaptive Payments Developer Guide Adaptive Payment Commands and Redirects NX 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 DGFlow function Sets up the embedded payment flow where trigger is one or more trigger null expType null HTML ids of events that trigger the flow and expType is one of the following experience type requests e light requests that the embedded payment flow displays in a lightbox default e mini requests that the embedded payment flow displays in a minibrowser PayPal handles other values including misspellings as Light Opening a minibrowser in a lightbox causes errors during the flow NOTE PayPal does not honor the lightbox experience request if the sender is required to log into PayPal setTrigger function id Add a trigger for the flow where idis the HTML id of the event that triggers the flow The flow must first be set up by calling PAYPAL apps DGFlow startFlow function url Explicitly start the embedded payment flow where ur1 is the URL that triggers the flow NOTE You are only r
82. 93 196 206 209 226 228 240 242 248 251 to response field 93 239 totalOfAllRefunds response field 223 totalShipping request field 155 totalShipping response field 144 totalTax request field 155 totalTax response field 144 trackinglId IPN variable 260 trackingld request field 82 217 trackingld response field 116 transac tion n receiver IPN variable 259 transaction type IPN variable 257 260 transaction n amount IPN variable 259 Ad IPN variable 258 Aid for sender IPN variable 258 Invoiceld IPN variable 259 transaction n is primary receiver IPN variable 259 transaction n refund account charged IPN variable 259 transaction n refund amount IPN variable 259 transaction n refund id IPN variable 259 transaction n status IPN variable 258 transaction n status for sender txn IPN variable 259 transactionId request field 217 transactionId response field 118 transactionStatus response field 118 type response field 93 184 239 248 transaction n transaction n transaction n Sa a a August 7 2012 297 U useCredentials request field 86 useCredentials response field 15 119 120 August 7 2012 Adaptive Payments Developer Guide 298
83. ATURE 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 amp actionType PAY amp senderEmail sender domain amp receiverList receiver 0 email receiver domain amp receiverList receiver 0 amount 100 00 amp currencyCode USD amp feesPayer EACHRECEIVER amp memo Simple payment example amp cancelUrl http your cancel url amp returnUrl http your return url amp ipnNotificationUrl http your ipn notification url Response for an explicitly approved payment responseEnvelope timestamp 2009 07 13T12 3A34 3A29 316 07 3A00 amp responseEnvelope ack Success amp responseEnvelope correlationId d615a365bed61 amp responseEnvelope build DEV amp payKey AP 3TY01110684428730 amp paymentExecStatus CREATED NOTE You must redirect the sender to PayPal to complete the payment Response for an implicitly approved payment responseEnvelope timestamp 2009 07 10T11 3A47 3A29 311 07 3A00 amp responseEnvelope ack Success amp responseEnvelope correlationId 34e44c0bdbed6 amp responseEnvelope build DEV SpayKey AP 54224401WG093204T amp paymentExecStatus COMPLETED Parallel payment example In this example the sender makes a payment of 100 to a PayPal registered receiver and 50 to another PayPal registered receiver If an error occurs all funds are returned
84. AUD e Brazilian Real BRL NOTE The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts Canadian Dollar CAD Czech Koruna CZK Danish Krone DKK Euro EUR Hong Kong Dollar HKD Hungarian Forint HUF Israeli New Sheqel ILS Japanese Yen JPY Malaysian Ringgit MYR NOTE The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts Mexican Peso MXN Norwegian Krone NOK New Zealand Dollar NZD Philippine Peso PHP Polish Zloty PLN Pound Sterling GBP Singapore Dollar SGD Swedish Krona SEK Swiss Franc CHF Taiwan New Dollar TWD Thai Baht THB Turkish Lira TRY NOTE The Turkish Lira is supported as a payment currency and currency balance only for Turkish PayPal accounts e U S Dollar USD xs string Optional The payer of PayPal fees Allowable values are e SENDER Sender pays all fees for personal implicit simple parallel payments do not use for chained or unilateral payments e PRIMARYRECEIVER Primary receiver pays all fees chained payments only e EACHRECEIVER Each receiver pays their own fee default personal and unilateral payments e SECONDARYONLY Secondary receivers pay all fees use only for chained payments with one secondary receiver 80 August 7 2012 Adaptive Payments Developer Guide Pay API Operation BN PayRequest Message Field D
85. Adaptive Payments Developer Guide 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 The terms sender and receiver refer to sender and receivers of the original payment using the Pay API operation When making a refund the sender s account receives the refund and the receivers accounts are the source of the refund Refunds are made from one or more receivers to a sender To make a refund using the Refund API operation you must e have made a Pay request for which payment you want to refund the payment or you must have received the part of the payment you want to refund and e have permission to make a refund on behalf of the receiver unless you are also the receiver in other words each receiver whose account is the source of the refund must have granted you third party access permission to call the Refund API operation NOTE A receiver can grant you third party access to make a refund by logging in to PayPal choosing API Access on the Profile page then clicking the link to Grant API permission and selecting Refund after clicking Configure a custom API author
86. After clicking Log In PayPal displays a Log in to your PayPal account page in the minibrowser The sender enters an email address and password and can also check a box which allows the sender to skip this step for subsequent purchases Adaptive Payments Developer Guide August 7 2012 41 al Introducing Adaptive Payments Embedded Payments Log in to your PayPal account Windows Internet E Se eise pe enn PayPal a English K Log in to your PayPal account Email address PayPal password Have a security key Forgot your email address or password TF For faster checkout skip login for future purchases using this computer How it works bag cance PayPal protects your privacy and security 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 IMPORTANT Opting in to the remember me behavior does not guarantee that the sender will not be asked to provide log in credentials After logging in PayPal displays the You are about to pay page sometimes called the review your payment page in the minibrowser 42 August 7 2012 Adaptive Payments Developer Guide Introducing Adaptive Payments Embedded Payments Jos Ramirez esee PayPal j You are about to pay Receiver Amount Rapid Action Towing 5 00 Total 5 00 USD My PayPal Balance View PayPal p
87. E Your API signature which is required only if you use 3 token authorization a certificate does not use a signature X PAYPAL SECURITY SUBJECT Third party permission specification which specifies the email address or phone number for mobile of the party on whose behalf you are calling the API operation The subject must grant you third party access in their PayPal profile NOTE Resources specified by the API operation such as a payment or preapproval identified by a key must be owned by the subject granting the third party permission Specifying JSON NVP or XML Data Formats Use the HTTP header X PAYPAL REQUEST DATA FORMAT to specify the data format the request body You can send messages using JSON NVP or straight XML Use the and X PAYPAL RESPONSE DATA FORMAT headers to specify the data format for the response Adaptive Payments Developer Guide August 7 2012 67 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 e NV Name value pairs e XML Extensible markup language e JSON JavaScript object notation X PAYPAL RESPONSE DATA FORMAT The payload format for the response Allowable values are e NV Name value pairs e XML Extensible markup language e JSON JavaScript object notation SOAP Messages To use Adaptive Pay
88. Id 1 1 string build 1 1 string 6j any 0 E ErrorData errorId long domain string e subdomain 0 1 string severity ErrorSeverity category ErrorCategory e message string e exceptionId 0 1 token e parameter 0 ErrorParameter ErrorData E ErrorSeverity e errorId long domain string E ErrorCategory e subdomain 0 1 string ErrorParameter severity ErrorSeverity name string category ErrorCategory e message string e exceptionId 0 1 token e parameter 0 ErrorParameter FaultMessage Fields Field Description error common ErrorData Detailed error information responseEnvelope common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status 194 August 7 2012 Adaptive Payments Developer Guide CancelPreapproval API Operation NER PPFault Message ErrorData Fields Field Description category common ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect domain xs string The domain to which this service belongs errorld xs long A 6 digit number that uniquely identifies a particular error exceptionID This field is not used message xs string A desc
89. Includes information about embedded payments and a digital goods example 10 10 2010 Revised draft for version 1 6 0 07 13 2010 Revised draft for version 1 5 0 Includes information about guest payments 06 28 2010 Release draft for version 1 5 0 03 10 2010 Release draft for version 1 4 0 10 09 2009 Release draft for version 1 3 0 09 26 2009 Review draft for version 1 3 0 09 25 2009 Review draft for version 1 3 0 08 27 2009 Revised draft for version 1 3 0 08 17 2009 Revised draft for version 1 2 0 08 07 2009 Revised draft for version 1 1 0 07 16 2009 Initial draft for version 1 0 0 Adaptive Payments Developer Guide August 7 2012 291 292 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 response field 93 239 allowedFundingType request field 83 amount request field 198 amount response field 91 204 237 approved IPN variable 260 approved response field 180 backupFundingSource response field 91 236
90. It cannot exceed 2 000 USD or its equivalent in other currencies Contact PayPal if you do not want to specify a maximum amount currencyCode The code for the currency in which the payment is made you can specify only one currency regardless of the number of receivers cancelUrl URL to redirect the sender s browser to after canceling the preapproval returnUrl URL to redirect the sender s browser to after the sender has logged into PayPal and confirmed the preapproval requestEnvelope errorLanguage The code for the language in which errors are returned which must be en US Preapproval Notifications Notifications are sent after preapproval is complete Adaptive Payments Developer Guide August 7 2012 163 sss Preapproval API Operation PreapprovalRequest Message e PayPal sends an email to the sender that confirmed the approval e 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 constraints are additive thus for example if you specify a preapproval that allows payments only on Fridays and on the 13th day of the month the preapproval would be valid only on Friday the 13th of months within the specified time period 2 The startingDate and endingDate can be in either Zulu or GMT offset formats as in the following respective examples 2010 09 102 2010 09 10T17 24 03 874 07 00 Preappr
91. Overview lll sss es 163 Preapproval Notifications e 163 Additional Notes About the PreApproval API Operation 164 PreapprovalRequest Message ln 164 PreapprovalRequest Fields eee 165 ClientDetails Fields ee 169 RequestEnvelope Fields a 170 Adaptive Payments Developer Guide August 7 2012 7 EN Contents PreapprovalResponse Message 2 000 eee ee 170 PreapprovalResponse Fields 0 eee eee 170 ResponseEnvelope Fields 000 eee ee ee 171 PPFault Message ee 171 FaultMessage Fields 2 0 0 ee 172 ErrorData Fields us sca geek aw A OO a Ra o Oe SUR ee OR X 173 ResponseEnvelope Fields llle 173 Preapproval Examples Using NVP and CURL 22 2000 4 174 Preapproval Errors s sos s ea llle rns 175 Chapter 9 PreapprovalDetails API Operation 177 PreapprovalDetailsRequest Message lll ln 177 PreapprovalDetailsRequest Fields lll 177 RequestEnvelope Fields 22s 178 PreapprovalDetailsResponse Message 22e 178 PreapprovalDetailsResponse Fields o ee 180 AddressList Fields 2 2 ee 183 Address FieldS 25 5884 o UR Xo Rom XX RR Sa RO 183 BaseAddress Fields 22222 184 ResponseEnvelope Field 2e 184 PPFault Message geek a Sl dob ae a ee a 185 FaultMes
92. PAL APPLICATION ID app id https svcs sandbox paypal com AdaptivePayments PreapprovalDetails d preapprovalKey PA 9JR04288NR0519129 amp requestEnvelope errorLanguage en US Response responseEnvelope timestamp 2009 07 13T13 3A50 3A40 496 07 3A00 amp responseEnvelope ack Success amp responseEnvelope correlationId 16dbc35flaea7 amp responseEnvelope build DEV amp approved false amp cancelUrl your cancel url amp curPayments 0 amp curPayment sAmount 0 00 amp curPeriodAttempts 0 amp currencyCode USD amp dateOfMonth 0 amp dayOfWeek NO DAY SPECIFIED amp endingDate 2009 12 13T13 3A40 3A37 0 08 3A00 amp maxAmountPerPayment 200 00 amp maxNumberOfPayments 30 amp maxTotalAmountOfAllPayments 1500 00 amp paymentPeriod NO PERIOD SPECIFIED amp pinType NOT REQUIRED amp returnUrl your cancel url estartingDate 2009 07 13T13 3A40 3A37 0 07 3A00 amp status ACTIVE August 7 2012 Adaptive Payments Developer Guide PreapprovalDetails API Operation Preapproval Details Errors Preapproval Details Errors Code Message Additional Information 500000 520002 520003 520003 520006 540031 550001 580001 580001 589019 589019 There is a system error Internal error User name password is incorrect Authentication failed API credentials are incorrect This call is not defined in the database You do not have permission to get these preapproval details User is not allowed to perform this action Inv
93. PayPal 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 Soci t en Commandite par Actions Registered office 22 24 Boulevard Royal L 2449 Luxembourg R C S Luxembourg B 118 349 Consumer advisory The PayPal payment service is regarded as a stored value facility under Singapore law As such it does not require the approval of the Monetary Authority of Singapore You are advised to read the terms and conditions carefully Notice of non liability PayPal Inc is providing the information in this document to you AS IS with all faults PayPal Inc makes no warranties of any kind whether express implied or statutory with respect to the information contained herein PayPal Inc assumes no liability for damages whether direct or indirect caused by errors or omissions or resulting from the use of this document or the information contained in this document or resulting from the application or use of the product
94. Support correlationId xs string Correlation identifier It is a 13 character alphanumeric string for example db87c705a910e that is used only by PayPal Merchant Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs Adaptive Payments Developer Guide August 7 2012 171 a Preapproval API Operation PPFault Message E FaultMessage i ResponseEnvelope e responseEnvelope 1 1 ResponseEnvelope e timestamp 1 1 dateTime e error 0 ErrorData ack 1 1 AckCode e correlationId 1 1 string build 1 1 string 6j any 0 E ErrorData errorId long domain string e subdomain 0 1 string severity ErrorSeverity category ErrorCategory e message string e exceptionId 0 1 token e parameter 0 ErrorParameter ErrorData E ErrorSeverity e errorId long domain string E ErrorCategory e subdomain 0 1 string ErrorParameter
95. T l any 0 246 August 7 2012 ResponseEnvelope e timestamp 1 ack 1 e correlationId 1 e build 1 7 any 0 E Address Ef addresseeName 0 1 string Ef baseAddress 1 1 BaseAddress fe addressId 0 1 string F any 0 BaseAddress e linet iss e line2 0 E city 1 e state 0 e postalCode 0 e countryCode 1 type 0 7j any 0 1 dateTime AckCode string string string string string string string string string Adaptive Payments Developer Guide 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 addresseeName baseAddress addressId Description xs string The name associated with the address common BaseAddress Street address 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 linel xs string The first line of the address line2 xs string An second line of the street add
96. The type of address ResponseEnvelope Fields Field Description ack common AckCode Acknowledgement code It is one of the following values e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message build xs string Build number It is used only by PayPal Merchant Technical Support 184 August 7 2012 Adaptive Payments Developer Guide PreapprovalDetails API Operation NER 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 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs Fault Message ResponseEnvelope e responseEnvelope 1 1 ResponseEnvelope e timestamp 1
97. a web browser cookie If a device ID was passed with the PayRequest use the same ID here Maximum length 127 characters xs string Optional Sender s geographic location Maximum length 127 characters xs string Optional Sender s IP address If an IP addressed was passed with the PayRequest use the same ID here xs string Optional A sub identification of the application Maximum length 127 characters 82 August 7 2012 Adaptive Payments Developer Guide Pay API Operation BN 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 If this field is omitted the payment can be funded by any funding type that is supported for Adaptive Payments NOTE FundingConstraint is unavailable to API callers with standard permission levels for more information refer to the section Adaptive Payments Permission Levels NOTE To use iACH omit this field and do not specify a funding source for the payment FundingTypeList Fields Field Description fundingTypeInfo ap FundingTypeInfo Optional Specifies a list of allowed funding selections f
98. a910e that is used only by PayPal Merchant Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs FaultMessage ResponseEnvelope e responseEnvelope 1 1 ResponseEnvelope e timestamp 1 1 dateTime e error 0 ErrorData e ack 1 1 AckCode 240 e correlationId 1 1 string e build 1 1 string fl any 0 ErrorData e errorId long e domain string e subdomain 0 1 string e severity ErrorSeverity e category ErrorCategory message string e exceptionId 0 1 token e parameter 0 ErrorParameter August 7 2012 Adaptive Payments Developer Guide ErrorData E ErrorSeverity GetFundingPlans API Operation PPFault Message parameter FaultMessage Fields e errorId long domain string El ErrorCategory e subdomain 0 1 string severity ErrorSeverity E ErrorParameter e category ErrorCategory e message string
99. al key to identify the preapproval as follows preapprovalKey preapprovalKey curPayments The current number of payments by the sender for this preapproval curPaymentsAmount The current total of payments by the sender for this preapproval curPeriodAttempts The current number of payments by the sender this period for this preapproval curPeriodEndingDate Ending date for the current period Time is currently not supported 180 August 7 2012 Adaptive Payments Developer Guide PreapprovalDetails API Operation PreapprovalDetailsResponse Message Field Description currencyCode The currency code represented by the following values e Australian Dollar AUD e Brazilian Real BRL NOTE The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts Canadian Dollar CAD Czech Koruna CZK Danish Krone DKK Euro EUR Hong Kong Dollar HKD Hungarian Forint HUF Israeli New Sheqel ILS Japanese Yen JPY Malaysian Ringgit MYR NOTE The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts Mexican Peso MXN Norwegian Krone NOK New Zealand Dollar NZD Philippine Peso PHP Polish Zloty PLN Pound Sterling GBP Singapore Dollar SGD Swedish Krona SEK Swiss Franc CHF Taiwan New Dollar TWD Thai Baht THB Turkish Lira TRY NOTE The Turkish Lira is supported as a payment currenc
100. alid request Invalid request lt value gt The preapproval key is invalid The preapproval key lt value gt is invalid Since 1 6 0 Since 1 6 0 Since 1 6 0 Since 1 6 0 Adaptive Payments Developer Guide August 7 2012 189 SI PreapprovalDetails API Operation Preapproval Details Errors 190 August 7 2012 Adaptive Payments Developer Guide 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 fe RequestEnvelope E CancelPreapprovalRequest requestEnvelope 1 1 RequestEnvelope e detailLevel 0 1 DetaillevelCode sec f preapprovalkey 1 1 string so e errorLanguage 1 1 string 6 any 0 E any 0 CancelPreapprovalRequest Fields The table below lists the fields for the CancelPreapprovalRequest message Field Description preapprovalKey xs string Required The preapproval key that identifies the preapproval to be canceled requestEnvelope common requestEnvelope Required Information common to each API operation such as the language in which an error message is returned Adaptive Payments Deve
101. allel Payment responseEnvelope timestamp 2009 11 03T08 3A12 937 07 3A00 amp responseEnvelope ack Success amp responseEnvelope correlationId blcc3eabfa4c1 amp responseEnvelope build 942345 amp payKey AP 688241038Y786593D amp paymentExecStatus CREATED The response includes a pay key which is a token you use in subsequent calls to Adaptive Payments APIs to identify this particular payment 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 August 7 2012 Adaptive Payments Developer Guide Getting Started Ex 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 e You send a PayRequest enabling the primary receiver e You receive a response with a pay key e 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 The receiver only sees the transaction from the primary API caller The transactions from and to the receivers are hidden from the sender and receivers In the example below Tim makes a single payment of 100 to Frank who is the primary receiver Of this amount Frank keeps 25 and pays Yvonne 75 The following event sequence takes place Pay Request for Chaine
102. ame session e Preapproval cancellations This release includes a new API operation to allow consumers to cancel preapprovals the Cancel Preapproval API operation In past releases consumers could only cancel preapprovals through paypal com For more information refer to the CancelPreapproval API Operation section e 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 Adaptive Payments Developer Guide August 7 2012 279 EN 1 3 0 Features current Foreign Exchange rate For more information refer to the ConvertCurrenty API Operation section e 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 applicationld Version 1 3 0 require
103. amp currencyCode USD amp feesPayer EACHRECEIVER amp memo Simple payment example amp cancelUrl http your cancel url amp returnUrl http your return url amp ipnNotificationUrl http your ipn notification url amp receiverList receiver 0 paymentType DIGITALGOODS Response to a payment for digital goods d responseEnvelope timestamp 2009 07 13T12 3A34 3A29 316 07 3A00 amp responseEnvelope ack Success amp responseEnvelope correlationId d615a365bed61 amp responseEnvelope build DEV amp payKey AP 3TY01110684428730 amp paymentExecStatus CREATED NOTE You must redirect the sender to the following PayPal URL to complete the payment for digital goods https www paypal com webapps adapt ivepayment flow pay paykey Pay Errors Code Message Additional Information 500000 There is a system error 520002 Internal error 520003 User name password is incorrect 520003 e The caller s credential doesn t have permission for the fee Since 1 6 0 payer lt value gt e The caller s credential doesn t have permission for the payment type lt value gt e Authentication failed API credentials are incorrect 104 August 7 2012 Adaptive Payments Developer Guide Pay API Operation aa Pay Errors Code Message Additional Information 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 n
104. an Forint HUF Israeli New Sheqel ILS Japanese Yen JPY Malaysian Ringgit MYR NOTE The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts Mexican Peso MXN Norwegian Krone NOK New Zealand Dollar NZD Philippine Peso PHP Polish Zloty PLN Pound Sterling GBP Singapore Dollar SGD Swedish Krona SEK Swiss Franc CHF Taiwan New Dollar TWD Thai Baht THB Turkish Lira TRY NOTE The Turkish Lira is supported as a payment currency and currency balance only for Turkish PayPal accounts U S Dollar USD 200 August 7 2012 Adaptive Payments Developer Guide ConvertCurrency API Operation ConvertCurrencyRequest Message CurrencyCodeList Fields Field Description currencyCode xs string Required The currency code Allowable values are e Australian Dollar AUD e Brazilian Real BRL NOTE The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts Canadian Dollar CAD Czech Koruna CZK Danish Krone DKK Euro EUR Hong Kong Dollar HKD Hungarian Forint HUF Israeli New Sheqel ILS Japanese Yen JPY Malaysian Ringgit MYR NOTE The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts Mexican Peso MXN Norwegian Krone NOK New Zealand Dollar NZD Philippine Peso PHP Polish Zloty
105. and each receiver must have different accounts The receivers cannot belong to the same PayPal account The tracking ID already exists and cannot be duplicated The email account exceeds the receiving limit The email account exceeds the purse limit The email account exceeds the sending limit Invalid request Your request was invalid Check the parameter of the error to see which is invalid e Invalid request parameter payKey with value lt value gt e payKey lt value gt has already been used to make a payment The funding plan data is not present Since 1 6 0 Tried to pass in a non zero funding plan and there are no funding plans present Invalid request The argument is unsupported The URL lt value gt is malformed Invalid request A pay key transaction ID or tracking ID is missing Since 1 6 0 This transaction cannot be processed at this time Please try again Since 1 3 0 later This payment cannot be processed because no payment source is available If a fractional amount is rounded due to currency conversion funds could be lost The email address is invalid It may not be registered in PayPal s system yet Adaptive Payments Developer Guide August 7 2012 137 a ExecutePayment API Operation ExecutePayment Errors 138 August 7 2012 Adaptive Payments Developer Guide GetPaymentOptions API Operation You use the GetPaymentOptions API operation to retrieve the payment options passed with the SetPaymentOptio
106. and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs FaultMessage ResponseEnvelope e responseEnvelope 1 1 ResponseEnvelope e timestamp 1 1 dateTime e error 0 ErrorData e ack 1 1 AckCode e correlationId 1 1 string e build 1 1 string fl any 0 ErrorData e errorId long e domain string e subdomain 0 1 string e severity ErrorSeverity e category ErrorCategory message string e exceptionId 0 1 token e parameter 0 ErrorParameter Adaptive Payments Developer Guide August 7 2012 121 122 PaymentDetails API Operation PPFault Message le le le le le le le le ErrorData E ErrorSeverity errorId long domain string iE ErrorCategory subdomain 0 1 string severity ErrorSeverity E ErrorParameter category ErrorCategory message string exceptionId 0 1 token parameter 0 ErrorParameter FaultMessage Fields Field Descript
107. antage of being remembered Opting in reduces the number of steps to purchase goods or services without significantly increasing the risk that the sender s account might be misused After the initial login PayPal bypasses the login step if subsequent payments meet specific criteria such as a subsequent payment for a small amount Adaptive Payments Developer Guide August 7 2012 27 al Introducing Adaptive Payments Embedded Payments Embedded Payment Flow Presentations PayPal provides the following kinds of visual presentations for the embedded payment flow e 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 Jos Ramirez Not you Log out You are about to pay Receiver Amount Johnson Getaways Inc 1 00 1 00 USD My PayPal Balance View PayPal policies 1 00 USD My PayPal Balance Memo papalapapiricoipi Pay Cancel PayPal protects your privacy and security e The payment flow can appear in a minibrowser window that appears in front of your web page which does not require an IFRAME 28 August 7 2012 Adaptive Payments Developer Guide Innovate 2010 Introducing Adaptive Payments Embedded Payments Wwe 5 Review Your Purchase PayPal Google Chrome A https www paypal com webapps adaptivepayment flow corepay execution e lt lt as s s 5 A A A __ _ _
108. application s identification which is issued by PayPal NOTE 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 X PAYPAL SERVICE VERSION Optional The version of an API operation to use By default PayPal executes a request with the current version of an API operation NOTE PayPal recommends not specifying a version unless it is absolutely required Making a Simple Payment JSON A simple payment is when a sender whose account is debited sends a payment amount and currency to a single receiver whose account is credited e You send a PayRequest message to PayPal e You receive a response with a pay key e You must redirect the sender s browser to PayPal to approve the payment Pay Request for Simple Payment returnUrl http example com returnURL htm requestEnvelope errorLanguage en US currencyCode USD receiverList receiver email david example com V amount 10 00 cancelUr1 http example com cancelURL htm actionType PAY Pay Response for Simple Payment responseEnvelope timestamp 2009 10 06T14 30 39 383 07 00 ack Success correlationId cfe8 8783 1d3 build DEV ON payKey AP 17266198048308436 paymentExecStatus
109. as interrupted e Warning Processing of the request was completed This field is not used Receiver Fields Field Description amount xs decimal Amount to be refunded to the receiver email xs string Receiver s email address Maximum length 127 characters invoiceld xs string This fields is not used Maximum length 127 characters paymentType xs string This field is not used August 7 2012 Adaptive Payments Developer Guide Refund API Operation NER 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 Possible values are e true Primary receiver chained payment e false Secondary receiver simple parallel payment PhoneNumberType Response Fields Field Description countryCode xs string Telephone country code 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 e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully how
110. ata Fields Field Description category common ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect domain xs string The domain to which this service belongs errorld xs long A 6 digit number that uniquely identifies a particular error exceptionID This field is not used message xs string A description of the error parameter common ErrorParameter Represents contextual information about the error severlty common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request was interrupted e 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 e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message build xs string Build number It is used only by PayPal Merchant Technical Support Adaptive Payments Developer Guide August 7 2012 159 EM SetPaymentOptions API Operation SetPaymentOptions Examples Using NVP and CURL Field Descrip
111. ates a PayPal account and confirms the email address If a refund specifies a receiver whose email address is not yet registered or confirmed the payment to the receiver is canceled Adaptive Payments Developer Guide August 7 2012 213 214 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 The bank draft is usually completed within a couple of days At this time since the primary has enough funds in his account PayPal completes the refund to the buyer If the bank draft fails the refund request is cancelled NOTE The Refund API operation does not support iACH RefundRequest Message The refundRequest message specifies information about the refund and how it is to be allocated to PayPal account holders E RefundRequest Gi requestEnvelope 1 1 RequestEnvelope fe currencyCode 0 1 string payKey 0 1 string ses f transactionId 0 1 string trackingId 0 1 string receiverList 0 1 ReceiverList FE any E ReceiverList sec Ef receiver 1 Rec
112. bdomain 0 1 string ErrorSeverity e severity e category e message string e exceptionId 0 1 token e parameter 0 ErrorParameter ErrorCategory FaultMessage Fields Pay API Operation BE PPFault Message ResponseEnvelope e timestamp 1 1 dateTime ack 1 1 AckCode e correlationId 1 1 string build 1 1 string T any 0 ErrorData errorId long domain string e subdomain 0 1 string severity ErrorSeverity category e message string e exceptionId 0 1 token e parameter 0 ErrorParameter 5 ErrorSeverity E ErrorCategory ErrorParameter ErrorCategory name string Field Description error common ErrorData Detailed error information responseEnvelope common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status Adaptive Payments Developer Guide August 7 2012 97 98 Pay API Operation PPFault Message ErrorData Fields Field Description category common ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect domain xs string The domain to which this service belongs errorld xs long A 6 digit number that uniquely identifies a particular erro
113. ble values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect domain xs string The domain to which this service belongs errorld xs long A 6 digit number that uniquely identifies a particular error exceptionID This field is not used message xs string A description of the error parameter common ErrorParameter Represents contextual information about the error severlty common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request was interrupted e 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 e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message build xs string Build number It is used only by PayPal Merchant Technical Support August 7 2012 Adaptive Payments Developer Guide GetShippingAddresses API Operation Ng GetShippingAddresses Errors Field Description correlationId xs string Correlation identifier It is a 13 character alphanumeric string for example db87c705a910e that is used
114. ccount holder PayPal handles guest payments in the same way that it handles explicitly approved payments Instead of logging into PayPal to complete transaction the sender provides credit card information on the PayPal payment screen Adaptive Payments Developer Guide August 7 2012 59 al Introducing Adaptive Payments Fee Payment Configuration Mid Valley Construction Your payment summary Choose a way to pay Description Friends n Stitches Neediework 2 00 USO Pay with my PayPal account Raymond Adams Toni Pay with a credit or debit card M you dont have a PayPal account ntry United States va ES EJ Create a PayPal account NOTE 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 If receivers pay the fee you can specify whether the 60 August 7 2012 Adaptive Payments Developer Guide Introducing Adaptive Payments E 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 Fee payment configurations include e Sender Pays the Fee e Receiver Pays the Fee in a Parallel Payment e Each Receiver Pays the Fee in a Chained Payment e Primary Receiver Pays the Fee in a Chained Payment NOTE Fees are determined by PayPal
115. ceiver will be fully refunded if you specify the transaction ID requestEnvelope common requestEnvelope Required Information common to each API operation such as the language in which an error message is returned transactionId xs string Optional The PayPal transaction ID associated with the payment that you want to refund trackingld xs string Optional The tracking ID associated with the payment that you want to refund ReceiverList Fields Field Description receiver ap Receiver Required Receiver is the party whose account is credited Receiver Fields Field Description amount xs decimal Required Amount to be credited to the receiver s account email xs string Required Receiver s email address Maximum length 127 characters invoiceld xs string Optional This fields is not used Maximum length 127 characters paymentType xs string Optional This field is not used Adaptive Payments Developer Guide August 7 2012 217 sa Refund API Operation RefundRequest Message Field Description payment SubType 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 sp
116. cenarios Possible values are e 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 e 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 e 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 fora minibrowser on any page that invokes or terminates the embedded payment flow Function and Signature Description PAYPAL apps DGFlow function New expType trigger null expType null e mini requests that the embedded payment flow displays in a minibrowser 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
117. ckH When the sender clicks Close PayPal redirects the sender s browser to the return URL specified in the Pay API operation s request message NOTE 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 For subsequent payments in which PayPal does not require the account holder to log in again and the account holder has chosen to be remembered the PayPal payment pages appear in a lightbox rather than in a minibrowser and PayPal bypasses the log in steps For these payments the actions you take to launch the flow and close the lightbox remain the same For example the lightbox for reviewing a payment would appear in your page as follows Adaptive Payments Developer Guide August 7 2012 35 Introducing Adaptive Payments Embedded Payments Jos R mirez Not you Log out You are about to pay Receiver Amount 1 00 1 00 USD Pay with My PayPal Balance View PayPal policies My PayPal Balance x Memo papalapapiricoipi Pay Cancel PayPal protects your privacy and security 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 ES Jos R mirez Loa out Anou 1 00 1 00 USD e You paid
118. d Payment PayRequest lt requestEnvelope gt errorLanguage en US errorLanguage lt requestEnvelope gt cancelUrl xmlns gt http exammple com cancelURL htm lt cancelUrl gt lt actionType gt PAY lt actionType gt lt currencyCode xmlns gt USD lt currencyCode gt lt receiverList xmlns gt lt receiver gt lt amount gt 100 lt amount gt lt email gt frank example com lt email gt lt primary gt true lt primary gt lt receiver gt lt receiver gt amount gt 75 lt amount gt lt email gt yvonne example com lt email gt lt primary gt false lt primary gt lt receiver gt lt receiverList gt returnUrl xmlns gt http example com returnURL htm lt returnUrl gt lt PayRequest gt Adaptive Payments Developer Guide August 7 2012 71 al Getting Started Making a Chained Payment XML Pay Response for Chained Payment lt xml version 1 0 encoding UTF 8 gt lt ns2 PayResponse xmlns ns2 http svcs paypal com types ap gt lt responseEnvelope gt lt timestamp gt 2009 10 06T17 24 03 874 07 00 lt timestamp gt ack Success ack correlationId eca3a204200f4 correlationId lt build gt 1044393 lt build gt lt responseEnvelope gt lt payKey gt AP 688241038Y786593D lt payKey gt lt paymentExecStatus gt CREATED lt paymentExecStatus gt lt ns2 PayResponse gt The response includes a pay key which is a token you use in subsequent calls to Adaptive Payments APIs to ident
119. d d615a365bed61 amp responseEnvelope build DEV amp payKey AP 1CB41255YH2406602 amp paymentExecStatus CREATED Chained payment example In this example the sender makes a payment of 100 to a PayPal registered receiver who is identified as the primary receiver This receiver sends 50 of the 100 to another PayPal registered receiver Request Adaptive Payments Developer Guide August 7 2012 101 102 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 actionType PAY amp cancelUrl http your cancel url amp clientDetails applicationId fitnesse amp clientDetails ipAddress 127 0 0 1 amp currencyCode USD amp feesPayer EACHRECEIVER amp memo Parallel payment example amp receiverList receiver 0 amount 100 00 amp receiverList receiver 0 email receiver Qdomain amp receiverList receiver 0 primary true amp receiverList receiver 1 amount 50 00 amp receiverList receiver 1 email receiver2 domain amp receiverList receiver 1 primary false amp requestEnvelope errorLanguage en US amp returnUrl http your return url amp senderEmail sender domain Response responseEnvelope timestamp
120. d 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 The PayPal supplied JavaScript provides all the code needed to set up the flow as an 40 August 7 2012 Adaptive Payments Developer Guide Introducing Adaptive Payments E 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 Read the complete story instantly Story 200 000 Android devices sold each day 1 00 PayPal responds to the JavaScript that initiates the flow If it is the first payment or if PayPal determines that the payment requires the sender to log in PayPal displays a Log In button in the IFRAME created by the JavaScript n Full body scans Read the complete story ins x Story 200 000 Android device PayPal sw Log in to your PayPal account to complete this purchase EC New to PayPal Sor Sian up for a PayPal account and complete this purchase now Or check out with a debit or credit card no PayPal Mot account required Mol Zhe visa E Sor The The IFRAME also allows the sender to sign up for a PayPal account or pay as a guest without logging in NOTE Guest checkout only provides the visual benefits of an embedded payment It does not reduce the payment steps
121. ddress of the sender who logs in to approve the request becomes the email address associated with the preapproval key Maximum length 127 characters startingDate xs dateTime Required First date for which the preapproval is valid It cannot be before today s date or after the ending date displayMaxTotalAmount xs boolean Optional Whether to display the maximum total amount of this preapproval It is one of the following values e TRUE Display the amount e FALSE Do not display the amount default 168 August 7 2012 Adaptive Payments Developer Guide Preapproval API Operation PreapprovalRequest Message Field Description feesPayer xs string Optional The payer of PayPal fees Allowable values are e SENDER Sender pays all fees for personal implicit simple parallel payments do not use for chained or unilateral payments e PRIMARYRECEIVER Primary receiver pays all fees chained payments only e EACHRECEIVER Each receiver pays their own fee default personal and unilateral payments e SECONDARYONLY Secondary receivers pay all fees use only for chained payments with one secondary receiver ClientDetails Fields Field Description applicationId customerld customerType deviceld geoLocation ipAddress model xs string Optional Your application s identification such as the name of your application xs string Optional Your ID for this sender Maximum length
122. de It is one of the following values e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message build xs string Build number It is used only by PayPal Merchant Technical Support August 7 2012 Adaptive Payments Developer Guide ConvertCurrency API Operation NER 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 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues ConvertCurrency Errors Code Message Additional Information 520002 Internal error 580022 Your request was invalid Check the parameter of the error to see which is invalid 580027 The argument is unsupported Adaptive Payments Developer Guide August 7 2012 209 ConvertCurrency API Operation ConvertCurrency Errors 210 August 7 2012
123. ds 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 Adaptive Payments Developer Guide August 7 2012 267 a 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 maxNumberOfPaymentsPerPe riod 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 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 businessName New field xs string Optional The URL of the image that displays in the header of a payment page If set it
124. e 41 string paymentSubType 41 string F any E PayResponse Fields 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 Possible values are e CREATED The payment request was received funds will be transferred once the payment is approved e COMPLETED The payment was successful e INCOMPLETE Some transfers succeeded and some failed for a parallel payment or for a delayed chained payment secondary receivers have not been paid e ERROR The payment failed and all attempted transfers failed or all completed transfers were successfully reversed e REVERSALERROR One or more transfers failed when attempting to reverse a payment e PROCESSING The payment is in progress e PENDING The payment is awaiting processing defaultFundingPlan ap FundingPlan Default funding plan responseEnvelope common responseEnvelope Common response information including a timestamp and the response acknowledgement status 90 August 7 2012 Adaptive Payments Developer Guide PayErrorList Fields Pay API Operation PayResponse Message Field Description payError PayError indicates the err
125. e business name to display The name cannot exceed 128 characters 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 Adaptive Payments Developer Guide August 7 2012 153 154 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 Maximum length 127 characters firstName xs string institutionCustomerId institutionId lastName Required The first name of the consumer as known by the institution Maximum length 64 characters xs string Required The unique identifier assigned to the consumer by the institution Maximum length 64 characters xs string Required The unique identifier assigned to the institution Maximum length 64 characters xs string Required The last name of the consumer as known by the institution Maxim
126. e city of the billing address BaseAddress countryCode xs string The country code for the billing address BaseAddress linel 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 278 August 7 2012 Adaptive Payments Developer Guide 1 3 0 Features ERE Field Description BaseAddress state xs string The state for the billing address BaseAddress type xs string The type of billing address Possible values are e 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 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 e 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 s
127. e message Field Description refundInfoList refundInf New field o errorList xs string Information about why a refund failed 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 290 August 7 2012 Adaptive Payments Developer Guide 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 payment Type 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 Includes new API operation fields for Convert Currency and changes to JavaScript functions 05 11 2011 Added information about minibrowser embedded payments flow 04 05 2011 Revised draft for version 1 7 0 Includes information about invoice data and item details which was introduced in version 1 6 0 01 05 2011 Revised draft for version 1 6 0 Includes information about preapproved future payments and shipping address information for embedded payments 10 29 2010 Revised draft for version 1 6 0
128. e operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message build xs string Build number It is used only by PayPal Merchant Technical Support correlationId xs string Correlation identifier It is a 13 character alphanumeric string for example db87c705a910e that is used only by PayPal Merchant Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues PaymentDetails Examples Using NVP and CURL These examples 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 Adaptive Payments Developer Guide August 7 2012 123 124 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 NOTE The sam
129. e she holds in PayPal e 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 e 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 ConvertCurrencyResponse Message The ConvertCurrencyResponse message returns the following information to the application in response to the ConvertCurrencyRequest message 202 August 7 2012 Adaptive Payments Developer Guide E ConvertCurrencyResponse ConvertCurrency API Operation NN ConvertCurrencyResponse Message E ResponseEnvelope responseEnvelope 1 1 ResponseEnvelope e timestamp 1 1 dateTime fe estimatedAmountTable 1 1 CurrencyConversionTable e ack 1 1 AckCode correlationId 1 1 string e build 1 1 string 7 any 0 E CurrencyConversionTable seo Ef currencyConversionList 1 CurrencyConversionList E CurrencyConversionTable ses currencyConversionList 1 CurrencyConversionList E CurrencyConversionList baseAmount 1 1 CurrencyType fe currencyList 1 1 CurrencyList E CurrencyList s f currency 1 CurrencyType ConversionCurrencyResponse Fields E CurrencyConversionList Ef baseAmount 1 1 CurrencyType
130. e this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs 146 August 7 2012 Adaptive Payments Developer Guide E FaultMessage e responseEnvelope 1 1 ResponseEnvelope e error 0 ErrorData ErrorData errorId domain subdomain long string 0 1 string ErrorSeverity e severity e category e message e exceptionId 0 1 token e parameter ErrorCategory string 0 ErrorParameter FaultMessage Fields GetPaymentOptions API Operation PPFault Message ResponseEnvelope 1 1 dateTime AckCode timestamp ack e correlationId 1 e build Fany string 1 0 string E ErrorData errorId domain e subdomain severity category e message e exceptionId 0 1 token parameter 5 ErrorSeverity E ErrorCategory ErrorParameter long string 0 1 string ErrorSeverity ErrorCategory string 0 ErrorParameter name
131. ecify at most one primary receiver Omit this field for refunds for simple and parallel payments Allowable values are e true Primary receiver e false Secondary receiver default PhoneNumberType Fields Field Description countryCode xs string Required Telephone country code phoneNumber xs string Required Telephone number extension xs string Optional Telephone extension RequestEnvelope Fields Field Description detailLevel errorLanguage 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 ReturnA11 which provides the maximum level of detail 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 218 August 7 2012 Adaptive Payments Developer Guide Refund API Operation NX Refund Response Message Refund Response Message The refundResponse message contains status information about a refund request E RefundResponse E ResponseEnvelope responseEnvelope 1 1 ResponseEnvelope e timestamp 1 1 dateTime currencyCode 1 1 string e ack 1 1 AckCode refundInfoList 1 1 RefundInfoList e correlati
132. ects 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 ww paypal com webscr you must specify a command that identifies the flow Command Description _ap payment Invokes PayPal login to approve a payment using Adaptive Payments _ap preapproval Invokes PayPal login to set up a preapproval using Adaptive Payments _ap payment Command The sender can log in to paypal com and approve a payment when you redirect the sender s browser to paypal com with the ap payment command Redirect to PayPal using the _ap payment command https www paypal com webscr cmd _ap payment amp paykey value Parameter Description cmd Required ap payment paykey Required The payment key from the Pay response message for example AP 12345678901234567 Response to _ap payment command from PayPal PayPal redirects to the return URL you set in the Pay request NOTE Any additional parameters you specify in the URL are not returned Adaptive Payments Developer Guide August 7 2012 253 S Adaptive Payment Commands and Redirects Embedded Payment Flow Redirect ap preapproval Command The sender can
133. ed 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 Adaptive Payments Developer Guide August 7 2012 273 a 1 4 0 Features PaymentDetails Pending Reason Feature in Version 1 5 0 The PaymentDetailsResponse now return
134. edirected after the sender cancels the preapproval at paypal com Maximum length 1024 characters clientDetails common ClientDetailsType Required Information about the sender Adaptive Payments Developer Guide August 7 2012 165 Preapproval API Operation PreapprovalRequest Message Field Description currencyCode dateOfMonth xs string Required The currency code Allowable values are e Australian Dollar AUD e Brazilian Real BRL NOTE The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts Canadian Dollar CAD Czech Koruna CZK Danish Krone DKK Euro EUR Hong Kong Dollar HKD Hungarian Forint HUF Israeli New Sheqel ILS Japanese Yen JPY Malaysian Ringgit MYR NOTE The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts Mexican Peso MXN Norwegian Krone NOK New Zealand Dollar NZD Philippine Peso PHP Polish Zloty PLN Pound Sterling GBP Singapore Dollar SGD Swedish Krona SEK Swiss Franc CHF Taiwan New Dollar TWD Thai Baht THB Turkish Lira TRY NOTE The Turkish Lira is supported as a payment currency and currency balance only for Turkish PayPal accounts e U S Dollar USD xs int Optional The day of the month on which a monthly payment is to be made Allowable values are numbers between 0 and 31 A number between 1 a
135. eir assessment The following example shows the receivers paying the fees 62 August 7 2012 Adaptive Payments Developer Guide Introducing Adaptive Payments EX Fee Payment Configuration a m Secondary receiver 200 Fees 5 10 a e 8 Sender diia E Secondary receiver 500 150 Fees Fees 0 62 e 2 70 Secondary receiver 130 Fees 3 03 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 NOTE 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 The fees paid by the primary receiver however are based upon the total fees assigned to all receivers The following example shows only the primary receiver identified as the merchant paying all fees Adaptive Payments Developer Guide August 7 2012 63 al Introducing Adaptive Payments Fee Payment Configuration a Secondary receiver 200 y No Fees pena Primary receiver Secondary receiver Fees 0 62 5 10 2 70 3 03 No Fees Secondary receiver 130 No Fees NOTE The scenario above is an example only and is not representative of actual PayPal fees 64 August 7 2012 Adaptive Payments Developer Guide Getting Started
136. eiver sea aea Gi amount Gi email Gi phone e primary RequestEnvelope e detailLevel e errorLanquage 1 1 string Ej any 0 0 1 DetaillevelCode E ReceiverList Ef receiver 1 Receiver E Receiver decimal string PhoneNumberType boolean Gi invoiceId 41 string Gi paymentType T string paymentSubType T string FE any August 7 2012 Adaptive Payments Developer Guide Refund API Operation NER RefundRequest Message E Receiver PhoneNumberType e countryCode 1 1 string e phoneNumber 1 1 string Gi amount 1 1 decimal email 1 string 1 1 phone 1 PhoneNumberType e extension 0 1 string primary 41 boolean invoiceld 1 string Gi paymentType hs string fe paymentSubType b string Ej any RefundRequest Fields You must specify a value for only one of the following fields to identify the part of the payment to refund payKey transactionld or trackingld Adaptive Payments Developer Guide August 7 2012 215 sa Refund API Operation RefundRequest Message Field Description currencyCode payKey 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 Allowable values are e Australian Dollar AUD e Brazilian Real BRL NOTE The Real is supported as a payment c
137. eiver Pay with My PayPal Balance View PayPal policies 1 00 USD My PayPal Balance Memo papalapapiricoipi Raya Cancel PayPal protects your privacy and security The lightbox containing the confirmation would appear in your page as follows Adaptive Payments Developer Guide August 7 2012 45 al Introducing Adaptive Payments Embedded Payments Jos Ramirez Log out Thank you for using PayPal Receiver Amount Johnson Getaways Inc 1 00 1 00 USD e You paid with My PayPal Balance Your order information has been sentto pbehara usbuyer paypal com PayPal protects your privacy and security 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 If you invoke the embedded payment flow passing both a payment key obtained by calling Pay and a preapproval key obtained by calling Preapproval PayPal displays the checkbox on the payment page 46 August 7 2012 Adaptive Payments Developer Guide Introducing Adaptive Payments Jos R mirez You are about to pay Receiver Rapid Action Towing My PayPal Balance View PayPal policies 5 00 USD My PayPal Balance v Memo Payment Preapprove future payments to Pretty Flower Florist
138. eiverOptions Structure for Version 1 6 0 270 New Receiverldentifier Structure for Version 1 6 0 00004 270 Additional Error Messages for Version 1 6 0 271 1 50 00 Features s id o dd td Xe a a a A 273 Ability to Delay a Chained Payment Feature in Version1 5 0 273 PaymentDetails Pending Reason Feature in Version 1 5 0 274 1 4 0 Features 22 ll lll less sees hos s 274 New API Operations for Version 1 4 0 0 00000 274 Changes to the Pay API Operation 2 2 e 4 4 276 Changes to the PaymentDetails API Operation ss 276 Changes to the PreapprovalDetails API Operation 278 Changes to the PreapprovalDetails API Operation 278 Changes to the Refund API Operation 20 0000 ln 279 1 30 FeatlteS w r cios aci a a de Re xL na Be a a La 279 Overview of Changes for Version 1 8 0 o e e e 279 HTTP Header Changes aaa a les 280 Changes to the Pay API Operation for Version 1 3 0 sss 281 Changes to the PaymentDetails API Operation for Version 1 3 0 283 1 2 0 Features ocx do a Se we ee a EON a DUELO RC TR s a 284 Changes to the Pay API Operation for Version 1 2 0 sss 285 Changes to the Payment Details API Operation for Version 1 2 0 285 Change
139. eiverOptions response fields 144 referrerCode request field 154 referrrerCode response field 144 Refund API operation 211 refundedAmount response field 118 refundFeeA mount response field 222 refundGrossA mount response field 222 refundHasBecomeFull response field 222 refundInfo response field 222 RefundInfo response fields 222 refundInfoList response field 221 RefundInfoList response fields 222 refundNetAmount response field 222 RefundRequest fields 216 RefundRequest message 214 RefundResponse fields 221 RefundResponse message 219 refundStatus response field 223 Adaptive Payments Developer Guide 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 requireShippingA ddressSelection request field 154 263 requireShippingAddressSelection response field 144 responseEnvelope PPFault field 97 122 134 147 158 172 186 194 207 227 241 249 responseEnvelope response field 90 115 130 182 192 203 221 236 247 ResponseEnvelope response fields 96 98 120 123 132 135 146 148 157 159 171 173 184 187 193 195 206 208 225 228 239 242 248 250 responseEnvelope response fields 171 return_url IPN variable 259 returnUrl request field 81 returnUrl
140. ent to a receiver 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 130 August 7 2012 Adaptive Payments Developer Guide ErrorData Fields ExecutePayment API Operation ExecutePaymentResponse Message Field Description category common ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect domain xs string The domain to which this service belongs errorld xs long A 6 digit number that uniquely identifies a particular error exceptionID This field is not used message xs string A description of the error parameter common ErrorParameter Represents contextual information about the error severlty common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request was interrupted e Warning Processing of the request was completed subdomain This field is not used Receiver Fields Field Description amount xs decimal Amount to be paid to the receiver email xs string Receiver s email address Maximu
141. entDetailsResponse Message Field Description email xs string Receiver s email address Maximum length 127 characters invoiceld 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 Possible values are e GOODS This is a payment for non digital goods SERVICE This is a payment for services default PERSONAL This is a person to person payment CASHADVANCE This is a person to person payment for a cash advance DIGITALGOODS This is a payment for digital goods BANK MANAGED WITHDRAWAL This is a person to person payment for bank withdrawals available only with special permission paymentSubType xs string The transaction subtype for the payment phone common PhoneNumberType The receiver s phone number primary xs boolean Whether this receiver is the primary receiver If this field is set to true this is a chained payment If this field shows false this is a simple or parallel payment Possible values are e true Primary receiver chained payment e false Secondary receiver simple parallel payment Senderldentifier Fields Field Description useCredentials xs boolean If true credentials identify the sender default is false taxIdDetails ap TaxIdDetails Tax ID details For Brazil only Adaptive Payments Developer Guide Augu
142. entials identify the sender default is false taxIdDetails ap TaxIdDetails Tax ID details For Brazil only 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 Adaptive Payments Developer Guide August 7 2012 15 Nal 1 8 1 Features 16 August 7 2012 Adaptive Payments Developer Guide 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 You are an application owner such as a merchant that owns a website the owner of a widget on a social networking site the provider of a payment application on mobile phones and so on Your application is the caller of Adaptive Payments API operations NOTE The application owner must have a PayPal Business account Senders and receivers can have any PayPal account type Senders and receivers are not required to have PayPal accounts initially PayPal prompts a sender to create an account before a payment can be completed A receiver must create an account to receive the funds after the payment completes With many ap
143. equest 160 August 7 2012 Adaptive Payments Developer Guide 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 amp receiverOptions 0 receiver email test Gtest com amp receiverOptions 0 invoiceData item 0 name ITEM1 amp receiverOptions 0 invoi ceData item 0 price 50 0 amp receiverOptions 0 invoiceData item 0 itemCount 2 amp receiverOptions 0 invoiceData item 0 itemPrice 25 0 amp receiverOptions 0 invoiceData totalTax 25 0 amp receiverOptions 0 invoiceData totalShipping 25 0 amp payKey SetPaymentOptions Errors Code Message Additional Information 520002 Internal error 520003 Authentication failed API credentials are incorrect Since 1 6 0 550001 User is not allowed to perform this action 550001 This payment request must be authorized by the sender 540031 You do not have permission to set these payment options 540031 You do not have permission to set these payment options Since 1 6 0 Operation is not permitted because the credentials do not match those of the initial operation 580001 Invalid request lt value
144. equest parameter payKey with value lt value gt Invalid Phone Country Code lt value gt Invalid Country Code lt value gt for Receiver Invalid Receiver Phone Type lt value gt lt value gt lt value gt Invalid Phone Format lt value gt lt value gt Invalid Phone Number lt value gt lt value gt Invalid Receiver Phone Number lt value gt lt value gt Invalid Area or Exchange Code lt value gt lt value gt lt value gt has already been set and cannot be set multiple times Invalid request parameter lt value gt with value lt value gt Invalid request parameter lt value gt lt value gt is invalid Invalid request parameter value value is duplicated Invalid request parameter value value cannot be negative or zero August 7 2012 Adaptive Payments Developer Guide Pay API Operation Pay Errors Code Message Additional Information 580023 580023 580027 580027 580028 580029 580030 589009 589019 589023 589039 Invalid request e The fee payer lt value gt cannot be used if a primary receiver is specified e The fee payer lt value gt can only be used if a primary receiver 1s specified e The fee payer lt value gt must have exactly 2 receivers e The reverseAllParallelPaymentOnError field can be true only if a primary receiver is not specified e The fee payer lt value gt cannot be used if a preapproval key is specified e Invalid request FundingType cannot be
145. equired to explicitly start the flow when there is no triggering event for example when you want to associate the embedded payment flow with playing a Flash movie closeFlow function Close the minibrowser or lightbox associated with the flow Use this function after the sender completes or cancels the payment NOTE In addition to calling this function you must explicitly close the PayPal window using the close JavaScript function isOpen function Determine whether the minibrowser or lightbox is still open Adaptive Payments Developer Guide August 7 2012 255 a Adaptive Payment Commands and Redirects Embedded Payment Flow Redirect 256 August 7 2012 Adaptive Payments Developer Guide 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 The IPN messages listed here do not use the IPN message handler that you can specify in the Profile IPN messages are only sent to the notification URL specified in the Adaptive Payment API operation s request IMPORTANT IPN variable names such as transaction 0 sta
146. er 0 primary false receiverList receiver 1 amount 50 00 receiverList receiver 1 email receiver2 domain receiverList receiver 1 primary false amp requestEnvelope errorLanguage en US amp returnUrl http your return url amp reverseAllParallelPaymentsOnError true amp senderEmail sender domain Response responseEnvelope timestamp 2009 07 13T12 3A34 3A29 316 07 3A00 amp responseEnvelope ack Success amp responseEnvelope correlationId d615a365bed61 amp responseEnvelope build DEV amp payKey AP 42706441J712795911 amp paymentExecStatus COMPLETED Digital goods payment In this example the sender makes a payment of 1 to a PayPal registered receiver The sender must explicitly approve the payment NOTE The sample code below uses the insecure setting to work around the certificate for testing in a sandbox environment For actual implementations you must specify the location of the certificate Request Adaptive Payments Developer Guide August 7 2012 103 sa 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 amp actionType PAY amp receiverList receiver 0 amount 1 00
147. erTransactionStatus 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 284 August 7 2012 Adaptive Payments Developer Guide Changes to the Pay API Operation for Version 1 2 0 Changes to PayRequest messages Field Description ClientDetails devicelD This field is now optional it is no longer required Receiver invoiceld 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 0 Changes to PaymentDetailsReponse message Field Description Receiver invoicelD New field xs string The invoice number for the payment Adaptive Payments Developer Guide August 7 2012 285 a 1 1 0 Features Changes to Preapproval API Operation for Version 1 2 0 28
148. erity category e message string e exceptionId 0 1 token parameter 5 ErrorSeverity E ErrorCategory ErrorParameter ErrorCategory 0 ErrorParameter name string Field Description error common ErrorData Detailed error information responseEnvelope common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status Adaptive Payments Developer Guide August 7 2012 207 208 ConvertCurrency API Operation PPFault Message ErrorData Fields Field Description category common ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect domain xs string The domain to which this service belongs errorld xs long A 6 digit number that uniquely identifies a particular error exceptionID This field is not used message xs string A description of the error parameter common ErrorParameter Represents contextual information about the error severlty common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request was interrupted e Warning Processing of the request was completed subdomain This field is not used ResponseEnvelope Fields Field Description ack common AckCode Acknowledgement co
149. escription fundingConstraint ap FundingConstraint Optional Specifies a list of allowed funding types for the payment This is a list of funding selections that can be combined in any order to allow payments to use the indicated funding type If this Parameter is omitted the payment can be funded by any funding type that is supported for Adaptive Payments NOTE FundingConstraint is unavailable to API callers with standard permission levels for more information refer to the section Adaptive Payments Permission Levels ipnNotificationUrl xs string Optional The URL to which you want all IPN messages for this payment to be sent Maximum length 1024 characters memo xs string Optional A note associated with the payment text not HTML Maximum length 1000 characters including newline characters pin xs string Optional The sender s personal identification number which was specified when the sender signed up for a preapproval preapprovalKey xs string Optional The key associated with a preapproval for this payment The preapproval key is required if this is a preapproved payment NOTE The Preapproval API is unavailable to API callers with Standard permission levels receiverList ap ReceiverList Required Information about the receivers of the payment requestenvelope common RequestEnvelope Required Information common to each Method such as the language in which an error message is returned retur
150. etail errorLanguage xs string Required RFC 3066 language in which error messages are returned by default it is en_US which is the only language currently supported PayResponse Message The PayResponse message contains a key that you can use to identify the payment and the payment s status 86 August 7 2012 Adaptive Payments Developer Guide Pay API Operation BEN PayResponse Message E ResponseEnvelope E PayResponse e timestamp 1 1 dateTime responseEnvelope 1 1 ResponseEnvelope Ef payKey 1 1 string e ack 1 1 AckCode E paymentExecStatus 1 1 string so e correlationid 1 1 string payErrorList 0 1 PayErrorList e build 1 1 string Ef defaultFundingPlan 0 1 FundingPlan f jany 0 F any 0 E PayErrorList se ef payError 1 PayError E FundingPlan e FundingPlanId 1 1 string e FundingAmount 1 1 CurrencyType backupFundingSource 0 1 FundingSource eee senderFees 0 1 CurrencyType e currencyConversion 0 CurrencyConversion charge 1 FundingPlanCharge fl any 0 ES PayErrorList E PayError ef payError 1 PayError Ef receiver 1 1 Receiver ses 69 error 1 1 ErrorData Fan 0 Adaptive Payments Developer Guide August 7 2012 87 88 Pay API Operation PayResponse Message E FundingPlan e fundingPlanId e fundingAmount 1 1 1 1 e
151. ever there is a warning message e FailureWithWarning The operation failed with a warning message build xs string Build number It is used only by PayPal Merchant Technical Support Adaptive Payments Developer Guide August 7 2012 225 S 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 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs Fault Message ResponseEnvelope e responseEnvelope 1 1 ResponseEnvelope e timestamp 1 1 dateTime e error 0 ErrorData e ack 1 1 AckCode e correlationId 1 1 string e build 1 1 string 6 any 0 ErrorData errorId long domain string e subdomain 0 1 string severity ErrorSeverity category ErrorCategory message string e exceptionId 0
152. ey e You do not have permission to get these funding plan details Invalid request lt value gt e Invalid request parameter lt value gt e Invalid request parameter payKey with value lt value gt This parameter is not supported A pay key transaction ID or tracking ID is missing This transaction cannot be processed at this time Please try again later Since 1 6 0 Since 1 6 0 Since 1 6 0 Since 1 6 0 Since 1 6 0 Since 1 6 0 Since 1 6 0 Since 1 3 0 Adaptive Payments Developer Guide August 7 2012 243 Ix GetFundingPlans API Operation GetFundingPlan Errors 244 August 7 2012 Adaptive Payments Developer Guide 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 GetShippingAddressesRequest Message E GetShippingAddressesRequest Is RequestEnvelope Gi requestEnvelope 1 1 RequestEnvelope e detailLevel 0 1 DetailLevelCode se f key 1 1 string s e errorLanguage 1 1 string Ej any 0 Fany 0 GetShippingAddressesRequest Fields You must specify a value for the key field which uses the payKey to identify t
153. f the following values e TRUE Display the amount e FALSE Do not display the amount default xs string The payer of PayPal fees Allowable values are e SENDER Sender pays all fees for personal implicit simple parallel payments do not use for chained or unilateral payments e PRIMARYRECEIVER Primary receiver pays all fees chained payments only e EACHRECEIVER Each receiver pays their own fee default personal and unilateral payments e SECONDARYONLY Secondary receivers pay all fees use only for chained payments with one secondary receiver Address List Fields Field Description AddressList ap Address Returns a billing address Address Fields Field Description addresseeName xs string The name associated with the address Adaptive Payments Developer Guide August 7 2012 183 sss PreapprovalDetails API Operation PreapprovalDetailsResponse Message Field Description baseAddress common BaseAddress Street address addressId xs string The ID associated with the address BaseAddress Fields Field city countryCode linel line2 postalCode state type Description xs string The city of the address xs string The country code of the address xs string The first line of the address xs string An second line of the street address xs string The postal code of the address xs string The state for the address xs string
154. formation about the error common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request was interrupted e Warning Processing of the request was completed This field is not used 134 August 7 2012 Adaptive Payments Developer Guide ExecutePayment API Operation NER ExecutePayment Errors ResponseEnvelope Fields Field Description ack build common AckCode Acknowledgement code It is one of the following values e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message xs string Build number It is used only by PayPal Merchant Technical Support correlationId xs string timestamp Correlation identifier It is a 13 character alphanumeric string for example db87c705a910e that is used only by PayPal Merchant Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues ExecutePayment Errors
155. he account holder Field Description key xs string Required The payment paykey that identifies the account holder for whom you want to obtain the selected shipping address NOTE Shipping information can only be retrieved through the payment payKey not through the preapprovalKey requestEnvelope common requestEnvelope Required Information common to each API operation such as the language in which an error message is returned Adaptive Payments Developer Guide August 7 2012 245 isa GetShippingAddresses API Operation GetShippingAddressesHesponse 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 ReturnA11 which provides the maximum level of detail errorLanguage xs string Required RFC 3066 language in which error messages are returned by default it is en_US which is the only language currently supported GetShippingAddressesResponse Message E GetShipping ddressesResponse Ef responseEnvelope 1 1 ResponseEnvelope fe selectedAddress 0 1 Address F j any 0 Ef Address Ef addresseeName 0 1 string baseAddress 1 1 BaseAddress Ef addressId 0 1 string
156. he payment flow August 7 2012 Adaptive Payments Developer Guide Pay API Operation BER PayRequest Message PayRequest Message The PayRequest message contains the instructions required to make a payment E PayRequest E RequestEnvelope Ef requestEnvelope 1 1 RequestEnvelope e detailLevel 0 1 DetaillevelCode Ef clientDetails 0 1 ClientDetailsType ees e errorLanguage 1 1 string e actionType 1 1 string FE any 0 Ef cancelurl 1 1 string currencyCode 1 1 string E ClientDetailsType l FeesPayer 0 1 string e ip ddress 0 1 string Ef ipnNotificationurl 0 1 string deviceId 0 1 string E memo 0 1 string e applicationId 0 1 string Ef pin 0 1 string model 0 1 string preapprovalkey 0 1 string se e geoLocation 0 1 string Ef receiverList 1 1 ReceiverList e customerType 0 1 string e reverseAllParallelPaymentsOnError 0 1 boolean partnerName 0 1 string senderEmail 0 1 string customerId 0 1 string Ef returnurl 1 1 string fl any 0 Ef trackingId 0 1 string fundingConstraint 0 1 FundingConstraint Ej ReceiverList sender 0 1 SenderIdentifier s EP receiver 1 Receiver E FundingConstraint s e allowedFundingType 0 1 FundingTypeList E SenderIdentifier e useCredentials 0 1 boolean E FundingConstraint E Fu
157. hnical Support uses the information to assist with reported issues Adaptive Payments Developer Guide August 7 2012 157 a SetPaymentOptions API Operation PPFault Message PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs FaultMessage ResponseEnvelope e responseEnvelope 1 1 ResponseEnvelope e timestamp 1 1 dateTime e error 0 ErrorData e ack 1 1 AckCode e correlationId 1 1 string e build 1 1 string T l any 0 ErrorData errorId long domain string e subdomain 0 1 string severity ErrorSeverity category ErrorCategory e message string e exceptionId 0 1 token e parameter 0 ErrorParameter E ErrorData E ErrorSeverity e errorId long e domain string EJ ErrorCategory e subdomain 0 1 string severity ErrorSeverity ErrorParameter name string category ErrorCategory message string e exceptionId 0 1 token e parameter 0 ErrorParameter FaultMessage Fields Field Description error common ErrorData Detailed error information responseEnvelope common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status 158 August 7 2012 Adaptive Payments Developer Guide SetPaymentOptions API Operation NER PPFault Message ErrorD
158. ifferent currency than the payment request Adaptive Payments Developer Guide August 7 2012 105 106 Pay API Operation Pay Errors Code Message Additional Information 579028 The payment amount exceeds the maximum amount per payment 579030 The number of payments made this period exceeds the maximum number of payments per period 579031 The total amount of all payments exceeds the maximum total amount for all payments 579033 The sender and each receiver must have different accounts 579040 The receivers cannot belong to the same PayPal account 579042 The tracking ID already exists and cannot be duplicated 579045 The email account exceeds the receiving limit 579047 The email account exceeds the purse limit 579048 The email account exceeds the sending limit 580001 Invalid request 580001 e Invalid request both email and phone cannot be set value Since 1 6 0 value value e Invalid request neither email nor phone is set value e To use currency value currency must be held by sender and all receivers e Invalid request More than one field cannot be used to specify a sender e Invalid request lt value gt 580022 Your request was invalid Check the parameter of the error to see which is invalid 580022 Invalid request parameter lt value gt Since 1 6 0 Invalid Request Parameter institutionId with value lt value gt The institution id lt value gt is not activated The clientDetails parameter is missing Invalid r
159. ify this particular payment 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 72 August 7 2012 Adaptive Payments Developer Guide 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 If you want more than a simple payment add fields for the specific kind of request which include parallel payments chained payments implicit payments and preapproved payments Common Fields for All Payments For each kind of payment you must specify values for the following fields Field Description actionType The action for this request Possible values are e PAY Use this option if you are not using the Pay request in combination with ExecutePayment e CREATE Use this option to set up the payment instructions with Set PaymentOptions and then execute the payment at a later time with the ExecutePayment e PAY PRIMARY For chained payments only specify this value to delay payments to the secondary receivers only the payment to the primary receiver is proces
160. imary receiver an amount from which the primary receiver pays secondary receivers The sender only knows about the primary receiver not the secondary receivers The secondary receivers only know about the primary receiver not the sender The following diagram shows the relationship between you as both the sender and the application owner that directs payments to receivers August 7 2012 Adaptive Payments Developer Guide Introducing Adaptive Payments E Simple Parallel and Chained Payments Your application 3 a PayPal API Server Send jdm immi Receiver Sender 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 e Simple payments enable a sender to send a single payment to a single receiver For example your website can use an Adaptive Payments payment flow to transfer money resulting from a sale from your customer s PayPal account to your own account This is the traditional kind of payment e Parallel payments enable a sender to send a single payment to multiple receivers For example your application might be a shopping cart that enables a buyer to pay for items from several
161. ing string 111 js PaymentDetails API Operation PaymentDetailsResponse Message ES Receiver E PhoneNumberType Ef amount 1 decimal e countryCode 1 1 string email 1 string s e phoneNumber 1 1 string 1 Ef phone 1 PhoneNumberType extension 0 1 string primary 41 boolean invoiceld 1 string paymentType 41 string Ef paymentSubType 0 1 string Fl any am E FundingConstraint E FundingTypeList seol f allowedFundingType 0 1 FundingTypeList ss e fundingTypelnfo 1 FundingTypeInfo E FundingTypeList E FundingTypeInfo s fundingTypeInfo 1 FundingTypelnfo Ef FundingType 1 1 string F any 0 E Accountldentifier E TaxidDetails Ef email 0 1 string taxid 0 1 string Ef phone 0 1 PhoneNumberType f taddType 0 1 string FE any 0 FE any 0 E Senderldentifier E useCredentials 0 1 boolean e taddDetails 0 1 TaxldDetails Ej AccountIdentifier E PhoneNumberType Ef email 0 1 string Ef countryCode 1 1 string s f phone 0 1 PheneNumberType s phoneNumber 1 1 string 1 1 F lany 0 e extension 0 1 string 112 August 7 2012 Adaptive Payments Developer Guide PaymentDetails API Operation NER PaymentDetailsResponse Message PaymentDetailsResponse Fields Field Description actionType xs string Whether the Pay request is
162. ion GetPaymentOptionsResponse Message 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 Receiverldentifier Fields Field Description email xs string Receiver s email address Maximum length 127 characters phone common PhoneNumberType Receiver s phone number PhoneNumberType Response Fields Field Description countryCode xs string Telephone country code phoneNumber xs string Telephone number extension xs string Telephone extension Adaptive Payments Developer Guide August 7 2012 145 al GetPaymentOptions API Operation PPFault Message ResponseEnvelope Fields Field Description ack common AckCode Acknowledgement code It is one of the following values e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message build xs string Build number It is used only by PayPal Merchant Technical Support correlationId xs string Correlation identifier It is a 13 character alphanumeric string for example db87c705a910e that is used only by PayPal Merchant Technical Support NOTE You must log and stor
163. ion error common ErrorData Detailed error information responseEnvelope common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status ErrorData Fields Field category domain errorId exceptionID message parameter Description common ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect xs string The domain to which this service belongs xs long A 6 digit number that uniquely identifies a particular error This field is not used xs string A description of the error common ErrorParameter Represents contextual information about the error August 7 2012 Adaptive Payments Developer Guide PaymentDetails API Operation EN PaymentDetails Examples Using NVP and CURL Field Description severity common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request was interrupted e 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 e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning Th
164. ion is in progress REVERSED The payment was returned to the sender REFUNDED The payment was refunded FAILED The payment failed The identification number for the refund The amount that was refunded The email address of the debit account of the refund The receiver s email address for the transaction The invoice number for this transaction The payment amount of the transaction Whether there is a primary receiver for this transaction which indicates whether the transaction is a chained payment Possible values are e true There is a primary receiver chained payment e false There is no primary receiver simple or parallel payment The URL to which the sender s browser is redirected after approving a payment on paypal com Use the pay key to identify the payment as follows payKey payKey The URL to which the sender s browser is redirected 1f the sender cancels the approval for a payment on paypal com Use the pay key to identify the payment as follows payKey payKey The URL to which all IPN messages for this payment are sent The pay key that identifies this payment This is a token that is assigned by the Pay API after a PayRequest message is received and can be used in other Adaptive Payments APIs as well as the cancelURL and returnURL to identify this payment The pay key is valid for 3 hours A note associated with the payment Adaptive Payments Developer Guide August 7 2012 259 a Instan
165. is handled by a separate cancellation URL to which PayPal redirects the sender s browser any time the sender cancels while on paypal com In addition to these steps PayPal notifies you and the sender of the payment 24 August 7 2012 Adaptive Payments Developer Guide Introducing Adaptive Payments E 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 com and sets up the preapproval which includes setting the following information e duration of the preapproval from the start date to the end date inclusive e the maximum amount being preapproved e the maximum number of payments The following diagram shows the basic flow of control during a preapproval operation Legend al Web Flow gt API Call Preapproval Key D Preapproval request D PayPal A BA LL ien Send money 3 HTTP redirect O 4 HTTP redirect to return URL Your site The following items correspond to the circled numbers in the diagram 1 Your site or device sends a Preapproval request to PayPal on behalf of a sender Adaptive Payments Developer Guide August 7 2012 25 S Introducing Adaptive Payments Preapproved Payments Flow 2 PayPal responds
166. ization NOTE The Adaptive Payments Refund API call does not support pay keys generated by the Mobile Payment Library MPL For each kind of refund you must specify values for the following fields Adaptive Payments Developer Guide August 7 2012 211 212 Refund API Operation Refund API Overview Common fields for all refunds Field Description currencyCode requestEnvelope errorLanguage 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 The code for the language in which errors are returned which must be en_US You can refund a payment from all receivers associated with a payment by specifying the payment s payment key or tracking ID Refunds that apply to all receivers Field Description payKey trackingId The key used to create the payment that you want to refund The tracking ID associated with the payment that you want to refund You can make a refund to the sender of a payment from specific receivers associated with a payment key or tracking ID In this case you must specify e either the payment key or tracking ID that identifies the original payment e foreach receiver making a refund the receiver s email address e for each receiver the amount to refund to the sender from the receiver s account NOTE Thereceiver can t make a partial refund if the original payment was a cash
167. key value PA gt lt input type submit id submitBtn value Pay with PayPal gt lt form gt NOTE To modify an existing application to use the embedded payment flow change the redirect from https www paypal com webscr cmd ap payment amp paykey to https www paypal com webapps adaptivepayment flow pay paykey after obtaining the pay key 3 Include the PayPal JavaScript functions from dg js lt script src https www paypalobjects com js external dg js gt lt script gt 4 Create an embedded flow object and associate it with your payment form or button lt script gt var dgFlow new PAYPAL apps DGFlow trigger submitBtn lt script gt After Completing This Task On the pages you identify as the return and cancel URLs in the Pay API operation you must include the PayPal JavaScript functions from dg js and close the PayPal window as in the following example dgFlow top dgFlow top opener top dgFlow dgFlow closeFlow top close August 7 2012 Adaptive Payments Developer Guide Introducing Adaptive Payments E 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
168. l address or a phone number as the payment receiver primary xs boolean Optional Whether this receiver is the primary receiver which makes the payment a chained payment You can specify at most one primary receiver Omit this field for simple and parallel payments Allowable values are e true Primary receiver e false Secondary receiver default PhoneNumberType Fields Field Description countryCode xs string Required Telephone country code phoneNumber xs string Required Telephone number extension xs string Optional Telephone extension Adaptive Payments Developer Guide August 7 2012 85 sa Pay API Operation PayResponse Message Senderldentifier Fields Field Description useCredentials xs boolean Optional If true use credentials to identify the sender default is false Accountldentifier Fields Field Description email xs string Optional Sender s email address Maximum length 127 characters phone common PhoneNumberType Optional Sender s phone number RequestEnvelope Fields Field Description detailLevel common DetailLevelCode Optional Level of detail required by the client application pertaining to a particular data component The detail level is specified as a detail level code which has all the enumerated values of the detail level for the component By default the detail level code is ReturnA11 which provides the maximum level of d
169. l for risk e 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 Get PaymentOptions and Set PaymentOptions 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 274 August 7 2012 Adaptive Payments Developer Guide 1 4 0 Features EE 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 Adaptive Payments Developer Guide August 7 2012 275 a 1 4 0 Features Changes to the Pay API Operation Changes to PayRequest and PayResponse Message Field Description actionType paymentType Receiver PhoneNumberType New CREATE value e PAY Use this option if you are not using the Pay request in combinations with the ExecutePayment request e 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 New person to person values PERSONAL and CASHADVANCE Person to person payments can
170. l is unnecessary Implicit approval payments in which your application is both the sender of a payment and the caller of the Adaptive Payments Pay API In this case PayPal makes the payment from your own account which eliminates the need for approval Adaptive Payments Service Permissions Adaptive Payments services are divided into 2 categories standard services that do not require specific permission to use and advanced services that require permission from PayPal to use You obtain permission to use a service when you submit an application to PayPal You can use the following standard services without requesting specific permission Making simple or parallel payments that require explicit approval of the sender Getting payment details Making refunds Performing currency conversions To use any other service you must receive permission from PayPal to use the service when you submit your application For example if your application makes chained payments which is an advanced service you request permission when you submit your application Later if you modify your application to support preapprovals which is also an advanced service you must resubmit your application to obtain permission from PayPal to use the service IMPORTANT If you allow a third party to PayPal to execute an application on your behalf the third party becomes the API caller because the party is now calling the Adaptive Payments API The third party must
171. ld ap PayErrorList Information about why a payment failed 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 Changes to PaymentDetailsResponse Field Description logDefaultShippingAddres New field S xs string Indicates when the Pay operation was called for this payKey trackingld Empty fields are not returned this is now enforced for trackingID New PaymentDetails error messages Code Message Additional Information 540031 You do not have permission to get the details of this Payment PaymentDetails Adaptive Payments Developer Guide August 7 2012 287 a 1 1 0 Features 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 288 August 7 2012 Adaptive Payments Developer Guide 1 1 0 Features EE 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
172. lds o 94 Receiver Fields a 95 PhoneNumberType Response Fields o 95 ResponseEnvelope Fields 2l 96 PPFault Message llle ee 96 FaultMessage Fields 22e 97 ErrorData FieldS a ee A a Da e a A E a a A a 98 ResponseEnvelope Fields oaoa o aa a a 98 Pay Examples Using NVP and CURL 0 0 0000 eee ee eee 99 Pay EMOS iosa amp a god oem Bie mx REOR la ee a ALES a ee XO ecu 104 Chapter 4 PaymentDetails API Operation 109 PaymentDetailsRequest Message len 109 PaymentDetailsRequest Fields llle 109 RequestEnvelope Fields aa a 110 PaymentDetailsResponse Message 0 ee 110 PaymentDetailsResponse Fields llle 113 FundingTypeList Fields lle 116 FundingTypelnfo Fields soca sima lle 116 PaymentinfoList Fields 0 o e o 117 Paymentinfo Fields a 117 Receiver Fields llle 118 Senderldentifier Fields 2 222 oen 119 Accountldentifier Fields 0 000 ee ee ee 120 PhoneNumberType Response Fields e 120 ResponseEnvelope Fields aaa a 120 Adaptive Payments Developer Guide August 7 2012 5 EN Contents PPFault Message e 2 FaultMessage Fields ErrorData Fields a
173. lly e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message build xs string Build number It is used only by PayPal Merchant Technical Support correlationId xs string Correlation identifier It is a 13 character alphanumeric string for example db87c705a910e that is used only by PayPal Merchant Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues GetFundingPlan Errors Code Message Additional Information 520002 Internal error 242 August 7 2012 Adaptive Payments Developer Guide GetFundingPlans API Operation GetFundingPlan Errors Code Message Additional Information 520003 540031 550001 580001 580022 580027 580029 580030 Authentication failed API credentials are incorrect Operation is not permitted because the credentials do not match those of the initial operation e User is not allowed to perform this action e You are not allowed to get the funding plans for this k
174. log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues Pay Examples Using NVP and CURL These examples all use 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 Simple payment example In this example the sender makes a payment of 100 to a PayPal registered receiver If you are the sender and the caller the approval is implicit otherwise the sender must explicitly approve the payment The status of the request which is identified in the paymentExecStatus field of the response differs due to the kind of approval required Implicit approval allows the request to be completed immediately Explicit approval allows the request to be created however it is completed until the payment is approved NOTE The sample code below uses the insecure setting to work around the certificate for testing in a sandbox environment For actual implementations you must specify the location of the certificate Request Adaptive Payments Developer Guide August 7 2012 99 sa 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 SIGN
175. 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 com webscr cmd ap preapproval amp preapprovalkey value Parameter Description cmd Required _ap preapproval preapprovalkey Required The preapproval key from the Preapproval response message for example PA 12345678901234567 Response to _ap preapproval command from PayPal PayPal redirects to the return URL you set in the Preapproval request NOTE Any additional parameters you specify in the URL are not returned Embedded Payment Flow Redirect The sender of a payment can log in to paypal com and approve a payment using the embedded payment flow Your web pages must use PayPal provided JavaScript to launch the flow Redirect to PayPal https www paypal com webapps adaptivepayment flow pay paykey value amp preapprovalkey value Parameter Description paykey Required The payment key from the Pay response message for example AP 12345678901234567 preapprovalkey Optional The preapproval key from the Preapproval response message which enables the Preapprove future payments option for example PA 12345678901234567 Response from PayPal PayPal redirects to the return URL you set in the Pay request NOTE Any additional parameters you specify in the URL are not returned 254 August
176. loper Guide August 7 2012 191 am CancelPreapproval API Operation CancelPreapprovalResponse Message RequestEnvelope Fields Field Description detailLevel errorLanguage 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 ReturnA11 which provides the maximum level of detail 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 CancelPreapprovalResponse Message The Cancel PreapprovalResponse message contains information returned in response to a CancelPreapprovalRequest message ES CancelPreapprovalResponse Gi responseEnvelope 1 1 FE any 0 see ResponseEnvelope e timestamp 1 1 dateTime e ack 1 1 AckCode e correlationId 1 1 string e build 1 1 string Fl any 0 ResponseEnvelope CancelPreapprovalResponse Fields Field Description responseEnvelope common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status 192 August 7 2012 Adaptive Payments Developer Guide CancelPreapproval API Operation NER PPFault Message ResponseEnvelope Fields
177. m length 127 characters invoiceld xs string The invoice number for the payment This data in this field shows on the Transaction Details report Maximum length 127 characters Adaptive Payments Developer Guide August 7 2012 131 S ExecutePayment API Operation ExecutePaymentResponse Message Field Description paymentType paymentSubType phone primary xs string The transaction type for the payment Possible values are e GOODS This is a payment for non digital goods SERVICE This is a payment for services default PERSONAL This is a person to person payment CASHADVANCE This is a person to person payment for a cash advance DIGITALGOODS This is a payment for digital goods BANK MANAGED WITHDRAWAL This is a person to person payment for bank withdrawals available only with special permission xs string The transaction subtype for the payment common PhoneNumberType The receiver s phone number xs boolean Whether this receiver is the primary receiver If this field is set to true this is a chained payment If this field shows false this is a simple or parallel payment Possible values are e true Primary receiver chained payment e false Secondary receiver simple parallel payment ResponseEnvelope Fields Field ack build correlationId Description common AckCode Acknowledgement code It is one of the following values e Success The operation
178. mation to your application if an error occurs 248 August 7 2012 Adaptive Payments Developer Guide GetShippingAddresses API Operation E FaultMessage e responseEnvelope 1 1 ResponseEnvelope e error 0 ErrorData ErrorData e errorId long domain string e subdomain 0 1 string ErrorSeverity e severity e category e message string e exceptionId 0 1 token e parameter 0 ErrorParameter ErrorCategory FaultMessage Fields PPFault Message NE ResponseEnvelope e timestamp 1 1 dateTime ack 1 1 AckCode e correlationId 1 1 string build 1 1 string T any 0 E ErrorData errorId long domain string e subdomain 0 1 string severity ErrorSeverity category e message string e exceptionId 0 1 token e parameter 0 ErrorParameter 5 ErrorSeverity E ErrorCategory ErrorParameter ErrorCategory name string Field Description error common ErrorData Detailed error information responseEnvelope common ResponseEnvelope Common response information including a timestamp and the response acknowledgement status Adaptive Payments Developer Guide August 7 2012 249 250 GetShippingAddresses API Operation PPFault Message ErrorData Fields Field Description category common ErrorCategory The location where the error occurred Possi
179. ment currency and currency balance only for Malaysian PayPal accounts Mexican Peso MXN Norwegian Krone NOK New Zealand Dollar NZD Philippine Peso PHP Polish Zloty PLN Pound Sterling GBP Singapore Dollar SGD Swedish Krona SEK Swiss Franc CHF Taiwan New Dollar TWD Thai Baht THB Turkish Lira TRY NOTE The Turkish Lira is supported as a payment currency and currency balance only for Turkish PayPal accounts e U S Dollar USD The day of the month on which a monthly payment is to be made A number between and 31 indicates the day of the month A value of 0 indicates that the payment can be made on any day Adaptive Payments Developer Guide August 7 2012 261 Instant Payment Notifications Preapproval Message Variables Variable Description day of week starting date ending date max total amount of all payments max amount per payment max number of payments payment period pin type sender email 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 First date for which the preapproval is valid Last date for which the preapproval is valid Time is currently not supported The preapproved maximum total amount of all payments The preapproved maximum amount of all payments The maximum number of payments that is preapproved The pay
180. ment period Possible values are NO PERIOD SPECIFIED DAILY WEEKLY BIWEEKLY SEMIMONTHLY MONTHLY ANNUALLY Whether a personal identification number PIN is required It is one of the following values NOT REQUIRED A PIN is not required REQUIRED A PIN is required The sender s email address 262 August 7 2012 Adaptive Payments Developer Guide 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 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 Adaptive Payments Developer Guide August 7 2012 263 a 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 s
181. ments with SOAP include the HTTP headers for authentication as described in the section Authentication and the application ID as described in the next section In addition include the X PAYPAL MESSAGE PROTOCOL header with a SOAP11 value The following is a header example for an Adaptive Payments API call for a SOAP message headers put headers put headers put headers put headers put headers put X PAYPAL SECURITY USERID tok261 biz api abc com X PAYPAL SECURITY PASSWORD 1244612379 X PAYPAL SECURITY SIGNATURE lkfg9groingghb4uw5 X PAYPAL DEVICE IPADDRESS 168 212 226 204 X PAYPAL MESSAGE PROTOCOL SOAP11 X PAYPAL APPLICATION ID APP 80W284485P519543T ais Below are the service name port type binding and location for SOAP as defined in the Adaptive Payments WSDL wsdl service name AdaptivePayments gt wsdl port name AdaptivePaymentsSOAP11 http lt binding services AdaptivePaymentsSOAP11Binding gt lt soap address location https svcs paypal com AdaptivePayments gt Specifying Application and Device Information You also must identify the application You can optionally identify other information associated with the client and the API version 68 August 7 2012 Adaptive Payments Developer Guide Getting Started NX Making a Simple Payment JSON HTTP Headers for Application and Device identification Header Description X PAYPAL APPLICATION ID Required Your
182. n 73 Pay SUMMA o aue des e Poe a D ee deck e o e be ee a 8 73 Common Fields for All Payments o e e 73 Parallel Payments ss sa sea ad a leere 74 Chained Payments aoaaa ee 74 Implicit Payments a 75 Preapproved Payments 2l llle 75 Payments for Digital Goods a 75 Payment Notifications 22s 75 Additional Notes About the Pay API Operation 76 PayRequest Message llle 77 PayRequest Fields 22e 79 ClientDetails Fields ee 82 FundingConstraint Fields 22e 83 FundingTypelist Fields llle 83 FundingTypelnfo Fields llle 84 ReceiverList Fields 22h 84 Receiver Fields 2l lll sss 84 August 7 2012 Adaptive Payments Developer Guide Contents E PhoneNumberType Fields ole 85 Senderldentifier Fields o ole 86 Accountldentifier Fields 0 llle 86 RequestEnvelope Fields a 86 PayResponse Message 2222 llle 86 PayResponse Fields s ssr sa a ole 90 PayErrorList Fields ooa aaa a 91 FundingPlan Fields aoaaa aa o 91 CurrencyType Fields 2 91 FundingSource Fields lt o s s ea ca ace wa w aea o 92 CurrencyConversion Fields oaoa aaa e 93 FundingPlanCharge Fields oaao aa aa 22er 93 PayError FieldS aa i aaa i Boa ee 94 EmorDataFie
183. nUrl xs string Required The URL to which the sender s browser is redirected after approving a payment on paypal com Specify the URL with the HTTP or HTTPS designator Maximum length 1024 characters reverseAllParallelPaymen xs boolean tsOnError Optional Whether to reverse parallel payments if an error occurs with a payment Allowable values are e true Each parallel payment is reversed if an error occurs e false Only incomplete payments are reversed default Adaptive Payments Developer Guide August 7 2012 81 E 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 trackingld xs string Optional A unique ID that you specify to track the payment NOTE You are responsible for ensuring that the ID is unique Maximum length 127 characters ClientDetails Fields Field Description applicationId customerId customerType deviceld geoLocation ipAddress model xs string Optional Your application s identification such as the name of your application xs string Optional Your ID for this sender Maximum length 127 characters xs string Optional Your identification of the type of customer Maximum length 127 characters xs string Optional Sender s device ID such as a mobile device s IMEI number or
184. nd 31 indicates the date of the month Specifying 0 indicates that payment can be made on any day of the month 166 August 7 2012 Adaptive Payments Developer Guide Preapproval API Operation NE 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 NOTE You must specify a value unless you have specific permission from PayPal to omit this value ipnNotificationUrl 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 Maximum length 1024 characters maxAmount PerPayment xs decimal Optional The preapproved maximum amount per payment It cannot exceed the preapproved maximum total amount of all payments maxNumberOf Payments xs int Optional The preapproved maximum number of payments It cannot exceed the preapproved maximum total number of all payments maxNumberOfPaymentsPerPe xs int riod Optional The preapproved maximum number of all payments per period You must specify a value unless you have specific permission from PayPal maxTotalAmountOfAllPayme xs decimal nt
185. nding the request in JSON and requesting an XML response August 7 2012 Adaptive Payments Developer Guide Getting Started NR 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 1kfg9groingghb4uw5 headers put X PAYPAL DEVICE IPADDRESS 168 212 226 204 headers put X PAYPAL REQUEST DATA FORMAT NV headers put X PAYPAL RESPONSE DATA FORMAT NV headers put X PAYPAL APPLICATION ID APP 80W284485P519543T NOTE HTTP headers are case sensitive Authentication Use your PayPal account API credentials to authenticate your application Your API credentials include an API username and API password If you are using 3 token authentication you must also specify an API signature If you are using a certificate the certificate is used with the username and password the signature is not used To specify API credentials include the following HTTP headers in your request message observing case sensitivity HTTP Headers for Authentication Header Description X PAYPAL SECURITY USERID Your API username X PAYPAL SECURITY PASSWORD Your API password X PAYPAL SECURITY SIGNATUR
186. ndingTypeList F any seo f allowedFundinaType 0 1 FundinaTypeList ses f fundingTypeInfo 1 FundingTypelnfo E FundingTypeList 22 FundingTypeInfo ses f fundingTypeInfo 1 FundingTypelnfo Ef FundingType 1 1 string FE any 0 Adaptive Payments Developer Guide August 7 2012 77 78 Pay API Operation PayRequest Message ves E ReceiverList 2 receiver 1 Receiver fe amount Gi email Ef phone e primary Ef invoiceld fe paymentType E Receiver 1 0 Ef paymentSubType F any ef email 0 1 j phone 0 1 PhoneNumberType f any 0 1 decimal 1 string E Receiver Gi amount decimal Ef email 1 string phone 1 PhoneNumberType e primary 1 boolean Gi invoiceId 41 string fe paymentType T string fe paymentSubType it string fl any E PhoneNumberType e countryCode 1 1 string s e phoneNumber 1 1 string 1 1 1 PhoneNumberType extension 0 1 string 1 boolean 1 string 41 string 1 string string Ej Senderldentifier LI e useCredentials 0 1 boolean 0 1 TaxldDetails E AccountIdentifier string fe phone 0 1 PhoneNumberType e taddDetails Ef email 0 1 F lany 0 ES TaxidDetails j taxid 0 1 string ss f taddType 0 1 string RE any 0 E PhoneNumberType Ef countryCode 1 1 string ses
187. nsRequest GetPaymentOptionsRequest Message fe RequestEnvelope E GetPaymentOptionsRequest Ef requestEnvelope 1 1 RequestEnvelope detailLevel 0 1 DetailLevelCode s payKey 1 1 string so e errorLanguage 1 1 string F any 0 Ej any 0 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 requestEnvelope common requestEnvelope Required Information common to each API operation such as the language in which an error message is returned RequestEnvelope Fields Field Description detailLevel common DetailLevelCode Optional Level of detail required by the client application pertaining to a particular data component The detail level is specified as a detail level code which has all the enumerated values of the detail level for the component By default the detail level code is ReturnA11 which provides the maximum level of detail Adaptive Payments Developer Guide August 7 2012 139 am 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 GetPaymentOptionsResponse Message E GetPa
188. nts Developer Guide Contents E PhoneNumberType Response Fields 0 e 145 ResponseEnvelope Fields 22er 146 PPFault Message ee 146 FaultMessage Fields 222 147 ErrorData Fields llle 148 ResponseEnvelope Fields 2 2 aa a a 148 GetPaymentOptions Errors 2 ee 149 Chapter 7 SetPaymentOptions API Operation 151 SetPaymentsOptionsRequest Message 2222s 151 SetPaymentOptionsRequest Fields 2 2 0 0 a eee ee ee 152 DisplayOptions Fields 2 2 a ee 153 InitiatingEntity Fields RR 153 Institution Customer Fields llle 154 SenderOptions Fields 22e 154 ReceiverOptions Fields 2 llle 155 InvoiceDataFields llle 155 Invoiceltem Fields waa aaa ao A Ae a e a a aa a a 155 Receiverldentifier Fields aoaaa a a 156 PhoneNumberType Fields aaou a 156 RequestEnvelope Fields a a 156 SetPaymentOptionsResponse Message a 157 ResponseEnvelope Fields aaa 157 PPFault Message llle sss ss sor son 158 FaultMessage Fields 2e 158 ErrorData Fields 2 ss soo Re RR EORR d Rok b de 159 ResponseEnvelope Fields 2 a 159 SetPaymentOptions Examples Using NVP and CURL 160 SetPaymentOptions Errors a oaoa rs 161 Chapter 8 Preapproval API Operation 163 Preapproval
189. nurl 0 Gi addressList 0 Gi feesPayer 0 e displayMaxTotalAmount 0 FE any 0 1 1 1 1 1 E PreapprovalDetailsResponse 1 1 1 ResponseEnvelope boolean string long decimal long dateTime string int DayOfWeek dateTime decimal int int decimal string string string string string dateTime string string AddressList string boolean string BaseAddress string August 7 2012 PreapprovalDetails API Operation PreapprovalDetailsResponse Message E ResponseEnvelope e timestamp e ack 1 1 e correlationId 1 build F any E AddressList 1 0 dateTime AckCode string string E BaseAddress linet line2 e city e state e type F any 1 0 ts 0 e postalCode O e countryCode 1 0 0 1 1 1 1 1 1 1 x string string string string string string string 179 sss PreapprovalDetails API Operation PreapprovalDetailsResponse Message PreapprovalDetailsResponse Fields Field Description addresslist ap AddressList Returns a list of billing addresses approved Whether the preapproval request was approved Possible values are e true The request was approved e 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 Use the preapprov
190. od Possible values are e NO PERIOD SPECIFIED DAILY WEEKLY BIWEEKLY SEMIMONTHLY MONTHLY ANNUALLY Whether a personal identification number PIN is required It is one of the following values e NOT REQUIRED A PIN is not required e REQUIRED A PIN is required Common response information including a timestamp and the acknowledgement status The URL to which the sender s browser is redirected after the sender approves the preapproval on paypal com Use the preapproval key to identify the preapproval as follows preapprovalKey preapprovalKey 182 August 7 2012 Adaptive Payments Developer Guide PreapprovalDetails API Operation NER PreapprovalDetailsResponse Message Field Description senderEmail startingDate status displayMaxTotalAmount feesPayer 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 First date for which the preapproval is valid Whether this preapproval is active represented by the following values e ACTIVE The preapproval is active e CANCELED The preapproval was explicitly canceled by the sender or by PayPal e DEACTIVED The preapproval is not active you can be reactivate it by resetting the personal identification number PIN or by contacting PayPal xs boolean Whether to display the maximum total amount of this preapproval It is one o
191. olicies 5 00 USD My PayPal Balance Memo of standard transaction Digital Goods bal cance PayPal protects your privacy and security Site Feedback If the sender chooses Cancel PayPal redirects the sender s browser to the cancel URL specified in the Pay API operation s request message If the sender chooses Pay the Thank you for using PayPal page appears in the minibrowser Adaptive Payments Developer Guide August 7 2012 43 al Introducing Adaptive Payments Embedded Payments Jos R mirez spree PayPal j Thank you for using PayPal Receiver Amount Rapid Action Towing 5 00 Total 5 00 USD PayPal protects your privacy and security Site Feedback When the sender clicks Close PayPal redirects the sender s browser to the return URL specified in the Pay API operation s request message NOTE 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 For subsequent payments in which PayPal does not require the account holder to log in again and the account holder has chosen to be remembered PayPal bypasses the log in steps For example the lightbox for reviewing a payment would appear in your page as follows 44 August 7 2012 Adaptive Payments Developer Guide Introducing Adaptive Payments I Embedded Payments Rec
192. onId 1 1 string FE any 0 build 1 1 string FE any 0 E RefundInfoList E RefundInfoList E RefundInfo s f refundinfo 1 RefundInfo Ef receiver 1 Receiver e refundStatus 1 string e refundNetAmount 1 decimal e refundFeeAmount 41 decimal e refundGrossAmount 1 decimal e totalOFAllReFunds 1 decimal e refundHasBecomeFull 1 boolean e encryptedRefundTransactionId 0 1 string e refundTransactionStatus 1 string e errorList 1 ErrorList FE any E RefundInfo Ej Receiver receiver 1 1 Receiver amount 1 1 decimal e refundStatus 0 1 string Ef email 0 1 string e refundNetAmount 0 1 decimal fe phone 0 1 PhoneNumberType e refundFeeAmount 0 1 decimal primary 0 1 boolean e refundGrossAmount 0 1 decimal invoiceld 0 1 string vo 8 totalOfAllRefunds 0 1 decimal Ef paymentType 0 1 string e refundHasBecomeFull 0 1 boolean Ef paymentSubType 0 1 string e encryptedRefundTransactionId 0 1 string FE any 0 e refundTransactionStatus 0 1 string errorList 0 1 ErrorList Zany 4 E ErrorList s ef error 1 ErrorData Adaptive Payments Developer Guide August 7 2012 219 sa Refund API Operation Refund Response Message ES Receiver E PhoneNumberType Ef amount 1 1 decimal e countryCode 1 1 string email 0 1 string s e phoneNumber 1 1 string Ef phone 1
193. onal The PayPal transaction ID associated with the payment The IPN message associated with the payment contains the transaction ID trackingld xs string Optional The tracking ID that was specified for this payment in the PayRequest message 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 By default the detail level code is ReturnA11 which provides the maximum level of detail errorLanguage xs string Required RFC 3066 language in which error messages are returned by default it is en_US which is the only language currently supported PaymentDetailsResponse Message The PaymentDetailsResponse message contains information about the payment 110 August 7 2012 Adaptive Payments Developer Guide E PaymentDetailsResponse Ef responseEnvelope cancelUrl 1 1 string Ef currencyCode 1 1 string Ef ipnNotificationLrl 0 1 string Ef memo 0 1 string Ef paymentInfoList 1 1 PaymentInfoList Ef returnurl 1 1 string senderEmail 0 1 string ef status 1 1 string Ef trackingId 0 1 string Ef payKey 1 1 string ef actionType 1 1 string l feesPayer 1 1 string e reverseAllPa
194. onal Information 500000 520002 520003 520003 520006 540031 579049 579051 580001 580022 580029 580030 589052 There is a system error Internal error User name password is incorrect Authentication failed API credentials are incorrect This call is not defined in the database You do not have permission to get these payment details The payment request you are looking for was not found in our system The tracking ID is invalid Invalid request Invalid request parameter payKey with value lt value gt Invalid request This transaction cannot be processed at this time Please try again later The transaction ID is invalid Since 1 6 0 Since 1 6 0 Since 1 3 0 Adaptive Payments Developer Guide August 7 2012 125 De PaymentDetails API Operation Payment Details Errors 126 August 7 2012 Adaptive Payments Developer Guide ExecutePayment API Operation The ExecutePayment API operation lets you execute a payment set up with the Pay API operation with the action Type 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 E ExecutePaymentRequest RequestEnvelope Ef requestEnvelope 1 1 RequestEnvelope e detailLevel 0 1 DetailLevelCode Ef payKey 1 1 string ees e
195. only by PayPal Merchant Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues GetShippingAddresses Errors Code Message Additional Information 520002 Internal error 520003 Authentication failed API credentials are incorrect Since 1 6 0 540031 Operation is not permitted because the credentials do not match Since 1 6 0 those of the initial operation 550001 e User is not allowed to perform this action Since 1 6 0 e You are not allowed to get the addresses for this key 580001 Invalid request lt value gt Since 1 6 0 580022 e Invalid request parameter lt value gt Since 1 6 0 e Invalid request parameter payKey with value lt value gt e No sender is associated with this key 580029 A pay key transaction ID or tracking ID is missing Since 1 6 0 580030 This transaction cannot be processed at this time Please try again Since 1 3 0 later Adaptive Payments Developer Guide August 7 2012 251 Ix GetShippingAddresses API Operation GetShippingAddresses Errors 252 August 7 2012 Adaptive Payments Developer Guide Adaptive Payment Commands and Redir
196. onvertCurrencyRequest Fields The table below describes the fields for the ConvertCurrencyRequest message Adaptive Payments Developer Guide August 7 2012 197 am 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 requestEnvelope common RequestEnvelope Required Information common to each API operation such as the language in which an error message is returned countryCode xs string Optional The two character ISO code for the country where the function is supposed to happen The default value is US conversionType xs string Optional The conversion type allows you to determine the converted amounts for a PayPal user in different currency conversion scenarios e g sending a payment in a different currency than what this user holds accepting payment in a different currency than what the user holds or converting a balance to a different currency than the user holds The default value is SENDER_ SIDE CurrencyType Fields Field Description amount xs decimal Required The amount to be converted 198 August 7 2012 Adaptive Payments Developer Guide ConvertCurrency API Operation ConvertCurrencyRequest Message Field Description code xs string Required The currency
197. oper Guide August 7 2012 57 58 Introducing Adaptive Payments Embedded Payments 4 Create an embedded flow object and associate it with your payment form or button lt script gt function lt lt returnFunctionName gt gt lt lt Your code goes here gt gt lt script gt 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 VN quiet header X PAYPAL SERVICE VERSION 1 0 0 header X PAYPAL SECURITY USERID SAPIUSER header X PAYPAL SECURITY PASSWORD SAPIPASS header X PAYPAL SECURITY SIGNATURE SAPISIG header X PAYPAL REQUEST DATA FORMAT NV header X PAYPAL RESPONSE DATA FORMAT NV header X PAYPAL APPLICATION ID SAPPLICATIONID post data payKey PAYKEY amp requestEnvelope errorLanguage en US https www paypal com AdaptivePayments PaymentDetails if echo SPAYMENTDETAILS grep q amp status COMPLETED then echo Thank you for approving pay key SPAYKEY else echo Sorry you were unable to approve pay key SPAYKEY Please try another transaction fi Displaying and Collecting Shipping Addresses PayPal displays the default shipping address and allows the payment sender to change the address when you set senderOptions requireShippingAddressSelection to true in your request to the Set PaymentOptions API
198. operation You call the GetShippingAddresses API operation to obtain the selected shipping address after invoking the embedded payment flow The steps in this example assume that you have implemented the JavaScript for invoking the embedded payment flow that you have set up your button or form to invoke the flow and that you have included the code to close the window associated with the flow To display and collect the selected shipping address 1 Call the Pay API operation with actionType set to CREATE to obtain a payment key 2 Set senderOptions requireShippingAddressSelection to true in your request to Set PaymentOptions and call the API operation August 7 2012 Adaptive Payments Developer Guide Introducing Adaptive Payments E 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 The sender is not explicitly identified as a PayPal account holder during the transaction and is not required to have a PayPal account Each receiver of a guest payment must be a verified PayPal Business Verified or Premier Verified a
199. or if any that resulted on an attempted payment to a recelver FundingPlan Fields Field Description fundingPlanld xs string ID for this funding plan fundingAmount common CurrencyType Amount of available funding backupFundingSource ap FundingSource Backup funding source senderFees common CurrencyType currencyConversion charge Fees to be paid by the sender ap CurrencyConversion The currency conversion associated with the funding plan ap FundingPlanCharge The amount to be charged to this funding plan CurrencyType Fields Field Description amount xs decimal The converted amount Adaptive Payments Developer Guide August 7 2012 91 Pay API Operation PayResponse Message Field Description code xs string The currency code for the converted amount Possible values are Australian Dollar AUD Brazilian Real BRL NOTE The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts Canadian Dollar CAD Czech Koruna CZK Danish Krone DKK Euro EUR Hong Kong Dollar HKD Hungarian Forint HUF Israeli New Sheqel ILS Japanese Yen JPY Malaysian Ringgit MYR NOTE The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts Mexican Peso MXN Norwegian Krone NOK New Zealand Dollar NZD Philippine Peso PHP Polish Zloty
200. or service described herein PayPal Inc reserves the right to make changes to any information herein without further notice What s New Contents Adaptive Payments Developer Guide August 7 2012 15 1 8 1 Features CC 15 Senderldentifier Fields 22e 15 TaxldDetails Fields 22e 15 Chapter 1 Introducing Adaptive Payments 17 Adaptive Payments Actors and Objects a 17 Simple Parallel and Chained Payments llle 19 Simple Payments aoaaa 20 Parallel Payments a 20 Chained Payments aao aa ee 21 Payment Approval 22 a 22 Adaptive Payments Service Permissions 2 0 23 Explicit Approval Payment Flow 2 23 Preapproved Payments Flow 2l 25 Implicit Approval Payments Flow len 27 Embedded Payments rs 27 Embedded Payment Flow Presentations 28 Kinds of Embedded Payments a 30 Embedded Payments Implementation Basics 31 Embedded Payment Experience o 0002 eee ee eee 31 Preapprove Future Payments Checkbox llle 37 Shipping Address Information ao oa aa 39 Embedded Payment Experience llle 40 Setting Up Web Pages to Invoke the Embedded Payment Flow Using a Lightbox 55 Setting Up Web Pages to Invoke the Embedded Payment Flow Using a Minibrowser 57 Displaying and
201. or the payment This is a list of funding selections that can be combined in any order to allow payments to use the indicated funding type If this field is omitted the payment can be funded by any funding type that is supported for Adaptive Payments NOTE FundingConstraint is unavailable to API callers with standard permission levels for more information refer to the section Adaptive Payments Permission Levels Adaptive Payments Developer Guide August 7 2012 83 sa Pay API Operation PayRequest Message FundingTypelnfo Fields Field Description fundingType xs string Required Specifies a list of allowed funding selections for the payment This is a list of funding selections that can be combined in any order to allow payments to use the indicated funding type If this field is omitted the payment can be funded by any funding type that is supported for Adaptive Payments Allowable values are e ECHECK Electronic check e BALANCE PayPal account balance e CREDITCARD Credit card NOTE ECHECK and CREDITCARD include BALANCE implicitly NOTE FundingConstraint is unavailable to API callers with standard permission levels for more information refer to the section Adaptive Payments Permission Levels ReceiverList Fields Field Description receiver ap Receiver Required Receiver is the party whose account is credited Receiver Fields Field Description amount email
202. ot 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 e You are not allowed to confirm the preapproval for this key Since 1 6 0 e User is not allowed to perform this action 559044 Account setting on the receiver prohibited the payment 560027 The argument value is unsupported 569000 Split payments are not supported at this time 569013 The preapproval key has been canceled 569016 Preapproval PIN functionality is not enabled 569017 The preapproval key has been suspended 569018 Preapproved payments have been disabled 569019 The preapproval has been suspended due to too many PIN failures 569042 The email account is not confirmed by PayPal 579007 The maximum number of receivers is lt number gt 579010 If a preapproval key is specified the sender s email address must be too 579014 The preapproval key specifies a different sender than the payment request 579017 The amount for the primary receiver must be greater than or equal to the total of other chained receiver amounts 579024 The preapproval key cannot be used before the start date or after the end date 579025 The preapproval key cannot be used on this weekday 579026 The preapproval key cannot be used on this day of the month 579027 The preapproval key specifies a d
203. ovalRequest Message The PreapprovalRequest message contains the fields to set up a preapproval agreement between yourself and a sender 164 August 7 2012 Adaptive Payments Developer Guide Preapproval API Operation Nx PreapprovalRequest Message E PreapprovalRequest E RequestEnvelope Ef requestEnvelope 1 1 RequestEnvelope e detailLevel 0 1 DetaillevelCode E clientDetails 0 1 ClientDetailsType s e errorLanguage 1 1 string Ef cancelUrl 1 1 string FE any 0 Ef currencyCode 1 1 string dateOfMonth 0 1 int e dayOFWeek 0 1 DayofWeek e ipAddress 41 string e endingDate 0 1 dateTime deviceId 1 string Ef maxAmountPerPayment 0 1 decimal applicationId 1 string Ef maxNumberOfPayments 0 1 int model 41 string Ef maxNumberOfPaymentsPerPeriod 0 1 int geoLocation 1 string Ef maxTotal mountOfAllPayments 0 1 decimal e customerType 0 1 string Ef paymentPeriod 0 1 string partnerName 1 string Ef returnurl 1 1 string e customerId 41 string E memo 0 1 string FE any Ef ipnNotificationUrl 0 1 string Ef senderEmail 0 1 string E DayOfweek Ef startingDate 1 1 dateTime pinType 0 1 string Ef FeesPayer 0 1 string e display MaxTotal mount 0 1 boolean Ej any PreapprovalRequest Fields Field Description cancelUrl xs string Required The URL to which the sender s browser is r
204. overrides the header image URL specified in your account s Profile The image dimensions are 750 pixels high x 90 pixels wide New field xs string Optional The business name to display 268 August 7 2012 Adaptive Payments Developer Guide 1 6 0 Features ERE 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 Invoiceltem 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 requireShippingAddressSe xs boolean lection Optional If true require the sender to select a shipping address during the payment flow default is false Adaptive Payments Developer Guide August 7 2012 269 a 1 6 0 Features New Senderldentifier Structure for Ver
205. p 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 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 To set up a web page to invoke the embedded payment flow Adaptive Payments Developer Guide August 7 2012 55 56 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 adapt ivepayment 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 Set the expType parameter to indicate your preference for the context in which the PayPal payment flow is displayed You must specify light for lightbox lt form action https www paypal com webapps adaptivepayment flow pay target PPDGFrame gt lt input id type type hidden name expType value light gt input id paykey type hidden name paykey value AP gt lt input id preapprovalkey type hidden name preapproval
206. payment key that you can use for other API operations such as for obtaining details of the payment or for issuing a refund 26 August 7 2012 Adaptive Payments Developer Guide 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 The following diagram shows the basic flow of control during an implicitly approved payment operation Legend gt apical Pay Key D Pay request PayPal IN API Server Pay 2 Pay key The following items correspond to the circled numbers in the diagram 1 Your site or device sends a Pay request to PayPal NOTE A web flow is not required 2 PayPal responds with a key that you use for other API operations Embedded Payments An embedded payment is a payment that initiates a visual presentation of the Adaptive Payments payment flow in which the sender appears to never leave your checkout or payment page Embedded payments make it easier for a sender to make a payment because PayPal may allow the sender to bypass the PayPal login step The ability to bypass the login relies on a remember me cookie which is stored in the sender s browser when the sender chooses to take adv
207. pecified in the ipnNotificationUrl field of the Pay request Notes About the Pay API Operation 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 If reverseAllParallelPaymentsonError is disabled completed transfers are not reversed and funds that have already been transferred are no longer available to the sender You can specify your own unique tracking ID in the trackingID field and use this value to obtain information about a payment or to request a refund The tracking ID is provided as a convenience in cases when you already maintain an ID that you want to associate with a payment You can also track payments using the payKey You can use the Pay API operation to make unilateral payments under limited circumstances A unilateral payment is a payment that is made to a receiver who does not have a PayPal account Unilateral payments can be used with simple or parallel payments that are implicit or preapproved Unilateral payments are not designed to be used with chained payments or payments that require manual approval through the web flow When you send a unilateral payment you send a payment request that includes an email address for a receiver and this email address is not linked to a registered PayPal account The
208. ple as primary receiver you may require secondary receivers to perform some action such as shipping goods or waiting for expiration of a return period before making payment To complete the payment you must explicitly execute a payment to secondary receivers after the sender pays you The payment must occur within 90 days after which you cannot complete the payment as part of the original chained payment Payment Approval The sender of a payment must approve the transfer The sender can log in to paypal com to approve each payment preapprove payments or when the sender is your application be implicitly approved to make payments NOTE Preapproval requests require permission from PayPal There are 3 kinds of payment approvals e Explicit approval payments in which the sender logs in to paypal com to approve each payment Explicitly approving payments is the traditional way to pay with PayPal This method is the only option unless the sender has set up a preapproval agreement or you the API caller are also the sender August 7 2012 Adaptive Payments Developer Guide 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 approva
209. ple code below uses the insecure setting to work around the certificate for testing in a sandbox environment For actual implementations you must specify the location of the certificate Request curl 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 PaymentDetails d payKey AP 3TY01110684428730 amp requestEnvelope errorLanguage en US Response responseEnvelope timestamp 2009 08 14T09 3A00 3A37 748 07 3A00 amp responseEnvelope ack Success amp responseEnvelope correlat ionId 7967b2d03745a amp responseEnvelope build DEV amp cancelUrl your cancel url amp currencyCode USD amp logDefaultShippingAddress false amp memo Simple payment example amp paymentInfoList paymentInfo 0 receiver amount 100 00 s amp payment InfoList paymentInfo 0 receiver email receiver domain amp payment InfoList paymentInfo 0 receiver primary false amp returnUrl your retur url amp senderEmail sender domain amp status CREATED SpayKey AP 3TY01110684428730 amp actionType PAY amp feesPayer EACHRECEIVER August 7 2012 Adaptive Payments Developer Guide PaymentDetails API Operation Payment Details Errors Payment Details Errors Code Message Additi
210. plications you may be both the application owner and a receiver For example as the owner of a website you are the receiver of payments from the senders who are your customers The following diagram shows the relationship between a sender you as a receiver and PayPal Your application amen PayPal Leal q API Server Sender Receiver Adaptive Payments Developer Guide August 7 2012 17 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 The following diagram shows the relationship between a sender you as an application owner that directs payments to receivers and PayPal 7 PayPal nmm API Server Said Your application e im e nm Receiver 2 A y This diagram shows a payment in which the sender pays multiple receivers in a parallel payment With parallel payments the sender can see the transaction to each receiver The following diagram shows the relationship between a sender you as an application owner that directs payments to receivers and PayPal in a chained payment Your application G p PayPar m m API Server e S Sender TET Primary receiver Secondary receiver In a chained payment the sender pays the pr
211. ponse was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues PreapprovalDetails 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 Adaptive Payments Developer Guide August 7 2012 187 188 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 NOTE The sample code below uses the insecure setting to work around the certificate for testing in a sandbox environment For actual implementations you must specify the location of the certificate Request curl 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 PAY
212. proval In this example the caller of the Preapproval API sets up a preapproval that is valid from July 17 2009 through December 12 2009 The maximum amount of the preapproval is 1 500 of which a maximum of 30 payments are authorized with the largest payment not to exceed 200 The sender need not include a PIN The response contains the preapproval key that the caller can use in the Pay API operation NOTE The sample code below uses the insecure setting to work around the certificate for testing in a sandbox environment For actual implementations you must specify the location of the certificate Request August 7 2012 Adaptive Payments Developer Guide 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 d cancelUrl http your cancel url amp currencyCode USD sendingDate 2009 12 13T08 3A00 3A00 000Z amp maxAmountPerPayment 200 00 amp maxNumberOfPayments 30 amp maxTotalAmountOfAllPayments 1500 00 amp pinType NOT REQUIRED amp requestEnvelope errorLanguage en US amp returnUrl http your return url amp startingDate 2009 07 13T072 3A00 3A00 000Z amp senderEmail sender domain Response respon
213. quest field 85 156 218 extension response field 96 120 145 225 F FaultMessage PPFault fields 97 122 134 147 158 172 186 194 207 227 241 249 fees_payer IPN variable 260 feesPayer request field 80 169 183 feesPayer response field 114 firstName response field 143 154 from response field 93 239 fundingAmount response field 91 236 fundingConstraint request field 81 FundingConstraint request fields 83 FundingPlan fields 91 236 FundingPlan response field 236 FundingPlanCharge response fields 93 fundingPlanId request field 127 fundingPlanld response field 91 236 fundingSource response field 93 FundingSource response fields 92 238 fundingSourceld request field 266 fundingSourceld response field 93 239 fundingType request field 84 fundingType response field 116 fundingTypelInfo request field 83 Adaptive Payments Developer Guide FundingTypelnfo request fields 84 fundingTypelInfo response field 116 FundingTypelnfo 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 GetPaymentOptionsRequest message 139 GetPaymentOptionsResponse fields 141 GetPaymentOptionsRe
214. r extension xs string Telephone extension ResponseEnvelope Fields Field ack build correlationId timestamp Description common AckCode Acknowledgement code It is one of the following values e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message xs string Build number It is used only by PayPal Merchant Technical Support xs string Correlation identifier It is a 13 character alphanumeric string for example db87c705a910e that is used only by PayPal Merchant Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs 96 August 7 2012 Adaptive Payments Developer Guide E FaultMessage e responseEnvelope 1 1 ResponseEnvelope e error 0 ErrorData ErrorData e errorId long domain string e su
215. r exceptionID This field is not used message xs string A description of the error parameter common ErrorParameter Represents contextual information about the error severlty common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request was interrupted e 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 e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message build xs string Build number It is used only by PayPal Merchant Technical Support August 7 2012 Adaptive Payments Developer Guide Pay API Operation 5 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 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must
216. r there is a warning message e FailureWithWarning The operation failed with a warning message build xs string Build number It is used only by PayPal Merchant Technical Support August 7 2012 Adaptive Payments Developer Guide GetPaymentOptions API Operation E 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 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues GetPaymentOptions Errors Code Message Additional Information 520002 Internal error 520003 Authentication failed API credentials are incorrect Since 1 6 0 540031 You do not have permission to get these payment options 540031 You do not have permission to get these payment options Since 1 6 0 Operation is not permitted because the credentials do not match those of the initial operation 550001 User is not allowed to perform this action 580001 Invalid request value Since 1 6 0 580022 Invalid request parameter payKey with
217. rallelPaymentsOnError 0 1 boolean 7 preapprovalkey 0 1 string e fundingConstraint sender 0 1 SenderIdentifier F any 0 E PaymentInfoList Ef paymentInfo 1 PaymentInfo 1 1 ResponseEnvelope 0 1 FundingConstraint PaymentDetails API Operation PaymentDetailsResponse Message E ResponseEnvelope e timestamp 1 1 dateTime e ack 1 1 AckCode e correlationId 1 1 string e build 1 1 string 7 any 0 E PaymentInfoList seol f paymentInfo 1 PaymentInfo E FundingConstraint sec allewedFundingType 0 1 FundingTypeList E SenderIdentifier ss e useCredentials 0 1 boolean i PaymentInfo 22 PaymentInfo e transactionId e transactionStatus Gi receiver e refundedAmount e pendingRefund e senderTransactionId e senderTransactionStatus e pendingReason Ej any Adaptive Payments Developer Guide string string Receiver decimal boolean string string string August 7 2012 e transactionId e transactionStatus fe receiver e refundedAmount e pendingRefund e senderTransactionId e senderTransactionStatus e pendingReason Fl any E Receiver E amount email phone primary Gi invoiceId 2 paymentType paymentSubType Plany string string Receiver decimal boolean string string string decimal string PhoneNumberType boolean string str
218. refundInfo 0 receiver amount 3 15 amp refundInfoList refundInfo 0 receiver email receiver Qdomain amp refundInfoList refundInfo 0 refundStatus REFUNDED amp refundInfoList refundInfo 0 refundNetAmount 2 81 amp refundInfoList refundInfo 0 refundFeeAmount 0 34 amp refundInfoList refundInfo 0 refundGrossAmount 3 15 amp refundInfoList refundInfo 0 totalOfAllRefunds 3 15 amp refundInfoList refundInfo 0 refundHasBecomeFull true amp refundInfoList refundInfo 0 encryptedRefundTransactionId 48K11199GC160 amp refundInfoList refundInfo 0 refundTransactionStatus COMPLETED amp refundInfoList refundInfo 1 receiver amount 1 78 serefundInfoList refundInfo 1 receiver email receiver2 Odomain amp refundInfoList refundInfo 1 refundStatus REFUNDED amp refundInfoList refundInfo 1 refundNetAmount 1 43 amp refundInfoList refundInfo 1 refundFeeAmount 0 35 amp refundInfoList refundInfo 1 refundGrossAmount 1 78 amp refundInfoList refundInfo 1 totalOfAllRefunds 1 78 amp refundInfoList refundInfo 1 refundHasBecomeFull true amp refundInfoList refundInfo 1 encryptedRefundTransactionId 40Y76985BU687 amp refundInfoList refundInfo 1 refundTransactionStatus COMPLETED Refund Errors Code Message Additional Information 500000 There is a system error 520002 Internal error 520003 User name password is incorrect 520006 This call is not defined in the database 520008 You do not have a verified ACH 520009 Account is restricted 520010
219. rency 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 e UNILATERAL The payment is pending because it was made to an email address that is not yet registered or confirmed e 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 e VERIFY The payment is pending because the receiver is not yet verified e RISK The payment is pending while it is being reviewed by PayPal for risk e OTHER The payment is pending for a reason other than those listed above For more information contact PayPal Customer Service pendingRefund xs boolean Whether the payment has a pending refund Possible values are e true The payment has a pending refund e false The payment does not have a refund pending Adaptive Payments Developer Guide August 7 2012 117 a PaymentDetails API Operation PaymentDetailsResponse Message Field Description receiver ap Receiver The receiver of the payment refundedAmount xs decimal senderTransactionId senderTransactionStatus transactionId transactionStatus The total amount refunded for this payment since the payment occurred xs string The
220. request fields 168 returnUrl response field 115 182 reverse all parallel payments on error IPN variable 258 reverseAllParallelPaymentsOnError request field 81 reverseAllParallelPaymentsOnError response field 115 S sandbox environment 66 99 101 102 103 sandbox beta 66 selectedAddress response field 247 sender request field 82 sender_email IPN variable 258 senderEmail request field 82 senderEmail request fields 168 senderEmail response field 115 183 senderFees response field 91 236 Senderldentifier request fields 86 Senderldentifier response fields 120 senderOptions request field 152 senderOptions response field 142 senderTransactionID response field 118 senderTransactionStatus response field 118 SetPaymentOptionsRequest fields 152 SetPaymentOptionsResponse message 151 157 SetPaymentOptionsResponse operation 151 Adaptive Payments Developer Guide setTrigger JavaScript function 255 severity field 94 98 123 131 134 148 159 173 187 195 208 224 228 242 250 shippingAddressId request field 152 shippingAddressId response field 142 startFlow JavaScript function 255 startingDate request fields 168 startingDate response field 183 state response field 184 247 status IPN variable 258 status response field 116 183 subdomain field 94 98 123 131 134 148 159 173 187 195 208 224 228 242 250 T timestamp response field 96 99 121 123 133 135 146 149 157 160 171 174 185 187 1
221. 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 deviceld This field is now optional it is no longer required 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 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 maxNumberOf Payments The preapproved maximum number of payments is only available when you explicitly set the email address in the PreapprovalRequest message 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 Adaptive Payments Developer Guide August 7 2012 289 a 1 1 0 Features Changes to RefundRespons
222. ress postalCode xs string The postal code of the address state xs string The state for the address Adaptive Payments Developer Guide August 7 2012 247 al GetShippingAddresses API Operation PPFault Message Field Description type xs string The type of address ResponseEnvelope Fields Field Description ack build correlationId timestamp common AckCode Acknowledgement code It is one of the following values e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message xs string Build number It is used only by PayPal Merchant Technical Support xs string Correlation identifier It is a 13 character alphanumeric string for example db87c705a910e that is used only by PayPal Merchant Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope infor
223. ription of the error parameter common ErrorParameter Represents contextual information about the error severlty common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request was interrupted e 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 e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message build xs string Build number It is used only by PayPal Merchant Technical Support Adaptive Payments Developer Guide August 7 2012 195 a 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 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive
224. s Optional The preapproved maximum total amount of all payments It cannot exceed 2 000 USD or its equivalent in other currencies NOTE You must specify a value unless you have specific permission from PayPal to omit this value memo xs string Optional A note about the preapproval Maximum length 1000 characters including newline characters Adaptive Payments Developer Guide August 7 2012 167 SS Preapproval API Operation PreapprovalRequest Message Field Description paymentPeriod xs string Optional The payment period It is one of the following values e 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 It is one of the following values e NOT REQUIRED A PIN is not required default e REQUIRED A PIN is required the sender must specify a PIN when setting up the preapproval on PayPal requestEnvelope common RequestEnvelope Required Information common to each API operation such as the language in which an error message is returned returnUrl xs string Required The URL to which the sender s browser is redirected after the sender approves the preapproval on paypal com Maximum length 1024 characters senderEmail xs string Optional Sender s email address If not specified the email a
225. s 79 PayRequest message 77 PayResponse fields 90 PayResponse message 86 pendingReason response field 117 pendingRefund response field 117 phone request field 86 156 phone response field 120 145 phoneNumber request field 85 156 218 PhoneNumber request fields 85 156 218 phoneNumber response field 96 120 145 225 PhoneNumber response fields 95 120 145 225 pin request field 81 pinType request fields 168 pinType response field 182 PPFault message 96 121 133 146 158 171 185 193 206 226 240 248 August 7 2012 Preapproval Message variables 260 preapproval_key IPN variable 260 PreapprovalDetails API operation 177 PreapprovalDetailsRequest fields 177 PreapprovalDetailsRequest message 177 PreapprovalDetailsResponse fields 180 PreapprovalDetailsResponse message 178 preapprovalKey request field 81 177 191 preapprovalKey response field 115 preapprovalKey response fields 170 PreapprovalRequest fields 165 PreapprovalRequest message 164 PreapprovalResponse fields 170 price request field 155 price response field 145 production environment 66 R reason_code IPN variable 260 receiver request field 84 155 217 receiver response field 94 118 130 144 222 Receiverldentifier request fields 156 Receiverldentifier response fields 145 receiverList request field 81 217 ReceiverList request fields 84 217 receiverOptions request field 153 ReceiverOptions request fields 155 receiverOptions response field 142 Rec
226. s a new header to be passed to identify the application ID The ClientDetails applicationId element is no longer necessary 280 August 7 2012 Adaptive Payments Developer Guide 1 3 0 Features EE 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 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 e ECHECK Electronic check e BALANCE PayPal account balance e
227. s 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 Possible values are e ECHECK Electronic check e BALANCE PayPal account balance e 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 Adaptive Payments Developer Guide August 7 2012 283 EN 1 2 0 Features Field Description PaymentInfo send
228. s one of the following values e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message build xs string Build number It is used only by PayPal Merchant Technical Support Adaptive Payments Developer Guide August 7 2012 173 174 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 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues Preapproval 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 Setting up a preap
229. s only available when a partial refund has been requested xs decimal The total amount of the refund from this receiver 222 August 7 2012 Adaptive Payments Developer Guide Refund API Operation NER Refund Response Message Field Description refundStatus xs string Status of the refund It is one of the following values e REFUNDED Refund successfully completed e REFUNDED PENDING Refund awaiting transfer of funds for example a refund paid by eCheck e NOT_PAID Payment was never made therefore it cannot be refunded e ALREADY REVERSED OR REFUNDED Request rejected because the refund was already made or the payment was reversed prior to this request e NO API ACCESS TO RECEIVER Request cannot be completed because you do not have third party access from the receiver to make the refund e REFUND NOT ALLOWED Refund is not allowed e INSUFFICIENT BALANCE Request rejected because the receiver from which the refund is to be paid does not have sufficient funds or the funding source cannot be used to make a refund e AMOUNT EXCEEDS REFUNDABLE Request rejected because you attempted to refund more than the remaining amount of the payment call the PaymentDetails API operation to determine the amount already refunded e PREVIOUS REFUND PENDING Request rejected because a refund is currently pending for this part of the payment e NOT PROCESSED Request rejected because it cannot be processed at this
230. s 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 Possible values are e ECHECK Electronic check e BALANCE PayPal account balance e CREDITCARD Credit card 116 August 7 2012 Adaptive Payments Developer Guide PaymentDetails API Operation NER PaymentDetailsResponse Message PaymentinfoList Fields Fields Description paymentInfo ap Payment Info 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 Possible values are e 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 e ECHECK The payment is pending because it was made by an eCheck that has not yet cleared e 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 e MULTI CURRENCY The receiver does not have a balance in the cur
231. s the new pendingReason parameter This parameter returns a string describing the reason why a transaction is pending Possible values are e 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 e ECHECK The payment is pending because it was made by an eCheck that has not yet cleared e 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 e 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 e UNILATERAL The payment is pending because it was made to an email address that is not yet registered or confirmed e 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 e VERIFY The payment is pending because the receiver is not yet verified e RISK The payment is pending while it is being reviewed by PayPa
232. s to Preapproval API Operation for Version 1 2 0 286 Changes to Preapproval Details API Operation for Version 1 2 0 286 1 1 0 Featutres ilu o oo e RE e eO XS ee X XV e XE ae A 286 Changes to the Pay API Operation for Version 1 1 0 sls 287 Changes to PaymentDetails API Operation for Version 1 1 0 287 Changes to Preapproval API Operation for Version 1 1 0 289 Changes to PreapprovalDetails API Operation for Version 1 1 0 289 Changes to Refund API Operation for Version 1 1 00 0 289 Revision HISIOFV uunc og ox xoxo nex o Ede a E e e ae a o 2091 Index ew xoc momo m EO xs sme m VAS Umso a As TE cxx ow cw o 29B 12 August 7 2012 Adaptive Payments Developer Guide Contents Ex Adaptive Payments Developer Guide August 7 2012 13 E 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 NOTE Changes to API operations are backward compatible Senderldentifier Fields Field Description useCredentials xs boolean If true cred
233. sResponse 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 ReturnA11 which provides the maximum level of detail errorLanguage xs string Required RFC 3066 language in which error messages are returned by default it is en_US which is the only language currently supported PreapprovalDetailsResponse Message The PreapprovalDetailsResponse message provides details about the requested preapproval 178 August 7 2012 Adaptive Payments Developer Guide E Address Ef addresseeName 0 1 Ef baseAddress 1 1 Ef addressId 0 1 FE any 0 Adaptive Payments Developer Guide Gi responseEnvelope i Gi approved 1 Gi cancelUrl 1 Gi curPayments l Gi curPaymentsAmount 1 Gi curPeriodAttempts 0 curPeriodEndingDate 0 Gi currencyCode Ets Gi dateOfMonth 0 e dayOf Week 0 endingDate 0 Gi maxAmountPerPayment 0 Gi maxNumberOfPayments 0 seo maxNumberOfPaymentsPerPeriod 0 Gi maxTotal mountOFAllPayments 0 e paymentPeriod 0 e pinType 0 Gi returnUrl 1 Gi senderEmail 0 Gi memo 0 Gi startingDate Li Ef status iis E ipnNotificatio
234. sage Fields 2e 186 ErrorData Fields a 186 ResponseEnvelope Fields 2 2 0 o eo 187 PreapprovalDetails Examples Using NVP and CURL 187 Preapproval Details Errors 22s 189 Chapter 10 CancelPreapproval API Operation 191 CancelPreapprovalRequest Message oa a 191 CancelPreapprovalRequest Fields eee ee 191 RequestEnvelope Fields 2 22er 192 CancelPreapprovalResponse Message 2 0 0 eee ee 192 CancelPreapprovalResponse Fields llle 192 ResponseEnvelope Fields 2e 193 PPFault Message a eo oso A Soe Sk apis DR E Ou UR cate e aed 193 FaultMessage Fields 2 2 2e 194 ErrorData Fields 3 44 ana eai a ia a Bk Vee Ee Ree ee ALCUN 195 ResponseEnvelope Fields 2e 195 8 August 7 2012 Adaptive Payments Developer Guide Contents E CancelPreapproval Errors e ee 196 Chapter 11 ConvertCurrency API Operation 4197 ConvertCurrencyRequest Message 2222s 197 ConvertCurrencyRequest Fields 2 2 0 197 CurrencyType Fields 22s 198 CurrencyList Fields aaa 200 CurrencyCodeList Fields 2 oao 201 RequestEnvelope Fields 22e 202 ConversionType Fields o 202 ConvertCurrencyResponse Message 2222s 202 ConversionCurrencyResponse Fields 0 000 eee eee ne 20
235. seEnvelope timestamp 2009 08 14T09 3A00 3A37 748 07 3A00 amp responseEnvelope ack Success amp responseEnvelope correlat ionId 7967b2d03745a amp responseEnvelope build DEV amp preapprovalKey PA 9JR04288NR0519129 Preapproval Errors Code Message Additional Information 500000 520002 520003 520006 569016 569018 570026 579038 579055 There is a system error Internal error User name password is incorrect This call is not defined in the database Preapproval PIN functionality is not enabled Preapproved payments have been disabled The starting date is too far in the future The date range between the start date and the end date is too wide The limit for total amount of all payments is above PayPal s limit Adaptive Payments Developer Guide August 7 2012 175 SS Preapproval API Operation Preapproval Errors Code Message Additional Information 580001 Invalid request 580022 Account already exists Since 1 3 0 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 value 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 176 August 7 2012 Adaptive Payments Developer Guide PreapprovalDetails API Operation Use the PreapprovalDetails API operation to ob
236. sed receiverList receiver 0 email A receiver s email address receiverList receiver 0 amount Amount to be credited to the receiver s account currencyCode The code for the currency in which the payment is made you can specify only one currency regardless of the number of receivers cancelUrl URL to redirect the sender s browser to after canceling the approval for a payment it is always required but only used for payments that require approval explicit payments Adaptive Payments Developer Guide August 7 2012 73 sa Pay API Operation Pay Summary Field Description returnUrl requestEnvelope errorLanguage 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 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 For a parallel payment you must specify both the above values and the following fields Field Description receiverList receiver n email receiverList receiver n amount The receiver s email address for each receiver where n is between 0 and 5 for a maximum of 6 receivers Amount to send to each corresponding receiver Chained Payments For a chained payment you must specify all required fields for a parallel payment and you must also specif
237. sion 1 6 0 Field Description useCredentials xs boolean Optional If true use credentials to identify the sender default is false New Accountldentifier 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 Receiverldentifier Structure for Version 1 6 0 Field Description base common AccountIdentifier Account identifier 270 August 7 2012 Adaptive Payments Developer Guide 1 6 0 Features ERN Additional Error Messages for Version 1 6 0 Code Message 520003 Authentication failed API credentials are incorrect 520003 e The caller s credential doesn t have permission for the fee payer value e The caller s credential doesn t have permission for the payment type value e Authentication failed API credentials are incorrect 540031 You do not have permission to exec
238. specified when PaymentSubType is specified e Your Application is not approved to use the PaymentSubType lt value gt e Your Application is not approved to use the PaymentType lt value gt e Invalid request parameter PaymentType should be the same for all receivers lt value gt e Inconsistant request parameter for digitalgoods e Invalid request parameter PaymentSubType should be the same for all receivers lt value gt e Invalid Request RECEIVABLE cannot be used with other funding types e For chained payments receivers must have premier or business accounts The argument is unsupported e Currently the system does not accept the currency lt value gt e Unsupported country code lt value gt e Currently the system does not accept the currency lt value gt e The parameter is not supported The URL lt value gt is malformed Invalid request This transaction cannot be processed at this time Please try again later This payment cannot be processed because no payment source is available The preapproval key is invalid If a fractional amount is rounded due to currency conversion funds could be lost The email address is invalid It may not be registered in PayPal s system yet Since 1 6 0 Since 1 6 0 Since 1 3 0 Adaptive Payments Developer Guide August 7 2012 107 E Pay API Operation Pay Errors 108 August 7 2012 Adaptive Payments Developer Guide PaymentDetails API Operation Use the Paymen
239. sponse message 140 GetShippingAddresses API operation 245 GetShippingAddressesRequest fields 245 GetShippingAddressesRequest message 245 GetShippingAddressesResponse fields 247 GetShippingAddressesResponse message 246 H headerImageUrl request field 153 headerImageUrl response field 142 identifier request field 155 identifier response field 145 initiatingEntitity request field 152 initiatingEntitity response field 142 InitiatingEntity response fields 143 153 Institution Customer response fields 143 154 institutionCustomer response field 143 153 institutionCustomerld response field 143 154 institutionId response field 143 154 invoiceData request field 155 InvoiceData request fields 155 invoiceData response field 144 InvoiceData response fields 144 InvoiceItem request fields 155 Adaptive Payments Developer Guide Invoiceltem response fields 145 ipn_notification_url IPN variable 259 ipnNotificationUrl request field 81 ipnNotificationUrl request fields 167 ipnNotificationUrl response field 115 182 isOpen JavaScript function 255 item request field 155 item response field 144 itemCount request field 156 itemCount response field 145 itemPrice request field 156 itemPrice response field 145 J JavaScript functions 255 264 266 K key request field 245 L lastFourOfAccountNumber response field 92 238 lastName response field 143 154 linel response field 184 247 line2 response field 184 247 maxAmoun
240. st 7 2012 119 E PaymentDetails API Operation PaymentDetailsResponse Message TaxldDetails 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 Accountldentifier 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 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 e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message 120 August 7 2012 Adaptive Payments Developer Guide PaymentDetails API Operation NER 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 NOTE You must log
241. stitution Maximum length 64 characters lastName xs string Required The last name of the consumer as known by the institution Maximum length 64 characters Adaptive Payments Developer Guide August 7 2012 143 144 GetPaymentOptions API Operation GetPaymentOptionsResponse Message SenderOptions Fields Field Description requireShippingAddressSe lection referrerCode xs boolean If true require the sender to select a shipping address during the embedded payment flow default is false 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 Maximum length 1000 characters customId xs string An external reference or identifier you want to associate with the payment Maximum length 1000 characters invoiceData ap InvoiceData Item information for the payment which could appear on an invoice receiver ap Receiverldentifier Receiver ID associated with these options InvoiceData Fields Field Description item ap InvoiceItem Any number of items associated with the payment totalTax xs decimal Total tax associated with the payment totalShipping xs decimal Total shipping charge associated with the payment August 7 2012 Adaptive Payments Developer Guide Invoiceltem Fields GetPaymentOptions API Operat
242. t Invoiceltem Fields Field Description name xs string Optional Name of item identifier xs string Optional External reference to item or item ID price xs decimal Optional Total of item line Adaptive Payments Developer Guide August 7 2012 155 al SetPaymentOptions API Operation SetPaymentsOptionsRequest Message Field Description itemPrice xs decimal Optional Price of an individual item itemCount xs int Optional Item quantity Receiverldentifier Fields Field email phone Description xs string Optional Receiver s email address Maximum length 127 characters common PhoneNumberType Optional Receiver s phone number PhoneNumberType Fields Field Description countryCode xs string Required Telephone country code phoneNumber xs string Required Telephone number extension xs string Optional Telephone extension RequestEnvelope Fields Field Description detailLevel errorLanguage 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 ReturnA11 which provides the maximum level of detail xs string Required RFC 3066 language in which error messages are returned by default it
243. t Payment Notifications Preapproval Message Variables Variable Description fees payer trackingld preapproval_key reason code The payer of PayPal fees Possible values are e SENDER Sender pays all fees for personal implicit simple parallel payments do not use for chained or unilateral payments e PRIMARYRECEIVER Primary receiver pays all fees chained payments only e EACHRECEIVER Each receiver pays their own fee default personal and unilateral payments e SECONDARYONLY Secondary receivers pay all fees use only for chained payments with one secondary receiver The tracking ID that was specified for this payment in the PaymentDetailsRequest message The preapproval key returned after a PreapprovalRequest or the preapproval key that identifies the preapproval key sent with a PayRequest Whether this transaction is a chargeback partial or reversal Possible values are e Chargeback Settlement Transaction is a chargeback e Admin reversal Transaction was reversed by PayPal administrators e Refund Transaction was partially or fully refunded Preapproval Message Variables PayPal generates an IPN message that contains information about a preapproval in response to the Adaptive Payments Preapproval API operation Variable Description transaction type preapproval key approved cancel url current number of paymen ts The type of transaction For a preapproval this
244. t grant API access to a third party A personal account holder must issue the refund by specifying the transaction ID or by logging in to paypal com to make the refund 3 A payment made using the Pay API operation cannot be refunded by logging in to paypal com if the fees cannot be refunded In these cases you must use the Refund API operation to issue the refund 4 In the refund request specify the payment using either the pay key transaction ID or tracking ID it is not recommended to specify more than one of these arguments unless they identify the same payment If the arguments do not belong to the same payment the transaction ID is used next it uses the payment key If more than one way is specified the ID is never used 5 With the Adaptive Payments Pay API operation you can make payments to a person who does not have a PayPal account In essence you send a payment request that includes an email address for a receiver and this email address is not linked to a registered PayPal account The receiver receives an email notifying the receiver to create an account and claim the payment Supporting features include email notifications and IPNs to the sender receiver and API caller plus the ability to cancel unclaimed payments You can make such a payment in the same way that you make any other kind of payment however PayPal holds a payment to a receiver whose email address is not yet registered or confirmed until the receiver cre
245. t include https www paypalobjects com js external dg js for a lightbox or https www paypalobjects com js external apdg js fora minibrowser on any page that invokes or terminates the embedded payment flow Function and Signature Description PAYPAL apps DGFlow function New expType trigger null expType null e mini requests that the embedded payment flow displays in a minibrowser 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 266 August 7 2012 Adaptive Payments Developer Guide 1 6 0 Features EE 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 Fiel
246. tDetails 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 E PaymentDetailsRequest RequestEnvelope requestEnvelope 1 1 RequestEnvelope detailLevel 0 1 DetailLevelCode Ef payKey 0 1 string se e errorLanguage 1 1 string Ef transactionId 0 1 string fl any 0 Ef trackingld 0 1 string F l any 0 PaymentDetailsRequest Fields The payKey transactionId and trackingld fields identify the payment You can supply either the payKey field or the trackingld field in your request If you supply both fields the payKey field will be used to identify the payment and the trackingld field will be ignored Field Description payKey xs string Optional The pay key that identifies the payment for which you want to retrieve details This is the pay key returned in the PayResponse message requestEnvelope common RequestEnvelope Required Information common to each API operation such as the language in which an error message is returned Adaptive Payments Developer Guide August 7 2012 109 js PaymentDetails API Operation PaymentDetailsResponse Message Field Description transactionId xs string Opti
247. tPerPayment request fields 167 maxAmountPerPayment response field 182 maxNumberOfPayments request fields 167 maxNumberOfPayments response field 182 maxNumberOfPaymentsPerPeriod request fields 167 maxNumberOfPaymentsPerPeriod response field 182 maxTotalAmountOfAllPayments request fields 167 maxTotalAmountOfAllPayments response field 182 memo IPN variable 259 memo request field 81 memo request fields 167 memo response field 115 182 message field 94 98 122 131 134 148 159 173 186 195 208 224 227 241 250 August 7 2012 295 296 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 PaymentDetailsRequest message 109 PaymentDetailsResponse fields 110 113 paymentExecStatus response field 90 130 paymentInfo response field 117 PaymentInfo response fields 117 paymentInfoList response field 115 PaymentInfoList response fields 117 paymentPeriod request fields 168 paymentPeriod response field 182 PAYPAL apps DGFlow JavaScript function 255 264 266 PayRequest field
248. tain 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 E PreapprovalDetailsRequest RequestEnvelope Gi requestEnvelope 1 1 RequestEnvelope e detailLewel 0 1 DetaillevelCode Ef preapprovalKey 1 1 string ses e errorLanguage 1 1 string e getBiling amp ddress 0 1 boolean FE any 0 Ej any 0 PreapprovalDetailsRequest Fields Field Description getBillingAddress xs boolean Optional An option that lets you retrieve a list of billing addresses for the sender e true Includes the billing address in the response e 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 Permission Levels preapprovalKey xs string Required A preapproval key that identifies the preapproval for which you want to retrieve details The preapproval key is returned in the PreapprovalResponse message requestEnvelope common requestEnvelope Required Information common to each API operation such as the language in which an error message is returned Adaptive Payments Developer Guide August 7 2012 177 sss PreapprovalDetails API Operation PreapprovalDetail
249. te the payment to a particular receiver in chained and parallel payments Possible values are e Completed e Pending e Refunded The transaction ID for the sender where n is a number from 0 to 5 For simple single receiver payments this number will be 0 Numbers larger than 0 indicate the payment to a particular receiver in chained and parallel payments 258 August 7 2012 Adaptive Payments Developer Guide Instant Payment Notifications Pay Message Variables Variable Description transaction n status_fo r sender txn transaction n transaction n ount transaction n count charged transaction n transaction n transaction n transaction n y receiver return url cancel url refund id refund am refund ac receiver invoiceId amount is primar ipn notification url pay key memo The transaction status where n is a number from 0 to 5 For simple single receiver payments this number will be 0 Numbers larger than 0 indicate the payment to a particular receiver in chained and parallel payments Possible values are e COMPLETED The sender s transaction has completed e PENDING The transaction is awaiting further processing e CREATED The payment request was received funds will be transferred once approval is received PARTIALLY REFUNDED Transaction was partially refunded DENIED The transaction was rejected by the receiver PROCESSING The transact
250. that is initiating the payment Financial partners must first be set up in the Admin tool before they can use the PayPal APIs xs string Optional Sender s shipping address ID ap SenderOptions Optional Specifies information to be provided by the sender August 7 2012 Adaptive Payments Developer Guide SetPaymentOptions API Operation NER 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 The URL cannot exceed 1 024 characters The image dimensions are 43 pixels high x 240 pixels wide emailMarketingImageUrl xs string Optional The URL of the image that displays in the in customer emails The URL cannot exceed 1 024 characters The image dimensions are 80 pixels high x 530 pixels wide headerImageUrl xs string Optional The URL of an 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 URL cannot exceed 1 024 characters The image dimensions are 90 pixels high x 750 pixels wide businessName xs string Optional Th
251. time e REFUND ERROR Request rejected because of an internal error e PREVIOUS REFUND ERROR Request rejected because another part of this refund caused an internal error refundTransactionStatus xs string The status of the refund transaction Possible values are e UNKNOWN The status of the refund process is unknown e COMPLETED The refund process has been completed totalOfAllRefunds xs decimal The total of all refunds actually paid does not include pending amounts NOTE This field is only available when a partial refund has been requested Adaptive Payments Developer Guide August 7 2012 223 224 Refund API Operation Refund Response Message ErrorData Fields Field Description category domain errorId exceptionID message parameter severity subdomain common ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect xs string The domain to which this service belongs xs long A 6 digit number that uniquely identifies a particular error This field is not used xs string A description of the error common ErrorParameter Represents contextual information about the error common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request w
252. tion correlationId xs string Correlation identifier It is a 13 character alphanumeric string for example db87c705a910e that is used only by PayPal Merchant Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues SetPaymentOptions 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 Specifying Invoice data example In this example the details about the items or service being purchased in a given payment transaction are set up to be displayed in the payment review page before the user authorizes the payment The item details include the item description item count item price total shipping and total tax NOTE The sample code below uses the insecure setting to work around the certificate for testing in a sandbox environment For actual implementations you must specify the location of the certificate R
253. tion Description Refund ConvertCurrency GetFundingPlans GetAllowedFundingSources GetShippingAddresses GetAvailableShippingAddresses Refunds all or part of a payment Obtains the current foreign exchange FX rate for a specific amount and currency Determines the funding sources that are available for a specified payment Obtains the funding sources associated with a preapproval Obtains the selected shipping address Obtains available shipping addresses Adaptive Payments Endpoints The endpoint is determined by the API operation and the environment in which you want to execute the API operation For example if you want to send a Pay request to the sandbox endpoint specify the following URL https svcs sandbox paypal com AdaptivePayments Pay You can specify the following endpoints Environment Endpoint Production https svcs paypal com AdaptivePayments API_operation Sandbox https svcs sandbox paypal com AdaptivePayments API_operation Beta sandbox https svcs beta sandbox paypal com AdaptivePayments API_ operation HTTP Headers Each request message includes HTTP headers specifying authentication the application ID the device ID or IP address and the payload format or protocol SOAP Adaptive Payments supports request bodies with JSON NVP and XML data formats for REST implementations You can specify different formats for the request and response such as se
254. to the JavaScript that initiates the flow If 1t is the first payment or if PayPal determines that the payment requires the sender to log in PayPal displays a Log In button in the IFRAME created by the JavaScript Adaptive Payments Developer Guide August 7 2012 31 Introducing Adaptive Payments Embedded Payments PayPal Log in to your PayPal account to complete this purchase New to PayPal Sian up for a PayPal account and complete this purchase now Or check out with a debit or credit card no PayPal account required vse zz E The IFRAME also allows the sender to sign up for a PayPal account or pay as a guest without logging in NOTE 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 The sender enters an email address and password and can also check a box which allows the sender to skip this step for subsequent purchases 32 August 7 2012 Adaptive Payments Developer Guide Introducing Adaptive Payments Embedded Payments a Log in to your PayPal account Windows Internet E x GO ERE e ese i English Email address PayPal password Have a security key Forgot your email address or password For faster checkout skip login for future purchases using this computer How it works xoa cance PayPal protec
255. to the sender whether or not the funds were transferred to a receiver NOTE The sample code below uses the insecure setting to work around the certificate for testing in a sandbox environment For actual implementations you must specify the location of the certificate 100 August 7 2012 Adaptive Payments Developer Guide Pay API Operation a 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 com AdaptivePayments Pay d actionType PAY amp cancelUrl http your cancel url amp currencyCode USD amp feesPayer EACHRECEIVER amp memo Parallel payment example amp receiverList receiver 0 amount 100 00 amp receiverList receiver 0 email receiver Qdomain amp receiverList receiver 0 primary false amp receiverList receiver 1 amount 50 00 amp receiverList receiver 1 email receiver2 domain amp receiverList receiver 1 primary false amp requestEnvelope errorLanguage en_US amp returnUrl http your return url amp reverseAllParallelPaymentsOnError true amp senderEmail sender f domain Response responseEnvelope timestamp 2009 07 13T12 3A34 3A29 316 07 3A00 amp responseEnvelope ack Success amp responseEnvelope correlationI
256. transaction identification number of the sender of the payment xs string The transaction status of the payment Possible values are e COMPLETED The sender s transaction has completed e PENDING The transaction is awaiting further processing e CREATED The payment request was received funds will be transferred once approval is received PARTIALLY REFUNDED Transaction was partially refunded DENIED The transaction was rejected by the receiver PROCESSING The transaction is in progress REVERSED The payment was returned to the sender REFUNDED The payment was refunded FAILED The payment failed xs string PayPal transaction ID for this payment to the specified receiver xs string PayPal transaction status Possible values are e COMPLETED The sender s transaction has completed e PENDING The transaction is awaiting further processing e CREATED The payment request was received funds will be transferred once approval is received PARTIALLY REFUNDED Transaction was partially refunded DENIED The transaction was rejected by the receiver PROCESSING The transaction is in progress REVERSED The payment was returned to the sender REFUNDED The payment was refunded FAILED The payment failed Receiver Fields Field Description amount xs decimal Amount to be paid to the receiver 118 August 7 2012 Adaptive Payments Developer Guide PaymentDetails API Operation NER Paym
257. tring Type of funding source which is one of the following values e UNDEFINED BALANCE BANK INSTANT BANK DELAYED CREDITCARD DEBITCARD ACCOUNTS RECEIVABLE displayName xs string Display name of funding source fundingSourceld xs string Funding source ID allowed xs boolean Whether the funding source is allowed for this payment e true You can use this funding source for the payment e false You cannot use this funding source default CurrencyConversion Fields Field Description from ap CurrencyType The currency to be converted to ap CurrencyType The currency resulting from the conversion exchangeRate xs decimal The exchange rate for the from currency to the to currency ResponseEnvelope Fields Field Description ack common AckCode Acknowledgement code It is one of the following values e Success The operation completed successfully e Failure The operation failed e SuccessWithWarning The operation completed successfully however there is a warning message e FailureWithWarning The operation failed with a warning message Adaptive Payments Developer Guide August 7 2012 239 al GetFundingPlans API Operation PPFault Message Field Description build correlationId timestamp xs string Build number It is used only by PayPal Merchant Technical Support xs string Correlation identifier It is a 13 character alphanumeric string for example db87c705
258. ts your privacy and security J ee Ta pu SS ae 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 IMPORTANT Opting in to the remember me behavior does not guarantee that the sender will not be asked to provide log in credentials After logging in PayPal displays the You are about to pay page sometimes called the review your payment page in the minibrowser Adaptive Payments Developer Guide August 7 2012 33 j Introducing Adaptive Payments Embedded Payments Jos R mirez f T qui PayPal You are about to pay Receiver Amount Rapid Action Towing 5 00 Total 5 00 USD My PayPal Balance View PayPal policies 5 00 USD My PayPal Balance b Memo of standard transaction Digital Goods BE cance PayPal protects your privacy and security Site Feedback If the sender chooses Cancel PayPal redirects the sender s browser to the cancel URL specified in the Pay API operation s request message If the sender chooses Pay the Thank you for using PayPal page appears in the minibrowser 34 August 7 2012 Adaptive Payments Developer Guide Introducing Adaptive Payments E Embedded Payments Jos Ramirez cid PayPal j Thank you for using PayPal Receiver Amount Rapid Action Towing 5 00 Total 5 00 USD PayPal protects your privacy and security Site Feedba
259. tus are strings and you must manipulate them as strings Some languages such as PHP and others may attempt to interpret the non alphanumeric characters found in the variable name To avoid misinterpretation of these strings you should always to use the raw HTTP request string and process it yourself rather than rely on the support provided by the language to obtain request parameters Pay Message Variables PayPal generates an IPN message that contains information about the pay request or payment in response to the Adaptive Payments Pay and ExecutePayment API operations Variable Description transaction type The type of transaction Possible values are e Adaptive Payment PAY This notification occurs when is a payment is made due to a PayRequest The variables for the Adaptive Payment Pay notification are similar to the PaymentDetailsResponse fields e Adjustment This can be for a chargeback reversal or refund check the reason_code to see which it is Adaptive Payments Developer Guide August 7 2012 257 a Instant Payment Notifications Pay Message Variables Variable Description status sender email action type payment request date reverse all parallel pay ments on error transaction n id transaction n status transaction n id for se nder The status of the payment Possible values are e CREATED The payment request was received funds will be transferred once the payment is approved
260. um length 64 characters SenderOptions Fields Field Description requireShippingAddressSe lection referrerCode xs boolean Optional If true require the sender to select a shipping address during the embedded payment flow default is false xs string Optional A code that identifies the partner associated with this transaction Maximum length 32 characters August 7 2012 Adaptive Payments Developer Guide SetPaymentOptions API Operation NER SetPaymentsOptionsRequest Message ReceiverOptions Fields Field Description description customId invoiceData receiver 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 xs string Optional An external reference or identifier you want to associate with the payment Maximum length 1000 characters ap InvoiceData Optional Item information for the payment which could appear on an invoice ap ReceiverIdentifier Optional Receiver ID associated with these options InvoiceData Fields 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 paymen
261. unding source being charged Adaptive Payments Developer Guide August 7 2012 93 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 Field Description category common ErrorCategory The location where the error occurred Possible values are e System The system encountered errors try again e Application The application encountered errors try again e Request The request was incorrect domain xs string The domain to which this service belongs errorld xs long A 6 digit number that uniquely identifies a particular error exceptionID This field is not used message xs string A description of the error parameter common ErrorParameter Represents contextual information about the error severlty common ErrorSeverity The severity of the error encountered Possible values are e Error Processing of the request was interrupted e Warning Processing of the request was completed subdomain This field is not used August 7 2012 Adaptive Payments Developer Guide Pay API Operation m PayResponse Message Receiver Fields Field Description amount xs decimal Amo
262. unt to be paid to the receiver email xs string Receiver s email address Maximum length 127 characters invoiceld 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 Possible values are e GOODS This is a payment for non digital goods SERVICE This is a payment for services default PERSONAL This is a person to person payment CASHADVANCE This is a person to person payment for a cash advance DIGITALGOODS This is a payment for digital goods BANK MANAGED WITHDRAWAL This is a person to person payment for bank withdrawals available only with special permission paymentSubType xs string The transaction subtype for the payment phone common PhoneNumberType The receiver s phone number primary xs boolean Whether this receiver is the primary receiver If this field is set to true this is a chained payment If this field shows false this is a simple or parallel payment Possible values are e true Primary receiver chained payment e false Secondary receiver simple parallel payment PhoneNumberType Response Fields Field Description countryCode xs string Telephone country code Adaptive Payments Developer Guide August 7 2012 95 a Pay API Operation PPFault Message Field Description phoneNumber xs string Telephone numbe
263. up in the Admin tool before they can use the PayPal APIs shippingAddressId xs string Sender s shipping address ID senderOptions ap SenderOptions Specifies information to be provided by the sender receiverOptions ap ReceiverOptions Specifies information about each receiver requestEnvelope common requestEnvelope Information common to each API operation such as the language in which an error message is returned DisplayOptions Fields DisplayOptions fields allow the API caller to provide PayPal with a link to an image Field Description emailHeaderImageUrl emailMarketingImageUrl headerImageUrl businessName xs string The URL of the image that displays in the in the header of customer emails The image dimensions are 43 pixels high x 240 pixels wide xs string The URL of the image that displays in the in customer emails The image dimensions are 80 pixels high x 530 pixels wide xs string The URL of the image that displays in the header of a payment page Use this to configure payment flows by passing a different image URL for different scenarios If set it overrides the header image URL specified in your account s Profile The image dimensions are 90 pixels high x 750 pixels wide NOTE The headerImageUrl and businessName parameters are mutually exclusive only one of these fields can be used If you specify both the image will take precedence over the business name xs string The business name to
264. upport correlationId xs string Correlation identifier It is a 13 character alphanumeric string for example db87c705a910e that is used only by PayPal Merchant Technical Support NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues timestamp xs datetime Date on which the response was sent for example 2012 04 02T22 33 35 774 07 00 NOTE You must log and store this data for every response you receive PayPal Technical Support uses the information to assist with reported issues PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs 206 August 7 2012 Adaptive Payments Developer Guide E FaultMessage e responseEnvelope 1 1 ResponseEnvelope e error 0 ErrorData ErrorData e errorId long domain string e subdomain 0 1 string ErrorSeverity e severity e category e message string e exceptionId 0 1 token e parameter ErrorCategory 0 ErrorParameter FaultMessage Fields ConvertCurrency API Operation PPFault Message ResponseEnvelope e timestamp 1 1 dateTime ack 1 1 AckCode e correlationId 1 1 string build 1 1 string T any 0 E ErrorData errorId long domain string e subdomain 0 1 string severity ErrorSev
265. urrency and currency balance only for Brazilian PayPal accounts Canadian Dollar CAD Czech Koruna CZK Danish Krone DKK Euro EUR Hong Kong Dollar HKD Hungarian Forint HUF Israeli New Sheqel ILS Japanese Yen JPY Malaysian Ringgit MYR NOTE The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts Mexican Peso MXN Norwegian Krone NOK New Zealand Dollar NZD Philippine Peso PHP Polish Zloty PLN Pound Sterling GBP Singapore Dollar SGD Swedish Krona SEK Swiss Franc CHF Taiwan New Dollar TWD Thai Baht THB Turkish Lira TRY NOTE The Turkish Lira is supported as a payment currency and currency balance only for Turkish PayPal accounts e U S Dollar USD xs string Optional The key used to create the payment that you want to refund 216 August 7 2012 Adaptive Payments Developer Guide 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 If you do not specify any receivers all receivers will be fully refunded if you specify the payment key or tracking ID otherwise only the affected re
266. ust use the embedded payment flow You cannot associate a preapproval for future payments or enable shipping addresses in a payment for digital goods Embedded Payments Implementation Basics To implement the embedded payment flow you must e include JavaScript code from PayPal on your checkout or payment web pages e use the functions provided in the JavaScript to coordinate the PayPal flow with the appearance of your web pages e launch your preferred embedded payment flow which is either the lightbox or minibrowser and redirect the sender s browser to the PayPal URL that supports embedded payments which is https www paypal com webapps adaptivepayment flow pay paykey You must call the Pay API operation to obtain a payment key before launching the embedded payment flow If the payment is specifically for digital goods modify your Pay API operation to specify that each receiver is receiving payment for digital goods Embedded Payment Experience To the sender of a payment the embedded payment experience appears to be built into your website The PayPal supplied JavaScript provides all the code needed to set up the flow as an 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 Read the complete story instantly Story 200 000 Android devices sold each day 1 00 PAY win PayPal PayPal responds
267. ute 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 e You are not allowed to confirm the preapproval for this key e User is not allowed to perform this action 550001 You do not have permission to execute this payment implicitly 550001 e User is not allowed to perform this action e You are not allowed to get the funding plans for this key e You do not have permission to get these funding plan details 550001 e 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 58000
268. valid request parameter lt value gt lt value gt is duplicated Invalid request parameter lt value gt lt value gt cannot be negative or zero 580022 e Invalid request parameter lt value gt Invalid request parameter payKey with value lt value gt 580022 e Invalid request parameter lt value gt e Invalid request parameter payKey with value lt value gt e No sender is associated with this key 580022 The funding plan data is not present 272 August 7 2012 Adaptive Payments Developer Guide 1 5 0 Features Em Code Message 580023 e The fee payer value cannot be used if a primary receiver is specified e The fee payer value can only be used if a primary receiver is specified e The fee payer value must have exactly 2 receivers e 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 chain
269. value value Adaptive Payments Developer Guide August 7 2012 149 a GetPaymentOptions API Operation GetPaymentOptions Errors 150 August 7 2012 Adaptive Payments Developer Guide SetPaymentOptions API Operation You use the Set PaymentOptions API operation to specify settings for a payment of the actionType CREATE This actionType is specified in the PayRequest message SetPaymentsOptionsRequest Message E SeboymentOptoeques E requestEnvelope 1 1 RequestEnvelope E detaillevel 0 1 DetaillevelCode e payKey 1 1 string seo e errorLanguage 1 1 string e initiatingEntity 0 1 InitiatingEntity FE any 0 e displayOptions 0 1 DisplayOptions e shippingAddressId 0 1 string e senderOptions 0 1 SenderOptions receiverOptions 0 FE any 0 E InitiatingEntity institutionCustomer 0 1 InstitutionCustomer ReceiverOptions FE any 0 DisplayOptions e emailHeaderlmageUrl 0 1 string e emailMarketinglmageUrl 0 1 string Adaptive Payments Developer Guide August 7 2012 e headerlmageUrl e businessName F any 0 1 string 0 1 string 0 E SenderOptions e referrerCode l any e requireShippingAddressSelection 0 1 boolean 0 1 string 0 ReceiverOptions p description 0 1 0 1 0 1 1 1 referrerCode 0 1 H j any 0 customld invoiceData
270. variable returns Adaptive Payment Preapproval NOTE If this variable is set to Adaptive Payment Pay or Adjustment refer to the Pay Message Variable section The preapproval key returned after a PreapprovalRequest Whether the preapproval request was approved Possible values are e true The preapproval was approved e false The preapproval was denied The URL to which the sender s browser is redirected if the sender decides to cancel the preapproval as requested Use the preapproval key to identify the payment as follows preapprovalKey preapprovalKey The current number of payments made for this preapproval 260 August 7 2012 Adaptive Payments Developer Guide Instant Payment Notifications Preapproval Message Variables Variable Description current total amount of all payments current period attempts currencyCode date of month The current total of payments made for this preapproval The current number of attempts this period for this preapproval The currency code Possible values are e Australian Dollar AUD e Brazilian Real BRL NOTE The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts Canadian Dollar CAD Czech Koruna CZK Danish Krone DKK Euro EUR Hong Kong Dollar HKD Hungarian Forint HUF Israeli New Sheqel ILS Japanese Yen JPY Malaysian Ringgit MYR NOTE The Ringgit is supported as a pay
271. verted amount Adaptive Payments Developer Guide August 7 2012 237 isa GetFundingPlans API Operation GetFundingPlansResponse Message Field Description code xs string The currency code for the converted amount Possible values are e Australian Dollar AUD e Brazilian Real BRL NOTE The Real is supported as a payment currency and currency balance only for Brazilian PayPal accounts Canadian Dollar CAD Czech Koruna CZK Danish Krone DKK Euro EUR Hong Kong Dollar HKD Hungarian Forint HUF Israeli New Sheqel ILS Japanese Yen JPY Malaysian Ringgit MYR NOTE The Ringgit is supported as a payment currency and currency balance only for Malaysian PayPal accounts Mexican Peso MXN Norwegian Krone NOK New Zealand Dollar NZD Philippine Peso PHP Polish Zloty PLN Pound Sterling GBP Singapore Dollar SGD Swedish Krona SEK Swiss Franc CHF Taiwan New Dollar TWD Thai Baht THB Turkish Lira TRY NOTE The Turkish Lira is supported as a payment currency and currency balance only for Turkish PayPal accounts e U S Dollar USD FundingSource Fields Field Description lastFourOfAccountNumber xs string Last 4 digits or characters in account number 238 August 7 2012 Adaptive Payments Developer Guide GetFundingPlans API Operation ET GetFundingPlansResponse Message Field Description type xs s
272. y and currency balance only for Turkish PayPal accounts e U S Dollar USD dateOfMonth The day of the month on which a monthly payment is to be made A number between 1 and 31 indicates the day of the month 0 indicates that the payment can be made on any day Adaptive Payments Developer Guide August 7 2012 181 PreapprovalDetails API Operation PreapprovalDetailsResponse Message Field Description dayOfWeek endingDate ipnNotificationUrl maxAmountPerPayment maxNumberOfPayments maxNumberOfPaymentsPerPe riod maxTotalAmountOfAllPayme nts memo paymentPeriod pinType responseEnvelope returnUrl 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 Last date for which the preapproval is valid Time is currently not supported NOTE You must specify a value unless you have specific permission from PayPal to omit this value The URL to which all IPN messages for this preapproval are sent The preapproved maximum amount per payment The preapproved maximum number of payments This field is only returned if provided The preapproved maximum number of payments per period The preapproved maximum total amount of all payments NOTE You must specify a value unless you have specific permission from PayPal to omit this value A note about the preapproval The payment peri
273. y enable the primary receiver Field Description receiverList receiver n email receiverList receiver n amount receiverList receiver n primary The receivers email addresses where n is between 0 and 5 for a total of one primary receiver and between one and 5 secondary receivers Amount to send to each corresponding receiver Set to true to indicate a chained payment only one receiver can be a primary receiver Omit this field or set it to false for simple and parallel payments By default a payment requires explicit approval in which the sender must log in to PayPal In that case you are not required to specify the sender s email address To initiate the approval process you must redirect the sender to PayPal as follows https www paypal com webscr cmd ap payment amp paykey value NOTE Thecommandis ap payment You obtain the value of the paykey parameter from the payKey field in the Pay API operation s response message 74 August 7 2012 Adaptive Payments Developer Guide Pay API Operation m 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 specif
274. y steps Consumer advisory PayPal Pte Ltd the holder of PayPal s stored value facility does not require the approval of the Monetary Authority of Singapore Users are advised to read the terms and conditions carefully 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 al Introducing Adaptive Payments Embedded Payments Jos Ramirez PayPal a Log out Sign up for future payments With Pretty Flower Florist Start July 7 2012 End December 7 2012 Memo Preapproval from test application PayPal will use Default payment method By clicking the button below authorize Pretty Flower Florist to automatically charge my PayPal account for my future payments If your payment fails PayPal will use the other payment methods linked to your account We will use your available PayPal balance first View PayPal policies To stop payments under this agreement go to My preapproved payments in your PayPal Profile To cancel this agreement contact Pretty Flower Florist PayPal protects your privacy and security 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 E Embedded Payments Jos R mirez PayPal e Log out
275. y values for the fields below Field Description preapprovalKey Preapproval key for the approval set up between you and the sender pin Sender s personal identification number if one was specified when the sender agreed to the approval Payments for Digital Goods You handle payments for digital goods in the same way you handle payments for other goods and services with the following exceptions e To specify a payment for digital goods you must specify DIGITALGOODS for each receiver in your receiver list specify receiverList receiver n payment Type DIGITALGOODS for each receiver where n identifies the receiver starting with 0 e If you specify a payment for digital goods you cannot specify a senderEmail address or include a funding constraint e You must redirect the sender to the following PayPal URL to complete the payment for digital goods https www paypal com webapps adaptivepayment flow pay paykey Payment Notifications Notifications are sent after payment is executed which follows approval of the payment by the sender if required e PayPal sends an email to the sender and all receivers associated with a payment when the transfer is complete you receive an email only if you are also the payment sender or receiver Adaptive Payments Developer Guide August 7 2012 75 76 Pay API Operation Pay Summary Additional 1 When the payment is complete PayPal sends an IPN message to the URL s
276. ymentOptionsResponse i ResponseEnvelope EHE AAA NARA xAAA lt m A A ej responseEnvelope 1 1 ResponseEnvelope e timestamp 1 1 dateTime amp initiatingEntity 0 1 InitiatingEntity e ack 1 1 AckCode E displayOptions 0 1 DisplayOptions e correlationId 1 1 string se f shippingAddressId 0 1 string build 1 1 string Ef senderOptions 0 1 SenderOptions FE any 0 Ef receiverOptions D ReceiverOptions FE any 0 E InitiatingEntity MU AAA AAA Gi institutionCustomer 0 1 InstitutionCustomer FE any 0 E DisplayOptions E emailHeaderImageUr 0 1 string Ef emailMarketinglmageUrl 0 1 string Ef headerImageUrl 0 1 string Ef businessName 0 1 string 7 any 0 E SenderOptions e requireShippingAddressSelection 0 1 boolean F any 0 E ReceiverOptions Ef description 0 1 string Ef customId 0 1 string l invoiceData 0 1 InvoiceData Ef receiver 1 1 ReceiverIdentifier F any 0 140 August 7 2012 Adaptive Payments Developer Guide ES InitiatingEntity fe institutionCustomer 0 1 InstitutionCustomer Ej any 0 E ReceiverOptions e description 0 1 string e customId 0 1 string Ef invoiceData 0 InvoiceData fe receiver 1 1 ReceiverIdentifier 7 any 0 E InvoiceData fe item 0 InvoiceItem Ef totalTax 0 1 decimal Ef totalshipping 0 1 decimal 6 any

PayPal Adaptive Payments - 2012 Developer's Guide

Contents

Download Pdf Manuals

Related Search

Related Contents