Invoicing API Introduction
Important: The NVP/SOAP integration method for Invoicing is Deprecated. For new integrations, see the REST Invoicing Overview.
PayPal enables you to create and manage invoices. When you send an invoice, PayPal emails the recipient and allows him or her to pay with PayPal.
The following diagram shows the basic execution flow for creating and sending an invoice:
The circled numbers indicate actions that you take as well as actions taken by PayPal and your customer:
Specify the contents of the invoice in the
CreateInvoicerequest and send the request to the
Examine the response and verify that the
Using the invoice ID in the response, create a
SendInvoicerequest and send it to the
Examine the response and verify that the
Note: You can combine the creation and transmission of an invoice in the same request, which is
CreateAndSend. After you create the request, send it to the
SendInvoicerequest was successful, PayPal sends an invoice by email to the payer whose email you specified in the
When your customer clicks Pay Invoice in the email, the customer's browser is redirected to PayPal and the customer is prompted to log in.
The customer can then pay on PayPal.
The contents of an invoice depend on what you specify in the
CreateAndSend requests. Following is an example invoice:
Sending Invoices on Behalf of a Merchant
You can send invoices on behalf of a merchant if you have permission to do so. There is no difference in how you set up your request for
CreateAndSendInvoice, except that you specify the merchant's email address instead of your own in the request, and you include an additional header that indicates you have the permission of the third party to send invoices on their behalf.
The merchant grants you permission using their PayPal profile, or you request permission using the Permissions Service API. For more information about this API, see PayPal Permissions Service at PayPal Permissions Service.
Invoicing API Operations
Use the Invoicing API to create and send invoices to your customers.
Note: You must have a valid app ID to use the Invoicing Service API. If you have an existing app ID, you can reuse it. For more information, see Create and Manage NVP/SOAP API Credentials.
Create and Send Invoices
|CreateInvoice||Creates a new invoice.|
|SendInvoice||Sends an invoice to a customer.|
|CreateAndSendInvoice||Creates and sends an invoice, which is equivalent to the combination of the
|GenerateInvoiceNumber||Retrieves an invoice number for use in creating a new invoice.|
|CancelInvoice||Cancels an invoice.|
|DeleteInvoice||Deletes an invoice that is in the draft state.|
|GetInvoiceDetails||Obtains the contents of an invoice.|
|MarkInvoiceAsPaid||Marks an invoice as having been paid.|
|MarkInvoiceAsUnpaid||Marks an invoice as unpaid.|
|MarkInvoiceAsRefunded||Marks an invoice as having been refunded.|
|RemindInvoice||Searches for invoices based on specified criteria.|
|SearchInvoices||Searches for invoices based on specified criteria.|
|UpdateInvoice||Updates an invoice.|
IPN Variables for Invoicing API Operations
PayPal sends IPN messages for invoice payments and for invoices cancelled by the buyer. For more information about IPN, see the Instant Payment Notification Guide.
mc_gross: 37.12 protection_eligibility: Eligible address_status: confirmed payer_id: ABF644D44GSPJ address_street: 5656 South Market Street payment_date: 15:57:39 Sep 12, 2011 PDT payment_status: Completed invoice_id: INV2-VMYW-LQKA-QBGC-6YDE charset: windows-1252 address_zip: 95131 first_name: Nick mc_fee: 1.38 address_country_code: US address_name: Selling Fruits notify_version: 3.4 payer_status: verified business: email@example.com address_country: United States address_city: San Jose verify_sign: AFcWxV21C7fd0v3bYYYRCpSSRl31A23x28hwIQCThw2nNi2s8MlV2o10 payer_email: firstname.lastname@example.org txn_id: 68H067535A2789915 payment_type: instant last_name: Ronald address_state: CA receiver_email: email@example.com payment_fee: 1.38 receiver_id: 9N3VVZS28ELHL txn_type: invoice_payment mc_currency: USD residence_country: US transaction_subject: Send the Reminder Soon. invoice_number: 0151 payment_gross: 37.12 ipn_track_id: ogo4fwr-n.J7dGNgDiJzqg
merchant_business_name: Fruits Packaging Inc. merchant_first_name: Joan notify_version: 3.4 txn_type: invoice_payer_cancel invoice_number: 0021 charset: windows-1252 payer_email: firstname.lastname@example.org payer_last_name: Bond merchant_last_name: Joan payer_first_name: Henry merchant_email: email@example.com verify_sign: AiPC9BjkCyDFQXbSkoZcgqH3hpacAAV9zVNI.GLTI1sLOHpeeWp3oMQZ invoice_id: INV2-UHWN-STXM-65B7-PT4R ipn_track_id: 2eKZJ-cZftAHzSWbsS7qjQ