PayPal XMLPay - 2009 Developer's Guide
XMLPay Developer’s
Guide
Last updated: December 2009
Payflow Pro XMLPay Developer’s Guide
Document Number: 200013.en_US-200912
© 2010 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 (Europe) S.à r.l. et Cie., S.C.A., Société en Commandite par Actions. Registered office: 22-24 Boulevard
Royal, L-2449, Luxembourg, R.C.S. Luxembourg B 118 349.
Consumer advisory: The PayPal™ payment service is regarded as a stored value facility under Singapore law. As such, it does not require the approval
of the Monetary Authority of Singapore. You are advised to read the terms and conditions carefully.
Notice of non-liability:
PayPal, Inc. is providing the information i n this document t o you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information co ntained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused
by errors or omissions, or resulting from the use of this document or the information contained in t his document or result ing from the ap plication or use
of the product or service described herein. PayPal, Inc. reserves the right to make changes to any information herein without further notice.
Contents
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Intended Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Organization of This Document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
Where to Go For More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7
How to Contact Customer Service . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Revision History . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8
Chapter 1 XMLPay Overview . . . . . . . . . . . . . . . . . . . . . . 9
About XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Benefits of XML . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Well-formed XML Document. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Using XMLPay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
XMLPay Instruments. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
XMLPay Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
XMLPay Processing Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Business-to-Consumer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
Business-to-Business . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
XMLPay Messaging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12
XMLPayRequest. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
XMLPayResponse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Chapter 2 XMLPay Syntax . . . . . . . . . . . . . . . . . . . . . . .15
Syntax Notation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
The XMLPayRequest Document (Transactions). . . . . . . . . . . . . . . . . . . . . . . 15
Transaction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
RequestAuth. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21
The XMLPayRequest Document (Recurring Profiles) . . . . . . . . . . . . . . . . . . . . 22
RecurringProfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22
PayData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
PayDataAuth. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Invoice. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
Items. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
MerchantInfo. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
XMLPay Developer’s Guide 3
Contents
AdditionalAmounts. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
Tender . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
RPData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
ExtData . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
The XMLPayResponse Document (Transactions). . . . . . . . . . . . . . . . . . . . . . 37
TransactionResult . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
The XMLPayResponse Document (Recurring Profiles) . . . . . . . . . . . . . . . . . . . 41
BuyerAuthResult. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
RecurringProfileResult. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
Chapter 3 XMLPay Elements . . . . . . . . . . . . . . . . . . . . . . 47
General Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Credit Card Transaction Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
Retail Credit Card Transaction Parameters . . . . . . . . . . . . . . . . . . . . . . . 48
Level 3 (Commercial) Credit Card Transaction Parameters. . . . . . . . . . . . . . . 52
Buyer Authentication Transaction Parameters. . . . . . . . . . . . . . . . . . . . . . . . 58
Credit Card Transaction Response Parameters . . . . . . . . . . . . . . . . . . . . . . . 58
ACH Transaction Parameters (Norwest). . . . . . . . . . . . . . . . . . . . . . . . . . . 60
PayPal Express Checkout Request Transaction Parameters . . . . . . . . . . . . . . . . 60
PayPal Express Checkout Response Transaction Parameters . . . . . . . . . . . . . . . 63
Chapter 4 XMLPay Transaction Profiles . . . . . . . . . . . . . . . .65
ACH Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Buyer Authentication Transactions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
Card Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Purchase Card Level I . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Purchase Card Level II . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Purchase Card Level III . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
Check Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 67
PayPal Transactions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 68
Chapter 5 XMLPay Examples . . . . . . . . . . . . . . . . . . . . . . 69
ACH Sale Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
ACH Sale Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Card Authorization Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
Card Authorization Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72
4 XMLPay Developer’s Guide
Contents
Card Capture Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Card Capture Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
Card Credit Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74
Card Credit Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Card Credit Reference Credit Request . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
Card Credit Reference Credit Response . . . . . . . . . . . . . . . . . . . . . . . . 75
Card Force Capture Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76
Card Force Capture Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Card Sale Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77
Card Sale Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 78
Card Secure Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
Card Status Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Card Status Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 80
Card Void Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Card Void Response. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
Check Sale Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82
Check Sale Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Customer IP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
Express Checkout Authorization Transaction . . . . . . . . . . . . . . . . . . . . . . . . 84
Set Express Checkout Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84
Set Express Checkout Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Get Express Checkout Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Get Express Checkout Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
Do Express Checkout Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
Do Express Checkout Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
IAVS Result Request. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
Level 3 Invoice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
Line Item Sale Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90
Line Item Sale Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92
Merchant Description and Merchant Service Number . . . . . . . . . . . . . . . . . . . . 92
Processor Result. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
Recurring Billing Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
ACH Recurring Billing Profile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94
Credit Card Recurring Billing Profile. . . . . . . . . . . . . . . . . . . . . . . . . . . 95
Shipping Carrier and Shipping Method . . . . . . . . . . . . . . . . . . . . . . . . . . . 96
Transaction Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
ValidateAuthentication Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
ValidateAuthentication Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98
XMLPay Developer’s Guide 5
Contents
VerifyEnrollment Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
VerifyEnrollment Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99
Appendix A XMLPay Schemas . . . . . . . . . . . . . . . . . . . . . 101
XMLPay Schema. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
XMLPay Types Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
Appendix B XMLPay DTD. . . . . . . . . . . . . . . . . . . . . . . . 131
Appendix C Transaction Results . . . . . . . . . . . . . . . . . . . . 145
AVS Result Codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153
6 XMLPay Developer’s Guide
Preface
This document defines an XML syntax for payment transaction requests, responses, and
receipts in a payment processing network.
Intended Audience
The typical user of XMLPay is an Internet merchant or merchant aggregator who wants to
dispatch credit card, corporate purchase card, Automated Clearing House (ACH), or other
payment requests to a financial processing network.
Organization of This Document
This document is organized as follows:
z Chapter 1, “XMLPay Overview,” describes XML and XMLPay, presenting processing
models, networking, messaging and related specifications.
z Chapter 2, “XMLPay Syntax,” presents the syntax for transaction requests, responses, and
receipts using a simplified notation.
z Chapter 3, “XMLPay Elements,”provides tables defining the existing Payflow SDK
parameters (name/value pairs) and their XMLPay equivalents.
z Chapter 4, “XMLPay Transaction Profiles,” lists the transactions supported for each tender
type—ACH, Card, Check—along with the data elements used for each of those
transactions.
z Chapter 5, “XMLPay Examples,” gives several XMLPay document samples.
z Appendix A, “XMLPay Schemas,” provides standard W3C schemas for XMLPay and
XMLPay Types.
z Appendix B, “XMLPay DTD,” presents the Document Type Definition XMLPay schema.
z Appendix C, “Transaction Results,” lists transaction result codes and response messages as
well as Address Verification Service (AVS) result codes.
Where to Go For More Information
This guide is not the complete source of all the information you need to develop Payflow
applications. Use the Payflow Pro Developer’s Guide along with this guide. It provides
XMLPay Developer’s Guide 7
Preface
How to Contact Customer Service
detailed descriptions of all the Payflow name-value pair parameters. In addition, it contains
testing data, the test and live URLs, and error codes.
How to Contact Customer Service
For problems with transaction processing or connections, contact Customer Service by
opening a ticket on the Contact Support tab at http://www.paypal.com/mts.
Revision History
Revision history for Website Payments Pro Payflow Edition—XMLPay Developer’s Guide.
Date Description
December 2009 Added an example of using ExtData to pass values for unsupported NVP tags.
October 2008 Added a card credit request example. Renamed the existing credit request example Card
Refereence Credit Request.
Updated the RESULT values and RESPMSG table.
February 2008 Minor updates for technical accuracy.
December 2007 Updated host addresses in RESULT values and RESPMSG table.
August 2007 Updated RESPMSD text.
Updated PayPal logo.
May 2007 Represents a merge of content from two separate XMLPay developer guides.
Corrections for technical accuracy.
February 2007 Updated transaction RESULT values and RESPMSG text.
August 2006 Updated URLs to PayPal test and live servers.
May 2006 Reformatted in PayPal templates.
Integrated Direct Payment feature.
March 2006 Integrated Express Checkout feature.
8 XMLPay Developer’s Guide
1
About XML
XML (eXtensible Markup Language) is derived from Standardized General Markup
Language (SGML) and HyperText Markup Language (HTML). In a sense, XML is SGML
“lite”, but XML manages to maintain SGML’s strength as well as HTML’s simplicity. What’s
more, XML can be converted to HTML.
The main advantage of XML is that text can be meaningfully annotated. In XML, markers
identify and tag the text. But the markers themselves have no defined meaning; it is the
applications that define the markers.
XML allows complex transactions to be structured. Client integration is simplified through the
exchange of XML documents. Since XML provides support for digital signatures, documents
from unknown sources can be trusted. In addition, XML can easily produce large documents
such as transaction logs and reports.
XMLPay Overview
Benefits of XML
The main benefits of XML are that it:
z Allows text annotation
z Presents text, data, and content to applications as a structured document
z Facilitates integration of diverse applications
z In addition to these benefits, XML is easy to:
z Read (all text)
z Parse and validate
z Search for content
z Produce
Well-formed XML Document
A well-formed XML document conforms to XML syntax and must have:
z An XML processing instruction at the beginning (prolog)
z A single root element
z Matching (case sensitive) start and end tags for all elements
z All XML elements properly nested
z Attribute values in quotes
XMLPay Developer’s Guide 9
XMLPay Overview
1
Using XMLPay
Example 1
<?xml version=“1.0”?>
<Card>
<CardType> MasterCard </CardTy pe>
<CardNumber>495576040004</Card Number>
<ExpDate>200011</ExpDate>
CVNum>828</CVNum>
</Card>
Example 2
<?xml version=“1.0”?>
<Items ID=“IDTI123”>
<Item Number=“1”>
<Description>Electric Toothbrush< /Description>
<Quantity>1</Quantity>
<UnitPrice>100</UnitPrice>
<TotalAmt>100</TotalAmt>
</Item>
<Item Number=“2”>
<Description>ToothPaste</Descr iption>
<Quantity>20</Quantity>
<UnitPrice>2</UnitPrice>
<TotalAmt>40</TotalAmt>
</Item>
…
</Items>
Using XMLPay
XMLPay defines an XML syntax for payment transaction requests and responses in a payment
processing network.
The typical user of XMLPay is an Internet merchant or merchant aggregator who wants to
dispatch credit card, corporate purchase card, Automated Clearing House (ACH), or other
payment requests to a financial processing network.
Using the data type definitions specified by XMLPay, a user creates a client payment request
and dispatches it—using a mechanism left unspecified by XMLPay—to an associated
XMLPay-compliant server component. Responses (also formatted in XML) convey the results
of the payment requests to the client.
NOTE: For specific examples of how to submit XML documents using the Website Payments
Pro Payflow Edition client service, see the PayPal Manager Download package.
XMLPay Instruments
XMLPay supports payment processing using the following payment instruments:
z Retail credit and debit cards
10 XMLPay Developer’s Guide
z Corporate purchase cards: Levels 1, 2, and 3
HTTPS (typical)
XMLPay
Payment
Gateway
Seller
Buyer
Payment
Processor
Financial
networks
Merchant
Web Store
Card 3455-342
$37.95
BUY
z Automated Clearing House (ACH)
XMLPay Operations
Typical XMLPay operations include:
z Funds authorization and capture
z Sales and repeat sales
z Voiding of transactions
XMLPay Processing Models
XMLPay is intended for use in both Business-to-Consumer (B2C) and Business-to-Business
(B2B) payment processing applications.
XMLPay Overview
XMLPay Processing Models
1
Business-to-Consumer
In a B2C Sale transaction, the Buyer presents a payment instrument (for example, a credit card
number) to a Seller to transfer money from the Buyer to the Seller.
The Seller uses XMLPay to forward the Buyer’s payment information to a Payment Processor.
The Seller formats an XMLPayRequest and submits it either directly to an XMLPaycompliant payment processor or, as pictured, indirectly via an XMLPay-compliant Payment
Gateway. Responses have the type XMLPayResponse.
The Buyer-to-Seller and Payment Gateway-to-Processor channels are typically left unaffected
by use of XMLPay. For example, XMLPay is typically not used in direct communications
between the buyer and the seller. Instead, conventional HTML form submission or other
Internet communication methods are typically used. Similarly, because Payment Processors
often differ considerably in the formats they specify for payment requests, XMLPay server
logic is usually localized at the Payment Gateway, leaving the legacy connections between
gateways and processors unchanged.
XMLPay Developer’s Guide 11
XMLPay Overview
XMLPay
Payment
Gateway
Sellers
Buyers
Payment
Processor
Financial
networks
Trading
Exchange
1
XMLPay Messaging
Business-to-Business
When used in support of B2B transactions, the Seller does not typically initiate XMLPay
requests. Instead, an aggregator or trading exchange uses XMLPay to communicate businessfocused purchasing information (such as level 3 corporate purchase card data) to a payment
gateway.
In this way, the Trading Exchange links payment execution to other XML-based
communications between Buyers and Sellers such as Advance Shipping Notice delivery,
Purchase Order communication, or other B2B communication functions.
XMLPay Messaging
The highest-level XMLPay structures represent payment transaction requests and responses.
12 XMLPay Developer’s Guide
XMLPayRequest
<RequestData>
<MerchantId>
<Transactions>
<RequestAuth>
<XMLPayRequest>
Payment transactions are submitted, one or more at a time, as XMLPayRequest documents.
The high-level structure of a request looks like this:
XMLPay Overview
XMLPay Messaging
1
Merchant ID identifies the merchant of record for the transaction within the target payment
processing network. The merchant of record may be different from the submitting party in a
delegated processing model.
Transactions is the list of payment transactions to be processed. XMLPay supports up to 32
transactions per XMLPay document submission.
RequestAuth is an optional structure used to authenticate the submitting party, in the absence
of transport level authentication.
See Chapter 2, “XMLPay Syntax,” for a detailed description of request documents.
XMLPayResponse
Each XMLPayRequest submission produces a corresponding XMLPayResponse document
containing results for each submitted transaction request. The high-level structure of a
response looks like this:
XMLPay Developer’s Guide 13
XMLPay Overview
<ResponseData>
<MerchantId>
<TransactionResults>
<Signature>
<XMLPayResponse>
<TransactionReceipts>
1
XMLPay Messaging
NOTE: Signature and TransactionReceipts are not supported on the Payment server.
See Chapter 2, “XMLPay Syntax,” for a detailed description of response documents.
14 XMLPay Developer’s Guide
XMLPay Syntax
2
This chapter presents the syntax for transaction requests and responses using a simplified
notation.
z Appendix A, “XMLPay Schemas,” provides the complete syntax, expressed in W3C
XML-schema notation.
z Appendix B, “XMLPay DTD,” provides a document type definition (DTD) representation
of the schema.
Syntax Notation
The following example presents the notation used to describe XMLPay document:
<Example>
(element)
(optionalElement)?
(alternativeElement1|alternati veElement2)
(element)+
(element)*
</Example>
element Indicates the occurrence of a (possibly complex) XML element (for
example, <element>...</element>) defined elsewhere.
? Indicates an optional element.
| Separates alternative elements, any one of which is allowed.
+ Indicates that one or more occurrences of an element are allowed.
* Indicates that zero or more occurrences of an element are allowed.
NOTE: The Payflow SDK SDK download package provides specific examples of XML
documents using the Pro client service.
The XMLPayRequest Document (Transactions)
<XMLPayRequest Timeout="30" ve rsion = "2.0">
<RequestData>
(Vendor)
(Partner)
<Transactions>
XMLPay Developer’s Guide 15
XMLPay Syntax
2
The XMLPayRequest Document (Transactions)
(Transaction)+
</Transactions>
</RequestData>
(RequestAuth)?
</XMLPayRequest>
Attribute Description
Vendor Iden tifies the merchant of record for the transaction within the target
Partner Identifies the submitting party.
Transaction Defined on page 16. XMLPay supports up to 32 transactions per
RequestAuth Defined on page 21.
Timeout The value of this attribute is ignored.
payment processing network. In a delegated processing model, the
merchant of record may be different from the submitting party.
XMLPay document submission.
Transaction
XMLPay supports up to 32 transactions per XMLPay document submission.
<Transaction Id=? CustRef=?>
</Transaction>
Attribute Description
Id
(Authorization|Capture|Sale|Cr edit|Void|
ForceCapture|RepeatSale|GetSta tus|
VerifyEnrollment|ValidateAuthe ntication|
TransactionUpdate|SetExpressCh eckout|
GetExpressCheckout|DoExpressCh eckout)
Optional attribute that tracks the transaction through the payment-
processing network. The submitting merchant generates this transaction
identifier, which must be unique among all transactions submitted by that
merchant.
Id need not be globally unique across merchants, since the paymentprocessing network interprets it within the context of the merchant
associated with the transaction. If an Id attribute is provided in a
transaction, it will be included in the matching TransactionResult in the
resultant XMLPayResult.
Similarly, CustRef is a merchant-generated ID identifying a specific
customer of this merchant and associating it with this transaction.
Authorization Transaction
An authorization transaction verifies the availability of funds and reserves them for later
capture.
16 XMLPay Developer’s Guide
XMLPay Syntax
The XMLPayRequest Document (Transactions)
<Authorization>
<PayData>
(Invoice)
(Tender)
</PayData>
(ExtData)*
</Authorization>
Attribute Description
PayData Specifies the details of the purchase, within Invoice, as well as the
payment Tender to use.
ExtData Optional element that may carry extended data (outside the syntax of the
XMLPay schema).
Capture Transaction
A capture transaction transfers the funds secured by a previous authorization transaction,
identified by PNRef, into the merchant’s account.
2
<Capture>
(PNRef)
(Invoice)?
(ExtData)*
</Capture>
Attribute Description
Invoice An updated Invoice may optionally be provided, specifying any changes
in the purchase details from the original invoice in the reference
authorization.
ExtData Optional element that may carry extended data (outside the syntax of the
XMLPay schema).
Sale Transaction
A sale transaction verifies the availability of funds and captures funds in one step.
<Sale>
<PayData>
(Invoice)
(Tender)
</PayData>
(ExtData)*
</Sale>
Attribute Description
PayData Specifies the details of the purchase, within Invoice, as well as the
payment Tender to use.
XMLPay Developer’s Guide 17
XMLPay Syntax
2
The XMLPayRequest Document (Transactions)
Attribute Description
ExtData Optional element that may carry extended data (outside the syntax of the
Credit Transaction
A credit transaction reverses a previous sale or capture transaction.
<Credit>
(PNRef|Tender)
(Invoice)?
(ExtData)*
</Credit>
Attribute Description
PNRef|Tender The transaction to be credited is identified by PNRef. Acredit may be run
Invoice In the case of a partial credit, you must provide Invoice and provide
XMLPay schema).
without a PNRef by providing the Tender for the account to be credited
and Invoice for the amount.
details on the items being returned.
ExtData Optional element that may carry extended data (outside the syntax of the
XMLPay schema).
Void Transaction
A void transaction cancels a pending sale, capture, or credit.
<Void>
(PNRef)
(ExtData)*
</Void>
Attribute Description
PNRef The transaction to be cancelled is identified by PNRef. If the referenced
transaction has already been processed, the void fails.
SetExpressCheckout Transaction
SetExpressCheckout indicates to the server that you are using Express Checkout to obtain
payment from your customer.
<SetExpressCheckout>
(Authorization|Sale)
(ExtData)*
18 XMLPay Developer’s Guide
XMLPay Syntax
The XMLPayRequest Document (Transactions)
</SetExpressCheckout>
Attribute Description
Authorization The Express Checkout transaction: an authorization for payment or a
sale.
ExtData Optional element that may carry extended data (outside the syntax of the
XMLPay schema).
GetExpressCheckout Transaction
GetExpressCheckout returns information about the customer using Express Checkout,
including the name and address on file at PayPal.
<SetExpressCheckout>
(Authorization|Sale)
(ExtData)*
</SetExpressCheckout>
Attribute Description
2
Authorization The Express Checkout transaction: an authorization for payment or a
sale.
ExtData Optional element that may carry extended data (outside the syntax of the
XMLPay schema).
DoExpressCheckout Transaction
DoExpressCheckout obtains payment through Express Checkout for a Sale transaction or
requests an Authorization for a later capture of payment.
<DoExpressCheckout>
(Authorization|Sale)
(ExtData)*
</DoExpressCheckout>
Attribute Description
Authorization The Express Checkout transaction to be carried out: an authorization for
payment or a sale.
ExtData Optional element that may carry extended data (outside the syntax of the
XMLPay schema).
ForceCapture Transaction
A ForceCapture transaction captures funds reserved through an out-of-band authorization (for
example, a voice authorization received over the phone).
<ForceCapture>
<PayData>
(Invoice)
XMLPay Developer’s Guide 19
XMLPay Syntax
2
The XMLPayRequest Document (Transactions)
(Tender)
</PayData>
(AuthCode)
(ExtData)*
</ForceCapture>
Attribute Description
AuthCode Authorization code received out-of-band.
PayData Specifies the details of the purchase, within Invoice, as well as the
ExtData Optional element that may carry extended data (outside the syntax of the
GetStatus Transaction
A GetStatus transaction queries the status of a previous transaction.
<GetStatus>
(PNRef)
(ExtData)*
</GetStatus>
payment Tender to use.
XMLPay schema).
Attribute Description
PNRef The transaction to query is identified by PNRef.
ExtData Optional element that may carry extended data (outside the syntax of the
XMLPay schema).
VerifyEnrollment Transaction
For the Buyer Authentication Service, this transaction is used to determine whether the card
holder is enrolled in the 3D-Secure program.
Refer to Payflow Pro Fraud Protection Services User’s Guide on the sequence of steps
involved in performing a Buyer Authentication transaction. This transaction is submitted only
to the Buyer Authentication server and not to the core OLTP server.
<VerifyEnrollment>
<PayData>
(Invoice)
(Tender)
</PayData>
(ExtData)*
</VerifyEnrollment>
Attribute Description
PayData Specifies the details of the credit card used in the purchase.
20 XMLPay Developer’s Guide
XMLPay Syntax
The XMLPayRequest Document (Transactions)
Attribute Description
ExtData Optional element that may carry extended data (outside the syntax of the
XMLPay schema).
ValidateAuthentication Transaction
For the Buyer Authentication Service, this transaction validates the signature on the PARes
data returned by the issuing bank and parses the authentication information. Refer to Payflow
Pro Fraud Pr otection Services User’s Guide on the sequence of steps involved in performing a
Buyer Authentication transaction.
<ValidateAuthentication>
<PARes>
(ExtData)*
</ValidateAuthentication>
Attribute Description
PARes The authentication data returned by Issuer's ACS.
2
ExtData Optional element that may carry extended data (outside the syntax of the
RequestAuth
The RequestAuth element provides authentication of the requestor through either a username
and password, using UserPass, or a digital signature, using Signature.
<RequestAuth>
</RequestAuth>
In the case of a digital signature, the W3C XML Signature syntax is used and the signature is
executed over the RequestData.
UserPass
<UserPass>
</UserPass>
Attribute Description
XMLPay schema).
(UserPass|Signature)
(User)
(UserDomain)?
(Password)
User String identifier assigned to a user.
UserDomain Names a partner or a vendor under whose auspice a transaction is being
submitted.
Password User's password (string).
XMLPay Developer’s Guide 21
XMLPay Syntax
2
The XMLPayRequest Document (Recurring Profiles)
The XMLPayRequest Document (Recurring Profiles)
A RecurringProfile transaction defines a scheduled payment that enables you to automatically
bill your customers at regular intervals.
<XMLPayRequest Timeout="30" ve rsion = "2.0">
<RequestData>
(Vendor)
(Partner)
<RecurringProfiles>
(RecurringProfile)+
</RecurringProfiles>
</RequestData>
(RequestAuth)?
</XMLPayRequest>
Attribute Description
Vendor Iden tifies the merchant of record for the transaction within the target
payment processing network. In a delegated processing model, the
merchant of record may be different from the submitting party.
Partner Identifies the submitting party.
RecurringProfile Defined on page 22.
RequestAuth Defined on page 21.
Timeout The value of this attribute is ignored.
RecurringProfile
<Profile Id=? CustRef=?>
(Add|Modify|Cancel|Reactivate| Payment|Inquiry
</Profile>
Attribute Description
Id
Optional attribute that tracks the transaction through the payment-
processing network. The submitting merchant generates this transaction
identifier, which should be unique among all transactions submitted by
that merchant.
Id need not be globally unique across merchants, since the paymentprocessing network interprets it within the context of the merchant
associated with the transaction. If an Id attribute is provided in a
transaction, it will be included in the matching TransactionResult in the
resultant XMLPayResult.
Similarly, CustRef is a merchant-generated ID identifying a specific
customer of this merchant and associating it with this transaction.
22 XMLPay Developer’s Guide
XMLPay Syntax
The XMLPayRequest Document (Recurring Profiles)
Add Recurring Profile
Add a new recurring profile either by sending all data required to defin e the profile or by
converting an existing transaction into a profile.
<Add>
(RPData)
(Tender)
</Add>
Attribute Description
RPData Describes recurring profile details. Defined on page 36.
Tender Specifies type of payment
Modify Recurring Profile
Modify any profile value by sending any subset of the profile parameters, including an
Optional Transaction.
2
<Modify>
(RPData)
(Tender)
(ProfileID)
</Modify>
Attribute Description
RPData Describes recurring profile details. Defined on page 36.
Tender Specifies type of payment
ProfileID Profile ID of the profile that you want to modify.
Cancel Recurring Profile
Cancel (deactivate) a recurring profile.
<Cancel>
(ProfileID)
</Cancel>
Attribute Description
ProfileID Profile ID of the profile that you want to cancel.
Reactivate Recurring Profile
Reactivate a profile with an inactive status. Profiles can be deactivated for the following
reasons: the term has completed, the profile reached maximum allowable payment failures, or
the profile was canceled.
XMLPay Developer’s Guide 23
XMLPay Syntax
2
The XMLPayRequest Document (Recurring Profiles)
<Reactivate>
(RPData)
(Tender)
(ProfileID)
</Reactivate>
Attribute Description
RPData Describes recurring profile details. Defined on page 36.
Tender Specifies type of payment
ProfileID Profile ID of the profile that you want to reactivate.
Payment Recurring Profile
The Payment action performs a real-time retry on a previously failed transaction.
<Payment>
(RPData)
(Tender)
(ProfileID)
</Payment>
Attribute Description
RPData Describes recurring profile details. Defined on page 36.
Tender Specifies type of payment
ProfileID Profile ID of the profile you want to retrying payment for.
Inquiry Recurring Profile
Inquire about the status of a profile.
<Inquiry>
(ProfileID)
</Inquiry>
Attribute Description
ProfileID Profile ID of the profile you want to review.
24 XMLPay Developer’s Guide
Core Structures
PayData
<PayData>
(Invoice)
(Tender)
</PayData>
Attribute Description
Invoice Describes the details of a purchase. Defined on page 25.
Tender Describes the payment instrument. Defined on page 32.
PayDataAuth
XMLPay Syntax
Core Structures
2
Invoice
The PayDataAuth element provides authentication of the payer for an associated PayData,
using either a PKCS-7 format or a W3C XML Signature format digital signature.
<PayDataAuth>
(PKCS7Signature|Signature)
</PayDataAuth>
<Invoice>
(CustIP)*
(MerchantDescription)*
(MerchantServiceNum)*
(Recurring)*
(InvNum)?
(OrigInvNum)*
(Date)?
(OrderDateTime)*
<BillFrom>
(Name)?
(Address)?
(EMail)?
(Phone)?
(Fax)?
(URL)?
</BillFrom>
<BillTo>
(CustomerId)*
(Name)?
(Address)?
XMLPay Developer’s Guide 25
XMLPay Syntax
2
Core Structures
(EMail)?
(Phone)?
(Phone2)?
(Fax)?
(CustCode)?
(PONum)?
(TaxExempt)?
(PhoneType)?
</BillTo>
<ShipCarrier/>?
<ShipMethod/>?
<ShipFrom>
(Name)?
(Address)?
(EMail)?
(Phone)?
(Fax)?
(ShipFromEU)?
</ShipFrom>
<ShipTo>
(Name)?
(Address)?
(EMail)?
(Phone)?
(Phone2)
(Fax)?
(ShipToEU)?
</ShipTo>
(Description)*
(Items)*
(DiscountAmt)?
(ShippingAmt)?
(DutyAmt)?
(TaxAmt)?
(NationalTaxIncl)?
(TotalAmt)?
(FreightAmt)?
(HandlingAmt)?
(ItemAmt)?
(Comment)?
(Level3Invoice)
(Memo)
(Custom)
(OrderDesc)
(ExtData)*
(MerchantInfo)*
(AdditionalAmounts)*
(SKU)*
(CustomerHostName)*
(CustomerBrowser)*
</Invoice>
26 XMLPay Developer’s Guide
XMLPay Syntax
Core Structures
Attribute Description
CustIP Customer IP address (filter transactions).
MerchantDescripton Merchant descriptor. For example, ABCCMPY*FALLCATALOG
MechantServiceNum Merchant telephone number. For example, 603-555-1212
Recurring Identifies the transaction as recurring. This value does not activate the
Recurring Billing Service. If the RECURRING parameter was set to Y
for the original transaction, then the setting is ignored when forming
Credit, Void, and Force transactions. If you subscribe to the Fraud
Protection Services: T o avoid charging you to filter recurring transactions
that you know are reliable, the fraud filters do not screen recurring
transactions. To screen a prospective recurring customer, submit the
transaction data using PayPal Manager's Transaction Terminal page. The
filters screen the transaction in the normal manner. If the transaction
triggers a filter, then you can follow the normal process to review the
filter results. Format: Y or N
2
InvNum Invoice number.
OrigInvNum
Date Invoice date: YYYYMMDD, ISO 8601.
OrderDateTime
BillFrom Name,
Address, EMail, Phone,
Fax, and URL
BillTo CustomerId,
Name, Address, EMail,
Phone, Phone2,
PhoneType, and Fax
BillTo PONum Buyer's purchase order number.
BillTo TaxExempt Indicates that the buyer is a tax exempt entity.
ShipCarrier Shipping carrier.
ShipMethod Shipping method.
ShipFrom and ShipTo Information about the shipping addresses, if different from BillFrom and
Information about the biller.
Information about the buyer.
BillTo respectively.
Description Summary description of the purchase. This field, in the case of an Amex
purchase card, can contain up to four separate descriptions of 40
characters each.
Items Full line-item breakdown of the purchase. Defined on page 28.
XMLPay Developer’s Guide 27
XMLPay Syntax
2
Core Structures
Attribute Description
DiscountAmt Discount to be applied to the item subtotal.
ShippingAmt T o tal of shipping and handling charges. For separate shipping and
handling amounts, use FreightAmt and HandlingAmt, respectively.
DutyAmt Duty fees (if applicable)
TaxAmt Total of all taxes.
NationalTaxIncl Boolean which when true, indicates that the national tax in included in
the TaxAmt.
TotalAmt Grand total (item subtotal - DiscountAmt + ShippingAmt (or
HandlingAmt + FreightAmt) + DutyAmt + TaxAmt).
FreightAmt Shipping charges without handling included.
HandlingAmt Handling charges without shipping included.
ItemAmt Sum of cost of all items in this order.
Items
Comment Free-form comment about the purchase.
Level3Invoice See Table 3.3, “Level 3 (commercial) credit card transaction parameters”
on page 52.
Memo Custom memo about the credit.
Custom Free-form field for your own use, such as a tracking number or other
value you want PayPal to return in the GetExpressCheckout response.
OrderDesc Description of items the customer is purchasing.
ExtData Optional element that may carry extended data (outside the syntax of the
XMLPay schema).
MerchantInfo Merchant name and location defined on page 30.
AdditionalAmounts Detail of a charge for additional breakdown of the amount, defined in
“AdditionalAmounts” on page 31.
SKU Merchant product SKU.
CustomerHostName Name of the server that the account holder is connected to.
CustomerBrowser Account holder’s HTTP browser type
Items is a list of line item detail records. Item is defined below.
<Items>
(Item)+
</Items>
28 XMLPay Developer’s Guide
XMLPay Syntax
Core Structures
Item
<Item Number=>
(SKU)?
(UPC)?
(Description)?
(Quantity)?
(UnitOfMeasurement)?
(UnitPrice)?
(DiscountAmt)?
(TaxAmt)?
(ShippingAmt)?
(FreightAmt)?
(HandlingAmt)?
(TotalAmt)?
<PickUp>
(Address)?
(Time)?
(Date)?
(RecordNumber)?
</PickUp>
<Delivery>
(Date)?
(Time)?
</Delivery>
(CostCenterNumber)?
(TrackingNumber)?
(CatalogNumber)?
(UNSPSCCode)?
(ExtData)*
</Item>
2
Attribute Description
Number Line number for the item in the invoice.
SKU Merchant's product code for the item (stock keeping unit).
UPC Item's universal product code.
Description Item's description.
Quantity Number of units of this item. UnitOfMeasurement provides the
units for Quantity (ISO 31).
UnitPrice Cost of each unit.
DiscountAmt Discount to be applied to this line item.
TaxAmt Total of all taxes for this line item.
XMLPay Developer’s Guide 29
XMLPay Syntax
2
Core Structures
Attribute Description
ShippingAmt Total of shipping and handling charges. For separate shipping
and handling amounts, use FreightAmt and HandlingAmt,
respectively.
FreightAmt Shipping charges without handling included.
HandlingAmt Handling charges without shipping included.
TotalAmt Total amount including tax and discount for this line item:
(Quantity * UnitPrice) + TaxAmt - DiscountAmt.
PickUp Address, Time, Date,
and RecordNumber
Delivery Date and Time Expected delivery date and time.
CostCenterNumber Purchaser's department number to which the item will be billed.
TrackingNumber Shipper’s tracking code
CatalogNumber Merchant’s product code (SKU may also be used for the same
UNSPSCCode Universal Standard Products and Services Classification. Global
ExtData Optional element that may carry extended data (outside the
MerchantInfo
<MerchantInfo>
</MerchantInfo>
Shipment pickup information
purpose).
marketplace classification system developed and managed by the
Electronic Commerce Code Management Association
(ECCMA).
syntax of the XMLPay schema).
(MerchantName)?
(MerchantStreet)?
(MerchantCity)?
(MerchantState)?
(MerchantCountryCode)?
(MerchantZip)?
Attribute Description
MerchantName Merchant’s name.
MerchantStreet Merchant’s street address, including number .
MerchantCity Merchant’s city name.
MerchantState Merchant’s state or province. For US addresses, two character s tate codes
should be used.
30 XMLPay Developer’s Guide
Loading...