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 which actions you take, PayPal takes, and your customer takes:

  1. Specify the contents of the invoice in the CreateInvoice request and send the request to the endpoint.

  2. Examine the response and verify that the ACK field contains SUCCESS.

  3. Using the invoice ID in the response, create a SendInvoice request and send it to the endpoint.

  4. Examine the response and verify that the ACK field contains SUCCESS.

    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 endpoint.

  5. If the SendInvoice request succeeds, PayPal emails an invoice to the payer's email you specified in the CreateInvoice or CreateAndSendInvoice request.

  6. 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.

  7. The customer can pay on PayPal.

The contents of an invoice depend on what you specify in the CreateInvoice, or CreateAndSend requests. Following is an example invoice:

Send 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 CreateInvoice or 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 API. If you have an existing app ID, you can reuse it. For more information, see Create and Manage NVP/SOAP API Credentials.

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.

Invoice payments

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
address_country: United States
address_city: San Jose
verify_sign: AFcWxV21C7fd0v3bYYYRCpSSRl31A23x28hwIQCThw2nNi2s8MlV2o10
txn_id: 68H067535A2789915
payment_type: instant
last_name: Ronald
address_state: CA
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

Canceled invoices

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_last_name: Bond
merchant_last_name: Joan
payer_first_name: Henry
verify_sign: AiPC9BjkCyDFQXbSkoZcgqH3hpacAAV9zVNI.GLTI1sLOHpeeWp3oMQZ
invoice_id: INV2-UHWN-STXM-65B7-PT4R
ipn_track_id: 2eKZJ-cZftAHzSWbsS7qjQ