Getting Started with the Invoicing Service API

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

Get up and running with the Invoicing API:

Overview
Key concepts
Make your first call
Next steps

Overview

Merchants, developers, and business service providers can use the Invoicing APIs for electronic invoices.

Invoicing APIs can be used to:

Dynamically create, send, and manage invoices
Track, record, and reconcile payments

For the API calls available, see the Invoicing API reference.

Key concepts

To use the Invoicing API to request payment, you start by making one of the Invoicing API calls to PayPal. Your customer receives the invoice via email and clicks on an included link to view the invoice on PayPal's website. Customers who have a PayPal account can log into their PayPal accounts to pay the invoice. Customers can also pay using a check, debit, or credit card.

You can deliver invoices to customers using either a combination of the CreateInvoice and SendInvoice API calls, or using a single CreateAndSendInvoice call. CreateInvoice includes merchant, payer, and API caller information, in addition to invoice detail. The response to the call contains an invoice ID and URL. SendInvoice sends an invoice to a payer, and notifies the payer of the pending invoice. The call includes an invoice ID and the payer's email address.

When you successfully use the CreateAndSendInvoice call on behalf of a merchant, the following flow ensues:

Your integrated application calls CreateAndSendInvoice API on behalf of a merchant.
The API call is received at PayPal.
PayPal builds an invoice.
PayPal sends the invoice to the consumer.
The customer receives the invoice.
The customer clicks the Pay button and logs into their PayPal account.
The merchant clicks the Invoice # to see the invoice details.
The client finishes paying by clicking Pay Now.
You log into you own PayPal account to view invoices and status.

The sequence is shown in the following illustration:

Implementing Mobile Checkout

Invoicing on behalf of a merchant

Make your first call

Obtain the endpoint for the service and environment you're addressing.

The Sandbox endpoint for the Invoicing CreateInvoice operation is:
```
https://svcs.sandbox.paypal.com/Invoice/CreateInvoice
```
This is the endpoint for a name/value pair in the Sandbox; for other endpoints see API Endpoints.

Format the HTTP headers needed to make the call.

// Sandbox API credentials for the API Caller account -H "X-PAYPAL-SECURITY-USERID: Sandbox-Caller-User-Id" -H "X-PAYPAL-SECURITY-PASSWORD: Sandbox-Caller-Password" -H "X-PAYPAL-SECURITY-SIGNATURE: Sandbox-Caller-Security-Signature"

// Global Sandbox Application ID -H "X-PAYPAL-APPLICATION-ID: APP-5XV204960S3290106"

The CreateInvoice operation requires several payload input fields, shown here as a JSON object:

{
  "requestEnvelope": {
    "errorLanguage": "en_US"
  },
  "invoice": {
    "merchantEmail": "jerry1619-facilitator@hotmail.com",
    "payerEmail": "sender_1335455648_per@yourdomain.com",
    "currencyCode": "USD",
    "paymentTerms": "Net15",
    "itemList": {
      "item": [
        {
          "name": "Banana+Leaf+--+001",
          "description": "Banana+Leaf",
          "quantity": "1",
          "unitPrice": "1",
          "taxName": "Tax1",
          "taxRate": "10.25"
        }
      ]
    }
  }
}

The response contains a timestamp, status, invoice ID, and invoice URL:

{
  "responseEnvelope": {
    "timestamp": "2011-06-16T:12:30.861-07:00",
    "ack": "Success",
    "correlationId": "78733df04b1f0",
    "build": "1942837"
  },
  "invoiceID": "INV2-C4AK-UU3J-5SCL-9KZY",
  "invoiceNumber": "1192",
  "invoiceURL": "invoiceURL"
}

Congratulations! You have created and sent an invoice using the Invoicing API.

Try it

To try this, in the cURL command listed below, you need to replace the four properties in the brackets "< >" with your own developer data, as described below:

Property	Description
`your PayPal developer user ID`	This is your facilitator Username from your sandbox account. To locate this: Log in to https://developer.paypal.com with your test account email address and password. Go to the Dashboard from the menu on the top. Select Accounts from the menu on the left under Sandbox. On the Sandbox Test Accounts page, expand the item in the table that shows the facilitator email address (something like myemal-facilitator@myemail.com). To verify that, click the Profile link. That will display the Account details dialog. From that dialog, go to the API Credentials tab. There you will see the Username, Password and Signature. The user ID looks something like this: myemail-facilitator_apl1.myemail.com.
`your PayPal dev user PW`	This is the password for the Username described above. How to retrieve this Password is also described in the item above. The password looks something like: TX7N9PSNWV3MYQTA.
`your PayPal security signature`	This is the security signature that is tied to your sandbox account. How to retrieve the signature is also described in the first item listed in this table. The security signature looks something like this: AbtI7HV1xB428VygBUcIhARzxch4AL65.T18CLaylixNNxDZUu0iO87b.
`your merchant account email address`	This is the facilitator email address that is listed on Step 3 of the procedure listed in the first item of this table. The email address looks something like this: myemal-facilitator@myemail.com.

Note: The following cURL command only works on UNIX. To run this on Windows, use the second command listed, where the quotes are escaped with /" in all places.

UNIX

curl https://svcs.sandbox.paypal.com/Invoice/CreateInvoice \
  -s \
  --insecure \
  -H "X-PAYPAL-SECURITY-USERID: your PayPal developer user ID" \
  -H "X-PAYPAL-SECURITY-PASSWORD: your PayPal dev user password" \
  -H "X-PAYPAL-SECURITY-SIGNATURE: your PayPal security signature" \
  -H "X-PAYPAL-REQUEST-DATA-FORMAT: JSON" \
  -H "X-PAYPAL-RESPONSE-DATA-FORMAT: JSON" \
  -H "X-PAYPAL-APPLICATION-ID:APP-80W284485P519543T" \
  -d '{
        "requestEnvelope": {
          "errorLanguage": "en_US"
        },
        "invoice": {
          "merchantEmail": "your merchant account email address",
          "payerEmail": "sender_1335455648_per@yourdomain.com",
          "currencyCode": "USD",
          "paymentTerms": "Net15",
          "itemList": {
            "item": [{
              "name": "Banana+Leaf+--+001",
              "description": "Banana+Leaf",
              "quantity": "1",
              "unitPrice": "1",
              "taxName": "Tax1",
              "taxRate": "10.25"
            }]
          }
        }
      }’

Windows

curl https://svcs.sandbox.paypal.com/Invoice/CreateAndSendInvoice \
  -s \
  --insecure \
  -H "X-PAYPAL-SECURITY-USERID: your PayPal developer user ID" \
  -H "X-PAYPAL-SECURITY-PASSWORD: your PayPal dev user password" \
  -H "X-PAYPAL-SECURITY-SIGNATURE: your PayPal security signature" \
  -H "X-PAYPAL-REQUEST-DATA-FORMAT: JSON" \
  -H "X-PAYPAL-RESPONSE-DATA-FORMAT: JSON" \
  -H "X-PAYPAL-APPLICATION-ID:APP-80W284485P519543T" \
  -d '{
        "requestEnvelope": {
          "errorLanguage": "en_US"
        },
        "invoice": {
          "merchantEmail": "your merchant account email address",
          "payerEmail": "sender_1335455648_per@yourdomain.com",
          "currencyCode": "USD",
          "paymentTerms": "DueOnReceipt",
          "itemList": {
            "item": [{
              "name": "BananaPlant",
              "quantity": "1",
              "unitPrice": "38.95"
            }, {
              "name": "PeachTee",
              "quantity": "2",
              "unitPrice": "14.95"
            }]
          }
        }
      }'

Next steps

To learn more about the Invoicing API:

Set up a sandbox environment so you can make test calls with the Invoicing APIs. See Apps 101 for more information.
Substitute your own Sandbox credentials in the above cURL command, then reissue the command to see that you have correctly set up your Sandbox users. If you get a successful response, modify the inputs to the command to test the different Invoicing API functionality.
See How to Send an Invoice Using the Invoicing Service.
See How to Get Invoice Details Using the Invoicing Service.
The Invoicing API Developer Guide introduces the API, and the Invoicing API reference describes the Invoicing API operations and their input parameters.