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
IMPORTANT: Payments for digital goods must use the embedded payment flow. Y ou 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
include JavaScript code from PayPal on your checkout or payment web pages
use the functions provided in the JavaScript to coordinate the PayPal flow with the
appearance of your web pages
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.
Introducing Adaptive Payments
Embedded Payments
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:
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:
Adaptive Payments Developer Guide August 7, 2012 31
Introducing Adaptive Payments
Embedded Payments
The IFRAME also allows the sender to sign up for a PayPal account or pay as a guest without
logging in.
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
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
Introducing Adaptive Payments
Embedded Payments
If the sender chooses Cancel, PayPal redirects the sender’s browser to the cancel URL
specified in the Pay API operation’s request message. 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
Embedded Payments
When the sender clicks Close, PayPal redirects the sender’s browser to the return URL
specified in the Pay API operation’s request message.
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
The lightbox containing the confirmation would appear in your page as follows:
36 August 7, 2012 Adaptive Payments Developer Guide
Introducing Adaptive Payments
Embedded Payments
Preapprove Future Payments Checkbox
You can add a Preapprove future payments checkbox to the sender’s embedded payment
experience, which enables the sender to preapprove subsequent payments. 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
Introducing Adaptive Payments
Embedded Payments
If the payment sender checks the preapproval box, the confirmation page provides details
about the preapproval:
38 August 7, 2012 Adaptive Payments Developer Guide
Introducing Adaptive Payments
Embedded Payments
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
Introducing Adaptive Payments
Embedded Payments
The sender of a payment can select one of the available shipping addresses or add a new
shipping address by selecting Add new shipping address from the Ship to: drop-down menu:
Embedded Payment Experience
To the sender of a payment, the embedded payment experience appears to be built into your
website. 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
Embedded Payments
IFRAME within the sender’s browser and as a pop-up mini-browser that appears in front of
your website.
Typically, the sender initiates a payment by clicking a button:
PayPal responds to the JavaScript that initiates the flow. 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:
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:
Adaptive Payments Developer Guide August 7, 2012 41
Introducing Adaptive Payments
Embedded Payments
The checkbox controls the remember me behavior for log in. This behavior allows the sender
to skip the log in step in cases where there is little risk of the account being misused.
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
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
Introducing Adaptive Payments
Embedded Payments
When the sender clicks Close, PayPal redirects the sender’s browser to the return URL
specified in the Pay API operation’s request message.
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
Embedded Payments
The lightbox containing the confirmation would appear in your page as follows:
Adaptive Payments Developer Guide August 7, 2012 45
Introducing Adaptive Payments
Embedded Payments
The actions you take to launch the flow and close the lightbox are the same steps you take for
the minibrowser.
Preapprove Future Payments Checkbox
You can add a Preapprove future payments checkbox to the sender’s embedded payment
experience, which enables the sender to preapprove subsequent payments. 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
Embedded Payments
If the payment sender checks the preapproval box, the confirmation page provides details
about the preapproval:
Adaptive Payments Developer Guide August 7, 2012 47
Introducing Adaptive Payments
Embedded Payments
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&expType=mini
PayPal first asks the user to log into their PayPal account:
48 August 7, 2012 Adaptive Payments Developer Guide
Introducing Adaptive Payments
Embedded Payments
After signing in, the user is presented with a consent form that the user must agree to:
Adaptive Payments Developer Guide August 7, 2012 49
Introducing Adaptive Payments
Embedded Payments
If the seller has enabled PIN code entry, after consenting to the agreement, the user is
prompted to enter a PIN code by the seller:
50 August 7, 2012 Adaptive Payments Developer Guide
Introducing Adaptive Payments
Embedded Payments
Finally, the user is presented with a confirmation screen:
Adaptive Payments Developer Guide August 7, 2012 51
Introducing Adaptive Payments
Embedded Payments
Shipping Address Selection
You can display and collect shipping address information for a transaction with the embedded
payment flow. PayPal displays the default shipping address when you set
senderOptions.requireShippingAddressSelection to true in your request to
SetPaymentOptions:
52 August 7, 2012 Adaptive Payments Developer Guide
Introducing Adaptive Payments
Embedded Payments
The sender of a payment can select one of the available shipping addresses or add a new
shipping address by selecting Add new shipping address from the Ship to: drop-down menu:
Adaptive Payments Developer Guide August 7, 2012 53
Introducing Adaptive Payments
Embedded Payments
After the sender of the payment clicks Pay, PayPal displays the selected shipping address on
the Thank you for using PayPal page:
54 August 7, 2012 Adaptive Payments Developer Guide
Introducing Adaptive Payments
Embedded Payments
You can call the GetShippingAddresses API operation to obtain the selected shipping
address for the transaction using the key assoicated with the payment.
Setting Up Web Pages to Invoke the Embedded Payment Flow Using a
Lightbox
Use the JavaScript functions in
https://www.paypalobjects.com/js/external/dg.js to set up and control the
embedded payment flow. This example shows how to initiate the embedded payment flow
after obtaining a payment key.
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
Introducing Adaptive Payments
Embedded Payments
1. Call the Pay API operation to obtain a valid pay key.
2. Create your form or button.
– You must include the pay key and redirect to
https://www.paypal.com/webapps/adaptivepayment/flow/pay.
– Optionally , include a preapproval key if you want to enable the sel ection 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.
<form action=
"https://www.paypal.com/webapps/adaptivepayment/flow/pay"
target="PPDGFrame">
<input id="type" type="hidden" name="expType" value="light">
<input id="paykey" type="hidden" name="paykey" value="AP-..."> <input
id="preapprovalkey" type="hidden" name="preapprovalkey" value="PA-...">
<input type="submit" id="submitBtn" value="Pay with PayPal"> </form>
NOTE: To modify an existing application to use the embedded payment flow, change the
redirect from
https://www.paypal.com/webscr?cmd=_ap-payment&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.
<script src="https://www.paypalobjects.com/js/external/dg.js">
</script>
4. Create an embedded flow object and associate it with your payment form or button.
<script>
var dgFlow = new PAYPAL.apps.DGFlow({ trigger: 'submitBtn' });
</script>
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();
56 August 7, 2012 Adaptive Payments Developer Guide
Introducing Adaptive Payments
Embedded Payments
Setting Up Web Pages to Invoke the Embedded Payment Flow Using a
Minibrowser
Use the JavaScript functions in
https://www.paypalobjects.com/js/external/apdg.js to set up and control the
embedded payment flow. This example shows how to initiate the embedded payment flow
after obtaining a payment key.
This example assumes that you obtain a payment key before initiating the flow and that the
key does not change or expire before the sender completes the flow.
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 sel ection 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.
<form action=
"https://www.paypal.com/webapps/adaptivepayment/flow/pay"
target="PPDGFrame">
<input id="type" type="hidden" name="expType" value="mini">
<input id="paykey" type="hidden" name="paykey" value="AP-..."> <input
id="preapprovalkey" type="hidden" name="preapprovalkey" value="PA-...">
<input type="submit" id="submitBtn" value="Pay with PayPal"> </form>
NOTE: To modify an existing application to use the embedded payment flow, change the
redirect from https://www.paypal.com/webscr?cmd=_appayment&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.
<script src="https://www.paypalobjects.com/js/external/apdg.js">
</script>
Adaptive Payments Developer Guide August 7, 2012 57
Introducing Adaptive Payments
Embedded Payments
4. Create an embedded flow object and associate it with your payment form or button.
<script>
function <<returnFunctionName>>() {
<<Your code goes here.>>
}
</script>
After Completing This Task:
The following minibrowser return script can be used to determine whether the payment
successfully completed:
PAYMENTDETAILS=$(wget --no-check-certificate \
--output-document=- \
--quiet \
--header="X-PAYPAL-SERVICE-VERSION: 1.0.0" \
--header="X-PAYPAL-SECURITY-USERID: $APIUSER" \
--header="X-PAYPAL-SECURITY-PASSWORD: $APIPASS" \
--header="X-PAYPAL-SECURITY-SIGNATURE: $APISIG" \
--header="X-PAYPAL-REQUEST-DATA-FORMAT: NV" \
--header="X-PAYPAL-RESPONSE-DATA-FORMAT: NV" \
--header="X-PAYPAL-APPLICATION-ID: $APPLICATIONID" \
--post-data="payKey=$PAYKEY&requestEnvelope.errorLanguage=en_US" \
https://www.paypal.com/AdaptivePayments/PaymentDetails)
if echo $PAYMENTDETAILS | grep -q "\&status=COMPLETED"
then echo "Thank you for approving pay key $PAYKEY"
else echo "Sorry, you were unable to approve pay key $PAYKEY. 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 SetPaymentOptions API 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 SetPaymentOptions and call the API operation.
58 August 7, 2012 Adaptive Payments Developer Guide
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 account 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:
Introducing Adaptive Payments
Guest Payments
Adaptive Payments Developer Guide August 7, 2012 59
Introducing Adaptive Payments
Fee Payment Configuration
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
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:
Sender Pays the Fee
Receiver Pays the Fee in a Parallel Payment
Each Receiver Pays the Fee in a Chained Payment
Primary Receiver Pays the Fee in a Chained Payment
NOTE: Fees are determined by PayPal 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:
Introducing Adaptive Payments
Fee Payment Configuration
In this example, the sender pays a total of $510.83, which includes all fees.
Adaptive Payments Developer Guide August 7, 2012 61
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:
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 their assessment. The following example shows the receivers paying the fees:
62 August 7, 2012 Adaptive Payments Developer Guide
Introducing Adaptive Payments
Fee Payment Configuration
In this example, the primary receiver, identified as the merchant, pays a fee for $20 received.
Each of the other receivers also pay a fee on the amount each receives.
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
Introducing Adaptive Payments
Fee Payment Configuration
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
2
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 applicatio n 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
GetPaymentOptions Obtain the settings specified with the SetPaymentOptions API
operation
SetPaymentOptions 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
Getting Started
Adaptive Payments Endpoints
Other API Operations
API Operation Description
Refund Refunds all or part of a payment
ConvertCurrency Obtains the current foreign exchange (FX) rate for a specific amount
and currency
GetFundingPlans Determines the funding sources that are available for a specified
payment
GetAllowedFundingSources Obtains the funding sources associated with a preapproval.
GetShippingAddresses Obtains the selected shipping address
GetAvailableShippingAddresses 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 sending the request in JSON and requesting an XML response.
66 August 7, 2012 Adaptive Payments Developer Guide
For SOAP, you must also include a specific SOAP protocol header (see the SOAP messages
section).
The following is an example of HTTP headers for NVP in Java for a web implementation:
headers.put("X-PAYPAL-SECURITY-USERID", "tok261_biz_api.abc.com");
headers.put("X-PAYPAL-SECURITY-PASSWORD","1244612379");
headers.put("X-PAYPAL-SECURITY-SIGNATURE","lkfg9groingghb4uw5"
headers.put("X-PAYPAL-DEVICE-IPADDRESS", "168.212.226.204");
headers.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):
Getting Started
HTTP Headers
HTTP Headers for Authentication
Header Description
X-PAYPAL-SECURITY-USERID Your API username
X-PAYPAL-SECURITY-PASSWORD Your API password
X-PAYPAL-SECURITY-SIGNATURE 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 b y 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:
NV – Name-value pairs
XML – Extensible markup language
JSON – JavaScript object notation
X-PAYPAL-RESPONSE-DATA-FORMAT The payload format for the response.
Allowable values are:
NV – Name-value pairs
XML – Extensible markup language
JSON – JavaScript object notation
SOAP Messages
To use Adaptive Payments 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("X-PAYPAL-SECURITY-USERID", "tok261_biz_api.abc.com");
headers.put("X-PAYPAL-SECURITY-PASSWORD","1244612379");
headers.put("X-PAYPAL-SECURITY-SIGNATURE","lkfg9groingghb4uw5"
headers.put("X-PAYPAL-DEVICE-IPADDRESS", "168.212.226.204");
headers.put("X-PAYPAL-MESSAGE-PROTOCOL", "SOAP11");
headers.put("X-PAYPAL-APPLICATION-ID","APP-80W284485P519543T");
Below are the service name, port type, binding and location for SOAP as defined in the
Adaptive Payments WSDL.
<wsdl:service name="AdaptivePayments">
<wsdl:port name="AdaptivePaymentsSOAP11_http"
<binding="services:AdaptivePaymentsSOAP11Binding">
<soap:address location="https://svcs.paypal.com/AdaptivePayments" />
Specifying Application and Device Information
You also must identify the application. Y o u can op tion all y identify other information
associated with the client and the API version:
68 August 7, 2012 Adaptive Payments Developer Guide
Getting Started
Making a Simple Payment (JSON)
HTTP Headers for Application and Device identification
Header Description
X-PAYPAL-APPLICATION-ID (Required) Your application’s identification, which is issued
by PayPal.
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).
You send a PayRequest message to PayPal
You receive a response with a pay key.
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", \
"amount":"10.00",}]},"cancelUrl":"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":"cfe8f8783f1d3","build":"DEV"},\
"payKey":"AP-17266198048308436","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.
Adaptive Payments Developer Guide August 7, 2012 69
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.
You send a PayRequest, specifying an amount to be paid for each receiver.
You receive a response with a pay key.
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
&actionType=PAY
&cancelUrl=http:\\example.com\cancel.htm
¤cyCode=USD
&receiverList.receiver(0).amount=9.00
&receiverList.receiver(0).email=andrea@example.com
&receiverList.receiver(1).amount=5.00
&receiverList.receiver(1).email=linda@example.com
&requestEnvelope.errorLanguage=en_US
&returnUrl=http:\\example.com\return.htm
Pay Response for Parallel Payment
responseEnvelope.timestamp=2009-11-03T08%3A12.937-07%3A00
&responseEnvelope.ack=Success
&responseEnvelope.correlationId=b1cc3eabfa4c1
&responseEnvelope.build=942345
&payKey=AP-688241038Y786593D
&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.
70 August 7, 2012 Adaptive Payments Developer Guide
Making a Chained Payment (XML)
A chained payment is when a sender sends a payment to a PayPal-registered receiver who is
the primary receiver.
You send a PayRequest, enabling the primary receiver.
You receive a response with a pay key.
You must redirect the sender’s browser to PayPal to approve the payment.
With chained payments, the sender only sees the transaction to the primary API caller. 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 Chained Payment
Getting Started
Making a Chained Payment (XML)
<PayRequest>
<requestEnvelope>
<errorLanguage>en_US</errorLanguage> </requestEnvelope>
<cancelUrl xmlns="">http://exammple.com/cancelURL.htm</cancelUrl>
<actionType>PAY</actionType>
<currencyCode xmlns="">USD</currencyCode>
<receiverList xmlns="">
<receiver>
<amount>100</amount>
<email>frank@example.com</email>
<primary>true</primary>
</receiver>
<receiver>
<amount>75</amount>
<email>yvonne@example.com</email>
<primary>false</primary>
</receiver>
</receiverList>
<returnUrl xmlns="">http://example.com/returnURL.htm</returnUrl>
</PayRequest>
Adaptive Payments Developer Guide August 7, 2012 71
Getting Started
Making a Chained Payment (XML)
Pay Response for Chained Payment
<?xml version='1.0' encoding='UTF-8'?>
<ns2:PayResponse xmlns:ns2="http://svcs.paypal.com/types/ap">
<responseEnvelope>
<timestamp>2009-10-06T17:24:03.874-07:00</timestamp>
<ack>Success</ack><correlationId>eca3a204200f4</correlationId>
<build>1044393</build></responseEnvelope>
<payKey>AP-688241038Y786593D</payKey>
<paymentExecStatus>CREATED</paymentExecStatus></ns2:PayResponse>
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.
72 August 7, 2012 Adaptive Payments Developer Guide
Pay API Operation
3
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 fo llowing fields:
Field Description
actionType The action for this request. Possible values are:
PAY – Use this option if you are not using the Pay
request in combination with ExecutePayment.
CREATE – Use this option to set up the payment
instructions with SetPaymentOptions and then
execute the payment at a later time with the
ExecutePayment.
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.
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
Pay API Operation
Pay Summary
Field Description
returnUrl URL to redirect the sender’s browser to after the sender has
logged into PayPal and approved a payment; it is always
required but only used if a payment requires explicit
approval
requestEnvelope.errorLanguage The code for the language in which errors are returned,
which must be en_US.
Parallel Payments
For a simple payment, you must specify values for the fields above. For a parallel payment,
you must specify both the above values and the following fields:
Field Description
receiverList.receiver(
receiverList.receiver(
n).email The receiver ’s email address for each receiver, where n is
between 0 and 5 for a maximum of 6 receivers
n).amount Amount to send to each corresponding receiver
Chained Payments
For a chained payment, you must specify all required fields for a parallel payment and you
must also specify enable the primary receiver:
Field Description
receiverList.receiver(
receiverList.receiver(
receiverList.receiver(
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:
n).email The receivers’ email addresses, where n is between 0 and 5
for a total of one primary receiver and between one and 5
secondary receivers
n).amount Amount to send to each corresponding receiver
n).primary Set to true to indicate a chained payment; only one receiver
can be a primary receiver. Omit this field, or set it to false
for simple and parallel payments.
https://www.paypal.com/webscr?cmd=_ap-payment&paykey=value
NOTE: The command is _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
Pay Summary
Implicit Payments
If you are the API caller and you specify your email address in the senderEmail field,
PayPal implicitly approves the payment without redirecting to PayPal:
Field Description
senderEmail Sender’s email address
Preapproved Payments
If the sender has set up a preapproval, you can use the preapproval to avoid explicit approval.
In that case, you must specify values for the fields below.
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 digita l goods in the same way you handle payments for other goods
and services, with the following exceptions:
T o specify a payment for digital goods, you must specify DIGITALGOODS for each receiver
in your receiver list; specify
receiverList.receiver(
where
n identifies the receiver, starting with 0.
If you specify a payment for digital goods, you cannot specify a senderEmail address or
n).paymentType=DIGITALGOODS for each receiver,
include a funding constraint.
You must redirect the sender to the following PayPal URL to complete the payment for
digital goods:
https://www.paypal.com/webapps/adaptivepayment/flow/pay?paykey=...
Payment Notifications
Notifications are sent after payment is executed, which follows approval of the payment by the
sender if required:
PayPal sends an email to the sender and all receivers associated with a payment when the
transfer is complete; you receive an email only if you are also the payment sender or
receiver.
Adaptive Payments Developer Guide August 7, 2012 75
Pay API Operation
Pay Summary
When the payment is complete, PayPal sends an IPN message to the URL specified in the
ipnNotificationUrl field of the Pay request.
Additional Notes About the Pay API Operation
1. With parallel payments, fund transfers to some receivers may occur before others.
Therefore, set reverseAllParallelPaymentsOnError to true. In the event of an
error, this setting guarantees that transfers to all receivers are reversed and all funds are
returned to the sender. If reverseAllParallelPaymentsonError is disabled,
completed transfers are not reversed and funds that have already been transferred are no
longer available to the sender.
2. 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.
3. 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 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.
4. 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.
5. 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.
6. 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.
7. 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 the payment flow.
76 August 7, 2012 Adaptive Payments Developer Guide
PayRequest Message
The PayRequest message contains the instructions required to make a payment.
Pay API Operation
PayRequest Message
Adaptive Payments Developer Guide August 7, 2012 77
Pay API Operation
PayRequest Message
78 August 7, 2012 Adaptive Payments Developer Guide
PayRequest Fields
Field Description
actionType xs:string
(Required) Whether the Pay request pays the receiver or whether the Pay
request is set up to create a payment request, but not fulfill the payment until
the ExecutePayment is called.
Allowable values are:
PAY – Use this option if you are not using the Pay request in combination
with ExecutePayment.
CREATE – Use this option to set up the payment instructions with
SetPaymentOptions and then execute the payment at a later time with
the ExecutePayment.
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
Pay API Operation
PayRequest Message
clientDetails common:ClientDetailsType
(Optional) Information about the sender.
Adaptive Payments Developer Guide August 7, 2012 79
Pay API Operation
PayRequest Message
Field Description
currencyCode xs:string
(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
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
Ne w 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
feesPayer xs:string
(Optional) The payer of PayPal fees. Allowable values are:
SENDER – Sender pays all fees (for personal, implicit simple/parallel
payments; do not use for chained or unilateral payments)
PRIMARYRECEIVER – Primary receiver pays all fees (chained payments
only)
EACHRECEIVER – Each receiver pays their own fee (default, personal and
unilateral payments)
SECONDARYONLY – Secondary receivers pay all fees (use only for chained
payments with one secondary receiver)
80 August 7, 2012 Adaptive Payments Developer Guide
Field Description
fundingConstraint ap:FundingConstraint
(Optional) Specifies a list of allowed funding types for the payment. This is a
list of funding selections that can be combined in any order to allow payments
to use the indicated funding type. If this Parameter is omitted, the payment can
be funded by any funding type that is supported for Adaptive Payments.
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
Pay API Operation
PayRequest Message
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.
returnUrl xs:string
(Required) The URL to which the sender’s browser is redirected after
approving a payment on paypal.com. Specify the URL with the HTTP or
HTTPS designator.
Maximum length: 1024 characters
reverseAllParallelPaymen
tsOnError
xs:boolean
(Optional) Whether to reverse parallel payments if an error occurs with a
payment.
Allowable values are:
true – Each parallel payment is reversed if an error occurs
false – Only incomplete payments are reversed (default)
Adaptive Payments Developer Guide August 7, 2012 81
Pay API Operation
PayRequest Message
Field Description
senderEmail xs:string
(Optional) Sender’s email address.
Maximum length: 127 characters
sender ap:SenderIdentifier
(Optional) Sender’s identifying information.
trackingId xs:string
(Optional) A unique ID that you specify to track the payment.
NOTE: You are responsible for ensuring that the ID is unique.
Maximum length: 127 characters
ClientDetails Fields
Field Description
applicationId xs:string
(Optional) Your application’s identification, such as the name of your
application
customerId xs:string
(Optional) Your ID for this sender
Maximum length: 127 characters
customerType xs:string
(Optional) Your identifi cation of the type of customer
Maximum length: 127 characters
deviceId xs:string
(Optional) Sender’s device ID, such as a mobile device’s IMEI number or a
web browser cookie. If a device ID was passed with the PayRequest, use the
same ID here.
Maximum length: 127 characters
geoLocation xs:string
(Optional) Sender’s geographic location
Maximum length: 127 characters
ipAddress xs:string
(Optional) Sender’s IP address. If an IP addressed was passed with the
PayRequest, use the same ID here.
model xs:string
(Optional) A sub-identification of the application
Maximum length: 127 characters
82 August 7, 2012 Adaptive Payments Developer Guide
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.
Pay API Operation
PayRequest Message
NOTE: To use iACH, omit this field and do not specify a funding source for
the payment.
FundingTypeList Fields
Field Description
fundingTypeInfo ap:FundingTypeInfo
(Optional) Specifies a list of allowed funding selections for the payment. This
is a list of funding selections that can be combined in any order to allow
payments to use the indicated funding type. If this field is omitted, the payment
can be funded by any funding type that is supported for Adaptive Payments.
NOTE: 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
Pay API Operation
PayRequest Message
FundingTypeInfo Fields
Field Description
fundingType xs:string
(Required) Specifies a list of allowed funding selections for the payment. This
is a list of funding selections that can be combined in any order to allow
payments to use the indicated funding type. If this field is omitted, the payment
can be funded by any funding type that is supported for Adaptive Payments.
Allowable values are:
ECHECK – Electronic check
BALANCE – PayPal account balance
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 xs:decimal
(Required) Amount to be paid to the receiver.
email 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
invoiceId xs:string
(Optional) The invoice number for the payment. This data in this field shows
on the Transaction Details report.
Maximum length: 127 characters
84 August 7, 2012 Adaptive Payments Developer Guide
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 email address or a phone number as the payment receiver.
Pay API Operation
PayRequest Message
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:
true – Primary receiver
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
Pay API Operation
PayResponse Message
SenderIdentifier Fields
Field Description
useCredentials xs:boolean
(Optional) If true, use credentials to identify the sender; default is false.
AccountIdentifier Fields
Field Description
email xs:string
(Optional) Sender’s email address.
Maximum length: 127 characters
phone common:PhoneNumberType
(Optional) Sender’s phone number.
RequestEnvelope Fields
Field Description
detailLevel common:DetailLevelCode
(Optional) Level of detail required by the client application pertaining to a
particular data component. The detail level is specified as a detail level code,
which has all the enumerated values of the detail level for the component. By
default, the detail level code is ReturnAll, which provides the maximum
level of detail.
errorLanguage xs:string
(Required) RFC 3066 language in which error messages are returned; by
default it is en_US, which is the only language currently supported.
PayResponse Message
The 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
PayResponse Message
Adaptive Payments Developer Guide August 7, 2012 87
Pay API Operation
PayResponse Message
88 August 7, 2012 Adaptive Payments Developer Guide
Pay API Operation
PayResponse Message
Adaptive Payments Developer Guide August 7, 2012 89
Pay API Operation
PayResponse Message
PayResponse Fields
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:
CREATED – The payment request was received; funds will be transferred
once the payment is approved
COMPLETED – The payment was successful
INCOMPLETE – Some transfers succeeded and some failed for a parallel
payment or, for a delayed chained payment, secondary receivers have not
been paid
ERROR – The payment failed and all attempted transfers failed or all
completed transfers were successfully reversed
REVERSALERROR – One or more transfers failed when attempting to
reverse a payment
PROCESSING – The payment is in progress
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
Pay API Operation
PayResponse Message
PayErrorList Fields
Field Description
payError PayError indicates the error, if any, that resulted on an attempted payment to
a receiver.
FundingPlan Fields
Field Description
fundingPlanId xs:string
ID for this funding plan.
fundingAmount common:CurrencyType
Amount of available funding.
backupFundingSource ap:FundingSource
Backup funding source.
senderFees common:CurrencyType
Fees to be paid by the sender.
currencyConversion ap:CurrencyConversion
The currency conversion associated with the funding plan.
charge ap:FundingPlanCharge
The amount to be charged to this funding plan.
CurrencyType Fields
Field Description
amount xs:decimal
The converted amount.
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
Ne w 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
FundingSource Fields
Field Description
lastFourOfAccountNumber xs:string
Last 4 digits or characters in account number.
92 August 7, 2012 Adaptive Payments Developer Guide
Field Description
type xs:string
Type of funding source, which is one of the following values:.
UNDEFINED
BALANCE
BANK_INSTANT
BANK_DELAYED
CREDITCARD
DEBITCARD
ACCOUNTS_RECEIVABLE
displayName xs:string
Display name of funding source.
fundingSourceId xs:string
Funding source ID.
allowed xs:boolean
Whether the funding source is allowed for this payment:
true – You can use this funding source for the payment
false – You cannot use this funding source (defaul t)
Pay API Operation
PayResponse Message
CurrencyConversion Fields
Field Description
from ap:CurrencyType
The currency to be converted.
to ap:CurrencyType
The currency resulting from the conversion.
exchangeRate xs:decimal
The exchange rate for the from currency to the to currency.
FundingPlanCharge Fields
Field Description
charge common:CurrencyType
Amount charged to funding source.
fundingSource ap:FundingSource
Funding source being charged.
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:
System – The system encountered errors; try again
Application – The application encountered errors; try again
Request – The request was incorrect
domain xs:string
The domain to which this service belongs.
errorId xs:long
A 6-digit number that uniquely identifies a particular error.
exceptionID This field is not used.
message xs:string
A description of the error.
parameter common:ErrorParameter
Represents contextual information about the error.
severity common:ErrorSeverity
The severity of the error encountered.
Possible values are:
Error – Processing of the request was interrupted
Warning – Processing of the request was completed
subdomain This field is not used.
94 August 7, 2012 Adaptive Payments Developer Guide
Receiver Fields
Field Description
amount xs:decimal
Amount to be paid to the receiver.
email xs:string
Receiver’s email address.
Maximum length: 127 characters
invoiceId xs:string
The invoice number for the payment. This data in this field shows on the
Transaction Details report.
Maximum length: 127 characters
paymentType xs:string
The transaction type for the payment.
Possible 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.
Pay API Operation
PayResponse Message
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:
true – Primary receiver (chained payment)
false – Secondary receiver (simple/parallel payment)
PhoneNumberType Response Fields
Field Description
countryCode xs:string
T elephone country code.
Adaptive Payments Developer Guide August 7, 2012 95
Pay API Operation
PPFault Message
Field Description
phoneNumber xs:string
Telephone number.
extension xs:string
T elephone extension.
ResponseEnvelope Fields
Field Description
ack common:AckCode
Acknowledgement code. It is one of the following values:
Success – The operation completed successfully.
Failure – The operation failed.
SuccessWithWarning – The operation completed successfully;
however, there is a warning message.
FailureWithWarning – The operation failed with a warning message.
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 stri ng (for exam ple,
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.
96 August 7, 2012 Adaptive Payments Developer Guide
Pay API Operation
PPFault Message
FaultMessage Fields
Field Description
error common:ErrorData
Detailed error information.
responseEnvelope common:ResponseEnvelope
Common response information, including a timestamp and the response
acknowledgement status.
Adaptive Payments Developer Guide August 7, 2012 97
Pay API Operation
PPFault Message
ErrorData Fields
Field Description
category common:ErrorCategory
The location where the error occurred.
Possible values are:
System – The system encountered errors; try again
Application – The application encountered errors; try again
Request – The request was incorrect
domain xs:string
The domain to which this service belongs.
errorId xs:long
A 6-digit number that uniquely identifies a particular error.
exceptionID This field is not used.
message xs:string
A description of the error.
parameter common:ErrorParameter
Represents contextual information about the error.
severity common:ErrorSeverity
The severity of the error encountered.
Possible values are:
Error – Processing of the request was interrupted
Warning – Processing of the request was completed
subdomain This field is not used.
ResponseEnvelope Fields
Field Description
ack common:AckCode
Acknowledgement code. It is one of the following values:
Success – The operation completed successfully.
Failure – The operation failed.
SuccessWithWarning – The operation completed successfully;
however, there is a warning message.
FailureWithWarning – The operation failed with a warning message.
build xs:string
Build number. It is used only by PayPal Merchant Technical Support.
98 August 7, 2012 Adaptive Payments Developer Guide
Field Description
correlationId xs:string
Correlation identifier. It is a 13-character, alphanumeric stri ng (for exam ple,
db87c705a910e) that is used only by PayPal Merchant Technical Support.
NOTE: You must log and store this data for every response you receive.
PayPal Technical Support uses the information to assist with reported
issues.
timestamp xs:datetime
Date on which the response was sent, for example:
2012-04-02T22:33:35.774-07:00
NOTE: You must log and store this data for every response you receive.
PayPal Technical Support uses the information to assist with reported
issues.
Pay Examples Using NVP and CURL
Pay API Operation
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 explicitl y
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
Pay API Operation
Pay Examples Using NVP and CURL
curl -s --insecure
-H "X-PAYPAL-SECURITY-USERID: api_username"
-H "X-PAYPAL-SECURITY-PASSWORD: api_password"
-H "X-PAYPAL-SECURITY-SIGNATURE: api_signature"
-H "X-PAYPAL-REQUEST-DATA-FORMAT: NV"
-H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV"
-H "X-PAYPAL-APPLICATION-ID: app_id"
https://svcs.sandbox.paypal.com/AdaptivePayments/Pay -d
"requestEnvelope.errorLanguage=en_US
&actionType=PAY
&senderEmail=sender@domain
&receiverList.receiver(0).email=receiver@domain
&receiverList.receiver(0).amount=100.00
¤cyCode=USD
&feesPayer=EACHRECEIVER
&memo=Simple payment example.
&cancelUrl=http://your_cancel_url
&returnUrl=http://your_return_url
&ipnNotificationUrl=http://your_ipn_notification_url"
Response for an explicitly approved payment:
responseEnvelope.timestamp=2009-07-13T12%3A34%3A29.316-07%3A00
&responseEnvelope.ack=Success
&responseEnvelope.correlationId=d615a365bed61
&responseEnvelope.build=DEV
&payKey=AP-3TY011106S4428730
&paymentExecStatus=CREATED
NOTE: You must redirect the sender to PayPal to complete the payment.
Response for an implicitly approved payment:
responseEnvelope.timestamp=2009-07-10T11%3A47%3A29.311-07%3A00
&responseEnvelope.ack=Success
&responseEnvelope.correlationId=34e44c0bdbed6
&responseEnvelope.build=DEV
&payKey=AP-54224401WG093204T
&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 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
Loading...