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.
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/CreateA ndSendInvoice endpoint.
Invoicing Service API GuideMay 201211
Introduction to the Invoicing Service API
1
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 customer’s 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:
12May 2012Invoicing Service API Guide
Introduction to the Invoicing Service API
Sending Invoices on Behalf of a Merchant
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.
1
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
API OperationDescription
CreateInvoiceCreates a new invoice.
SendInvoiceSends an invoice to a customer.
CreateAndSendInvoiceCreates and sends an invoice, which is equivalent to the combination
of the CreateInvoice operation followed by the SendInvoice
operation.
Managing Invoices
API OperationDescription
UpdateInvoiceUpdates an invoice.
GetInvoiceDetailsObtains the contents of an invoice.
CancelInvoiceCancels an invoice.
SearchInvoicesSearches for invoices based on specified criteria.
MarkInvoiceAsPaidMarks an invoice as having been paid.
Invoicing Service API GuideMay 201213
Introduction to the Invoicing Service API
1
IPN Variables for Invoicing API Operations
API OperationDescription
MarkInvoiceAsUnpaidMarks an invoice as unpaid.
MarkInvoiceAsRefundedMarks an invoice as having been refunded.
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: Eligib le
address_status: confirmed
payer_id: ABF644D44GSPJ
address_street: 5656 South Mar ket Street
payment_date: 15:57:39 Sep 12, 2011 PDT
payment_status: Completed
invoice_id: INV2-VMYW-LQKA-QBGC-6 YDE
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-business1@pa ypal.com
address_country: United States
address_city: San Jose
verify_sign: AFcWxV21C7fd0v3bY YYRCpSSRl31A23x28h wIQCThw2nNi2s8MlV2o10
payer_email: jbui-us-personal1 @paypal.com
txn_id: 68H067535A2789915
payment_type: instant
last_name: Ronald
address_state: CA
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-busine ss1@paypal.com
verify_sign: AiPC9BjkCyDFQXbSk oZcgqH3hpacAAV9zVN I.GLTI1sLOHpeeWp3oMQZ
invoice_id: INV2-UHWN-STXM-65B7-P T4R
ipn_track_id: 2eKZJ-cZftAHzSWbsS7 qjQ
Introduction to the Invoicing Service API
IPN Variables for Invoicing API Operations
1
Invoicing Service API GuideMay 201215
Introduction to the Invoicing Service API
1
IPN Variables for Invoicing API Operations
16May 2012Invoicing Service API Guide
Invoicing Service API Examples
2
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:
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 GuideMay 201217
Invoicing Service API Examples
2
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-SUBJECTThird-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-FORM AT 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
HeaderDescription
X-PAYPAL-REQUEST-DATA-FORMATThe payload format for the request.
Allowable values are:
NV – Name-value pairs
XML – Extensible markup language
JSO N – JavaScript object notation
X-PAYPAL-RESPONSE-DATA-FORMATThe payload format for the response.
Allowable values are:
NV – Name-value pairs
XML – Extensible markup language
JSO N – JavaScript object notation
18May 2012Invoicing Service API Guide
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:
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: Y our_API_username"
-H "X-PAYPAL-SECURITY-PASSWORD : Y our_API_password"
-H "X-PAYPAL-SECURITY-SIGNATUR E: Y our_API_signature"
This example shows how to send an invoice using UpdateInvoice. If the invoice has not
been sent, the invoice continues to be a draft; otherwise, the invoice is resent.
NOTE: When updating an invoice, in addition to the updated fields, you must also provide all
of the original fields used to create the invoice.
curl -s --insecure
-H "X-PAYPAL-SECURITY-USERID: Y our_API_username"
-H "X-PAYPAL-SECURITY-PASSWORD : Y our_API_password"
-H "X-PAYPAL-SECURITY-SIGNATUR E: Y our_API_signature"
-H "X-PAYPAL-REQUEST-DATA-FORM AT: NV"
-H "X-PAYPAL-RESPONSE-DATA-FOR MAT: NV"
-H "X-PAYPAL-APPLICATION-ID: Your_AppID"
https://sandbox.svcs.paypal.co m/Invoice/UpdateInvoi ce
This example shows how to create and send an invoice using CreateAndSendInvoi ce. You
must have created the original invoice either for yourself or on behalf of another merchant.
PayPal can return a maximum of 100 invoices per page. In this example, only the first 10
invoices that you created using the Invoicing Service API for the jb-us-
seller1@paypal.com account are returned:
curl -s --insecure
-H "X-PAYPAL-SECURITY-USERID: Y our_API_username"
-H "X-PAYPAL-SECURITY-PASSWORD : Y our_API_password"
-H "X-PAYPAL-SECURITY-SIGNATUR E: Y our_API_signature"
Use the CreateInvoice API operation to create a new invoice. The call includes merchant,
payer, and API caller information, in addition to invoice detail. The response to the call
contains an invoice ID and URL.
CreateInvoiceRequest Message
Use the CreateInvoiceRequest message to create a new invoice. The merchant issuing the
invoice, and the partner, if any, making the call, must have a PayPal account in good standing.
Invoicing Service API GuideMay 201225
CreateInvoice API Operation
3
CreateInvoiceRequest Message
26May 2012Invoicing Service API Guide
CreateInvoice API Operation
CreateInvoiceRequest Message
3
Invoicing Service API GuideMay 201227
CreateInvoice API Operation
3
CreateInvoiceRequest Message
RequestEnvelope Fields
FieldDescription
detailLevelcommon:DetailLevel Code
(Optional) Level of detail required by the client application for components. It
is one of the following values:
Re turnAll – This value provides the maximum level of detail (default).
errorLanguagexs:string
(Required) RFC 3066 language in which error messages are returned; by
default it is en_US, which is the only language currently supported.
CreateInvoiceRequest Fields
FieldDescription
invoiceinv:InvoiceType
(Required) Merchant, payer, and invoice information.
requestEnvelopecommon:requestEnve lope
(Required) Information common to each API operation, such as the language
in which an error message is returned.
InvoiceType Fields
FieldDescription
merchantEmailxs:string
(Required) Merchant email address.
payerEmailxs:string
(Required) Payer email address.
numberxs:string
(Optional) Unique identifier for the invoice.
merchantInfoinv:BusinessInfoTy pe
Company contact information of the merchant company sending the invoi ce.
itemListinv:InvoiceItemListType
(Required) List of items included in this invoice.
currencyCodexs:string
(Required) Currency used for all invoice item amounts and totals.
invoiceDatexs:dateTime
(Optional) Date on which the invoice is enabled.
28May 2012Invoicing Service API Guide
FieldDescription
dueDatexs:dateTime
(Optional) Date on which the invoice payment is due.
paymentTermsinv:PaymentTermsTy pe
(Required) Terms by which the invoice payment is due. It is one of the
following values:
Du eOnReceipt – Payment is due when the payer receives the invoice.
Du eOnDateSpecified – Payment is due on the date specified in the
invoice.
Ne t10 – Payment is due 10 days from the invoice date.
Ne t15 – Payment is due 15 days from the invoice date.
Ne t30 – Payment is due 30 days from the invoice date.
Ne t45 – Payment is due 45 days from the invoice date.
discountPercentxs:decimal
(Optional) Discount percent applied to the invoice.
discountAmountxs:decimal
(Optional) Discount amount applied to the invoice, if any. If
discountPercent is provided, discountAmoun t is ignored.
CreateInvoice API Operation
CreateInvoiceRequest Message
3
termsxs:string
(Optional) General terms for the invoice.
notexs:string
(Optional) Note to the payer company.
merchantMemoxs:string
(Optional) Memo for bookkeeping that is private to the merchant.
billingInfoinv:BusinessInfoTy pe
(Optional) Billing information for the payer.
shippingInfoinv:BusinessInfoTy pe
(Optional) Shipping information for the payer.
shippingAmountxs:decimal
(Optional) Cost of shipping.
shippingTaxNamexs:string
(Optional) Name of the applicable tax on shipping cost.
shippingTaxRatexs:decimal
(Optional) Rate of the applicable tax on shipping cost.
logoURLxs:string
(Optional) Complete URL to an external image used as the logo, if any.
ReferrerCodexs:string
(Optional) Build Notification (BN) code for tracking transactions with a
particular partner..
Invoicing Service API GuideMay 201229
CreateInvoice API Operation
3
CreateInvoiceRequest Message
FieldDescription
customAmountLabelxs:string
customAmountValuexs:decimal
BusinessInfoType Fields
FieldDescription
firstNamexs:string
lastNamexs:string
Label used to display custom amount value. If a value is entered for
customAmountLabel, then customAmountValu e cannot be empty.
Value of custom amount.If a value is entered for customAmountValue, then
customAmountLabel cannot be empty.
(Optional) First name of the company contact.
(Optional) Last name of the company contact.
businessNamexs:string
(Optional) Company business name.
phonexs:string
(Optional) Phone number for contacting the company.
faxxs:string
(Optional) Fax number used by the company.
websitexs:string
(Optional) Website us ed by the company.
customValuexs:string
(Optional) Custom value to be displayed in the contact information details..
addresscommon:BaseAddress
(Optional) Street address of the company.
BaseAddress Fields
FieldDescription
cityxs:string
(Required) City of the address.
countryCodexs:string
(Required) Country code of the address.
30May 2012Invoicing Service API Guide
Loading...
+ 92 hidden pages
You need points to download manuals.
1 point = 1 manual.
You can buy points or you can get point for every manual you upload.