Vantiv. PayPal Credit Integration Guide. August XML Release: Document Version: 2.0

Transcription

1 Vantiv PayPal Credit Integration Guide August 2014 XML Release: 8.27 Document Version: 2.0

2 Vantiv PayPal Credit Integration Guide Document Version: 2.0 All information whether text or graphics, contained in this manual is confidential and proprietary information of Vantiv, LLC and is provided to you solely for the purpose of assisting you in using a Vantiv, LLC product. All such information is protected by copyright laws and international treaties. No part of this manual may be reproduced or transmitted in any form or by any means, electronic, mechanical or otherwise for any purpose without the express written permission of Vantiv, LLC. The possession, viewing, or use of the information contained in this manual does not transfer any intellectual property rights or grant a license to use this information or any software application referred to herein for any purpose other than that for which it was provided. Information in this manual is presented "as is" and neither Vantiv, LLC or any other party assumes responsibility for typographical errors, technical errors, or other inaccuracies contained in this document. This manual is subject to change without notice and does not represent a commitment on the part Vantiv, LLC or any other party. Vantiv, LLC does not warrant that the information contained herein is accurate or complete. All trademarks are the property of their respective owners and all parties herein have consented to their trademarks appearing in this manual. Any use by you of the trademarks included herein must have express written permission of the respective owner. Copyright , Vantiv, LLC - ALL RIGHTS RESERVED.

3 About This Guide CONTENTS Intended Audience...v Revision History...v Document Structure...vi Vantiv Documentation Set... vii PayPal Credit Technical Documentation... vii Typographical Conventions... viii Contact Information...ix Chapter 1 Introduction PayPal Credit Overview... 2 PayPal Credit Transaction Processing... 3 PayPal Credit on iq... 5 Testing Your PayPal Credit Transactions... 5 Getting Started with PayPal Credit... 6 Chapter 2 Structuring XML Transactions for PayPal Credit Understanding the PayPal Credit Authorization Variations... 8 PayPal Credit Data Requirements for Authorizations... 9 Using PayPal Credit Elements in LitleXML Transactions Chapter 3 PayPal Credit Transaction Examples Transaction Types and Examples About the Transaction Types Presented in this Section Authorization Transactions Authorization Request Structure Authorization Response Structure Sale Transactions Sale Request Structure Sale Response Structure Credit For Non-Vantiv Processed Transactions Credit Request Structure for Non-Vantiv Processed Transaction Credit Response Structure Chapter 4 LitleXML PayPal Credit Elements addressindicator authenticatedbymerchant authorizationsourceplatform Document Version: 2.0 XML Release: 8.27 iii

4 Contents billmelaterrequest billmelaterresponsedata bmlmerchantid bmlproducttype cardholderauthentication creditline customerinfo customeripaddress customerregistrationdate customertype customerworktelephone dob deliverytype employername incomeamount incomecurrency itemcategorycode ordersource preapprovalnumber residencestatus shippingamount ssn termsandconditions type type Element as a Child of the Parent Elements listed below virtualauthenticationkeydata virtualauthenticationkeypresenceindicator yearsatemployer yearsatresidence Appendix A PayPal Credit Response Codes Index iv Document Version: 2.0 XML Release: 8.27

5 ABOUT THIS GUIDE This guide provides information on integrating PayPal Credit (formerly Bill Me Later) into your Vantiv implementation. Intended Audience This document is intended for technical personnel who set up and maintain your payment processing system. This document assumes the following: You are planning to or are already processing with Vantiv. You already understand PayPal Credit basics, and you are able to plan and code your own merchant-level PayPal Credit requirements such as UI modifications, shopping carts, etc. Revision History This document has been revised as follows: TABLE 1 Document Revision History Doc. Version Description Location(s) 1.1 Initial version. All 1.2 Added a list of BML elements that are not currently used but are reserved for future use. 1.3 Added information about the best practices for handling BML authorization that have multiple settlements. Chapter 1 Chapter Complete revision. All 1.5 Draft Updated for LitleXML 8.0 All Document Version: XML Release: 8.27 v

6 About This Guide TABLE 1 Document Revision History (Continued) Doc. Version Description Location(s) 1.6 Updated information on supported transaction types, clarified information on BML Authorization types, updated XML Examples, added notes on certain XML elements which may be specific to BML Private Label products. 1.7 Removed namespace (xmlns) attribute from all Response examples. This hasn t been used since schema version Added information about re-using order ID numbers before an authorization has aged out. 1.9 Added information on a previously un-documented response code (401). 2.0 Re-branded the entire guide to reflect the Litle-Vantiv merger. Also re-branded Bill Me Later to PayPal Credit. Chapters 1, 2, 3, and 4 Chapter 4 Chapter 1, Chapter 3 Appendix A All Updated to LitleXML 8.27 Chapter 3 Document Structure This manual contains the following sections: Chapter 1, "Introduction" This chapter introduces PayPal Credit and describes how to get started on integrating PayPal Credit payments with your LitleXML transactions. Chapter 2, "Structuring XML Transactions for PayPal Credit" This chapter describes how to structure LitleXML Transactions when using PayPal Credit as a payment type. Chapter 3, "PayPal Credit Transaction Examples" This chapter contains examples of LitleXML transactions for PayPal Credit payments. Chapter 4, "LitleXML PayPal Credit Elements" This chapter provides definitions for LitleXML elements used in PayPal Credit transactions. vi Document Version: XML Release: 8.27

7 About This Guide Appendix A, "PayPal Credit Response Codes" This appendix provides reference material regarding the response codes returned in a LitleXML response for a PayPal Credit payment transaction. Vantiv Documentation Set The Vantiv documentation set also include the items listed below. Please refer to the appropriate guide for information concerning other Vantiv product offerings. Vantiv LitleXML Reference Guide Vantiv Chargeback API Reference Guide Vantiv Chargeback Process Guide Vantiv PayPal Integration Guide Vantiv PayFac API Reference Guide Vantiv PayFac Portal User Guide Vantiv PayPage Integration Guide Vantiv LitleXML Differences Guide Vantiv Scheduled Secure Reports Reference Guide Vantiv Chargeback XML and Support Documentation API Reference Guide (Legacy) Vantiv Virtual Terminal User Guide (Legacy) PayPal Credit Technical Documentation For the latest PayPal Credit documentation, contact your PayPal Credit Project Implementation Manager. PayPal Credit documentation includes, but is not limited to: PayPal Credit Implementation Guide (version 8.8 or later) PayPal Credit Implementation Supplement Guides PayPal Credit Certification Guide PayPal Credit Call Center Guidelines & Training Materials PayPal Credit User Guide PayPal Credit Call Center & Technical Support Procedures Guide Document Version: XML Release: 8.27 vii

8 About This Guide Typographical Conventions Table 2 describes the conventions used in this guide. TABLE 2 Convention... Typographical Conventions Meaning Vertical ellipsis points in an example mean that information not directly related to the example has been omitted.... Horizontal ellipsis points in statements or commands mean that parts of the statement or command not directly related to the example have been omitted. < > Angle brackets are used in the following situations: user-supplied values (variables) XML elements [ ] Brackets enclose optional clauses from which you can choose one or more option. bold text Italicized text blue text Bold text indicates emphasis. Italic type in text indicates a term defined in the text, the glossary, or in both locations. Blue text indicates a hypertext link. viii Document Version: XML Release: 8.27

9 About This Guide Contact Information This section provides contact information for organizations within Vantiv. Implementation - For certification and technical issues concerning your implementation of LitleXML, contact the Implementation Department. You can call your assigned Vantiv Implementation Consultant or send to the address below. Implementation Contact Information Hours Available implementation@litle.com. Monday Friday, 8:30 a.m. 5:30 p.m. EST Customer Experience Management/Customer Service - For non-technical issues, including questions concerning the user interface, help with passwords, modifying merchant details, and changes to user account permissions, contact the Customer Experience Management/Customer Service Department. Customer Experience Management/Customer Service Contact Information Telephone Hours Available customerservice@litle.com Monday Friday, 8:00 A.M. 6:30 P.M. EST Chargebacks - For questions regarding financial transactions and documentation related to chargeback cases, contact the Chargebacks Department. Chargebacks Contact Information Telephone (option 4) Hours Available chargebacks@litle.com Monday Friday, 8:30 a.m. 5:30 p.m. EST Technical Publications - For questions or comments about this document, please address your feedback to the Technical Publications Department. All comments are welcome. Technical Publications Contact Information TechPubs@litle.com Document Version: XML Release: 8.27 ix

10 About This Guide x Document Version: XML Release: 8.27

11 1 INTRODUCTION This chapter introduces PayPal Credit (formerly Bill Me Later or BML), an alternative payment method, and describes how to get started integrating PayPal Credit payments with your LitleXML transactions. This chapter contains the following sections: PayPal Credit Overview PayPal Credit Transaction Processing PayPal Credit on iq Testing Your PayPal Credit Transactions Getting Started with PayPal Credit Document Version: XML Release:

12 Introduction PayPal Credit Overview 1.1 PayPal Credit Overview PayPal Credit provides instant credit at the point of sales for your customers. It was designed to function as a fully integrated Method of Payment (MOP) and leverage industry-leading Processor and ATP infrastructures. From a payment processing perspective, PayPal Credit looks simply like another card type or MOP. You can present PayPal Credit as a MOP either over the phone or via your web site. Customers authenticate themselves using "top-of-mind" information such as the last four digits of their social security number and their date of birth, thereby eliminating the need for the customer to remember their account number. Currently, Vantiv supports PayPal Credit transactions that originate and settle in US dollars. Only one-time payments are supported (no recurring). Vantiv supports PayPal Credit transactions by means of LitleXML format only. NOTE: Initial authorizations for PayPal Credit transactions must be performed using online processing only. The following LitleXML transaction types are supported: Authorization Capture Sale Credit For additional information on the structure of LitleXML requests and responses for these transaction types, as well as XML examples, see Chapter 2, "Structuring XML Transactions for PayPal Credit" and Chapter 3, "PayPal Credit Transaction Examples". 2 Document Version: XML Release: 8.27

13 PayPal Credit Transaction Processing Introduction 1.2 PayPal Credit Transaction Processing When a customer places an order, you send an Authorization for the entire amount of the order just as you would with a credit card. PayPal Credit will either approve or decline the purchase. If the order is declined, direct your customer to a different method of payment. At the time of purchase, you should send an Authorization for the entire value of the order, including back-ordered items, as long as you reasonably expect to complete orders within 30 days. Re-Authorizations - after 30 days, and if you expect to keep an order open, PayPal Credit recommends re-authorizing for the remaining items prior to shipment. However, PayPal Credit does not automatically reject, nor apply penalty pricing to, a capture that is made in respect to a stale authorization. If you do not re-authorize and you ship after 30 days, your chargeback rights may be affected. Please see your PayPal Credit Merchant Agreement. If the billing or shipping information is changed in any way after the initial approval, the entire order must be re-authorized. NOTE: If an authorization has been approved, do not use the same order ID number for a re-authorization, unless the authorization has aged-out (after 30 days), as the authorizaiton attempt results in a duplicate transaction response. Add-Ons to the Original Authorization - in a case where a small amount needs to be added to an order (i.e. expedited shipping or accessory), an add-on can be made to the original purchase for up to $10.00 or 10% of the total order, whichever is greater. Specify the Order Number and the cumulative amount (the amount of the original order plus the new amount from the customer's add-on) from the original Authorization. The lifespan of this new Authorization is not 30 days; this new Authorization expires the same date that the original Authorization was due to expire. Back orders - you can perform either a real-time authorization once the product is available for shipment or perform a batch authorization using the Authenticated transaction variation. You must re-authorize every 30 days in the event of extended time frames for back orders. Credits - returns and credits should be handled just like credit card transactions. A merchandise credit should be issued if a PayPal Credit order is returned to a physical store location. When issuing a credit where the customer took advantage of promotional financing, the credit must be issued under the same <merchantid> (promotional financing ID) as the authorized transaction. Figure 1-1 illustrates an overview of PayPal Credit transaction processing. Document Version: XML Release:

14 Introduction PayPal Credit Transaction Processing FIGURE 1-1 PayPal Credit Transaction Processing PayPal Credit Merchant Customer 1. Checkout or Call Center Order Entry Auth Request 5. Order Fulfillment Sales and Returns Merchant Reporting and Funding Vantiv 2. Authorization Formatting 6. Sales and Returns Validation, Capture, and Formatting 8. Settlement Reconciliation Auth Response Settlement File PayPal Credit 3. Authorization Process Validation Authentication Credit Decision Response 7. Settlement Credit Bureau 4. New Customer Credit Inquiry 4 Document Version: XML Release: 8.27

15 PayPal Credit on iq Introduction 1.3 PayPal Credit on iq iq Reporting and Analytics enables you to find, view, and work with PayPal Credit transactions, similar to other methods of payment: All applicable reports show PayPal Credit as a method of payment, including Activity, Settlement, Fee, Chargeback, Transaction Summary, and Payment Detail reports. You can search for a PayPal Credit transaction the same way you search for a credit card transaction. You can use the User Interface to work with chargebacks in the same manner as credit card chargebacks. 1.4 Testing Your PayPal Credit Transactions The purpose of the testing and certification process is to verify that your order entry and supporting systems construct and send XML messages that comply with the LitleXML requirements and PayPal Credit requirements. The Vantiv testing process involves submitting Vantiv-supplied data for specific fields in a request, and receiving specific data back in a response. The response returned allows you to verify that you have parsed the LitleXML Response file correctly. After successful completion of testing and certification with Vantiv and prior to going live, you must also perform end-to-end testing to the PayPal Credit test environment, via Vantiv, in order to complete the PayPal Credit certification process. The Vantiv testing process for all types of LitleXML transactions is described in detail in the Vantiv LitleXML Reference Guide, Chapter 2, Testing your LitleXML Transactions. Document Version: XML Release:

16 Introduction Getting Started with PayPal Credit 1.5 Getting Started with PayPal Credit Before you start using the PayPal Credit payment type with LitleXML transactions, you must first complete the following tasks: Obtain approval from PayPal Credit. Comply with PayPal Credit s Acceptable Use Policy and sign the appropriate processing agreements with PayPal Credit and Vantiv Work with your Customer Experience Manager for more information and assistance with these requirements. Modify your web site and/or call center to accept PayPal Credit payments: Comply with requirements for placement of PayPal Credit service marks on your web site. Add or update the LitleXML API to reflect PayPal Credit-specific payment elements. Update your fulfillment, reconciliation, and dispute resolution processes to support PayPal Credit. Test and certify your LitleXML transactions with Vantiv. Test and certify your end-to-end transactions with PayPal Credit. 6 Document Version: XML Release: 8.27

17 2 STRUCTURING XML TRANSACTIONS FOR PAYPAL CREDIT This chapter describes how to structure LitleXML Transactions when using PayPal Credit as a payment type, and contains the following sections: Understanding the PayPal Credit Authorization Variations PayPal Credit Data Requirements for Authorizations Using PayPal Credit Elements in LitleXML Transactions Document Version: XML Release:

18 Structuring XML Transactions for PayPal Credit Understanding the PayPal Credit Authorization Variations 2.1 Understanding the PayPal Credit Authorization Variations PayPal Credit categorizes authorizations into three variations: No Account, Authenticated, and Not Authenticated. Each variation differs depending on whether: The customer is new or returning. The PayPal Credit account number is stored. The order was placed on your web site or via a call center. Each of these variations also require slightly different data elements when structuring LitleXML transactions. See PayPal Credit Data Requirements for Authorizations on page 9 for further information. For more information on these authorization variations, see the PayPal Credit Implementation Guide (v8.8 or later), or contact your PayPal Credit Project Implementation Manager. The authorization variations are further described below: No Account (New Customers) - the new customer variation is used when a PayPal Credit account number is not on file for a customer. Purchase Types: Web and call center Usage: You do not store PayPal Credit account numbers, or you store PayPal Credit account numbers and this is the customer s first purchase using PayPal Credit. Requirements: Generic PayPal Credit account number ( ), presentation of PayPal Credit screen (web only), customer s date of birth, and the last four digits of their Social Security number. Authenticated (Returning Customers) - the returning customer variations are used for web purchases only. This case is very much like a credit card information on file transaction. Purchase Types: Web only Usage: You store PayPal Credit account numbers Requirements: PayPal Credit account number (504990xxxxxxxxxx) Not Authenticated - In a Call Center environment, you will always need to collect and pass the customer s date of birth and last four digits of their Social Security number for verification purposes, since it is not possible to verify the identity of the caller (as there is no login user name and password recorded during this type of transaction). Purchase Types: Call center only Usage: You store PayPal Credit account numbers Requirements: PayPal Credit account number (504990xxxxxxxxxx), customer s date of birth, and the last four digits of their Social Security number. 8 Document Version: XML Release: 8.27

19 PayPal Credit Data Requirements for Authorizations Structuring XML Transactions for PayPal Credit 2.2 PayPal Credit Data Requirements for Authorizations Table 2-1 lists the PayPal Credit-required data elements for authorization and sale transactions, and the LitleXML mappings for each of the data elements. Each of these elements apply to both web transactions and call center transactions, except where noted. See Table 2-2, PayPal Credit-Related Elements for Supported Transactions for a list of all the PayPal Credit-related elements used in LitleXML Transactions. TABLE 2-1 PayPal Credit Data Requirements Mapping Data Element Required? PayPal Credit Data Element No Account Authenticated Not Authenticated LitleXML Element(s) to Use in Transactions Customer Name Required Required Required <name> Customer Address Required Required Required <addressline1>, <addressline2>, <city>, <state>, <zip>, <country> Customer Phone Number Customer Address Note: Recommended, but not required, for call center transactions. Required Required Required <phone> Required Required Required < > Shipping Name Required Required Required <name> Shipping Address Required Required Required <addressline1>, <addressline2>, <city>, <state>, <zip>, <country> Customer Registration Date Required Not Required Not Required <customerregistrationdate> Customer Type Flag Required Not Required Customer Date of Birth Required Not Required Customer SSN Required Not Required Not Required Required Required <customertype> <dob> <ssn> Customer IP Address Note: Not applicable for call center transactions. Required Required Required <customeripaddress> Document Version: XML Release:

20 Structuring XML Transactions for PayPal Credit PayPal Credit Data Requirements for Authorizations TABLE 2-1 PayPal Credit Data Requirements Mapping Data Element Required? PayPal Credit Data Element No Account Authenticated Not Authenticated LitleXML Element(s) to Use in Transactions Terms & Conditions Code Required Not Required Not Required <termsandconditions> Transaction Type Required Required Required <ordersource> Product Delivery Type Required Required Required <deliverytype> Item Category Code Required Required Required <itemcategorycode> PayPal Credit Account Number Required: Generic # Required: Stored # Required: Stored # <number>, <type> Merchant Order Number Required Required Required <orderid> Shipping Cost Required Required Required <shippingamount> Authorization Amount Required Required Required <amount> Merchant ID Required Required Required <bmlmerchantid> 10 Document Version: XML Release: 8.27

21 Using PayPal Credit Elements in LitleXML Transactions Structuring XML Transactions for PayPal Credit 2.3 Using PayPal Credit Elements in LitleXML Transactions Table 2-2 lists all the PayPal Credit-related elements used in LitleXML Transactions. When structuring LitleXML transactions for use with PayPal Credit, use the standard required LitleXML elements for each LitleXML transaction type, and the PayPal Credit-required elements for the appropriate authorization variations listed in Table 2-1, PayPal Credit Data Requirements Mapping. The PayPal Credit-related elements used in transactions also differ depending on which PayPal Credit product you are using (consumer, private label, etc.). Contact your PayPal Credit Project Implementation Manager for more information. See Chapter 3, "PayPal Credit Transaction Examples" for examples that use elements listed in Table 2-2, and Chapter 4, "LitleXML PayPal Credit Elements" for definitions and use of each element. NOTE: Elements in Table 2-1 and Table 2-2 listed as Required are required by Vantiv, PayPal Credit, or both for the specified transaction types, however these elements may actually be optional according to the LitleXML schema (for non-paypal Credit transactions). TABLE 2-2 PayPal Credit-Related Elements for Supported Transactions Vantiv Transaction Type Authorization Capture PayPal Credit-Related Elements Used Required: <name>, <addressline1>, <city>, <state>, <zip>, <country>, <phone>, < >, <customerregistrationdate>, <customertype>, <termsandconditions>, <itemcategorycode>, <bmlmerchantid>, <dob>, <ssn>, <customeripaddress>, <ordersource>, <deliverytype>, <number>, <type>, <orderid>, <shippingamount>, <amount>, <bmlmerchantid> Optional: <addressline2>, <authenticatedbymerchant>, <authorizationsourceplatform>, <bmlproducttype>, <customerworktelephone>, <employername>, <incomeamount>, <incomecurrency>, <preapprovalnumber>, <residencestatus>, <virtualauthenticationkeydata>, <virtualauthenicationkeypresenceindicator>, <yearsatemployer>, <yearsatresidence> none Document Version: XML Release:

22 Structuring XML Transactions for PayPal Credit Using PayPal Credit Elements in LitleXML Transactions TABLE 2-2 PayPal Credit-Related Elements for Supported Transactions (Continued) Vantiv Transaction Type Sale Credit (for a Vantiv-processed Transaction) Credit (for a non Vantiv-processed Transaction) PayPal Credit-Related Elements Used Required: <name>, <addressline1>, <city>, <state>, <zip>, <country>, <phone>, < >, <customerregistrationdate>, <customertype>, <termsandconditions>, <itemcategorycode>, <bmlmerchantid>, <dob>, <ssn>, <customeripaddress>, <ordersource>, <deliverytype>, <number>, <type>, <orderid>, <shippingamount>, <amount>, <bmlmerchantid> Optional: <addressline2>, <authenticatedbymerchant>, <authorizationsourceplatform>, <bmlproducttype>, <customerworktelephone>, <employername>, <incomeamount>, <incomecurrency>, <preapprovalnumber>, <residencestatus>, <virtualauthenticationkeydata>, <virtualauthenicationkeypresenceindicator>, <yearsatemployer>, <yearsatresidence> none Required: <bmlmerchantid> Optional: none 12 Document Version: XML Release: 8.27

23 3 PAYPAL CREDIT TRANSACTION EXAMPLES This chapter shows example LitleXML requests for use with the PayPal Credit payment type. This chapter contains the following topics: Transaction Types and Examples Authorization Transactions Sale Transactions Credit For Non-Vantiv Processed Transactions Document Version: XML Release:

24 PayPal Credit Transaction Examples Transaction Types and Examples 3.1 Transaction Types and Examples This section presents structural information for each supported PayPal Credit transaction type, followed by one or more examples of the LitleXML transaction. Each structural example shows the parent, child, and sub-child elements relevant to PayPal Credit, but does not show sub-children of other elements. The LitleXML examples however, do show child elements to multiple levels. The XML examples in this section are intended to present typical LitleXML PayPal Credit transactions. The examples do not include every possible element for a particular transaction type. When coding your XML, always consult the LitleXML schema files for information about all available elements. NOTE: The PayPal Credit-related elements used in transactions may also differ depending on which PayPal Credit product you are using (consumer, private label, etc.). Contact your PayPal Credit Project Implementation Manager for more information About the Transaction Types Presented in this Section This section contains examples of the following transaction types, which all require different treatment when using PayPal Credit as a payment type: Authorization Transactions Sale Transactions Credit For Non-Vantiv Processed Transactions No XML examples are given for the following transaction types, even though they are supported for PayPal Credit (the XML structures do not contain any PayPal Credit-specific elements and are therefore identical to non-paypal Credit transactions; see the Vantiv LitleXML Reference Guide for examples of these types of transactions.): Capture Transactions Credit Transactions for Vantiv-Processed Transactions 14 Document Version: XML Release: 8.27

25 Transaction Types and Examples PayPal Credit Transaction Examples Authorization Transactions An authorization for PayPal Credit enables merchants to obtain credit approval for a customer s purchases made using the PayPal Credit payment method. See Chapter 2, "Structuring XML Transactions for PayPal Credit", for information on required and optional elements. The Authorization examples in this section are: Authorization Request - PayPal Credit No Account Authorization Request - PayPal Credit Not Authenticated Authorization Request - PayPal Credit Authenticated PayPal Credit Authorization Response NOTE: If an authorization has been approved, do not use the same order ID number for a re-authorization, unless the authorization has aged-out (after 30 days), as the authorizaiton attempt results in a duplicate transaction response Authorization Request Structure You must structure an Authorization request for PayPal Credit as shown in the following examples. <authorization id="authorization Id" reportgroup="ui Report Group" customerid="customer Id"> <orderid>order Id</orderId> <amount>authorization Amount</amount> <ordersource>order Entry Source</orderSource> <customerinfo> <billtoaddress> <shiptoaddress> <card> <billmelaterrequest> <cardholderauthentication> <enhanceddata> </authorization> Document Version: XML Release:

26 PayPal Credit Transaction Examples Transaction Types and Examples Example: Authorization Request - PayPal Credit No Account The example below shows an online Authorization request for a PayPal Credit No Account Authorization. For Call Center transactions, the < > and <customeripaddress> elements are not required. <litleonlinerequest version="8.27" xmlns=" merchantid="000067"> <authentication> <user>xmltestv3</user> <password>password</password> </authentication> <authorization id="ab1" reportgroup="abc Division"> <orderid>bmlauth1</orderid> <amount>4999</amount> <ordersource>ecommerce</ordersource> <customerinfo> <ssn>1234</ssn> <dob> </dob> <customerregistrationdate> </customerregistrationdate> <customertype>new</customertype> </customerinfo> <billtoaddress> <name>john Smith</name> <addressline1>15 Main Street</addressLine1> <city>san Jose</city> <state>ca</state> <zip> </zip> <country>usa</country> <phone> </phone> < >john@smith.com</ > </billtoaddress> <shiptoaddress> <name>jane Smith</name> <addressline1>15 Main Street</addressLine1> <city>san Jose</city> <state>ca</state> <zip> </zip> <country>usa</country> <phone> </phone> < >jane@smith.com</ > </shiptoaddress> <card> <type>bl</type> 16 Document Version: XML Release: 8.27

27 Transaction Types and Examples PayPal Credit Transaction Examples <number> </number> </card> <billmelaterrequest> <bmlmerchantid>123456</bmlmerchantid> <termsandconditions>32103</termsandconditions> <itemcategorycode>1234</itemcategorycode> </billmelaterrequest> <cardholderauthentication> <customeripaddress> </customeripaddress> </cardholderauthentication> <enhanceddata> <deliverytype>phy</deliverytype> <shippingamount>1000</shippingamount> </enhanceddata> </authorization> </litleonlinerequest> Document Version: XML Release:

28 PayPal Credit Transaction Examples Transaction Types and Examples Example: Authorization Request - PayPal Credit Not Authenticated The example below shows an online Authorization request for a PayPal Credit Not Authenticated Authorization. For Call Center transactions, the < > and <customeripaddress> elements are not required. <litleonlinerequest version="8.27" xmlns=" merchantid="000067"> <authentication> <user>xmltestv3</user> <password>password</password> </authentication> <authorization id="ab1" reportgroup="abc Division"> <orderid>bmlauth1</orderid> <amount>4999</amount> <ordersource>ecommerce</ordersource> <customerinfo> <ssn>1234</ssn> <dob> </dob> </customerinfo> <billtoaddress> <name>john Doe</name> <addressline1>15 Main Street</addressLine1> <city>san Jose</city> <state>ca</state> <zip> </zip> <country>usa</country> <phone> </phone> < >bml@litle.com</ > </billtoaddress> <shiptoaddress> <name>jane Doe</name> <addressline1>15 Main Street</addressLine1> <city>san Jose</city> <state>ca</state> <zip> </zip> <country>usa</country> <phone> </phone> < >bml@litle.com</ > </shiptoaddress> <card> <type>bl</type> <number> </number> </card> 18 Document Version: XML Release: 8.27

29 Transaction Types and Examples PayPal Credit Transaction Examples <billmelaterrequest> <bmlmerchantid>123456</bmlmerchantid> <itemcategorycode>1234</itemcategorycode> </billmelaterrequest> <cardholderauthentication> <customeripaddress> </customeripaddress> <authenticatedbymerchant>false</authenticatedbymerchant> </cardholderauthentication> <enhanceddata> <deliverytype>phy</deliverytype> <shippingamount>1000</shippingamount> </enhanceddata> </authorization> </litleonlinerequest> Document Version: XML Release:

30 PayPal Credit Transaction Examples Transaction Types and Examples Example: Authorization Request - PayPal Credit Authenticated The example below shows an online Authorization request for a PayPal Credit Authenticated Authorization. NOTE: In this example, some of the elements (e.g., those included as child elements of <customerinfo>) are specific to a PayPal Credit Private Label product. Contact your PayPal Credit Project Implementation Manager to determine which elements are required for PayPal Credit products used by your organization. In this example, some of the elements included as child elements of <customerinfo> are specific to a PayPal Credit Private Label product. Contact your PayPal Credit Project Implementation Manager. <litleonlinerequest version="8.27" xmlns=" merchantid="000067"> <authentication> <user>xmltestv3</user> <password>password</password> </authentication> <authorization id="ab1" reportgroup="abc Division"> <orderid>bmlauth1</orderid> <amount>4999</amount> <ordersource>ecommerce</ordersource> <customerinfo> <incomeamount>100</incomeamount> <incomecurrency>usd</incomecurrency> <employername>litle</employername> <customerworktelephone> </customerworktelephone> <residencestatus>own</residencestatus> <yearsatresidence>5</yearsatresidence> <yearsatemployer>5</yearsatemployer> </customerinfo> <billtoaddress> <name>john Smith</name> <addressline1>15 Main Street</addressLine1> <city>san Jose</city> <state>ca</state> <zip> </zip> <country>usa</country> <phone> </phone> < >john@smith.com</ > </billtoaddress> 20 Document Version: XML Release: 8.27

31 Transaction Types and Examples PayPal Credit Transaction Examples <shiptoaddress> <name>jane Smith</name> <addressline1>15 Main Street</addressLine1> <city>san Jose</city> <state>ca</state> <zip> </zip> <country>usa</country> <phone> </phone> </shiptoaddress> <card> <type>bl</type> <number> </number> </card> <billmelaterrequest> <bmlmerchantid>123456</bmlmerchantid> <preapprovalnumber> </preapprovalnumber> <itemcategorycode>1234</itemcategorycode> </billmelaterrequest> <cardholderauthentication> <customeripaddress> </customeripaddress> <authenticatedbymerchant>true</authenticatedbymerchant> </cardholderauthentication> <enhanceddata> <deliverytype>phy</deliverytype> <shippingamount>1000</shippingamount> </enhanceddata> </authorization> </litleonlinerequest> Document Version: XML Release:

32 PayPal Credit Transaction Examples Transaction Types and Examples Authorization Response Structure An Authorization response for PayPal Credit transactions has the following structure. <authorizationresponse id="authorization Id" reportgroup="ui Report Group" customerid="customer Id"> <litletxnid>transaction Id</litleTxnId> <orderid>order Id</orderId> <response>response Code</response> <responsetime>date and Time in GMT</responseTime> <postdate>date transaction posted</postdate> <message>response Message</message> <authcode>approval Code</authCode> <accountinformation> <billmelaterresponsedata> </authorizationresponse> Example: PayPal Credit Authorization Response <litleonlineresponse version="8.27" response="0" message="valid Format"> <authorizationresponse id="ab1" reportgroup="abc Division"> <litletxnid> </litletxnid> <orderid>bmlauth1</orderid> <response>000</response> <responsetime> t10:00:00</responsetime> <postdate> </postdate> <message>approved</message> <authcode>12345a</authcode> <accountinformation> <type>bl</type> <number> </number> </accountinformation> <billmelaterresponsedata> <bmlmerchantid>13579</bmlmerchantid> <creditline>10000</creditline> <addressindicator>r</addressindicator> </billmelaterresponsedata> </authorizationresponse> </litleonlineresponse> 22 Document Version: XML Release: 8.27

33 Transaction Types and Examples PayPal Credit Transaction Examples Sale Transactions The Sale transaction enables you to both authorize fund availability and deposit those funds by means of a single transaction. The Sale transaction is also known as a conditional deposit, because the deposit takes place only if the authorization succeeds. If the authorization is declined, the deposit will not be processed. The PayPal Credit Sale transaction examples in this section are as follows: Online Sale Request - PayPal Credit No Account Online Sale Request - PayPal Credit Not Authenticated Online Sale Request - PayPal Credit Authenticated PayPal Credit Sale Response Sale Request Structure You must structure the Sale request as follows. <sale id="sale Id" reportgroup="ui Report Group" customerid="customer Id"> <orderid>order Id</orderId> <amount>authorization Amount</amount> <ordersource>order Entry Source</orderSource> <customerinfo> <billtoaddress> <shiptoaddress> <card> <billmelaterrequest> <cardholderauthentication> <custombilling> <enhanceddata> </sale> Document Version: XML Release:

34 PayPal Credit Transaction Examples Transaction Types and Examples Example: Online Sale Request - PayPal Credit No Account The example below shows an online Sale request for a PayPal Credit No Account Authorization. For Call Center transactions, the < > and <customeripaddress> elements are not required. <litleonlinerequest version="8.27" xmlns=" merchantid="000067"> <authentication> <user>xmltestv3</user> <password>password</password> </authentication> <sale id="ab1" reportgroup="abc Merchant"> <orderid>bmlauth1</orderid> <amount>4999</amount> <ordersource>ecommerce</ordersource> <customerinfo> <ssn>1234</ssn> <dob> </dob> <customerregistrationdate> </customerregistrationdate> <customertype>new</customertype> </customerinfo> <billtoaddress> <name>john Smith</name> <addressline1>15 Main Street</addressLine1> <city>san Jose</city> <state>ca</state> <zip> </zip> <country>usa</country> <phone> </phone> < >john@smith.com</ > </billtoaddress> <shiptoaddress> <name>jane Smith</name> <addressline1>15 Main Street</addressLine1> <city>san Jose</city> <state>ca</state> <zip> </zip> <country>usa</country> <phone> </phone> < >jane@smith.com</ > </shiptoaddress> <card> <type>bl</type> 24 Document Version: XML Release: 8.27

35 Transaction Types and Examples PayPal Credit Transaction Examples <number> </number> </card> <billmelaterrequest> <bmlmerchantid>123456</bmlmerchantid> <termsandconditions>32103</termsandconditions> <itemcategorycode>1234</itemcategorycode> </billmelaterrequest> <cardholderauthentication> <customeripaddress> </customeripaddress> <authenticatedbymerchant>false</authenticatedbymerchant> </cardholderauthentication> <custombilling> <phone> </phone> <descriptor>billing descriptor</descriptor> </custombilling> <enhanceddata> <deliverytype>phy</deliverytype> <shippingamount>1000</shippingamount> </enhanceddata> </sale> </litleonlinerequest> Example: Online Sale Request - PayPal Credit Not Authenticated The example below shows an online Sale request for a PayPal Credit Not Authenticated Authorization. For Call Center transactions, the < > and <customeripaddress> elements are not required. <litleonlinerequest version="8.27" xmlns=" merchantid="000067"> <authentication> <user>xmltestv3</user> <password>password</password> </authentication> <sale id="ab1" reportgroup="abc Merchant"> <orderid>bmlauth1</orderid> <amount>4999</amount> <ordersource>ecommerce</ordersource> <customerinfo> <ssn>1234</ssn> <dob> </dob> </customerinfo> <billtoaddress> Document Version: XML Release:

36 PayPal Credit Transaction Examples Transaction Types and Examples <name>john Doe</name> <addressline1>15 Main Street</addressLine1> <city>san Jose</city> <state>ca</state> <zip> </zip> <country>usa</country> <phone> </phone> </billtoaddress> <shiptoaddress> <name>jane Doe</name> <addressline1>15 Main Street</addressLine1> <city>san Jose</city> <state>ca</state> <zip> </zip> <country>usa</country> <phone> </phone> </shiptoaddress> <card> <type>bl</type> <number> </number> </card> <billmelaterrequest> <bmlmerchantid>123456</bmlmerchantid> <itemcategorycode>1234</itemcategorycode> </billmelaterrequest> <cardholderauthentication> <customeripaddress> </customeripaddress> <authenticatedbymerchant>false</authenticatedbymerchant> </cardholderauthentication> <enhanceddata> <deliverytype>phy</deliverytype> <shippingamount>1000</shippingamount> </enhanceddata> </sale> </litleonlinerequest> 26 Document Version: XML Release: 8.27

37 Transaction Types and Examples PayPal Credit Transaction Examples Example: Online Sale Request - PayPal Credit Authenticated The example below shows an online Sale request for a PayPal Credit Authenticated Authorization. NOTE: In this example, some of the elements (e.g., those included as child elements of <customerinfo>) are specific to a PayPal Credit Private Label product. Work with your PayPal Credit Project Implementation Manager to determine which elements are required for PayPal Credit Private Label products used by your organization. <litleonlinerequest version="8.27" xmlns=" merchantid="000067"> <authentication> <user>xmltestv3</user> <password>password</password> </authentication> <sale id="ab1" reportgroup="abc Merchant"> <orderid>bmlauth1</orderid> <amount>4999</amount> <ordersource>ecommerce</ordersource> <customerinfo> <incomeamount>100</incomeamount> <incomecurrency>usd</incomecurrency> <employername>litle</employername> <customerworktelephone> </customerworktelephone> <residencestatus>own</residencestatus> <yearsatresidence>5</yearsatresidence> <yearsatemployer>5</yearsatemployer> </customerinfo> <billtoaddress> <name>john Doe</name> <addressline1>15 Main Street</addressLine1> <city>san Jose</city> <state>ca</state> <zip> </zip> <country>usa</country> <phone> </phone> < >bml@litle.com</ > </billtoaddress> <shiptoaddress> <name>jane Doe</name> <addressline1>15 Main Street</addressLine1> Document Version: XML Release:

38 PayPal Credit Transaction Examples Transaction Types and Examples <city>san Jose</city> <state>ca</state> <zip> </zip> <country>usa</country> <phone> </phone> </shiptoaddress> <card> <type>bl</type> <number> </number> </card> <billmelaterrequest> <bmlmerchantid>123456</bmlmerchantid> <preapprovalnumber> </preapprovalnumber> <virtualauthenticationkeypresenceindicator>p </virtualauthenticationkeypresenceindicator> <virtualauthenticationkeydata>258</virtualauthenticationkeydata> <itemcategorycode>1234</itemcategorycode> </billmelaterrequest> <cardholderauthentication> <customeripaddress> </customeripaddress> <authenticatedbymerchant>true</authenticatedbymerchant> </cardholderauthentication> <enhanceddata> <deliverytype>phy</deliverytype> <shippingamount>1000</shippingamount> </enhanceddata> </sale> </litleonlinerequest> 28 Document Version: XML Release: 8.27

39 Transaction Types and Examples PayPal Credit Transaction Examples Sale Response Structure The Sale response has the following structure: <saleresponse id="sale Id" reportgroup="ui Report Group" customerid="customer Id"> <litletxnid>transaction Id</litleTxnId> <orderid>order Id</orderId> <response>response Code</response> <responsetime>date and Time in GMT</responseTime> <postdate>date of Posting</postDate> <message>response Message</message> <authcode>approval Code</authCode> <approvedamount>approved amount for partial Auth</approvedAmount> <accountinformation> <billmelaterresponsedata> </saleresponse> Example: PayPal Credit Sale Response <litleonlineresponse version="8.27" response="0" message="valid Format"> <saleresponse id="ab1" reportgroup="abc Merchant"> <litletxnid> </litletxnid> <orderid>bmlauth1</orderid> <response>000</response> <responsetime> t10:00:00</responsetime> <postdate> </postdate> <message>approved</message> <authcode>12345a</authcode> <accountinformation> <type>bl</type> <number> </number> </accountinformation> <billmelaterresponsedata> <bmlmerchantid>13579</bmlmerchantid> <creditline>10000</creditline> <addressindicator>r</addressindicator> </billmelaterresponsedata> </saleresponse> </litleonlineresponse> Document Version: XML Release:

40 PayPal Credit Transaction Examples Transaction Types and Examples Credit For Non-Vantiv Processed Transactions The Credit request for Non Vantiv-Processed PayPal Credit transactions enables a merchant to apply a refund against a PayPal Credit Capture or Sale that occurred outside of our system (for example, when a transaction was executed with a previous processor). The examples in this section are: Credit Request for Non Vantiv-Processed PayPal Credit Transactions Credit Response Credit Request Structure for Non-Vantiv Processed Transaction You must specify the Credit request for a Non-Vantiv processed transaction as follows. <credit id="credit Id" reportgroup="ui Report Group" customerid="customer Id"> <orderid>order Id</orderId> <amount>authorization Amount</amount> <ordersource>order Entry Source</orderSource> <billtoaddress> <card> <custombilling> <billmelaterrequest> </credit> Example: Credit Request for Non Vantiv-Processed PayPal Credit Transactions The example below shows an Credit request for a PayPal Credit transaction. <litleonlinerequest version="8.27" xmlns=" merchantid="000067"> <authentication> <user>xmltestv3</user> <password>password</password> </authentication> <credit id="cr12346" reportgroup="000242" customerid="foucre"> <orderid> </orderid> <amount>50050</amount> <ordersource>ecommerce</ordersource> <card> <type>bl</type> <number> </number> 30 Document Version: XML Release: 8.27

41 Transaction Types and Examples PayPal Credit Transaction Examples </card> <custombilling> <phone> </phone> <descriptor>billing descriptor</descriptor> </custombilling> <billmelaterrequest> <bmlmerchantid>123456</bmlmerchantid> </billmelaterrequest> </credit> </litleonlinerequest> Credit Response Structure The Credit response message is structures as follows: <creditresponse id="credit Id" reportgroup="ui Report Group" customerid="customer Id"> <litletxnid>transaction Id</litleTxnId> <orderid>order Id</orderId> <response>response Code</response> <responsetime>date and Time in GMT</responseTime> <postdate>date of Posting</postDate> <message>response Message</message> </creditresponse> Example: Credit Response <litleonlineresponse version="8.27" response="0" message="valid Format"> <creditresponse id="ab1" reportgroup="abc Merchant"> <litletxnid> </litletxnid> <orderid>bmlauth1</orderid> <response>000</response> <responsetime> t10:00:00</responsetime> <postdate> </postdate> <message>approved</message> </creditresponse> </litleonlineresponse> Document Version: XML Release:

42 PayPal Credit Transaction Examples Transaction Types and Examples 32 Document Version: XML Release: 8.27

43 4 LITLEXML PAYPAL CREDIT ELEMENTS This chapter provides definitions for the elements (both parent and child elements) used in the LitleXML for PayPal Credit transactions. Use this information in combination with the various LitleXML schema files to assist you as you build the code necessary to submit PayPal Credit transactions to Vantiv transaction processing systems. Each section defines a particular element, its relationship to other elements (parents and children), as well as any attributes associated with the element. For additional information on the structure of LitleXML requests and responses using these elements, as well as XML examples, see Chapter 2, "Structuring XML Transactions for PayPal Credit" and Chapter 3, "PayPal Credit Transaction Examples". For a comprehensive list of all LitleXML elements and usage, see Chapter 4, LitleXML Elements in the Vantiv LitleXML Reference Guide. The XML elements defined in this chapter are listed alphabetically. Document Version: XML Release: