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
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:
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 endpoint is for a name-and-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 app 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@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:
Property | Description |
---|---|
your PayPal developer user ID | Your facilitator user name from your sandbox account. To locate this:
The user ID looks like |
your PayPal dev user PW | The password for the user name. The password looks like TX7N9PSNWV3MYQTA . |
your PayPal security signature | The security signature that is tied to your sandbox account. The security signature looks like AbtI7HV1xB428VygBUcIhARzxch4AL65.T18CLaylixNNxDZUu0iO87b . |
your merchant account email address | The facilitator email address. The email address looks like myemail-facilitator@myemail.com . |
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:
- Set up a sandbox environment to make test calls with the Invoicing APIs. See Apps 101.
- 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.
- 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.