Invoicing API Examples

Important: The NVP/SOAP integration method for Invoicing is Deprecated. For new integrations, see the REST Invoicing Overview.

You can use the Invoicing 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.

The Invoicing API supports the JSON, NVP, XML, and SOAP formats.

You can specify different formats for the request and response, e.g. you can send a request in JSON and receive the response in XML.

In the case of the SOAP format, you must include a SOAP protocol header (see the SOAP messages section, below).

The following is an example of HTTP headers for the NVP format, in Java:

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 manage API certificates, see Creating and Managing NVP/SOAP API Credentials.

To specify API credentials, include the following HTTP headers in your request message (observing case sensitivity):

Table 1. 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 by a key, must be owned by the subject granting the third-party permission.

Specifying the JSON, NVP, or XML Data Format

Use the HTTP header X-PAYPAL-REQUEST-DATA-FORMAT to specify the data format the request body. You can send messages in the JSON, NVP or XML format (for SOAP, see the next section). Use the X-PAYPAL-RESPONSE-DATA-FORMAT header to specify the data format for the response.

Table 2. 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 the Invoicing API 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 Invoicing 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 Invoicing API WSDL.

<wsdl:service name="Invoice">
<wsdl:port name="InvoiceSOAP11_http" binding="services:InvoiceSOAP11Binding">
<soap:address location="https://svcs.paypal.com/Invoice"/>
/wsdl:port
/wsdl:service

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:

Table 3. HTTP Headers for Application and Device identification
Header Description
X-PAYPAL-APPLICATION-ID (Required) Your application's identification, which is issued by PayPal.
Note: For the application ID (app ID) for the sandbox, see PayPal Sandbox Testing Guide.
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.

Creating an Invoice

This example creates an invoice using CreateInvoice.

curl https://svcs.sandbox.paypal.com/Invoice/CreateInvoice \
  -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"  \
  -d requestEnvelope.errorLanguage=en_US \
  -d invoice.merchantEmail=merchant%40domain.com \
  -d invoice.payerEmail=jbui-us-business2%40paypal.com \
  -d invoice.currencyCode=USD \
  -d invoice.itemList.item(0).name=Banana+Leaf+--+001 \
  -d invoice.itemList.item(0).description=Banana+Leaf \
  -d invoice.itemList.item(0).quantity=1 \
  -d invoice.itemList.item(0).unitPrice=1 \
  -d invoice.itemList.item(0).taxName=Tax1 \
  -d invoice.itemList.item(0).taxRate=10.25 \
  -d invoice.paymentTerms=Net10 \
  -d 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 https://svcs.sandbox.paypal.com/Invoice/SendInvoice \
  -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"  \
  -d requestEnvelope.errorLanguage=en_US \
  -d invoiceID=INV2-RVY9-UWTW-64HZ-BR9W

Creating and Sending an Invoice

This example creates and sends an invoice using CreateAndSendInvoice.

curl https://svcs.sandbox.paypal.com/Invoice/CreateAndSendInvoice \
  -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"  \
  -d requestEnvelope.errorLanguage=en_US \
  -d invoice.merchantEmail=merchant%40domain.com \
  -d invoice.payerEmail=jbui-us-business2%40paypal.com \
  -d invoice.currencyCode=USD \
  -d invoice.itemList.item(0).name=Banana+Leaf+--+001 \
  -d invoice.itemList.item(0).description=Banana+Leaf \
  -d invoice.itemList.item(0).quantity=1 \
  -d invoice.itemList.item(0).unitPrice=1 \
  -d invoice.itemList.item(0).taxName=Tax1 \
  -d invoice.itemList.item(0).taxRate=10.25 \
  -d invoice.paymentTerms=Net10 \
  -d invoice.logoUrl=https%3A%2F%2Fwww.example.com%2FYour_logo.jpg

Updating an Invoice

This example sends an invoice using UpdateInvoice. If the invoice was not previously sent, it continues to be a draft. If the invoice was previously sent, it 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 https://sandbox.svcs.paypal.com/Invoice/UpdateInvoice \
  -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"  \
  -d requestEnvelope.errorLanguage=en_US \
  -d invoice.merchantEmail=merchant%40domain.com \
  -d invoice.payerEmail=jbui-us-business2%40paypal.com \
  -d invoice.currencyCode=USD \
  -d invoice.itemList.item(0).name=Banana+Leaf+--+001 \
  -d invoice.itemList.item(0).description=Banana+Leaf \
  -d invoice.itemList.item(0).quantity=3 \
  -d invoice.itemList.item(0).unitPrice=1 \
  -d invoice.itemList.item(0).taxName=Tax1 \
  -d invoice.itemList.item(0).taxRate=10.25 \
  -d invoice.paymentTerms=Net10 \
  -d invoice.logoUrl=https%3A%2F%2Fwww.example.com%2FYour_logo.jpg

Obtaining Invoice Details

This example gets information about an invoice using GetInvoiceDetails.

curl https://svcs.sandbox.paypal.com/Invoice/GetInvoiceDetails \
  -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"  \
  -d requestEnvelope.detailLevel=ReturnAll \
  -d requestEnvelope.errorLanguage=en_US \
  -d invoiceID=INV2-RVY9-UWTW-64HZ-BR9W

Canceling an Invoice

This example cancels an invoice using CancelInvoice. PayPal can notifiy the payer that the invoice has been canceled.

curl https://sandbox.svcs.paypal.com/Invoice/CancelInvoice \
  -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-DA TA-FORMAT: NV" \
  -H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV" \
  -H "X-PAYPAL-APPLICATION-ID: Your_AppID"  \
  -d requestEnvelope.errorLanguage=en_US \
  -d invoiceID=INV2-RVY9-UWTW-64HZ-BR9W" \
  -d subject=Cancel+it \
  -d noteForPayer=Cancel+it+now \
  -d sendCopyToMerchant=true

Searching for Invoices

This example searches for invoices using SearchInvoices. 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 https://svcs.sandbox.paypal.com/Invoice/SearchInvoices \
  -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"  \
  -d requestEnvelope.errorLanguage=en_US \
  -d merchantEmail=jb-us-seller1%40paypal.com \
  -d parameters.origin=API \
  -d parameters.email=jb-us-seller1%40paypal.com \
  -d page=1 \
  -d pageSize=10

Sending a Reminder that a Payment Is Due

This example uses RemindInvoice to request that a reminder be sent to a customer. The merchant intends to send the reminder for an existing invoice. The existing invoice already has been sent to the customer, but the customer hasn't paid the invoice yet:

curl https://svcs.sandbox.paypal.com/Invoice/RemindInvoice \
  -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"  \
  -d requestEnvelope.errorLanguage=en_US \
  -d invoiceID=INV2-RVY9-UWTW-64HZ-BR9W \
  -d subject=Reminder \
  -d noteForPayer=Please+pay+this+invoice