How to Send an Invoice Using the Invoicing Service

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

This guide describes how to send an e-mail invoice to a customer using the Invoicing Service CreateAndSendInvoice operation. The call returns an invoiceID value that you can use to reference the newly created invoice in related Invoicing Service calls.

A PayPal invoice contains a Pay With PayPal button in the e-mail, which lets customers pay using their PayPal accounts.

1. Set up the HTTP headers and the endpoint

Set up the call authentication in the headers:

# CreateAndSendInvoice HTTP headers (-H)

-H "X-PAYPAL-SECURITY-USERID: <caller_UID>"            # UserID from the Caller account
-H "X-PAYPAL-SECURITY-PASSWORD: <caller_PSWD>"         # Password from the Caller account
-H "X-PAYPAL-SECURITY-SIGNATURE: <caller_Sig>"         # Signature from the Caller account
-H "X-PAYPAL-REQUEST-DATA-FORMAT: JSON"
-H "X-PAYPAL-RESPONSE-DATA-FORMAT: JSON"
-H "X-PAYPAL-APPLICATION-ID: APP-80W284485P519543T"  # Sandbox AppID

# Endpoint (Sandbox in the example)
https://svcs.sandbox.paypal.com/Invoice/<strong>CreateAndSendInvoice</strong>

2. Set up the call payload

Detail the items to be included on the invoice by listing all the relevant costs and fees for each individual invoice item.

The following JSON snippet shows the payload for an invoice that contains two items. This code demonstrates the minimal set of payload fields required for a CreateAndSendInvoice request:

# ** Payload **
{
  "requestEnvelope": {
    "errorLanguage": "en_US"                # Language of returned errors
  },
  "invoice": {
    "merchantEmail": "caller@example.com",  # Receiver/Merchant e-ddress
    "payerEmail": "sender@example.com",     # Sender/Buyer e-dress
    "currencyCode": "USD",                  # Payment Currency code
    "paymentTerms": "DueOnReceipt",
    "itemList": {
      "item":[{
        "name": "BananaPlant",
        "quantity": "1",
        "unitPrice": "12"
      },
      {                                     # start second invoice item
        "name": "PeachTree",
        "quantity": "2",
        "unitPrice": "14"
      }]
    }
  }
}

3. Send the request

Here is a complete example formatted in cURL notation. Add your API credentials, the e-mail address of the buyer and receiver, and remove the line breaks to run the example on a command line.

curl https://svcs.sandbox.paypal.com/Invoice/CreateAndSendInvoice \
  -s \
  --insecure \
  -H "X-PAYPAL-SECURITY-USERID: callerUID" \
  -H "X-PAYPAL-SECURITY-PASSWORD: callerPswd" \
  -H "X-PAYPAL-SECURITY-SIGNATURE: callerSig" \
  -H "X-PAYPAL-REQUEST-DATA-FORMAT: JSON" \
  -H "X-PAYPAL-RESPONSE-DATA-FORMAT: JSON" \
  -H "X-PAYPAL-APPLICATION-ID: appID" \
  -d '{
        "requestEnvelope": {
          "errorLanguage": "en_US"
        },
        "invoice": {
          "merchantEmail": "receiverEdress",
          "payerEmail": "senderEdress",
          "currencyCode": "USD",
          "paymentTerms": "DueOnReceipt",
          "itemList": {
            "item": [{
              "name": "BananaPlant",
              "quantity": "1",
              "unitPrice": "38.95"
            }, {
              "name": "PeachTree",
              "quantity": "2",
              "unitPrice": "14.95"
            }]
          }
        }
      }'

If successful, the call response will be similar to the following:

{
  "responseEnvelope": {
    "ack": "Success",
    // ...
  },
  "invoiceID": "idNumber",
  "invoiceNumber": "1192",
  "invoiceURL": "PP-invoiceURL",
  "totalAmount":"4000"
}

Note: Use the returned invoiceID value to refer to this invoice in other Invoice Service calls.

Learn more

For more information about the Invoicing service, see the following resources:

Note: For instructions on using the PayPal APIs, how to use the Sandbox for testing, and how to move your app into production, see Apps 101.