Invoicing API Getting Started Guide

This guide presents the following sections to get you up and running with the Invoicing API:

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:

Implementing Mobile Checkout
Invoicing on behalf of a merchant

Making 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 is the endpoint for a name/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 Application ID
    -H "X-PAYPAL-APPLICATION-ID: APP-5XV204960S3290106"
    
  3. The CreateInvoice operation requires several payload input fields, shown here as a JSON object:
    {
    "invoice": {
    "requestEnvelope.errorLanguage": "en_US", // Language used for errors
    "merchantEmail": "jb-us-seller1%40paypal.com",
    "payerEmail": "jbui-us-premier2%40paypal.com",
    "currencyCode": "USD",
    "items": {
    "name": "Banana+Leaf+--+001",
    "description": "Banana+Leaf",
    "quantity": "1",
    "unitPrice": "1",
    "taxName": "Tax1",
    "taxRate": "10.25"
    },
    "paymentTerms": "Net15"
    }
    }
    

    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!

curl -s --insecure -H "X-PAYPAL-SECURITY-USERID: caller_1312486258_biz_api1.gmail.com" -H "X-PAYPAL-SECURITY-PASSWORD: 1312486294" -H "X-PAYPAL-SECURITY-SIGNATURE: AbtI7HV1xB428VygBUcIhARzxch4AL65.T18CTeylixNNxDZUu0iO87e" -H "X-PAYPAL-REQUEST-DATA-FORMAT: JSON" -H "X-PAYPAL-RESPONSE-DATA-FORMAT: JSON" -H "X-PAYPAL-APPLICATION-ID:APP-80W284485P519543T" https://svcs.sandbox.paypal.com/Invoice/CreateAndSendInvoice -d {\"requestEnvelope\":{\"errorLanguage\":\"en_US\"},\"invoice\":{\"merchantEmail\":\"caller_1335455804_biz@x.com\",\"payerEmail\":\"sender_1335455648_per@x.com\",\"currencyCode\":\"USD\",\"paymentTerms\":\"DueOnReceipt\",\"itemList\":{\"item\":[{\"name\":\"BananaPlant\",\"quantity\":\"1\",\"unitPrice\":\"38.95\"},{\"name\":\"PeachTree\",\"quantity\":\"2\",\"unitPrice\":\"14.95\"}]}}}

Next Steps

To learn more about the Invoicing API:

  1. Set up a Sandbox test environment so you can make test calls with the Invoicing APIs. See Apps 101 for more information.
  2. 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.
  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.
  6. Look at the Invoicing service calls in the Apigee Console.