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:

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

The sequence is shown in the following illustration:

Invoicing on behalf of a merchant

Make your first call

1. 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 endpoint is for a name-and-value pair in the sandbox. For other endpoints see API Endpoints.

2. 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 app ID
   -H "X-PAYPAL-APPLICATION-ID: APP-5XV204960S3290106"

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

   {
       "requestEnvelope": {
           "errorLanguage": "en_US"
       },
       "invoice": {
           "merchantEmail": "jerry1619-facilitator@example.com",
           "payerEmail": "sender_1335455648_per@example.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 date and time stamp, 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"
   }
   

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

Try it

To try this, replace the properties in the brackets "< >" in the following cURL command with your own developer data:

Note: The following cURL command only works on UNIX. To run this command on Windows, use the second command 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@example.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@example.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:

1. Set up a sandbox environment to make test calls with the Invoicing APIs. See Apps 101.
2. Substitute your sandbox credentials in the previous example and reissue the command to ensure that you have correctly set up your sandbox user accounts. If the request succeeds, modify the inputs to the command to test the different Invoicing API functionality.
3. See How to Send an Invoice Using the Invoicing Service.
4. See How to Get Invoice Details Using the Invoicing Service.
5. The Invoicing API Developer Guide introduces the API, and the Invoicing API reference describes the Invoicing API operations and their input parameters.