Invoicing Service API Guide Last updated: May 2012
Invoicing Service API Guide Document Number: 10128.en_US-201205 © 2011-2012 PayPal, Inc. All rights reserved. PayPal is a registered trademark of PayPal, Inc. The PayPal logo is a trademark of PayPal, Inc. Other trademarks and brands are the property of their respective owners. The information in this document belongs to PayPal, Inc. It may not be used, reproduced or disclosed without the written approval of PayPal, Inc. Copyright © PayPal. All rights reserved. PayPal S.à r.l. et Cie, S.C.A.
Contents Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Chapter 1 Introduction to the Invoicing Service API . . . . . . . . . . 11 Sending Invoices on Behalf of a Merchant. . . . . . . . . . . . . . . . . . . . . . . . . . 13 Invoicing Service API Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Creating and Sending Invoices . . . . . . . . . . . . . . .
Contents BaseAddress Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 InvoiceItemListType Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 InvoiceItemType Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 CreateInvoiceResponse Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 ResponseEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 CreateInvoiceResponse Fields . . . . . .
Contents FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 ResponseEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 CreateAndSendInvoice API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Chapter 6 UpdateInvoice API Operation . . . . . . . . . . . . . . . . 55 UpdateInvoiceRequest Message . . . . . . . . . . . . .
Contents GetInvoiceDetails API Errors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 Chapter 8 CancelInvoice API Operation . . . . . . . . . . . . . . . . 81 CancelInvoiceRequest Message. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 RequestEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81 CancelInvoiceRequest Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82 CancelInvoiceResponse Message . . . . . . . . . . . .
Contents ResponseEnvelope Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99 MarkInvoiceAsPaidResponse Fields . . . . . . . . . . . . . . . . . . . . . . . . . .100 PPFault Message . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100 FaultMessage Fields. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101 ErrorData Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101 ResponseEnvelope Fields . . . . . . . . .
Contents 8 May 2012 Invoicing Service API Guide
Preface You can use the Invoicing Service API to create, send, and manage invoices using PayPal. Documentation Feedback Help us improve this guide by sending feedback to: documentationfeedback@paypal.
Documentation Feedback 10 May 2012 Invoicing Service API Guide
1 Introduction to the Invoicing Service API PayPal enables you to create and manage invoices. When you send an invoice, PayPal emails the receipient 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: 1. Specify the contents of the invoice in the CreateInvoice request and send the request to the https://svcs.paypal.
1 Introduction to the Invoicing Service API 5. If the SendInvoice request was successful, PayPal sends an invoice by email to the payer whose 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 then pay on PayPal. The contents of an invoice depend on what you specify in the CreateInvoice, or CreateAndSend requests.
Introduction to the Invoicing Service API Sending Invoices on Behalf of a Merchant 1 Sending Invoices on Behalf of a Merchant You can send invoices on behalf of a merchant if you have permission to do so.
1 Introduction to the Invoicing Service API IPN Variables for Invoicing API Operations API Operation Description MarkInvoiceAsUnpaid Marks an invoice as unpaid. MarkInvoiceAsRefunded Marks an invoice as having been refunded. IPN Variables for Invoicing API Operations PayPal sends IPN messages for invoice payments and canceled invoices. For more information about IPN, see the Instant Payment Notification Guide: https://cms.paypal.com/cms_content/US/en_US/files/developer/IPNGuide.pdf.
Introduction to the Invoicing Service API IPN Variables for Invoicing API Operations 1 receiver_email: jbui-us-business1@paypal.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 Canceled Invoices merchant_business_name: Fruits Packaging Inc. merchant_first_name: Joan notify_version: 3.
1 16 Introduction to the Invoicing Service API IPN Variables for Invoicing API Operations May 2012 Invoicing Service API Guide
2 Invoicing Service API Examples You can use the Invoicing Service API to create, send, update, cancel, or obtain details of invoices for yourself or third-party merchants. You can also search invoices, and mark them as paid, unpaid, or refunded. HTTP Headers Each request message includes HTTP headers specifying authentication, the application ID, the device ID or IP address, and the payload format or protocol (SOAP).
2 Invoicing Service API Examples HTTP Headers HTTP Headers for Authentication Header Description X-PAYPAL-SECURITY-USERID Your API username X-PAYPAL-SECURITY-PASSWORD Your API password X-PAYPAL-SECURITY-SIGNATURE Your API signature, which is required only if you use 3token authorization; a certificate does not use a signature X-PAYPAL-SECURITY-SUBJECT Third-party permission specification, which specifies the email address or phone number (for mobile) of the party on whose behalf you are calling t
Invoicing Service API Examples HTTP Headers 2 SOAP Messages To use Adaptive Payments with SOAP, include the HTTP headers for authentication as described in the section Authentication and the application ID as described in the next section. In addition, include the X-PAYPAL-MESSAGE-PROTOCOL header with a SOAP11 value. The following is a header example for an Adaptive Payments API call for a SOAP message: headers.put("X-PAYPAL-SECURITY-USERID", "tok261_biz_api.abc.com"); headers.
2 Invoicing Service API Examples Creating an Invoice Creating an Invoice This example shows how to create an invoice using CreateInvoice. curl -s --insecure -H "X-PAYPAL-SECURITY-USERID: Your_API_username" -H "X-PAYPAL-SECURITY-PASSWORD: Your_API_password" -H "X-PAYPAL-SECURITY-SIGNATURE: Your_API_signature" -H "X-PAYPAL-REQUEST-DATA-FORMAT: NV" -H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV" -H "X-PAYPAL-APPLICATION-ID: Your_AppID" https://svcs.sandbox.paypal.com/Invoice/CreateInvoice -d "requestEnvelope.
Invoicing Service API Examples Creating and Sending an Invoice 2 Creating and Sending an Invoice This example shows how to create and send an invoice using CreateAndSendInvoice. It is equivalent to creating an invoice and sending it.
2 Invoicing Service API Examples Obtaining Invoice Details &invoice.payerEmail=jbui-us-business2%40paypal.com &invoice.currencyCode=USD &invoice.itemList.item(0).name=Banana+Leaf+--+001 &invoice.itemList.item(0).description=Banana+Leaf &invoice.itemList.item(0).quantity=3 &invoice.itemList.item(0).unitPrice=1 &invoice.itemList.item(0).taxName=Tax1 &invoice.itemList.item(0).taxRate=10.25 &invoice.paymentTerms=Net10 &invoice.logoUrl=https%3A%2F%2Fwww.example.com%2FYour_logo.
Invoicing Service API Examples Searching for Invoices 2 curl -s --insecure -H "X-PAYPAL-SECURITY-USERID: Your_API_username" -H "X-PAYPAL-SECURITY-PASSWORD: Your_API_password" -H "X-PAYPAL-SECURITY-SIGNATURE: Your_API_signature" -H "X-PAYPAL-REQUEST-DA TA-FORMAT: NV" -H "X-PAYPAL-RESPONSE-DATA-FORMAT: NV" -H "X-PAYPAL-APPLICATION-ID: Your_AppID" https://sandbox.svcs.paypal.com/Invoice/CancelInvoice -d "requestEnvelope.
2 24 Invoicing Service API Examples Searching for Invoices May 2012 Invoicing Service API Guide
3 CreateInvoice API Operation Use the CreateInvoice API operation to create a new invoice. The call includes merchant, payer, and API caller information, in addition to invoice detail. The response to the call contains an invoice ID and URL. CreateInvoiceRequest Message Use the CreateInvoiceRequest message to create a new invoice. The merchant issuing the invoice, and the partner, if any, making the call, must have a PayPal account in good standing.
3 26 CreateInvoice API Operation CreateInvoiceRequest Message May 2012 Invoicing Service API Guide
CreateInvoice API Operation CreateInvoiceRequest Message Invoicing Service API Guide May 2012 3 27
3 CreateInvoice API Operation CreateInvoiceRequest Message RequestEnvelope Fields Field Description detailLevel common:DetailLevelCode (Optional) Level of detail required by the client application for components. It is one of the following values: ReturnAll – This value provides the maximum level of detail (default). errorLanguage xs:string (Required) RFC 3066 language in which error messages are returned; by default it is en_US, which is the only language currently supported.
CreateInvoice API Operation CreateInvoiceRequest Message Field Description dueDate xs:dateTime (Optional) Date on which the invoice payment is due. paymentTerms inv:PaymentTermsType (Required) Terms by which the invoice payment is due. It is one of the following values: DueOnReceipt – Payment is due when the payer receives the invoice. DueOnDateSpecified – Payment is due on the date specified in the invoice. Net10 – Payment is due 10 days from the invoice date.
3 CreateInvoice API Operation CreateInvoiceRequest Message Field Description customAmountLabel xs:string Label used to display custom amount value. If a value is entered for customAmountLabel, then customAmountValue cannot be empty. customAmountValue xs:decimal Value of custom amount.If a value is entered for customAmountValue, then customAmountLabel cannot be empty. BusinessInfoType Fields Field Description firstName xs:string (Optional) First name of the company contact.
CreateInvoice API Operation CreateInvoiceRequest Message Field Description line1 xs:string (Required) First line of the address. line2 xs:string (Optional) Second line of the street address. postalCode xs:string (Optional) Postal code of the address. state xs:string (Optional) State for the address. type xs:string (Optional) Type of address. 3 InvoiceItemListType Fields Field Description item inv:InvoiceItemType (Required) Invoice item.
3 CreateInvoice API Operation CreateInvoiceResponse Message CreateInvoiceResponse Message The CreateInvoiceResponse message contains information returned in response to a CreateInvoiceRequest message. The response contains an invoice ID and the URL to the invoice on the PayPal system. ResponseEnvelope Fields Field Description ack common:AckCode Acknowledgement code. It is one of the following values: Success – The operation completed successfully. Failure – The operation failed.
CreateInvoice API Operation PPFault Message 3 CreateInvoiceResponse Fields Field Description responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status. invoiceId xs:string ID of the created invoice. invoiceNumber xs:string Invoice number of the created invoice. invoiceURL xs:string URL location where merchants view the invoice details. totalAmount xs:long The total amount of the invoice.
3 CreateInvoice API Operation PPFault Message FaultMessage Fields Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status. ErrorData Fields 34 Field Description category common:ErrorCategory The location where the error occurred.
CreateInvoice API Operation PPFault Message Field Description severity common:ErrorSeverity The severity of the error encountered. Possible values are: Error – Processing of the request was interrupted Warning – Processing of the request was completed subdomain This field is not used. 3 ResponseEnvelope Fields Field Description ack common:AckCode Acknowledgement code. It is one of the following values: Success – The operation completed successfully. Failure – The operation failed.
3 CreateInvoice API Operation CreateInvoice API Errors CreateInvoice API Errors 36 Code Message Additional Information 520002 Internal error. 520005 Authentication failed. API credentials are incorrect. 520009 Account is restricted. 570045 The number of items exceeds this allowed limit. 570046 The due date occurs before the invoice date. 570047 The invoice date is earlier than todays date.
4 SendInvoice API Operation Use the SendInvoice API operation to send an invoice to a payer, and notify the payer of the pending invoice. SendInvoiceRequest Message Use the SendInvoiceRequest message to send an invoice to a payer, and notify the payer of the pending invoice. RequestEnvelope Fields Field Description detailLevel common:DetailLevelCode (Optional) Level of detail required by the client application for components.
4 SendInvoice API Operation SendInvoiceResponse Message SendInvoiceRequest Fields The table below lists the fields for the SendInvoiceRequest message. Field Description requestEnvelope common:requestEnvelope (Required) Information common to each API operation, such as the language in which an error message is returned. invoiceID xs:string (Required) ID of the invoice to send.
SendInvoice API Operation SendInvoiceResponse Message Field Description correlationId xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. N O TE : timestamp 4 You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.
4 SendInvoice API Operation PPFault Message PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs. FaultMessage Fields 40 Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status.
SendInvoice API Operation PPFault Message 4 ErrorData Fields Field Description category common:ErrorCategory The location where the error occurred. Possible values are: System – The system encountered errors; try again Application – The application encountered errors; try again Request – The request was incorrect domain xs:string The domain to which this service belongs. errorId xs:long A 6-digit number that uniquely identifies a particular error. exceptionID This field is not used.
4 SendInvoice API Operation Send Invoice API Errors Field Description correlationId xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. N O TE : timestamp You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.
5 CreateAndSendInvoice API Operation Use the CreateAndSendInvoice API operation to create and send an invoice. CreateAndSendInvoiceRequest Message Use the CreateAndSendInvoiceRequest message to create and send a new invoice. The requester should authenticate the caller and verify that the merchant requesting the invoice has an existing PayPal account in good standing. Once the invoice is created, PayPal sends it to the specified payer, who is notified of the pending invoice.
5 44 CreateAndSendInvoice API Operation CreateAndSendInvoiceRequest Message May 2012 Invoicing Service API Guide
CreateAndSendInvoice API Operation CreateAndSendInvoiceRequest Message Invoicing Service API Guide May 2012 5 45
5 CreateAndSendInvoice API Operation CreateAndSendInvoiceRequest Message RequestEnvelope Fields Field Description detailLevel common:DetailLevelCode (Optional) Level of detail required by the client application for components. It is one of the following values: ReturnAll – This value provides the maximum level of detail (default). errorLanguage xs:string (Required) RFC 3066 language in which error messages are returned; by default it is en_US, which is the only language currently supported.
CreateAndSendInvoice API Operation CreateAndSendInvoiceRequest Message Field Description dueDate xs:dateTime (Optional) Date on which the invoice payment is due. paymentTerms inv:PaymentTermsType (Required) Terms by which the invoice payment is due. It is one of the following values: DueOnReceipt – Payment is due when the payer receives the invoice. DueOnDateSpecified – Payment is due on the date specified in the invoice. Net10 – Payment is due 10 days from the invoice date.
5 CreateAndSendInvoice API Operation CreateAndSendInvoiceRequest Message Field Description customAmountLabel xs:string Label used to display custom amount value. If a value is entered for customAmountLabel, then customAmountValue cannot be empty. customAmountValue xs:decimal Value of custom amount.If a value is entered for customAmountValue, then customAmountLabel cannot be empty. BusinessInfoType Fields Field Description firstName xs:string (Optional) First name of the company contact.
CreateAndSendInvoice API Operation CreateAndSendInvoiceRequest Message Field Description line1 xs:string (Required) First line of the address. line2 xs:string (Optional) Second line of the street address. postalCode xs:string (Optional) Postal code of the address. state xs:string (Optional) State for the address. type xs:string (Optional) Type of address. 5 InvoiceItemListType Fields Field Description item inv:InvoiceItemType (Required) Invoice item.
5 CreateAndSendInvoice API Operation CreateAndSendInvoiceResponse Message CreateAndSendInvoiceResponse Message The CreateAndSendInvoiceResponse message contains information returned in response to a CreateAndSendInvoiceRequest message. The response contains an invoice ID and the URL to the invoice on the PayPal system, and indicates whether the invoice was sent successfully. ResponseEnvelope Fields Field Description ack common:AckCode Acknowledgement code.
CreateAndSendInvoice API Operation PPFault Message 5 CreateAndSendInvoiceResponse Fields Field Description responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status. invoiceID xs:string ID of the created invoice. invoiceNumber xs:string Number of the created invoice. invoiceURL xs:string URL location where merchants view the invoice details. totalAmount xs:long The total amount of the invoice.
5 CreateAndSendInvoice API Operation PPFault Message FaultMessage Fields Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status. ErrorData Fields 52 Field Description category common:ErrorCategory The location where the error occurred.
CreateAndSendInvoice API Operation CreateAndSendInvoice API Errors Field Description severity common:ErrorSeverity The severity of the error encountered. Possible values are: Error – Processing of the request was interrupted Warning – Processing of the request was completed subdomain This field is not used. 5 ResponseEnvelope Fields Field Description ack common:AckCode Acknowledgement code. It is one of the following values: Success – The operation completed successfully.
5 54 CreateAndSendInvoice API Operation CreateAndSendInvoice API Errors Code Message Additional Information 520005 Authentication failed. API credentials are incorrect. 520009 Account is restricted. 570045 The number of items exceeds this allowed limit. 570046 The due date occurs before the invoice date. 570047 The invoice date is earlier than todays date.
6 UpdateInvoice API Operation Use the UpdateInvoice API operation to update an invoice. UpdateInvoiceRequest Message Use the UpdateInvoiceRequest message to update an invoice.
6 56 UpdateInvoice API Operation UpdateInvoiceRequest Message May 2012 Invoicing Service API Guide
UpdateInvoice API Operation UpdateInvoiceRequest Message Invoicing Service API Guide May 2012 6 57
6 UpdateInvoice API Operation UpdateInvoiceRequest Message RequestEnvelope Fields Field Description detailLevel common:DetailLevelCode (Optional) Level of detail required by the client application for components. It is one of the following values: ReturnAll – This value provides the maximum level of detail (default). errorLanguage xs:string (Required) RFC 3066 language in which error messages are returned; by default it is en_US, which is the only language currently supported.
UpdateInvoice API Operation UpdateInvoiceRequest Message Field Description invoiceDate xs:dateTime (Optional) Date on which the invoice is enabled. dueDate xs:dateTime (Optional) Date on which the invoice payment is due. paymentTerms inv:PaymentTermsType (Required) Terms by which the invoice payment is due. It is one of the following values: DueOnReceipt – Payment is due when the payer receives the invoice. DueOnDateSpecified – Payment is due on the date specified in the invoice.
6 UpdateInvoice API Operation UpdateInvoiceRequest Message Field Description ReferrerCode xs:string (Optional) Build Notification (BN) code for tracking transactions with a particular partner.. customAmountLabel xs:string Label used to display custom amount value. If a value is entered for customAmountLabel, then customAmountValue cannot be empty. customAmountValue xs:decimal Value of custom amount.If a value is entered for customAmountValue, then customAmountLabel cannot be empty.
UpdateInvoice API Operation UpdateInvoiceResponse Message 6 InvoiceItemType Fields Field Description name xs:string (Required) SKU or name of the item. Character length and limitations: 30 characters maximum description xs:string, (Optional) Item description. date xs:dateTime (Optional) Date on which the product or service was provided. quantity xs:decimal (Required) Item count. Valid values are 0 to 10.000.
6 UpdateInvoice API Operation UpdateInvoiceResponse Message ResponseEnvelope Fields Field Description ack common:AckCode Acknowledgement code. It is one of the following values: Success – The operation completed successfully. Failure – The operation failed. SuccessWithWarning – The operation completed successfully; however, there is a warning message. FailureWithWarning – The operation failed with a warning message. build xs:string Build number.
UpdateInvoice API Operation PPFault Message 6 PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs. FaultMessage Fields Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status.
6 UpdateInvoice API Operation PPFault Message ErrorData Fields Field Description category common:ErrorCategory The location where the error occurred. Possible values are: System – The system encountered errors; try again Application – The application encountered errors; try again Request – The request was incorrect domain xs:string The domain to which this service belongs. errorId xs:long A 6-digit number that uniquely identifies a particular error. exceptionID This field is not used.
UpdateInvoice API Operation UpdateInvoice API Errors Field Description correlationId xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. N O TE : timestamp 6 You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.
6 66 UpdateInvoice API Operation UpdateInvoice API Errors Code Message Additional Information 570058 Invalid token. 570059 Invoice number is too long. 570060 The status of the invoice is such that it can no longer be updated. 580022 This error code corresponds to validation error messages that deal with errors of supplied parameters. 580046 An invoice already exists for the merchant with this invoice number. 580047 Invoice does not exist.
7 GetInvoiceDetails API Operation Use the GetInvoiceDetails API operation to get detailed information about an invoice. GetInvoiceDetailsRequest Message Use the GetInvoiceDetailsRequest message to get detailed information about an invoice. RequestEnvelope Fields Field Description detailLevel common:DetailLevelCode (Optional) Level of detail required by the client application for components. It is one of the following values: ReturnAll – This value provides the maximum level of detail (default).
7 GetInvoiceDetails API Operation GetInvoiceDetailsResponse Message GetInvoiceDetailsRequest Fields Field Description invoiceID xs:string (Required) ID of the invoice to retrieve. requestEnvelope common:requestEnvelope (Required) Information common to each API operation, such as the language in which an error message is returned.
GetInvoiceDetails API Operation GetInvoiceDetailsResponse Message Invoicing Service API Guide May 2012 7 69
7 70 GetInvoiceDetails API Operation GetInvoiceDetailsResponse Message May 2012 Invoicing Service API Guide
GetInvoiceDetails API Operation GetInvoiceDetailsResponse Message 7 ResponseEnvelope Fields Field Description ack common:AckCode Acknowledgement code. It is one of the following values: Success – The operation completed successfully. Failure – The operation failed. SuccessWithWarning – The operation completed successfully; however, there is a warning message. FailureWithWarning – The operation failed with a warning message. build xs:string Build number.
7 GetInvoiceDetails API Operation GetInvoiceDetailsResponse Message Field Description timestamp xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.774-07:00 N O TE : You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues.
GetInvoiceDetails API Operation GetInvoiceDetailsResponse Message Field Description itemList inv:InvoiceItemListType List of items included in this invoice. currencyCode xs:string Currency used for all invoice item amounts and totals. invoiceDate xs:dateTime Date on which the invoice is enabled. dueDate xs:dateTime Date on which the invoice payment is due. paymentTerms inv:PaymentTermsType Terms by which the invoice payment is due.
7 GetInvoiceDetails API Operation GetInvoiceDetailsResponse Message Field Description shippingTaxRate xs:decimal Rate of the applicable tax on shipping cost. logoURL xs:string External image URL of the invoice logo, if any. referrerCode xs:string Build Notification (BN) code for tracking transactions with a particular partner. InvoiceDetailsType Fields 74 Field Description status inv:StatusType Status of the invoice.
GetInvoiceDetails API Operation GetInvoiceDetailsResponse Message Field Description lastSentDate xs:dateTime Date when the invoice was last sent. lastSentBy xs:string Account that last sent the invoice. paidDate xs:dateTime Date when the invoice was paid, if paid. 7 PaymentDetailsType Fields Field Description viaPayPal xs:boolean Returns True if the invoice was paid by PayPal. paypalPayment inv:PayPalPaymentDetailsType PayPal payment details about the invoice.
7 GetInvoiceDetails API Operation PPFault Message OtherPaymentDetailsType Fields Field Description method inv:PaymentMethodsType (Optional) Method that can be used to mark an invoice as paid when the payer pays offline. It is one of the following values: BankTransfer – Payment is made by a bank transfer. Cash – Payment is made in cash. Check – Payment is made by check. CreditCard – Payment is made by a credit card. DebitCard – Payment is made by a debit card.
GetInvoiceDetails API Operation PPFault Message 7 FaultMessage Fields Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status. ErrorData Fields Field Description category common:ErrorCategory The location where the error occurred.
7 GetInvoiceDetails API Operation GetInvoiceDetails API Errors Field Description severity common:ErrorSeverity The severity of the error encountered. Possible values are: Error – Processing of the request was interrupted Warning – Processing of the request was completed subdomain This field is not used. ResponseEnvelope Fields Field Description ack common:AckCode Acknowledgement code. It is one of the following values: Success – The operation completed successfully.
GetInvoiceDetails API Operation GetInvoiceDetails API Errors Code Message 520005 Authentication failed. API credentials are incorrect. 520009 Account is restricted. 550026 Partner did not create the invoice but attempted to access or modify it; a merchant’s invoice can be accessed or modified only by the partner who created it. 550027 Merchant cannot access or modify an invoice they did not create; an invoice can only be accessed or modified by the party who created it. 570058 Invalid token.
7 80 GetInvoiceDetails API Operation GetInvoiceDetails API Errors May 2012 Invoicing Service API Guide
8 CancelInvoice API Operation Use the CancelInvoice API operation to cancel an invoice. CancelInvoiceRequest Message Use the CancelInvoiceRequest message to cancel an invoice. RequestEnvelope Fields Field Description detailLevel common:DetailLevelCode (Optional) Level of detail required by the client application for components. It is one of the following values: ReturnAll – This value provides the maximum level of detail (default).
8 CancelInvoice API Operation CancelInvoiceResponse Message CancelInvoiceRequest Fields Field Description requestEnvelope common:requestEnvelope (Required) Information common to each API operation, such as the language in which an error message is returned. invoiceID xs:string (Optional) ID of the invoice. subject xs:string (Optional) Subject of the cancelation notification. noteForPayer xs:string (Optional) Note to send payer within the cancelation notification.
CancelInvoice API Operation CancelInvoiceResponse Message 8 ResponseEnvelope Fields Field Description ack common:AckCode Acknowledgement code. It is one of the following values: Success – The operation completed successfully. Failure – The operation failed. SuccessWithWarning – The operation completed successfully; however, there is a warning message. FailureWithWarning – The operation failed with a warning message. build xs:string Build number.
8 CancelInvoice API Operation PPFault Message PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs. FaultMessage Fields 84 Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status.
CancelInvoice API Operation PPFault Message 8 ErrorData Fields Field Description category common:ErrorCategory The location where the error occurred. Possible values are: System – The system encountered errors; try again Application – The application encountered errors; try again Request – The request was incorrect domain xs:string The domain to which this service belongs. errorId xs:long A 6-digit number that uniquely identifies a particular error. exceptionID This field is not used.
8 CancelInvoice API Operation CancelInvoice API Errors Field Description correlationId xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. N O TE : timestamp You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.
9 SearchInvoices API Operation Use the SearchInvoice API operation to search an invoice. SearchInvoicesRequest Message Use the SearchInvoiceRequest message to search an invoice.
9 SearchInvoices API Operation SearchInvoicesRequest Message RequestEnvelope Fields Field Description detailLevel common:DetailLevelCode (Optional) Level of detail required by the client application for components. It is one of the following values: ReturnAll – This value provides the maximum level of detail (default). errorLanguage xs:string (Required) RFC 3066 language in which error messages are returned; by default it is en_US, which is the only language currently supported.
SearchInvoices API Operation SearchInvoicesRequest Message Field Description page xs:integer (Required) Page number of result set, starting with 1. pageSize xs:integer (Required) Number of results per page, between 1 and 100. 9 SearchParametersType Fields Field Description email xs:string (Optional) Email search string. recipientName xs:string (Optional) Recipient search string. businessName xs:string (Optional) Company search string.
9 SearchInvoices API Operation SearchInvoicesResponse Message Field Description invoiceDate inv:dateRangeType (Optional) Invoice date range filter. dueDate inv:dateRangeType (Optional) Invoice due date range filter. paymentDate inv:dateRangeType (Optional) Invoice payment date range filter. creationDate inv:dateRangeType (Optional) Invoice creation date range filter. DateRangeType Fields Field Description startDate xs:dateTime (Optional) Start of the date range.
SearchInvoices API Operation SearchInvoicesResponse Message 9 ResponseEnvelope Fields Field Description ack common:AckCode Acknowledgement code. It is one of the following values: Success – The operation completed successfully. Failure – The operation failed. SuccessWithWarning – The operation completed successfully; however, there is a warning message. FailureWithWarning – The operation failed with a warning message. build xs:string Build number.
9 SearchInvoices API Operation SearchInvoicesResponse Message Field Description correlationId xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. N O TE : timestamp You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.
SearchInvoices API Operation SearchInvoicesResponse Message 9 InvoiceSummaryType Fields Field Description invoiceID xs:string ID of the invoice. merchantEmail xs:string Merchant email address. payerEmail xs:string Payer email address. number xs:string Unique identifier for the invoice. billingBusinessName xs:string Company contact information of the merchant company sending the invoice. billingFirstName xs:string First name of the business information.
9 SearchInvoices API Operation PPFault Message PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs. FaultMessage Fields 94 Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status.
SearchInvoices API Operation PPFault Message 9 ErrorData Fields Field Description category common:ErrorCategory The location where the error occurred. Possible values are: System – The system encountered errors; try again Application – The application encountered errors; try again Request – The request was incorrect domain xs:string The domain to which this service belongs. errorId xs:long A 6-digit number that uniquely identifies a particular error. exceptionID This field is not used.
9 SearchInvoices API Operation SearchInvoices API Errors Field Description correlationId xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. N O TE : timestamp You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues. xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.
10 MarkInvoiceAsPaid API Operation Use the MarkInvoiceAsPaid API operation to mark an invoice as paid. MarkInvoiceAsPaidRequest Message Use the MarkInvoiceAsPaidRequest message to mark an invoice as paid. RequestEnvelope Fields Field Description detailLevel common:DetailLevelCode (Optional) Level of detail required by the client application for components. It is one of the following values: ReturnAll – This value provides the maximum level of detail (default).
10 MarkInvoiceAsPaid API Operation MarkInvoiceAsPaidRequest Message Field Description errorLanguage xs:string (Required) RFC 3066 language in which error messages are returned; by default it is en_US, which is the only language currently supported. MarkInvoiceAsPaidRequest Fields Field Description invoiceID xs:string (Required) ID of the invoice to mark as paid. payment inv:OtherPaymentDetailsType (Required) Details of the payment made against this type.
MarkInvoiceAsPaid API Operation MarkInvoiceAsPaidResponse Message 10 MarkInvoiceAsPaidResponse Message The MarkInvoiceAsPaidResponse message marks an invoice as paid. ResponseEnvelope Fields Field Description ack common:AckCode Acknowledgement code. It is one of the following values: Success – The operation completed successfully. Failure – The operation failed. SuccessWithWarning – The operation completed successfully; however, there is a warning message.
10 MarkInvoiceAsPaid API Operation PPFault Message MarkInvoiceAsPaidResponse Fields Field Description responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status. invoiceID xs:string ID of the invoice marked as paid. invoiceNumber xs:string Number of the invoice marked as paid. invoiceURL xs:string URL location where merchants view the invoice details.
MarkInvoiceAsPaid API Operation PPFault Message 10 FaultMessage Fields Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status. ErrorData Fields Field Description category common:ErrorCategory The location where the error occurred.
10 MarkInvoiceAsPaid API Operation MarkInvoiceAsPaid API Errors Field Description severity common:ErrorSeverity The severity of the error encountered. Possible values are: Error – Processing of the request was interrupted Warning – Processing of the request was completed subdomain This field is not used. ResponseEnvelope Fields Field Description ack common:AckCode Acknowledgement code. It is one of the following values: Success – The operation completed successfully.
MarkInvoiceAsPaid API Operation MarkInvoiceAsPaid API Errors Code Message 520005 Authentication failed. API credentials are incorrect. 520009 Account is restricted. 550026 Partner did not create the invoice but attempted to access or modify it; a merchant’s invoice can be accessed or modified only by the partner who created it. 550027 Merchant cannot access or modify an invoice they did not create; an invoice can only be accessed or modified by the party who created it. 570058 Invalid token.
10 104 MarkInvoiceAsPaid API Operation MarkInvoiceAsPaid API Errors May 2012 Invoicing Service API Guide
11 MarkInvoiceAsUnpaid API Operation Use the MarkInvoiceAsUnpaid API operation to mark an invoice as unpaid. MarkInvoiceAsUnpaidRequest Message Use the MarkInvoiceAsUnpaidRequest message to mark an invoice as unpaid. RequestEnvelope Fields Field Description detailLevel common:DetailLevelCode (Optional) Level of detail required by the client application for components. It is one of the following values: ReturnAll – This value provides the maximum level of detail (default).
11 MarkInvoiceAsUnpaid API Operation MarkInvoiceAsUnpaidResponse Message MarkInvoiceAsUnpaidRequest Fields Field Description invoiceID xs:string (Required) ID of the invoice to mark as unpaid. requestEnvelope common:requestEnvelope (Required) Information common to each API operation, such as the language in which an error message is returned. MarkInvoiceAsUnpaidResponse Message The MarkInvoiceAsUnpaidResponse message marks an invoice as unpaid.
MarkInvoiceAsUnpaid API Operation MarkInvoiceAsUnpaidResponse Message Field Description timestamp xs:datetime Date on which the response was sent, for example: 2012-04-02T22:33:35.774-07:00 N O TE : 11 You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues.
11 MarkInvoiceAsUnpaid API Operation PPFault Message PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs. FaultMessage Fields 108 Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status.
MarkInvoiceAsUnpaid API Operation PPFault Message 11 ErrorData Fields Field Description category common:ErrorCategory The location where the error occurred. Possible values are: System – The system encountered errors; try again Application – The application encountered errors; try again Request – The request was incorrect domain xs:string The domain to which this service belongs. errorId xs:long A 6-digit number that uniquely identifies a particular error.
11 MarkInvoiceAsUnpaid API Operation MarkInvoiceAsUnpaid API Errors Field Description correlationId xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. N O TE : timestamp You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues.
12 MarkInvoiceAsRefunded API Operation Use the MarkInvoiceAsRefunded API operation to mark an invoice as refunded. This API operation can only be used for full refunds. MarkInvoiceAsRefundedRequest Message Use the MarkInvoiceAsRefundedRequest message to mark an invoice as refunded. RequestEnvelope Fields Field Description detailLevel common:DetailLevelCode (Optional) Level of detail required by the client application for components.
12 MarkInvoiceAsRefunded API Operation MarkInvoiceAsRefundedResponse Message Field Description requestEnvelope common:requestEnvelope (Required) Information common to each API operation, such as the language in which an error message is returned. OtherRefundDetailsType Fields Field Description note xs:string (Optional) Optional note associated with the refund. date xs:dateTime (Required) Date when the invoice was marked as refunded.
MarkInvoiceAsRefunded API Operation MarkInvoiceAsRefundedResponse Message Field Description correlationId xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. N O TE : timestamp 12 You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues.
12 MarkInvoiceAsRefunded API Operation PPFault Message PPFault Message The PPFaultMessage returns ErrorData and the ResponseEnvelope information to your application if an error occurs. FaultMessage Fields 114 Field Description error common:ErrorData Detailed error information. responseEnvelope common:ResponseEnvelope Common response information, including a timestamp and the response acknowledgement status.
MarkInvoiceAsRefunded API Operation PPFault Message 12 ErrorData Fields Field Description category common:ErrorCategory The location where the error occurred. Possible values are: System – The system encountered errors; try again Application – The application encountered errors; try again Request – The request was incorrect domain xs:string The domain to which this service belongs. errorId xs:long A 6-digit number that uniquely identifies a particular error.
12 MarkInvoiceAsRefunded API Operation MarkInvoiceAsRefunded API Errors Field Description correlationId xs:string Correlation identifier. It is a 13-character, alphanumeric string (for example, db87c705a910e) that is used only by PayPal Merchant Technical Support. N O TE : timestamp You must log and store this data for every response you receive. PayPal Technical Support uses the information to assist with reported issues.
Revision History The revision history identifies changes to the PayPal Invoicing Service documentation at a high level. Date Description 05/22/2012 Added two new APIs: MarkInvoiceAsUnpaid, MarkInvoiceAsRefunded. 01/24/2012 Clarified use of and examples for image URL. 09/19/2011 Initial release draft.
May 2012 Invoicing Service API Guide
Index A D ack response field 32, 35, 38, 41, 50, 53, 62, 64, 71, 78, 83, 85, 91, 95, 99, 102, 106, 109, 112, 115 address request field 30, 48, 60 date request field 31, 49, 61, 76, 98, 112 description request field 31, 49, 61 detailLevel request field 28, 37, 46, 58, 67, 81, 88, 97, 105, 111 discountAmount response field 73 discountPercent response field 73 discouontAmount request field 29, 47, 59 discouontPercent request field 29, 47, 59 domain field 34, 41, 52, 64, 77, 85, 95, 101, 109, 115 dueDate re
Index I N invoice request field 58 invoice response field 72, 92 invoiceDate request field 28, 46, 59, 90 invoiceDate response field 73, 93 invoiceDetails response field 72 invoiceID request field 38, 58, 68, 82, 98, 106, 111 invoiceID response field 33, 39, 51, 62, 83, 93, 100, 107, 113 invoiceList response field 92 invoiceNumber request field 89 invoiceNumber response field 33, 51, 62, 83, 100, 107, 113 InvoiceType 28, 46 invoiceURL response field 33, 39, 51, 62, 72, 83, 100, 107, 113 item request fiel
Index responseEnvelope PPFault field 34, 40, 52, 63, 77, 84, 94, 101, 108, 114 responseEnvelope response field 33, 39, 51, 62, 72, 83, 92, 100, 107, 113 ResponseEnvelope response fields 32, 35, 38, 41, 50, 53, 62, 64, 71, 78, 83, 85, 91, 95, 99, 102, 106, 109, 112, 115 V viaPayPal response field 75 W website request field 30, 48, 60 S sendCopyToMerchant request field 82 severity field 35, 41, 53, 64, 78, 85, 95, 102, 109, 115 shippingAmount request field 29, 47, 59 shippingAmount response field 73 shipp
Index 122 May 2012 Invoicing Service API Guide
