Supported formats

APIDeprecated


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 example shows the 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 use a certificate, it is processed by user name and password and not by signature. To manage API certificates, see Create and Manage 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.

Specify 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");

The following WSDL shows 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>

Specify 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.
ReferencePayPal.comPrivacyCookiesSupportLegalContact