PayPal Adaptive Payments - 2012 Developer's Guide
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, L2449, 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 i n this document t o you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information co ntained 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 f rom the application or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.
Contents
What’s New?. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
1.8.1 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
SenderIdentifier Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
TaxIdDetails Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Chapter 1 Introducing Adaptive Payments . . . . . . . . . . . . . . . 17
Adaptive Payments Actors and Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Simple, Parallel, and Chained Payments . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Simple Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Parallel Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Chained Payments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Payment Approval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Adaptive Payments Service Permissions . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Explicit Approval Payment Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Preapproved Payments Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Implicit Approval Payments Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Embedded Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
Embedded Payment Flow Presentations . . . . . . . . . . . . . . . . . . . . . . . . 28
Kinds of Embedded Payments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Embedded Payments Implementation Basics . . . . . . . . . . . . . . . . . . . . . . 31
Embedded Payment Experience . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Preapprove Future Payments Checkbox . . . . . . . . . . . . . . . . . . . . . . . . 37
Shipping Address Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Embedded Payment Experience . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 Collecting Shipping Addresses . . . . . . . . . . . . . . . . . . . . . 58
Guest Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59
Fee Payment Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
Sender Pays the Fee . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
Receiver Pays the Fee in a Parallel Payment . . . . . . . . . . . . . . . . . . . . . . 62
Each Receiver Pays the Fee in a Chained Payment . . . . . . . . . . . . . . . . . . 62
Primary Receiver Pays the Fee in a Chained Payment . . . . . . . . . . . . . . . . . 63
Adaptive Payments Developer Guide August 7, 2012 3
Contents
Chapter 2 Getting Started . . . . . . . . . . . . . . . . . . . . . . .65
Adaptive Payments API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
API Operations Related to Payments . . . . . . . . . . . . . . . . . . . . . . . . . . 65
API Operations Related to Preapprovals . . . . . . . . . . . . . . . . . . . . . . . . 65
Other API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Adaptive Payments Endpoints . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
HTTP Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
Specifying JSON, NVP, or XML Data Formats. . . . . . . . . . . . . . . . . . . . . . 67
SOAP Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Specifying Application and Device Information . . . . . . . . . . . . . . . . . . . . . 68
Making a Simple Payment (JSON). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Pay Request for Simple Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Pay Response for Simple Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
Making a Parallel Payment (NVP) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Pay Request for Parallel Payment. . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Pay Response for Parallel Payment. . . . . . . . . . . . . . . . . . . . . . . . . . . 70
Making a Chained Payment (XML) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Pay Request for Chained Payment . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Pay Response for Chained Payment . . . . . . . . . . . . . . . . . . . . . . . . . . 72
Chapter 3 Pay API Operation . . . . . . . . . . . . . . . . . . . . . .73
Pay Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Common Fields for All Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Parallel Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Chained Payments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Implicit Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Preapproved Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Payments for Digital Goods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Payment Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Additional Notes About the Pay API Operation . . . . . . . . . . . . . . . . . . . . . 76
PayRequest Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
PayRequest Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
ClientDetails Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
FundingConstraint Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
FundingTypeList Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
FundingTypeInfo Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
ReceiverList Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Receiver Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
4 August 7, 2012 Adaptive Payments Developer Guide
Contents
PhoneNumberType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
SenderIdentifier Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
AccountIdentifier Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
PayResponse Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
PayResponse Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
PayErrorList Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
FundingPlan Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
CurrencyType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
FundingSource Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
CurrencyConversion Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
FundingPlanCharge Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
PayError Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Receiver Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
PhoneNumberType Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . . 95
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
Pay Examples Using NVP and CURL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Pay Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .104
Chapter 4 PaymentDetails API Operation . . . . . . . . . . . . . . 109
PaymentDetailsRequest Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
PaymentDetailsRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110
PaymentDetailsResponse Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110
PaymentDetailsResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
FundingTypeList Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
FundingTypeInfo Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
PaymentInfoList Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
PaymentInfo Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .117
Receiver Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .118
SenderIdentifier Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .119
AccountIdentifier Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
PhoneNumberType Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . .120
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .120
Adaptive Payments Developer Guide August 7, 2012 5
Contents
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .121
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .123
PaymentDetails Examples Using NVP and CURL. . . . . . . . . . . . . . . . . . . . . .123
Payment Details Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .125
Chapter 5 ExecutePayment API Operation . . . . . . . . . . . . . . 127
ExecutePaymentRequest Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
ExecutePaymentRequest Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . .127
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .128
ExecutePaymentResponse Message . . . . . . . . . . . . . . . . . . . . . . . . . . . .128
ExecutePaymentResponse Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . .130
PayErrorList Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130
PayError Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .130
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
Receiver Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .133
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
ExecutePayment Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .135
Chapter 6 GetPaymentOptions API Operation . . . . . . . . . . . . 139
GetPaymentOptionsRequest Message . . . . . . . . . . . . . . . . . . . . . . . . . . .139
GetPaymentOptionsRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . .139
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .139
GetPaymentOptionsResponse Message . . . . . . . . . . . . . . . . . . . . . . . . . .140
GetPaymentOptionsResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . . .141
DisplayOptions Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .142
InitiatingEntity Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
Institution Customer Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143
SenderOptions Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144
ReceiverOptions Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144
InvoiceData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .144
InvoiceItem Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
ReceiverIdentifier Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .145
6 August 7, 2012 Adaptive Payments Developer Guide
Contents
PhoneNumberType Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . .145
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .146
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .147
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .148
GetPaymentOptions Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .149
Chapter 7 SetPaymentOptions API Operation . . . . . . . . . . . . 151
SetPaymentsOptionsRequest Message . . . . . . . . . . . . . . . . . . . . . . . . . . .151
SetPaymentOptionsRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . .152
DisplayOptions Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
InitiatingEntity Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
Institution Customer Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
SenderOptions Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
ReceiverOptions Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
InvoiceData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
InvoiceItem Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .155
ReceiverIdentifier Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
PhoneNumberType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .156
SetPaymentOptionsResponse Message. . . . . . . . . . . . . . . . . . . . . . . . . . .157
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .159
SetPaymentOptions Examples Using NVP and CURL . . . . . . . . . . . . . . . . . . .160
SetPaymentOptions Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .161
Chapter 8 Preapproval API Operation . . . . . . . . . . . . . . . . 163
Preapproval Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163
Preapproval Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .163
Additional Notes About the PreApproval API Operation. . . . . . . . . . . . . . . . .164
PreapprovalRequest Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164
PreapprovalRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165
ClientDetails Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .169
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170
Adaptive Payments Developer Guide August 7, 2012 7
Contents
PreapprovalResponse Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170
PreapprovalResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .170
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .171
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .172
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .173
Preapproval Examples Using NVP and CURL. . . . . . . . . . . . . . . . . . . . . . . .174
Preapproval Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .175
Chapter 9 PreapprovalDetails API Operation . . . . . . . . . . . . . 177
PreapprovalDetailsRequest Message . . . . . . . . . . . . . . . . . . . . . . . . . . . .177
PreapprovalDetailsRequest Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . .177
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .178
PreapprovalDetailsResponse Message . . . . . . . . . . . . . . . . . . . . . . . . . . .178
PreapprovalDetailsResponse Fields. . . . . . . . . . . . . . . . . . . . . . . . . . .180
AddressList Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
Address Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
BaseAddress Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .185
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187
PreapprovalDetails Examples Using NVP and CURL . . . . . . . . . . . . . . . . . . . .187
Preapproval Details Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .189
Chapter 10 CancelPreapproval API Operation. . . . . . . . . . . . . 191
CancelPreapprovalRequest Message . . . . . . . . . . . . . . . . . . . . . . . . . . . .191
CancelPreapprovalRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . .191
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .192
CancelPreapprovalResponse Message . . . . . . . . . . . . . . . . . . . . . . . . . . .192
CancelPreapprovalResponse Fields. . . . . . . . . . . . . . . . . . . . . . . . . . .192
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .195
8 August 7, 2012 Adaptive Payments Developer Guide
Contents
CancelPreapproval Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .196
Chapter 11 ConvertCurrency API Operation. . . . . . . . . . . . . . 197
ConvertCurrencyRequest Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197
ConvertCurrencyRequest Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . .197
CurrencyType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .198
CurrencyList Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200
CurrencyCodeList Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .202
ConversionType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .202
ConvertCurrencyResponse Message . . . . . . . . . . . . . . . . . . . . . . . . . . . .202
ConversionCurrencyResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . . .203
CurrencyConversionTable Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . .203
CurrencyConversionList Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204
CurrencyType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .204
CurrencyList Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .205
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .206
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .208
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .208
ConvertCurrency Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209
Chapter 12 Refund API Operation . . . . . . . . . . . . . . . . . . . 211
Refund API Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211
Refund Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .213
Additional Notes About the Refund API Operation . . . . . . . . . . . . . . . . . . .213
RefundRequest Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .214
RefundRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .215
ReceiverList Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217
Receiver Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .217
PhoneNumberType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .218
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .218
Refund Response Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .219
RefundResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .221
RefundInfoList Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222
RefundInfo Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .222
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224
Receiver Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224
Adaptive Payments Developer Guide August 7, 2012 9
Contents
PhoneNumberType Response Fields . . . . . . . . . . . . . . . . . . . . . . . . . .225
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .226
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .227
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228
Refund Examples Using NVP and CURL . . . . . . . . . . . . . . . . . . . . . . . . . .228
Refund Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
Chapter 13 GetFundingPlans API Operation . . . . . . . . . . . . . 233
GetFundingPlans Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233
Additional Notes About the Pay API Operation . . . . . . . . . . . . . . . . . . . . .233
GetFundingPlansRequest Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . .233
GetFundingPlansRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
GetFundingPlansResponse Message . . . . . . . . . . . . . . . . . . . . . . . . . . . .234
GetFundingPlansResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . . . .236
FundingPlan Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .236
CurrencyType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .237
FundingSource Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .238
CurrencyConversion Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .239
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .240
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .241
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242
GetFundingPlan Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .242
Chapter 14 GetShippingAddresses API Operation . . . . . . . . . . 245
GetShippingAddressesRequest Message . . . . . . . . . . . . . . . . . . . . . . . . . .245
GetShippingAddressesRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . .245
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .246
GetShippingAddressesResponse Message . . . . . . . . . . . . . . . . . . . . . . . . .246
GetShippingAddressesResponse Fields . . . . . . . . . . . . . . . . . . . . . . . .247
Address Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .247
BaseAddress Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .247
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .248
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .248
10 August 7, 2012 Adaptive Payments Developer Guide
Contents
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250
GetShippingAddresses Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .251
Chapter 15 Adaptive Payment Commands and Redirects . . . . . . . 253
Adaptive Payment Commands. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253
_ap-payment Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .253
_ap-preapproval Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254
Embedded Payment Flow Redirect . . . . . . . . . . . . . . . . . . . . . . . . . . . . .254
JavaScript Functions for Embedded Payments . . . . . . . . . . . . . . . . . . . . .255
Chapter 16 Instant Payment Notifications . . . . . . . . . . . . . . . 257
Pay Message Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .257
Preapproval Message Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .260
Older Versions of the Adaptive Payments API . . . . . . . . . . . . . 263
1.8.0 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .263
Changes to SenderOptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .265
New API Operations for Version 1.7.0. . . . . . . . . . . . . . . . . . . . . . . . . .266
Changes to ConfirmPreapprovalRequest Fields for Version 1.7.0 . . . . . . . . . . .266
Changes to JavaScript Functions for Embedded Payments. . . . . . . . . . . . . . .266
1.6.0 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .266
New API Operations for Version 1.6.0. . . . . . . . . . . . . . . . . . . . . . . . . .266
Changes to PayRequest Fields for Version 1.6.0 . . . . . . . . . . . . . . . . . . . .267
Changes to PayResponse Fields for Version 1.6.0 . . . . . . . . . . . . . . . . . . .267
Changes to ExecutePaymentRequest Fields for V ersion 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. . . . . . . . . . . . . . . . . . . . .268
Changes to DisplayOptions St ructure for Version 1.6.0 . . . . . . . . . . . . . . . . .268
New CurrencyConversion Structure for Version 1.6.0 . . . . . . . . . . . . . . . . .269
New InvoiceData Structure for Version 1.6.0 . . . . . . . . . . . . . . . . . . . . . .269
Adaptive Payments Developer Guide August 7, 2012 11
Contents
New InvoiceItem Structure for Version 1.6.0 . . . . . . . . . . . . . . . . . . . . . .269
New SenderOptions Structure for Version 1.6.0. . . . . . . . . . . . . . . . . . . . .269
New SenderIdentifier Structure for Version 1.6.0 . . . . . . . . . . . . . . . . . . . .270
New AccountIdentifier Structure for Version 1.6.0 . . . . . . . . . . . . . . . . . . . .270
New ReceiverOptions Structure for Version 1.6.0 . . . . . . . . . . . . . . . . . . . .270
New ReceiverIdentifier Structure for Version 1.6.0 . . . . . . . . . . . . . . . . . . .270
Additional Error Messages for Version 1.6.0. . . . . . . . . . . . . . . . . . . . . . .271
1.5.0 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .273
Ability to Delay a Chained Payment Feature in Version 1.5.0. . . . . . . . . . . . . .273
PaymentDetails Pending Reason Feature in Version 1.5.0 . . . . . . . . . . . . . . .274
1.4.0 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .274
New API Operations for Version 1.4.0. . . . . . . . . . . . . . . . . . . . . . . . . .274
Changes to the Pay API Operation . . . . . . . . . . . . . . . . . . . . . . . . . . .276
Changes to the PaymentDetails API Operation . . . . . . . . . . . . . . . . . . . . .276
Changes to the PreapprovalDetails API Operation . . . . . . . . . . . . . . . . . . .278
Changes to the PreapprovalDetails API Operation . . . . . . . . . . . . . . . . . . .278
Changes to the Refund API Operation . . . . . . . . . . . . . . . . . . . . . . . . .279
1.3.0 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .279
Overview of Changes for Version 1.3.0 . . . . . . . . . . . . . . . . . . . . . . . . .279
HTTP Header Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .280
Changes to the Pay API Operation for Version 1.3.0 . . . . . . . . . . . . . . . . . .281
Changes to the PaymentDetails API Operation for Version 1.3.0 . . . . . . . . . . . .283
1.2.0 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .284
Changes to the Pay API Operation for Version 1.2.0 . . . . . . . . . . . . . . . . . .285
Changes to the Payment Details API Operation for Version 1.2.0. . . . . . . . . . . .285
Changes 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 Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .286
Changes to the Pay API Operation for Version 1.1.0 . . . . . . . . . . . . . . . . . .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.0 . . . . . . . . . . . . . . . . . .289
Revision History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293
12 August 7, 2012 Adaptive Payments Developer Guide
Contents
Adaptive Payments Developer Guide August 7, 2012 13
Contents
14 August 7, 2012 Adaptive Payments Developer Guide
What’s New?
Adaptive Payments is intended for developers implementing payment solutions with PayPal’s
Adaptive Payments API. Check out what’s new in the current release.
1.8.1 Features
Version 1.8.1 of the Adaptive Payments API adds a new new fields related to tax ID details for
Brazil (shown below). Also a new BANK_MANAGED_WITHDRAWAL value has been
added to the paymentType field.
NOTE: Changes to API operations are backward-compatible.
SenderIdentifier Fields
Field Description
useCredentials xs:boolean
If true, credentials identify the sender; default is false.
taxIdDetails ap:TaxIdDetails
T ax 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
1.8.1 Features
16 August 7, 2012 Adaptive Payments Developer Guide
Introducing Adaptive Payments
1
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 applications, 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:
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:
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:
In a chained payment, the sender pays the primary 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:
18 August 7, 2012 Adaptive Payments Developer Guide
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
Introducing Adaptive Payments
Simple, Parallel, and Chained Payments
Adaptive Payments provides several kinds of payment: simple, parallel, and chained
payments. You create each kind of payment with the Pay API.
Simple payments enable a sender to send a single payment to a single receiver.
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.
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 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.
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
Introducing Adaptive Payments
Simple, Parallel, and Chained Payments
Simple Payments
Simple payments enable a sender to send a single payment to a single receiver. This is
sometimes considered a traditional payment, such as a payment from a buyer to a seller.
Scenarios involving simple payments might include the following scenarios:
Buyer makes a payment on a merchant’s website.
Buyer makes a single payment for a cart of items from the same merchant.
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:
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:
a single payment for multiple items from different merchants, such as a combination of
items in your inventory and items that partners drop ship for you.
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:
20 August 7, 2012 Adaptive Payments Developer Guide
Introducing Adaptive Payments
Simple, Parallel, and Chained Payments
NOTE: This scenario is an example only and does not take PayPal fees into account.
Chained Payments
A chained payment is a payment from a sender that is indirectly split among multiple
receivers. It is an extension of a typical payment from a sender to a receiver, in which a
receiver, known as the primary receiver, passes part of the payment to other receivers, who are
called secondary receivers.
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
Introducing Adaptive Payments
Payment Approval
In this example, the primary receiver receives $100 from the sender ’s perspective. The
primary receiver actually receives only $10 and passes a total of $90 to secondary receivers,
Receiver 2 and Receiver 3.
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 example, 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:
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.
22 August 7, 2012 Adaptive Payments Developer Guide
Adaptive Payments Service Permissions
Preapproved payments, in which a sender logs in to PayPal and sets up preapprovals that
approve future payments or set up a preapproval during the embedded payment flow.
The sender logs in to paypal.com once to set up the preapproval. After the sender agrees to
the preapproval, specific approval is unnecessary.
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:
Introducing Adaptive Payments
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, whi ch
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 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
Introducing Adaptive Payments
Explicit Approval Payment Flow
The following diagram shows the basic flow of control for a payment (such as payment for
items in a shopping cart at a web store) that requires the sender to log in to paypal.com to
approve the payment:
The following items correspond to the circled numbers in the diagram:
1. Your site or device sends a Pay request to PayPal on behalf of a sender.
2. PayPal responds with a key that you use when you direct the sender to PayPal.
3. 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 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
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:
duration of the preapproval, from the start date to the end date, inclusive
the maximum amount being preapproved
the maximum number of payments
The following diagram shows the basic flow of control during a preapproval operation:
Introducing Adaptive Payments
Preapproved Payments Flow
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
Introducing Adaptive Payments
Preapproved Payments Flow
2. PayPal responds with a key, called a preapproval key, that you use when you direct the
sender to PayPal, and once the preapproval has been established, whenever you
automatically complete a payment on behalf of the sender.
3. You redirect your sender’s browser to PayPal.
4. After the sender logs in to paypal.com and sets up the preapproval, PayPal redirects the
sender’s browser to a location you specify.
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:
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 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
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:
Introducing Adaptive Payments
Implicit Approval Payments Flow
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 advantage 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
Introducing Adaptive Payments
Embedded Payments
Embedded Payment Flow Presentations
PayPal provides the following kinds of visual presentations for the embedded payment flow:
The payment flow can be embedded as a lightbox on your web page, which gives the
impression that the payment is handled completely within your website:
The payment flow can appear in a minibrowser window that appears in front of your web
page, which does not require an IFRAME:
28 August 7, 2012 Adaptive Payments Developer Guide
Introducing Adaptive Payments
Embedded Payments
The payment flow can be embedded as a lightbox in an IFRAME on your web page, which
gives the impression that the payment is handled completely within your website:
Adaptive Payments Developer Guide August 7, 2012 29
Introducing Adaptive Payments
Embedded Payments
You choose your preferred visual presentation when you invoke the embedded payment flow.
In some cases, PayPal may override your choice to use a lightbox; for example, when the
sender is required to log into PayPal for the initial payment.
Kinds of Embedded Payments
Embedded payments can include
simple payments
parallel payments
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
Loading...