PayPal Invoicing 2012 User guide

Category
Software
Type
User guide

This manual is also suitable for

Invoicing Service API
Guide
Last updated: May 2012
Invoicing Service API Guide
Document Number: 10128.en_US-201205
© 2011-2012 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other
trademarks and brands are the property of their respective owners.
The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc.
Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard Royal, L-
2449, Luxembourg, R.C.S. Luxembourg B 118 349
Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval
of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.
Notice of non-liability:
PayPal, Inc. is providing the information in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information contained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused
by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting from the application or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.
Invoicing Service API Guide May 2012 3
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Chapter 1 Introduction to the Invoicing Service API . . . . . . . . . .11
Sending Invoices on Behalf of a Merchant. . . . . . . . . . . . . . . . . . . . . . . . . . 13
Invoicing Service API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Creating and Sending Invoices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Managing Invoices. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
IPN Variables for Invoicing API Operations . . . . . . . . . . . . . . . . . . . . . . . . . 14
Invoice Payments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14
Canceled Invoices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
Chapter 2 Invoicing Service API Examples. . . . . . . . . . . . . . .17
HTTP Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Specifying JSON, NVP, or XML Data Formats. . . . . . . . . . . . . . . . . . . . . . 18
SOAP Messages. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
Specifying Application and Device Information . . . . . . . . . . . . . . . . . . . . . 19
Creating an Invoice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Sending an Invoice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Creating and Sending an Invoice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Updating an Invoice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
Obtaining Invoice Details. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Canceling an Invoice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
Searching for Invoices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
Chapter 3 CreateInvoice API Operation . . . . . . . . . . . . . . . .25
CreateInvoiceRequest Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
CreateInvoiceRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
InvoiceType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
BusinessInfoType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Contents
4 May 2012 Invoicing Service API Guide
BaseAddress Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
InvoiceItemListType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
InvoiceItemType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
CreateInvoiceResponse Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
CreateInvoiceResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
CreateInvoice API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
Chapter 4 SendInvoice API Operation . . . . . . . . . . . . . . . . .37
SendInvoiceRequest Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
SendInvoiceRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
SendInvoiceResponse Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
SendInvoiceResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Send Invoice API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Chapter 5 CreateAndSendInvoice API Operation. . . . . . . . . . . .43
CreateAndSendInvoiceRequest Message . . . . . . . . . . . . . . . . . . . . . . . . . . 43
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
CreateAndSendInvoiceRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . 46
InvoiceType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
BusinessInfoType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
BaseAddress Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
InvoiceItemListType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
InvoiceItemType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
CreateAndSendInvoiceResponse Message . . . . . . . . . . . . . . . . . . . . . . . . . 50
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
CreateAndSendInvoiceResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . 51
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Invoicing Service API Guide May 2012 5
Contents
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
CreateAndSendInvoice API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Chapter 6 UpdateInvoice API Operation . . . . . . . . . . . . . . . .55
UpdateInvoiceRequest Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
UpdateInvoiceRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
InvoiceType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
BusinessInfoType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
InvoiceItemType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60
InvoiceItemType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
UpdateInvoiceResponse Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
UpdateInvoiceResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
UpdateInvoice API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Chapter 7 GetInvoiceDetails API Operation . . . . . . . . . . . . . .67
GetInvoiceDetailsRequest Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
GetInvoiceDetailsRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
GetInvoiceDetailsResponse Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
GetInvoiceDetailsResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
InvoiceType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
InvoiceDetailsType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
PaymentDetailsType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
PayPalPaymentDetailsType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
OtherPaymentDetailsType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Contents
6 May 2012 Invoicing Service API Guide
GetInvoiceDetails API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Chapter 8 CancelInvoice API Operation . . . . . . . . . . . . . . . .81
CancelInvoiceRequest Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
CancelInvoiceRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
CancelInvoiceResponse Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
CancelInvoiceResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
CancelInvoice API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Chapter 9 SearchInvoices API Operation . . . . . . . . . . . . . . .87
SearchInvoicesRequest Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
SearchInvoicesRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
SearchParametersType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
DateRangeType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
SearchInvoicesResponse Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
SearchInvoicesResponse Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
InvoiceSummaryListType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
InvoiceSummaryType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
SearchInvoices API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Chapter 10 MarkInvoiceAsPaid API Operation . . . . . . . . . . . . .97
MarkInvoiceAsPaidRequest Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
MarkInvoiceAsPaidRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
OtherPaymentDetailsType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
MarkInvoiceAsPaidResponse Message . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Invoicing Service API Guide May 2012 7
Contents
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
MarkInvoiceAsPaidResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . . .100
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102
MarkInvoiceAsPaid API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .102
Chapter 11 MarkInvoiceAsUnpaid API Operation . . . . . . . . . . . 105
MarkInvoiceAsUnpaidRequest Message . . . . . . . . . . . . . . . . . . . . . . . . . .105
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .105
MarkInvoiceAsUnpaidRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . .106
MarkInvoiceAsUnpaidResponse Message. . . . . . . . . . . . . . . . . . . . . . . . . .106
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .106
MarkInvoiceAsUnpaidResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . .107
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .109
MarkInvoiceAsUnpaid API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .110
Chapter 12 MarkInvoiceAsRefunded API Operation . . . . . . . . . . 111
MarkInvoiceAsRefundedRequest Message . . . . . . . . . . . . . . . . . . . . . . . . .111
RequestEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111
MarkInvoiceAsRefundedRequest Fields. . . . . . . . . . . . . . . . . . . . . . . . .111
OtherRefundDetailsType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112
MarkInvoiceAsRefundedResponse Message . . . . . . . . . . . . . . . . . . . . . . . .112
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .112
MarkInvoiceAsRefundedResponse Fields. . . . . . . . . . . . . . . . . . . . . . . .113
PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
ResponseEnvelope Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
MarkInvoiceAsRefunded API Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
Revision History. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Index. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
Contents
8 May 2012 Invoicing Service API Guide
Invoicing Service API Guide May 2012 9
Preface
You can use the Invoicing Service API to create, send, and manage invoices using PayPal.
Documentation Feedback
Help us improve this guide by sending feedback to:
documentationfe[email protected]
Documentation Feedback
10 May 2012 Invoicing Service API Guide
Invoicing Service API Guide May 2012 11
1
Introduction to the Invoicing
Service API
PayPal enables you to create and manage invoices. When you send an invoice, PayPal emails
the receipient and allows him or her to pay with PayPal.
The following diagram shows the basic execution flow for creating and sending an invoice:
The circled numbers indicate actions that you take as well as actions taken by PayPal and your
customer:
1. Specify the contents of the invoice in the CreateInvoice request and send the request to
the https://svcs.paypal.com/Invoice/CreateInvoice endpoint.
2. Examine the response and verify that the ACK field contains SUCCESS.
3. Using the invoice ID in the response, create a SendInvoice request and send it to the
https://svcs.paypal.com/Invoice/SendInvoice endpoint.
4. Examine the response and verify that the ACK field contains SUCCESS.
NOTE: You can combine the creation and transmission of an invoice in the same request,
which is CreateAndSend. After you create the request, send it to the
https://svcs.paypal.com/Invoice/CreateAndSendInvoice endpoint.
Introduction to the Invoicing Service API
1
12 May 2012 Invoicing Service API Guide
5. If the SendInvoice request was successful, PayPal sends an invoice by email to the payer
whose email you specified in the CreateInvoice or CreateAndSendInvoice request.
6. When your customer clicks Pay Invoice in the email, the customers browser is redirected
to PayPal and the customer is prompted to log in.
7. The customer can then pay on PayPal.
The contents of an invoice depend on what you specify in the CreateInvoice, or
CreateAndSend requests. Following is an example invoice:
Invoicing Service API Guide May 2012 13
Introduction to the Invoicing Service API
Sending Invoices on Behalf of a Merchant
1
Sending Invoices on Behalf of a Merchant
You can send invoices on behalf of a merchant if you have permission to do so. There is no
difference in how you set up your request for CreateInvoice or
CreateAndSendInvoice, except that you specify the merchant’s email address instead of
your own in the request, and you include an additional header that indicates you have the
permission of the third party to send invoices on their behalf.
The merchant grants you permission using their PayPal profile, or you request permission
using the Permissions Service API. For more information about this API, see PayPal
Permissions Service at
PayPal Permissions Service.
Invoicing Service API Operations
The operations in the Invoicing Service API enable you to create and send invoices to your
customers, as well manage existing invoices, which may or may not have been sent.
NOTE: Although you do not need to register your application with PayPal, you must have a
valid app ID to use the Invoicing Service API. If you have an existing app ID, you can
reuse it. See
x.com to obtain an app ID.
Creating and Sending Invoices
Managing Invoices
API Operation Description
CreateInvoice Creates a new invoice.
SendInvoice Sends an invoice to a customer.
CreateAndSendInvoice Creates and sends an invoice, which is equivalent to the combination
of the CreateInvoice operation followed by the SendInvoice
operation.
API Operation Description
UpdateInvoice Updates an invoice.
GetInvoiceDetails Obtains the contents of an invoice.
CancelInvoice Cancels an invoice.
SearchInvoices Searches for invoices based on specified criteria.
MarkInvoiceAsPaid Marks an invoice as having been paid.
Introduction to the Invoicing Service API
IPN Variables for Invoicing API Operations
1
14 May 2012 Invoicing Service API Guide
IPN Variables for Invoicing API Operations
PayPal sends IPN messages for invoice payments and canceled invoices. For more
information about IPN, see the Instant Payment Notification Guide:
https://cms.paypal.com/cms_content/US/en_US/files/developer/IPNGuide.pdf.
Invoice Payments
mc_gross: 37.12
protection_eligibility: Eligible
address_status: confirmed
payer_id: ABF644D44GSPJ
address_street: 5656 South Market Street
payment_date: 15:57:39 Sep 12, 2011 PDT
payment_status: Completed
invoice_id: INV2-VMYW-LQKA-QBGC-6YDE
charset: windows-1252
address_zip: 95131
first_name: Nick
mc_fee: 1.38
address_country_code: US
address_name: Selling Fruits
notify_version: 3.4
payer_status: verified
business: jbui-us-busines[email protected]
address_country: United States
address_city: San Jose
verify_sign: AFcWxV21C7fd0v3bYYYRCpSSRl31A23x28hwIQCThw2nNi2s8MlV2o10
payer_email: jbui-us-personal1@paypal.com
txn_id: 68H067535A2789915
payment_type: instant
last_name: Ronald
address_state: CA
MarkInvoiceAsUnpaid Marks an invoice as unpaid.
MarkInvoiceAsRefunded Marks an invoice as having been refunded.
API Operation Description
Invoicing Service API Guide May 2012 15
Introduction to the Invoicing Service API
IPN Variables for Invoicing API Operations
1
receiver_email: jbui-us-business1@paypal.com
payment_fee: 1.38
receiver_id: 9N3VVZS28ELHL
txn_type: invoice_payment
mc_currency: USD
residence_country: US
transaction_subject: Send the Reminder Soon.
invoice_number: 0151
payment_gross: 37.12
ipn_track_id: ogo4fwr-n.J7dGNgDiJzqg
Canceled Invoices
merchant_business_name: Fruits Packaging Inc.
merchant_first_name: Joan
notify_version: 3.4
txn_type: invoice_payer_cancel
invoice_number: 0021
charset: windows-1252
payer_email: jbui-us-personal1@paypal.com
payer_last_name: Bond
merchant_last_name: Joan
payer_first_name: Henry
merchant_email: jbui-us-business1@paypal.com
verify_sign: AiPC9BjkCyDFQXbSkoZcgqH3hpacAAV9zVNI.GLTI1sLOHpeeWp3oMQZ
invoice_id: INV2-UHWN-STXM-65B7-PT4R
ipn_track_id: 2eKZJ-cZftAHzSWbsS7qjQ
Introduction to the Invoicing Service API
IPN Variables for Invoicing API Operations
1
16 May 2012 Invoicing Service API Guide
Invoicing Service API Guide May 2012 17
2
Invoicing Service API Examples
You can use the Invoicing Service API to create, send, update, cancel, or obtain details of
invoices for yourself or third-party merchants. You can also search invoices, and mark them as
paid, unpaid, or refunded.
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.
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):
Invoicing Service API Examples
HTTP Headers
2
18 May 2012 Invoicing Service API Guide
HTTP Headers for Authentication
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.
For SOAP messages, refer to the next section.
HTTP Headers for JSON, NVP, and XML Data Formats
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 by a key, must be
owned by the subject granting the third-party
permission.
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
Invoicing Service API Guide May 2012 19
Invoicing Service API Examples
HTTP Headers
2
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. You can optionally identify other information
associated with the client and the API version:
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.
Invoicing Service API Examples
Creating an Invoice
2
20 May 2012 Invoicing Service API Guide
Creating an Invoice
This example shows how to create an invoice using CreateInvoice.
curl -s --insecure
-H "X-PAYPAL-SECURITY-USERID: Your_API_username"
-H "X-PAYPAL-SECURITY-PASSWORD: Your_API_password"
-H "X-PAYPAL-SECURITY-SIGNATURE: Your_API_signature"
-H "X-PAYPAL-REQUEST-DATA-FORMAT: NV"
-H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV"
-H "X-PAYPAL-APPLICATION-ID: Your_AppID"
https://svcs.sandbox.paypal.com/Invoice/CreateInvoice
-d
"requestEnvelope.errorLanguage=en_US
&invoice.merchantEmail=merchant%40domain.com
&invoice.payerEmail=jbui-us-business2%40paypal.com
&invoice.currencyCode=USD
&invoice.itemList.item(0).name=Banana+Leaf+--+001
&invoice.itemList.item(0).description=Banana+Leaf
&invoice.itemList.item(0).quantity=1
&invoice.itemList.item(0).unitPrice=1
&invoice.itemList.item(0).taxName=Tax1
&invoice.itemList.item(0).taxRate=10.25
&invoice.paymentTerms=Net10
&invoice.logoUrl=https%3A%2F%2Fwww.example.com%2FYour_logo.jpg"
Sending an Invoice
This example shows how to send an invoice using SendInvoice. The invoice ID, which is in
the response to CreateInvoice, identifies the invoice to send.
curl -s --insecure
-H "X-PAYPAL-SECURITY-USERID: Your_API_username"
-H "X-PAYPAL-SECURITY-PASSWORD: Your_API_password"
-H "X-PAYPAL-SECURITY-SIGNATURE: Your_API_signature"
-H "X-PAYPAL-REQUEST-DATA-FORMAT: NV"
-H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV"
-H "X-PAYPAL-APPLICATION-ID: Your_AppID"
https://svcs.sandbox.paypal.com/Invoice/SendInvoice
-d
"requestEnvelope.errorLanguage=en_US
&invoiceID=INV2-RVY9-UWTW-64HZ-BR9W"
  • Page 1 1
  • Page 2 2
  • Page 3 3
  • Page 4 4
  • Page 5 5
  • Page 6 6
  • Page 7 7
  • Page 8 8
  • Page 9 9
  • Page 10 10
  • Page 11 11
  • Page 12 12
  • Page 13 13
  • Page 14 14
  • Page 15 15
  • Page 16 16
  • Page 17 17
  • Page 18 18
  • Page 19 19
  • Page 20 20
  • Page 21 21
  • Page 22 22
  • Page 23 23
  • Page 24 24
  • Page 25 25
  • Page 26 26
  • Page 27 27
  • Page 28 28
  • Page 29 29
  • Page 30 30
  • Page 31 31
  • Page 32 32
  • Page 33 33
  • Page 34 34
  • Page 35 35
  • Page 36 36
  • Page 37 37
  • Page 38 38
  • Page 39 39
  • Page 40 40
  • Page 41 41
  • Page 42 42
  • Page 43 43
  • Page 44 44
  • Page 45 45
  • Page 46 46
  • Page 47 47
  • Page 48 48
  • Page 49 49
  • Page 50 50
  • Page 51 51
  • Page 52 52
  • Page 53 53
  • Page 54 54
  • Page 55 55
  • Page 56 56
  • Page 57 57
  • Page 58 58
  • Page 59 59
  • Page 60 60
  • Page 61 61
  • Page 62 62
  • Page 63 63
  • Page 64 64
  • Page 65 65
  • Page 66 66
  • Page 67 67
  • Page 68 68
  • Page 69 69
  • Page 70 70
  • Page 71 71
  • Page 72 72
  • Page 73 73
  • Page 74 74
  • Page 75 75
  • Page 76 76
  • Page 77 77
  • Page 78 78
  • Page 79 79
  • Page 80 80
  • Page 81 81
  • Page 82 82
  • Page 83 83
  • Page 84 84
  • Page 85 85
  • Page 86 86
  • Page 87 87
  • Page 88 88
  • Page 89 89
  • Page 90 90
  • Page 91 91
  • Page 92 92
  • Page 93 93
  • Page 94 94
  • Page 95 95
  • Page 96 96
  • Page 97 97
  • Page 98 98
  • Page 99 99
  • Page 100 100
  • Page 101 101
  • Page 102 102
  • Page 103 103
  • Page 104 104
  • Page 105 105
  • Page 106 106
  • Page 107 107
  • Page 108 108
  • Page 109 109
  • Page 110 110
  • Page 111 111
  • Page 112 112
  • Page 113 113
  • Page 114 114
  • Page 115 115
  • Page 116 116
  • Page 117 117
  • Page 118 118
  • Page 119 119
  • Page 120 120
  • Page 121 121
  • Page 122 122

PayPal Invoicing 2012 User guide

Category
Software
Type
User guide
This manual is also suitable for

Ask a question and I''ll find the answer in the document

Finding information in a document is now easier with AI