How to Send an Invoice on Behalf of a Third-Party Merchant

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 API request on behalf of a third party.

If you're coding an invoicing application that allows you to generate invoices for third-party merchants, you'll need to make API calls on behalf of the merchants whose invoices you're creating.

Making calls on behalf of others requires that you first obtain the needed permission credentials. For details, see How to Request Third-Party Permissions Using the Permissions Service.

1. Set Up the Third-Party Authorization Credentials

To make any API call on behalf of a third-party, add the following two HTTP headers to the normal headers of the call you are making:

  • X-PAYPAL-AUTHORIZATION: The authorization string that is generated using the permission credentials returned by the Permissions Service.
  • X-PAYPAL-SECURITY-SUBJECT: The e-mail address of the PayPal account for which you (the API caller) are making the API calls.

Here's the complete set of HTTP headers that you'll need to send an invoice:

# 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

# Third-party Auth headers
-H "X-PAYPAL-SECURITY-SUBJECT: receiverEdress"  # Merchant's PayPal e-mail
-H "X-PAYPAL-AUTHENTICATION: OAuthSig"          # Generated OAuth Signature

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

2. Set Up the Payload

Include the appropriate e-mail address in the merchantEmail parameter. This parameter identifies the Business account of the third-party merchant, and is different from the account whose credentials are used to make the call:

{
  "requestEnvelope": {
    "errorLanguage":"en_US"               # Language of returned errors
  },
  "invoice": {
    "merchantEmail":"receiver@example.com",  # Receiver/Merchant e-ddress
    "payerEmail":"sender@example.com",    # Sender/Buyer e-dress
    "currencyCode":"USD",
    "paymentTerms":"DueOnReceipt",
    "itemList": {
      "item":[{
        "name":"BananaPlant",
        "quantity":"1",
        "unitPrice":"38.95"
      },
      {
        "name":"PeachTree",
        "quantity":"2",
        "unitPrice":"14.95"
      }]
    }
  }
}

3. Send the Request

Here's the complete example formatted in cURL notation that's wrapped for readability. 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" \
  -H "X-PAYPAL-SECURITY-SUBJECT: receiverEdress" \
  -H "X-PAYPAL-AUTHENTICATION: OAuthSig" \
  -d '{
        "requestEnvelope": {
          "errorLanguage": "en_US"
        },
        "invoice": {
          "merchantEmail": "receiverEdress",
          "payerEmail": "buyerEdress",
          "currencyCode": "USD",
          "paymentTerms": "DueOnReceipt",
          "itemList": {
            "item": [{
              "name": "BananaPlant",
              "quantity": "1",
              "unitPrice": "38.95"
            }, {
              "name": "PeachTree",
              "quantity": "2",
              "unitPrice": "14.95"
            }]
          }
        }
      }'

If successful, the response will resemble the following:

{
  "responseEnvelope": {
    "ack": "Success",
    # ...
  },
  "invoiceID": "INV2-Z3PV-QKHY-YL45",
  "invoiceNumber": "0001",
  "invoiceURL": "https://www.sandbox.paypal.com/us/cgi-bin/?cmd=_inv-details&id=INV2-Z3PV-QKHY-YL45",
  "totalAmount": "6885"
}

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

4. Getting Details for a Third-Party Invoice

This step shows how to get the details for the third-party invoice you created in the previous example by using GetInvoiceDetails.

Because the invoice belongs to the third-party merchant, you must use the two third-party authentication headers to make the request:

  • X-PAYPAL-SECURITY-SUBJECT
  • X-PAYPAL-AUTHENTICATION

As in the first third-party call, the X-PAYPAL-AUTHENTICATION value is generated using the current time, proper endpoint, and permission credentials.

# GetInvoiceDetails HTTP headers (-H)
## cURL + Endpoint (Sandbox in the example)
curl https://svcs.sandbox.paypal.com/Invoice/GetInvoiceDetails \
  -s \
  --insecure \
  ## Standard GetInvoiceDetails header values \
  -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 \
  ## Third-party Auth headers \
  -H "X-PAYPAL-SECURITY-SUBJECT: e-mailOfReceiver"       # Merchants PayPal e-mail \
  -H "X-PAYPAL-AUTHENTICATION: OAuthSig"                 # GeneratedSig \
  ## Payload \
  -d '{
        "requestEnvelope":{
          "errorLanguage":"en_US",
          "detailLevel":"ReturnAll"
        },
        "invoiceID":"invoiceId"
      }

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.

Feedback