Paypal Xmlpay 2009 Developers Guide Developer’s

XMLPay - 2009 - Developer’s Guide PP_PayflowPro_XMLPay_2009 Free User Guide for PayPal Software, Manual

2015-07-27

: Paypal Paypal-Xmlpay-2009-Developers-Guide-778023 paypal-xmlpay-2009-developers-guide-778023 paypal pdf

Open the PDF directly: View PDF .
Page Count: 162

Download
Open PDF In Browser	View PDF

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 in this document to you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information contained 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 this document or resulting from the application 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

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

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

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

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.

Chapter 2, “XMLPay Syntax,” presents the syntax for transaction requests, responses, and
receipts using a simplified notation.

Chapter 3, “XMLPay Elements,”provides tables defining the existing Payflow SDK
parameters (name/value pairs) and their XMLPay equivalents.

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.

Chapter 5, “XMLPay Examples,” gives several XMLPay document samples.

Appendix A, “XMLPay Schemas,” provides standard W3C schemas for XMLPay and
XMLPay Types.

Appendix B, “XMLPay DTD,” presents the Document Type Definition XMLPay schema.

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

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.

XMLPay Developer’s Guide

XMLPay Overview

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.

Benefits of XML
The main benefits of XML are that it:
z

Allows text annotation

Presents text, data, and content to applications as a structured document

Facilitates integration of diverse applications

In addition to these benefits, XML is easy to:

Read (all text)

Parse and validate

Search for content

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)

A single root element

Matching (case sensitive) start and end tags for all elements

All XML elements properly nested

Attribute values in quotes

XMLPay Developer’s Guide

XMLPay Overview
Using XMLPay

Example 1

MasterCard
495576040004
200011
CVNum>828

Example 2

Electric Toothbrush
1
100
100

ToothPaste
20
2
40

…

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.
N O T E : 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
XMLPay Developer’s Guide

XMLPay Overview
XMLPay Processing Models

Corporate purchase cards: Levels 1, 2, and 3

Automated Clearing House (ACH)

XMLPay Operations
Typical XMLPay operations include:
z

Funds authorization and capture

Sales and repeat sales

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.

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.

Merchant
Web Store
Financial
networks

Card 3455-342
$37.95

HTTPS (typical)

Buyer

BUY

Seller

XMLPay
Payment
Gateway

Payment
Processor

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

XMLPay Overview
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.
Trading
Exchange

Buyers

Sellers

XMLPay

Payment
Gateway

Financial
networks

Payment
Processor

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.

XMLPay Developer’s Guide

XMLPay Overview
XMLPay Messaging

XMLPayRequest
Payment transactions are submitted, one or more at a time, as XMLPayRequest documents.
The high-level structure of a request looks like this:

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

XMLPay Overview
XMLPay Messaging
N O T E : Signature and

TransactionReceipts are not supported on the Payment server.

See Chapter 2, “XMLPay Syntax,” for a detailed description of response documents.

XMLPay Developer’s Guide

XMLPay Syntax

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.

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:

(element)
(optionalElement)?
(alternativeElement1|alternativeElement2)
(element)+
(element)*

element

Indicates the occurrence of a (possibly complex) XML element (for
example, ...) 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.

N O T E : The

Payflow SDK SDK download package provides specific examples of XML
documents using the Pro client service.

The XMLPayRequest Document (Transactions)

(Vendor)
(Partner)

XMLPay Developer’s Guide

XMLPay Syntax
The XMLPayRequest Document (Transactions)

(Transaction)+

(RequestAuth)?

Attribute

Description

Vendor

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

Transaction

Defined on page 16. XMLPay supports up to 32 transactions per
XMLPay document submission.

RequestAuth

Defined on page 21.

Timeout

The value of this attribute is ignored.

Transaction
XMLPay supports up to 32 transactions per XMLPay document submission.

Attribute

Description

Optional attribute that tracks the transaction through the paymentprocessing 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.

XMLPay Developer’s Guide

XMLPay Syntax
The XMLPayRequest Document (Transactions)

(Invoice)
(Tender)

(ExtData)*

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.

(PNRef)
(Invoice)?
(ExtData)*

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.

(Invoice)
(Tender)

(ExtData)*

Attribute

Description

PayData

Specifies the details of the purchase, within Invoice, as well as the
payment Tender to use.

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

Credit Transaction

A credit transaction reverses a previous sale or capture transaction.

(PNRef|Tender)
(Invoice)?
(ExtData)*

Attribute

Description

PNRef|Tender

The transaction to be credited is identified by PNRef. Acredit may be run
without a PNRef by providing the Tender for the account to be credited
and Invoice for the amount.

Invoice

In the case of a partial credit, you must provide Invoice and provide
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.

(PNRef)
(ExtData)*

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.

(Authorization|Sale)
(ExtData)*

XMLPay Developer’s Guide

XMLPay Syntax
The XMLPayRequest Document (Transactions)

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.

(Authorization|Sale)
(ExtData)*

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

DoExpressCheckout Transaction

DoExpressCheckout obtains payment through Express Checkout for a Sale transaction or
requests an Authorization for a later capture of payment.

(Authorization|Sale)
(ExtData)*

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

(Invoice)

XMLPay Developer’s Guide

XMLPay Syntax
The XMLPayRequest Document (Transactions)

(Tender)

(AuthCode)
(ExtData)*

Attribute

Description

AuthCode

Authorization code received out-of-band.

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

GetStatus Transaction

A GetStatus transaction queries the status of a previous transaction.

(PNRef)
(ExtData)*

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.

(Invoice)
(Tender)

(ExtData)*

Attribute

Description

PayData

Specifies the details of the credit card used in the purchase.

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 Protection Services User’s Guide on the sequence of steps involved in performing a
Buyer Authentication transaction.

(ExtData)*

Attribute

Description

PARes

The authentication data returned by Issuer's ACS.

ExtData

Optional element that may carry extended data (outside the syntax of the
XMLPay schema).

RequestAuth
The RequestAuth element provides authentication of the requestor through either a username
and password, using UserPass, or a digital signature, using Signature.

(UserPass|Signature)

In the case of a digital signature, the W3C XML Signature syntax is used and the signature is
executed over the RequestData.
UserPass

(User)
(UserDomain)?
(Password)

Attribute

Description

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

XMLPay Syntax
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.

(Vendor)
(Partner)

(RecurringProfile)+

(RequestAuth)?

Attribute

Description

Vendor

Identifies 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

Attribute

Description

Optional attribute that tracks the transaction through the paymentprocessing 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.

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 define the profile or by
converting an existing transaction into a profile.

(RPData)
(Tender)

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.

(RPData)
(Tender)
(ProfileID)

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.

(ProfileID)

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

XMLPay Syntax
The XMLPayRequest Document (Recurring Profiles)

(RPData)
(Tender)
(ProfileID)

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.

(RPData)
(Tender)
(ProfileID)

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.

(ProfileID)

Attribute

Description

ProfileID

Profile ID of the profile you want to review.

XMLPay Developer’s Guide

XMLPay Syntax
Core Structures

C o r e St r u c t u r e s
PayData

(Invoice)
(Tender)

Attribute

Description

Invoice

Describes the details of a purchase. Defined on page 25.

Tender

Describes the payment instrument. Defined on page 32.

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

(PKCS7Signature|Signature)

Invoice

(CustIP)*
(MerchantDescription)*
(MerchantServiceNum)*
(Recurring)*
(InvNum)?
(OrigInvNum)*
(Date)?
(OrderDateTime)*

(Name)?
(Address)?
(EMail)?
(Phone)?
(Fax)?
(URL)?

(CustomerId)*
(Name)?
(Address)?

XMLPay Developer’s Guide

XMLPay Syntax
Core Structures

(EMail)?
(Phone)?
(Phone2)?
(Fax)?
(CustCode)?
(PONum)?
(TaxExempt)?
(PhoneType)?

?
?

(Name)?
(Address)?
(EMail)?
(Phone)?
(Fax)?
(ShipFromEU)?

(Name)?
(Address)?
(EMail)?
(Phone)?
(Phone2)
(Fax)?
(ShipToEU)?

(Description)*
(Items)*
(DiscountAmt)?
(ShippingAmt)?
(DutyAmt)?
(TaxAmt)?
(NationalTaxIncl)?
(TotalAmt)?
(FreightAmt)?
(HandlingAmt)?
(ItemAmt)?
(Comment)?
(Level3Invoice)
(Memo)
(Custom)
(OrderDesc)
(ExtData)*
(MerchantInfo)*
(AdditionalAmounts)*
(SKU)*
(CustomerHostName)*
(CustomerBrowser)*

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: To 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

InvNum

Invoice number.

OrigInvNum
Date

Invoice date: YYYYMMDD, ISO 8601.

OrderDateTime
BillFrom Name,
Address, EMail, Phone,
Fax, and URL

Information about the biller.

BillTo CustomerId,
Name, Address, EMail,
Phone, Phone2,
PhoneType, and Fax

Information about the buyer.

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

XMLPay Syntax
Core Structures

Attribute

Description

DiscountAmt

Discount to be applied to the item subtotal.

ShippingAmt

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

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
Items is a list of line item detail records. Item is defined below.

(Item)+

XMLPay Developer’s Guide

XMLPay Syntax
Core Structures

Item

(SKU)?
(UPC)?
(Description)?
(Quantity)?
(UnitOfMeasurement)?
(UnitPrice)?
(DiscountAmt)?
(TaxAmt)?
(ShippingAmt)?
(FreightAmt)?
(HandlingAmt)?
(TotalAmt)?

(Address)?
(Time)?
(Date)?
(RecordNumber)?

(Date)?
(Time)?

(CostCenterNumber)?
(TrackingNumber)?
(CatalogNumber)?
(UNSPSCCode)?
(ExtData)*

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

XMLPay Syntax
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

Shipment pickup information

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
purpose).

UNSPSCCode

Universal Standard Products and Services Classification. Global
marketplace classification system developed and managed by the
Electronic Commerce Code Management Association
(ECCMA).

ExtData

Optional element that may carry extended data (outside the
syntax of the XMLPay schema).

MerchantInfo

(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 state codes
should be used.

XMLPay Developer’s Guide

XMLPay Syntax
Core Structures

Attribute

Description

MerchantCountryCode

Merchant’s country code (ISO 3166). Default is US.

MerchantZip

Merchant’s postal code.

AdditionalAmounts

(Amount1)?
(Amount2)?
(Amount3)?
(Amount4)?
(Amount5)?

Attribute

Description

Amount1
Amount2
Amount3
Amount4
Amount5

Address

(Street)?
(City)?
(State)?
(Zip)?
(Country)?

Attribute

Description

Street

Street address, including number.

City

City name.

State

State or province. For US addresses, two character state codes should be
used.

Zip

Postal code.

Country

Country code (ISO 3166). Default is US.

XMLPay Developer’s Guide

XMLPay Syntax
Core Structures

Tender

(ACH|Card|Check|Debit|PayPal)

ACH

ACH (Automated Clearing House) tender detail.

(AcctType)
(AcctNum)
(ABA)
(Prenote)?
(AuthType)
(CheckNum)
(TermCity)
(TermState)
(DL)
(SS)
(DOB)
(DLState)
(BankName)
(SellerMsg)
(BusName)
(ExtData)*

Attribute

Description

AcctType

Type of the bank account: checking or savings.

AcctNum

Account number.

ABA

Bank routing number.

AuthType

Method of authorization.

Prenote

Boolean. If true, then the purpose of this transaction is not to move
money, but to establish authorization for future transactions to be
submitted on a recurring basis.

ExtData

Optional element that may carry extended data (outside the syntax of the
XMLPay schema).

Card

Retail Credit/Debit and Corporate Purchase Card tender detail.

(CardType)
(CardNum)
(ExpDate)

XMLPay Developer’s Guide

XMLPay Syntax
Core Structures

(CVNum)?
(MagData)?
(NameOnCard)?
(ExtData)*

Attribute

Description

CardType

Optional. Identifies the type of card for the merchant’s records. Card
types are:
Visa
MasterCard
Amex
JCB
Discover
DinersClub
The server does not use this value, but rather uses the card number to
determine the card type.

CardNum

Account number.

ExpDate

Card expiration date: YYYYMM or ISO 8601.

CVNum

Card verification number (typically printed on the back of the card, but
not embossed on the front).

MagData

Data located on the magnetic strip of a credit card.

NameOnCard

Card holder's name as printed on the card.

ExtData

Optional element that may carry extended data (outside the syntax of the
XMLPay schema).

Check

Check tender detail.

(CheckType)
(CheckNum)
(MICR)
(DL)?
(SS)?
(DOB)?
(ExtData)*

Attribute

Description

CheckType

Indicates the type of the check: corporate, personal, or government.

CheckNum

Account holder's next unused check number.

XMLPay Developer’s Guide

XMLPay Syntax
Core Structures

Attribute

Description

MICR

Magnetic Ink Check Reader (MICR) is the entire line of numbers at the
bottom of the check. It includes the transit number, account number, and
check number.

Account holder's driver's license number. XxNnnnnnnn format, where
Xx is the state code; Nnnnnnnn is the number

Account holder's social security number.

DOB

Account holder's date of birth YYYYMMDD, ISO 8601

ExtData

Optional element that may carry extended data (outside the syntax of the
XMLPay schema).

PayPal

PayPal tender detail.

(EMail)*
(PayerID)*
(Token)*
(ReturnURL)*
(CancelURL)*
(NotifyURL)*
(ReqConfirmShippiing)*
(NoShipping)*
(AddressOverride)*
(LocaleCode)*
(PageStyle)*
(HeaderImage)*
(HeaderBorderColor)*
(HeaderBackColor)*
(PayflowColor)*
(ButtonSource)*
(ExtData)*

Attribute

Description

Email address of customer as entered during checkout. PayPal uses this
value to pre-fill the PayPal membership signup portion of the PayPal
login page.

PayerId

Unique encrypted PayPal customer account identification number

Token

A string value returned by Set Express Checkout response.

XMLPay Developer’s Guide

XMLPay Syntax
Core Structures

Attribute

Description

ReturnURL

URL to which the customer’s browser is returned after approving use of
PayPal.
Set RETURNURL to your order review page or the page on which the
customer clicked the “Edit Shipping” button or hyperlink.

NotifyURL

Your URL for receiving Instant Payment Notification (IPN) about this
transaction.

ReqConfirmShipping

Is 1 or 0. The value 1 indicates that you require that the customer’s
shipping address on file with PayPal be a confirmed address.
Setting this element overrides the setting you have specified in your
Merchant Account Profile.

NoShipping

Is 1 or 0. The value 1 indicates that on the PayPal pages, no shipping
address fields should be displayed whatsoever.

AddressOverride

Is 1 or 0. The value 1 indicates that the PayPal pages should display the
shipping address set by you in the shipping address (SHIPTO*
parameters) passed to this Set Express Checkout request, not the shipping
address on file with PayPal for this customer.
Displaying the PayPal street address on file does not allow the customer
to edit that address.

LocaleCode

Locale of pages displayed by PayPal during Express Checkout.

PageStyle

Sets the Custom Payment Page Style for payment pages associated with
this button/link. PageStyle corresponds to the HTML variable page_style
for customizing payment pages.

The value is the same as the Page Style Name you chose when adding or
editing the page style from the Profile subtab of the My Account tab of
your PayPal account.
HeaderImage

A URL for the image you want to appear at the top left of the payment
page. The image has a maximum size of 750 pixels wide by 90 pixels
high. PayPal recommends that you provide an image that is stored on a
secure (https) server.

HeaderBorderColor

Sets the border color around the header of the payment page. The border
is a 2-pixel perimeter around the header space, which is 750 pixels wide
by 90 pixels high.

HeaderBackColor

Sets the background color for the header of the payment page.

PayflowColor

Sets the background color for the payment page.

ButtonSource

Identification code for use by third-party applications to identify
transactions.

ExtData

Optional element that may carry extended data (outside the syntax of the
XMLPay schema).

XMLPay Developer’s Guide

XMLPay Syntax
Core Structures

RPData
Recurring Profile payment and scheduling details.

(Name)?
(TotalAmt)?
(Start)?
(Term)?
(PayPeriod)?
(MaxFailPayments)?
(RetryNumDays)?
(EMail)?
(CompanyName)?
(Comment)?
(OptionalTrans)?
(OptionalTransAmt)?

(Name)?
(Address)?
(Phone)?
(Fax)?

(OrigProfileID)?
(PaymentNum)?
(ExtData)*

Attribute

Description

Name

Account holder's name.

TotalAmt

Dollar amount (US dollars) to be billed.

Start

Beginning (or restarting) date for the recurring billing cycle used to
calculate when payments should be made.

Term

Number of payments to be made over the life of the agreement.

PayPeriod

Specifies how often the payment occurs.

MaxFailPayments

The number of payment periods (specified by PayPeriod) for which the
transaction is allowed to fail before PayPal cancels a profile.

RetryNumDays

The number of consecutive days that PayPal should attempt to process a
failed transaction until Approved status is received.

XMLPay Developer’s Guide

XMLPay Syntax
The XMLPayResponse Document (Transactions)

Attribute

Description

Customer e-mail address.

CompanyName

Company name for this profile.

Comment

Free-form comment about the purchase.

OptionalTrans

Defines an optional Authorization for validating the account information
or for charging an initial fee.

OptionalTransAmt

Amount of the Optional Transaction.

BillTo Name, Address,
Phone, and Fax

Information about the buyer.

ShipTo Name, Address,
Phone, and Fax

Information about the shipping addresses, if different from BillTo.

OrigProfileID

Profile ID of the profile that gets the action.

PaymentNum

Payment number identifying the failed payment to be retried.

ExtData

Optional element that may carry extended data (outside the syntax of the
XMLPay schema).

ExtData

Attribute

Description

Name

Name of the extended data element.

Value

Value of the extended data element.

The XMLPayResponse Document (Transactions)

(Vendor)
(Partner)

(TransactionResult)+

(Signature)?
(TransactionReceipts)?

XMLPay Developer’s Guide

XMLPay Syntax
The XMLPayResponse Document (Transactions)

Attribute

Description

Vendor

Identifies the merchant of record for the transaction within the payment
processing network.

Partner

Identifies the partner who submitted the transaction on behalf of the
vendor.

TransactionResult

Defined on page 38.

Signature

Optional signature over ResponseData, executed by the payment
processing gateway using the W3C XML Signature syntax. This
signature may be used to provide integrity protection of the response data
and/or authentication of the responder, if needed (transport-level security
may also be used to provide these protections).

TransactionReceipts

Optional list of receipts from the payment processing network.

TransactionResult

(Result)
(BuyerAuthResult)?
(ProcessorResult)?
(FraudPreprocessorResult)?
(FraudPostprocessorResult)?
(CardSecure)?
(IAVSResult)?
(AVSResult)?
(CVResult)?
(Message)?
(PNRef)?
(AuthCode)?
(HostCode)?
(HostURL)?
(OrigResult)?
(Status)?
(ReceiptURL)?
(ACHStatus)?
(OrigPNRef)?
(OrigMessage)?
(PayPalResult)?
(ExtData)*

XMLPay Developer’s Guide

XMLPay Syntax
The XMLPayResponse Document (Transactions)

Element

Description

Result

Number that indicates outcome of the transaction (see Appendix C,
“Transaction Results”).

BuyerAuthResult

Results of the VerifyEnrollment or ValidateAuthentication
transaction.

ProcessorResult

Processor-specific information. Only received if Verbosity is set to
High.

FraudPreprocessorResult

Results from the Fraud Protection Service pre-process stage.

FraudPostprocessorResult

Results from the Fraud Protection Service post-process stage.

CardSecure

CAVV information returned from the processor.

IAVSResult

International AVS result value, if appropriate.

AVSResult

Results of the AVS check, if appropriate.

CVResult

Results of the CV check, if appropriate. Possible values: match, no
match, service not available, or service not requested.

Message

Descriptive message describing Result.

PNRef

Identifier assigned to the transaction by the payment processing
network.

AuthCode

Authorization code for the transaction provided by the bank, if any.

HostCode

Result code returned by the payment processor, if any. Whereas
Result provides a normalized view the transaction status, HostCode
passes through the back-end processor status unmodified.

HostURL

URL returned by the payment processor, if any, to use in referring to
the transaction.

OrigResult

Original result for a transaction queried with GetStatus.

Status

Current status for a transaction queried with GetStatus.

ACHStatus

Status of the ACH transaction (returned by Inquiry transaction).

OrigPNRef

The PNRef value associated with the original transaction (returned
by Inquiry transaction).

OrigMessage

The Message value associated with the original transaction
(returned by Inquiry transaction).

PayPalResult
ReceiptURL

XMLPay Developer’s Guide

URL returned by the payment processor, if any, to use in referring to
a receipt for the transaction.

XMLPay Syntax
The XMLPayResponse Document (Transactions)

Element

Description

ExtData

Optional element that may carry extended data (outside the syntax
of the XMLPay schema).

Attribute

Description

Result

Number that indicates outcome of the transaction (see Appendix C,
“Transaction Results”).

CustRef

Reference string that identifies the customer.

Duplicate

Identify if the transaction has been run before.

AVSResult

(StreetMatch)
(ZipMatch)

Attribute

Description

StreetMatch

Indicates whether or not the billing street address matched the bank's
records. Possible values: match, no match, service not available, or
service not requested.

ZipMatch

Indicates whether or not the billing zip matched the bank's records.
Possible values: match, no match, service not available, or service not
requested.

PayPalResult

(EMail?)
(PayerID?)
(Token?)
(PPRef?)
(FeeAmount)
(PayerStatus?)
(PaymentType?)
(PendingReason?)
(Custom?)
(InvNum?)
(Phone?)
(Name?)
(ShipTo?)
(CorrelationID?)

XMLPay Developer’s Guide

XMLPay Syntax
The XMLPayResponse Document (Recurring Profiles)

Attribute

Description

Customer’s email address.

PayerID

Unique encrypted PayPal customer account identification number

Token

Value PayPal originally returns in Set Express Checkout response after
your first call to the Set Express Checkout request.

PPRef

Unique transaction ID of the payment.
If the request ACTION was A (Authorization), you should store the value
of PPREF if you need to research a specific transaction with PayPal.

FeeAmount

PayPal fee amount charged for the transaction.

PayerStatus

Status of payer.

PaymentType

Indicates whether the payment is instant or delayed.

PendingReason

The reason the payment is pending. Values are: none, echeck, intl, multicurrency, verify, other, and completed.

Custom

Free-form field for your own use.

InvNum

Merchant invoice number. The merchant invoice number is used for
authorizations and settlements and, depending on your merchant bank,
will appear on your customer's credit card statement and your bank
reconciliation report. If you do not provide an invoice number, the
transaction ID (PNREF) will be submitted.

Phone

Account holder’s telephone number.

ShipTo Name, Address,
EMail, Phone, Phone2,
Fax, and ShipToEU

Information about the shipping addresses, if different from BillTo.

CorrelationID

Value used for tracking this Direct Payment transaction.

The XMLPayResponse Document (Recurring Profiles)

(Vendor)
(Partner)

(RecurringProfileResult)+

(Signature)?
(TransactionReceipts)?

XMLPay Developer’s Guide

XMLPay Syntax
The XMLPayResponse Document (Recurring Profiles)

Attribute

Description

Vendor

Identifies the merchant of record for the transaction within the
payment processing network.

Partner

Identifies the partner who submitted the transaction on behalf of the
vendor.

RecurringProfileResult

Defined on page 43.

Signature

Optional signature over ResponseData, executed by the payment
processing gateway using the W3C XML Signature syntax. This
signature may be used to provide integrity protection of the response
data and/or authentication of the responder, if needed (transport-level
security may also be used to provide these protections).

TransactionReceipts

Optional list of receipts from the payment processing network.

BuyerAuthResult
Response for Buyer Authentication transactions, VerifyEnrollment and
ValidateAuthentication.

(Status)
(AuthenticationId)?
(PAReq)?
(ACSUrl)?
(ECI)?
(CAVV)?
(XID)?

Attribute

Description

Status

Status of the transaction.

AuthenticationId

Message id for the response.

PAReq

Payer authentication request returned if cardholder is enrolled.

ACSUrl

The issuer ACS URL at which the cardholder would authenticate by
providing the password.

ECI

The Electronic Commerce Indicator value that implies the authentication
outcome. Defaulted to 7 since cardholder has not authenticated yet.

CAVV

Cardholder Authentication Verification Value.

XID

Transaction ID.

XMLPay Developer’s Guide

XMLPay Syntax
The XMLPayResponse Document (Recurring Profiles)

RecurringProfileResult
Non-Inquiries

Response for Add, Modify, Cancel, Reactivate, and Payment actions.

(Result)
(Message)?
(ProfileID)?
(RPRef)?
(TransactionResult)?
(ExtData)*

Attribute

Description

Result

Number that indicates outcome of the transaction (see Appendix C,
“Transaction Results”).

Message

Descriptive message describing Result.

ProfileID

Profile ID of the profile that gets the action.

RPRef

Identifier assigned to the transaction by the payment processing network.

TransactionResult
ExtData

Optional element that may carry extended data (outside the syntax of the
XMLPay schema).

Identifier assigned to the transaction by the merchant (if one was
provided in the transaction request).

Inquiries

Response for Inquiry action.

(Result)
(Message)?
(ProfileID)?
(RPRef)?
(Status)?
(Name)?
(Start)?
(Term)?
(End)?
(PayPeriod)?
(MaxFailPayments)?
(RetryNumDays)?
(EMail)?
(CompanyName)?
(Amt)?

XMLPay Developer’s Guide

XMLPay Syntax
The XMLPayResponse Document (Recurring Profiles)

(PaymentsLeft)?
(NextPayment)?
(AggregateAmt)?
(AggregateOptionalTransAmt)?
(NumFailedPayments)?
(Tender)?
(BillTo)?
(ShipTo)?
(ExtData)*

Attribute

Description

Result

Number that indicates outcome of the transaction (see Appendix C,
“Transaction Results”).

Message

Descriptive message describing Result.

ProfileID

Profile ID of the profile that gets the action.

RPRef

Identifier assigned to the transaction by the payment processing
network.

Status

Current status of the profile.

Name

Account holder's name.

Start

Beginning (or restarting) date for the recurring billing cycle used to
calculate when payments should be made.

Term

Number of payments to be made over the life of the agreement.

End

Date that the last payment is due. Present only if this is not an
unlimited-term subscription.

PayPeriod

Specifies how often the payment occurs.

MaxFailPayments

The number of payment periods (specified by PayPeriod) for
which the transaction is allowed to fail before PayPal cancels a
profile.

RetryNumDays

The number of consecutive days that PayPal should attempt to
process a failed transaction until Approved status is received.

Customer e-mail address.

CompanyName

Company name for this profile.

Amt

Dollar amount (US dollars) to be billed.

PaymentsLeft

Number of payments left to be billed.

NextPayment

Date that the next payment is due

AggregateAmt

Amount collected so far for scheduled payments.

XMLPay Developer’s Guide

XMLPay Syntax
The XMLPayResponse Document (Recurring Profiles)

Attribute

Description

AggregateOptionalTransAmt

Amount collected through sending optional transactions

NumFailedPayments

Number of payments that failed.

Tender

Specifies payment type.

BillTo

Information about the buyer.

ShipTo

Information about the shipping addresses, if different from BillTo.

ExtData

Optional element that may carry extended data (outside the syntax
of the XMLPay schema).

XMLPay Developer’s Guide

XMLPay Syntax
The XMLPayResponse Document (Recurring Profiles)

XMLPay Developer’s Guide

XMLPay Elements

The following tables define the existing Payflow SDK parameters (name/value pairs) and their
XMLPay equivalent. Some parameters cannot be processed by specific processors. For details
on what your processor can process, see Payflow Pro Developer’s Guide.
If you are developing applications that use the Recurring Billing Service, see Recurring
Billing Service User’s Guide.That document provides detailed information about Payflow
SDK parameters specific to Recurring Billing.
N O T E : ExtData is an optional XMLPay element for including parameter data not supported by

the schema you are using. Place the data at the appropriate element level in the
XMLPay hierarchy. If you can’t find or are unsure of the appropriate location, place the
data in the Invoice element. See the examples in “Express Checkout Authorization
Transaction” on page 84.

General Transaction Parameters
The following are general parameters accepted in Payflow SDK transactions.
TABLE 3.1

Retail credit card transaction parameters

Payflow SDK
Parameter

Description

XMLPay Element

COMMCARD

Type of commercial card account number sent.

Card→CommercialCard

COUNTRYCODE

Destination country code. (See the appendix
entitled “ISO Country Codes” in the Payflow
Pro Developer’s Guide.)

ShipTo→Address→Country

COMPANYNAME

Billing country code

BillTo→Address→Company

CUSTIP

IP address of customer

Invoice→CustIP

ECI

Values returned from Buyer Auth transaction

Card→BuyerAuthResult→ECI

MERCHDESCR

Description of product.

Invoice→MerchantDescription

MERCHSVC

Merchant telephone number, including area
code (XXX-XXX-XXXX)

Invoice→MerchantServiceNum

ORDERDATE

Date of invoice

Invoice→Date

RECURRING

Recurring transaction?

Invoice→Recurring

UPDATEACTION

Update action to take

TransactionUpdate→Action

VERBOSITY

Verbosity level of response desired

Transaction→Verbosity

XMLPay Developer’s Guide

XMLPay Elements
Credit Card Transaction Parameters

Credit Card Transaction Parameters
The following parameters are accepted in Payflow SDK credit card transactions.

Retail Credit Card Transaction Parameters
Table 3.2 lists retail credit card transaction parameters.
TABLE 3.2

Retail credit card transaction parameters

Payflow SDK Parameter

Description

XMLPay Element

ABA

Bank routing number.

ABA

ACCT

The credit card or purchase card number

AcctNum or CardNum

ACCTTYPE

Type of the bank account.

AcctType or CheckType

AMT

Amount in US dollars.

Invoice→TotalAmt

AUTHCODE

The approval code obtained over the phone
from the processing network. Used only
when processing Voice Authorization
transactions.

AuthCode

AUTHTYPE

Method of authorization.

AuthType

CHKNUM

Check number.

CheckNum

CHKTYPE

Type of the bank account.

AcctType

CITY

Cardholder’s city.

City

COMMCARD

Type of commercial card account number
sent.

Card→CommercialCard

COMMENT1

Merchant-defined value for reporting and
auditing purposes.

Comment

COMMENT2

Merchant-defined value for reporting and
auditing purposes.

ExtData

COUNTRY

Destination country code. (See the appendix
entitled “ISO Country Codes” in the Payflow
Pro Developer’s Guide.)

Country

CUSTCODE

Customer code or customer reference ID.

CustCode

CUSTREF

Merchant-defined identifier for reporting and
auditing purposes.

CustRef

CVV2

The 3 or 4-digit Card Security Code (CSC)
found on the back of a credit card.

CVNum

DESC

General description of the transaction.

Item→Description

XMLPay Developer’s Guide

XMLPay Elements
Credit Card Transaction Parameters
TABLE 3.2

Retail credit card transaction parameters

Payflow SDK Parameter

Description

XMLPay Element

DESC1-4

Up to 4 additional lines describing the
transaction.

Item→Description

DISCOUNT

Discount amount on total sale.

DiscountAmt

Cardholder’s driver’s license number.

DOB

Cardholder’s date of birth.

DOB

DSGUID

Transaction ID

DUTYAMT

Duty or import tax.

DutyAmt

Email address.

ENDTIME

Specifies the end of the time period during
which the transaction specified by the
CUSTREF occurred. Optional for Inquiry
transactions when using CUSTREF to specify
the transaction.

ExtData

EXECUTOR

Names a partner or a vendor under whose
auspice a transaction is being submitted.

UserDomain

EXPDATE

Expiration date of the credit card.

ExpDate

FIRSTNAME

The cardholder’s name.

Name or NameOnCard

FREIGHTAMT

Freight amount.

FreightAmt or ShippingAmt

HANDLINGAMT

Handling amount.

Item→HandlingAmt

INVNUM

Merchant invoice number.

Invoice→InvNum

INVOICEDATE

Invoice date.

Date

L_AMT

Total line item amount including tax and
discount.

Invoice→TotalAmt

L_CARRIERSHIPMENTNUM

Shipment number.

ShipmentNumber

L_CATALOGNUM

Merchant’s product code.

CatalogNumber

L_COSTCENTERNUM

Purchaser's department number to which the
item will be billed.

CostCenterNumber

L_COST

Cost per item, excluding tax.

UnitPrice

L_DELIVERYDATE

Delivery date.

Date

L_DELIVERYTIME

Delivery time.

Time

L_DESC

Item description.

Item→Description

L_DISCOUNT

Discount per line item.

DiscountAmt

L_FREIGHTAMT

Line item freight amount.

FreightAmt

XMLPay Developer’s Guide

XMLPay Elements
Credit Card Transaction Parameters
TABLE 3.2

Retail credit card transaction parameters

Payflow SDK Parameter

Description

XMLPay Element

L_HANDLINGAMT

Line item handling amount.

Item→HandlingAmt

L_PICKUPCITY

Pickup city.

City

L_PICKUPCOUNTRY

Pickup record number.

Country

L_PICKUPDATE

Pickup date.

Date

L_PICKUPRECORDNUM

Pickup record number.

RecordNumber

L_PICKUPSTATE

Pickup state.

State

L_PICKUPSTREET

Pickup address.

Street

L_PICKUPTIME

Pickup time.

Time

L_PICKUPZIP

Pickup postal code.

Zip

L_PRODCODE

Supplier-specific product code.

SKU

L_QTY

Line item quantity.

Item→Quantity

L_SKU

Line item SKU identifier.

SKU

L_TAXAMT

Line item tax amount.

Item→TaxAmt

L_TRACKINGNUM

Tracking number.

TrackingNumber

L_UNSPSCCODE

Universal Standard Products and Services
Classification.

UNSPSCCode

L_UOM

Item unit of measure.

UnitOfMeasurement

L_UPC

Item commodity code.

UPC

MICR

Data located on the magnetic strip of a credit
card.

MagData or MICR

NATINCL

National tax included (true or false).

NationalTaxIncl

ORDERDATE

Order date.

ExtData

ORIGID

The Reference ID (PNREF) returned for all
transactions.

PNRef

PARTNER

The ID provided to you by the authorized
Reseller who registered you for the Website
Payments Pro Payflow Edition service. If you
purchased your account directly from PayPal,
use PayPal.
This value is case-sensitive.

Partner

PHONENUM

Telephone number.

Phone

PHONETYPE

Telephone call type identifier

BillTo→PhoneType

XMLPay Developer’s Guide

XMLPay Elements
Credit Card Transaction Parameters
TABLE 3.2

Retail credit card transaction parameters

Payflow SDK Parameter

Description

XMLPay Element

PONUM

Specified by the cardholder to identify the
order. Usually used as a Purchase Order
number.

BillTo→PONum

PRENOTE

Identifies the transaction as an authorization
for future transactions.

Prenote

PWD

The 6- to 32-character password that you
defined while registering for the account.
This value is case-sensitive.

Password

RECURRING

Identifies the transaction as recurring.

ExtData

SHIPFROMZIP

Ship-from postal code.

Zip

SHIPTOCITY

Ship-to city.

ShipTo→Address→City

SHIPTOFIRSTNAME

Ship-to name.

Name

SHIPTOSTATE

Ship-to state.

ShipTo→Address→State

SHIPTOSTREET

Ship-to street.

ShipTo→Address→Street

SHIPTOZIP

Ship-to postal code.

ShipTo→Address→Zip

Cardholder’s Social Security Number.

STARTTIME

Specifies the beginning of the time period
during which the transaction specified by the
CUSTREF occurred. Optional for Inquiry
transactions when using CUSTREF to specify
the transaction.

ExtData

STATE

Cardholder’s state.

State

STREET

The cardholder’s street address (number and
street name).

Street

SWIPE

Used to pass the Track 1 or Track 2 data (the
card’s magnetic stripe information) for cardpresent transactions.

MagData

TAXAMT

Tax amount.

Item→TaxAmt

TAXEXEMPT

Tax exempt status.

TaxExempt

TENDER

The method of payment.

Tender

XMLPay Developer’s Guide

XMLPay Elements
Credit Card Transaction Parameters
TABLE 3.2

Retail credit card transaction parameters

Payflow SDK Parameter

Description

XMLPay Element

TRXTYPE

The type of transaction. For XMLPay:
z Authorization
z Capture
z Sale
z Credit
z Void
z ForceCapture
z RepeatSale
z GetStatus

XMLPay transaction type

USER

If you set up one or more additional users on
the account, this value is the ID of the user
authorized to process transactions. If,
however, you have not set up additional users
on the account, USER has the same value as
VENDOR.
This value is case sensitive.

UserName

VENDOR

Your merchant login ID that you created
when you registered for the account.
This value is case sensitive.

Vendor

ZIP

The cardholder’s postal code.

Zip

Level 3 (Commercial) Credit Card Transaction Parameters
Table 3.3 lists level 3 (commercial) credit card transaction parameters.
TABLE 3.3

Level 3 (commercial) credit card transaction parameters

Payflow SDK Parameter

Description

XMLPay Element

ALLTAXEXEMPTCODE

Tax exempt code

Level3Invoice→AllTax

ALLTAXPERCENT

Tax rate

Level3Invoice→AllTax

ALTTAXAMT

Tax amount

Level3Invoice→AllTax

ALTERNATETAXAMT

Alternate tax amount

Level3Invoice→
AlternateTaxAmount

ALTERNATETAXID

Alternate tax ID number

Level3Invoice→
AlternateTaxID

BGNAME

Buying Group name

Level3Invoice→
BuyingGroup

BGFIRSTADDR

Buying Group first address line

Level3Invoice→
BuyingGroup

XMLPay Developer’s Guide

XMLPay Elements
Credit Card Transaction Parameters
TABLE 3.3

Level 3 (commercial) credit card transaction parameters

Payflow SDK Parameter

Description

XMLPay Element

BGSECONDADDR

Buying Group second address
line

Level3Invoice→
BuyingGroup

BGCITY

Buying Group city

Level3Invoice→
BuyingGroup

BGSTATE

Buying Group state

Level3Invoice→
BuyingGroup

BGZIP

Buying Group zip code

Level3Invoice→
BuyingGroup

BGCOUNTRY

Buying Group country

Level3Invoice→
BuyingGroup

CARDSTART

Starting date printed on card
(Switch Solo only)

Level3Invoice→
CardStart

CARDISSUE

Issue number printed on card
(Switch Solo only)

Level3Invoice→
CardIssue

COUNTYTAXAMT

County tax amount

Level3Invoice→
CountyTax

COUNTYTAXEXEMPTCODE

County tax exempt code

Level3Invoice→
CountyTax

COUNTYTAXPERCENT

County tax rate

Level3Invoice→
CountyTax

COUNTYSALESTAXAMT

County sales tax amount

Level3Invoice→
CountySalesTax

COUNTYSALESTAXEXEMPTCODE

County sales tax exempt code

Level3Invoice→
CountySalesTax

COUNTYSALESTAXPERCENT

County sales tax amount

Level3Invoice→
CountySalesTax

CITYTAXAMT

City tax amount

Level3Invoice→CityTax

CITYTAXEXEMPTCODE

City tax exempt code

Level3Invoice→CityTax

CITYTAXPERCENT

City tax rate

Level3Invoice→CityTax

COMMCODE

Commercial code for business
cards (not typically used)

Level3Invoice→
CommCode

CUSTVATREGNUM

Customer value added tax
registration number

Level3Invoice→
CustomerValueAddedTaxRegNum

EVTAXAMT

Environmental tax amount

Level3Invoice→
EnvironmentalTax

XMLPay Developer’s Guide

XMLPay Elements
Credit Card Transaction Parameters
TABLE 3.3

Level 3 (commercial) credit card transaction parameters

Payflow SDK Parameter

Description

XMLPay Element

EVTAXEXEMPTCODE

Environmental tax exempt code

Level3Invoice→
EnvironmentalTax

EVTAXPERCENT

Environmental tax rate

Level3Invoice→
EnvironmentalTax

FREIGHTRATE

Rate charged for shipping

Level3Invoice→
FreightRate

GENERICPRODDESC

Generic product description

Level3Invoice→
GenericProductDescription

HANDLINGRATE

Rate charged for handling

Level3Invoice→
HandlingRate

INVEXPDATE

Invoice expiration date

Level3Invoice→
InvoiceExpirationDate

LOCALTAXAMT

Local tax amount

Level3Invoice→
LocalTax

LOCALTAXEXEMPTCODE

Local tax exemption code

Level3Invoice→
LocalTax

LOCALTAXPERCENT

Local tax rate

Level3Invoice→
LocalTax

NATIONALTAXAMT

National tax amount

Level3Invoice→
NationalTax

RECURRING

Recurring billing indicator

REQNAME

Name of requestor

Level3Invoice→
Requestor

REQFIRSTADDR

First line of street address for
requestor

Level3Invoice→
Requestor

REQSECONDADDR

Second line of street address for
shipper

Level3Invoice→
Requestor

REQCITY

City of requestor

Level3Invoice→
Requestor

REQSTATE

State of requestor

Level3Invoice→
Requestor

REQZIP

Zip code of requestor

Level3Invoice→
Requestor

REQCOUNTRY

Country of requestor

Level3Invoice→
Requestor

SHIPPEDFROMNAME

Name of shipper

Invoice→ShipFrom

XMLPay Developer’s Guide

XMLPay Elements
Credit Card Transaction Parameters
TABLE 3.3

Level 3 (commercial) credit card transaction parameters

Payflow SDK Parameter

Description

XMLPay Element

SHIPPEDFROMFIRSTADDR

First line of street address for
shipper

Invoice→ShipFrom

SHIPPEDFROMSECONDADDR

Second line of street address for
shipper

Invoice→ShipFrom

SHIPPEDFROMCITY

City of shipper

Invoice→ShipFrom

SHIPPEDFROMSTATE

State of shipper

Invoice→ShipFrom

SHIPPEDFROMZIP

Zip code of shipper

Invoice→ShipFrom

SHIPPEDFROMCOUNTRY

Country of shipper

Invoice→ShipFrom

STATEANDLOCALTAXAMT

State and Local tax amount

Level3Invoice→
StateAndLocalTax

STATEANDLOCALTAXEXEMPTCODE

State and Local tax exempt code

Level3Invoice→
StateAndLocalTax

STATEANDLOCALTAXPERCENT

State and Local tax rate

Level3Invoice→
StateAndLocalTax

STATESALESTAXAMT

State tax amount

Level3Invoice→
StateTax

STATESALESTAXEXEMPTCODE

State tax exempt code

Level3Invoice→
StateTax

STATESALESTAXPERCENT

State tax rate

Level3Invoice→
StateTax

STATEGOODSTAXAMT

State goods tax amount

Level3Invoice→
StateGoodsTax

STATEGOODSTAXEXEMPTCODE

State goods tax exempt code

Level3Invoice→
StateGoodsTax

STATEGOODSTAXPERCENT

State goods tax rate

Level3Invoice→
StateGoodsTax

STATETAXAMT

State tax amount

Level3Invoice→
StateTax

STATETAXEXEMPTCODE

State tax exempt code

Level3Invoice→
StateTax

STATETAXPERCENT

State tax rate

Level3Invoice→
StateTax

STATESERVICESTAXAMT

State services tax amount

Level3Invoice→
StateServicesTax

STATESERVICESTAXEXEMPTCODE

State services tax exempt code

Level3Invoice→
StateServicesTax

XMLPay Developer’s Guide

XMLPay Elements
Credit Card Transaction Parameters
TABLE 3.3

Level 3 (commercial) credit card transaction parameters

Payflow SDK Parameter

Description

XMLPay Element

STATESERVICESTAXPERCENT

State services tax rate

Level3Invoice→
StateServicesTax

VATAXAMT

Value added tax amount

Level3Invoice→
ValueAddedTax

VATAXEXEMPTCODE

Value added tax exempt code

Level3Invoice→
ValueAddedTax

VATAXPERCENT

Value added tax rate

Level3Invoice→
ValueAddedTax

VATREGNUM

Value added tax registration
number

Level3Invoice→
ValueAddedTaxRegNum

Line item Transactions - Identifies one item in a transaction with multiple items. The number of the item is
appended to the parameter.

L_ALLTAXAMT

All tax amount line item

Level3Item→AllTax

L_ALLTAXEXEMPTCODE

All tax exemption code line item

Level3Item→AllTax

L_ALLTAXPERCENT

All tax rate line item

Level3Item→AllTax

L_CITYTAXAMT

City tax amount line item

Level3Item→CityTax

L_CITYTAXEXEMPTCODE

City tax exemption code line item

Level3Item→CityTax

L_CITYTAXPERCENT

City tax rate line item

Level3Item→CityTax

L_COUNTYSALESTAXAMT

County sales tax amount line item

Level3Item→
CountySalesTax

L_COUNTYSALESTAXEXEMPTCODE

County sales tax exemption code
line item

Level3Item→
CountySalesTax

L_COUNTYSALESTAXPERCENT

County sales tax rate line item

Level3Item→
CountySalesTax

L_COUNTYTAXAMT

County tax amount line item

Level3Item→
CountyTax

L_COUNTYTAXEXEMPTCODE

County tax exemption code line
item

Level3Item→
CountyTax

L_COUNTYTAXPERCENT

County tax rate line item

Level3Item→
CountyTax

L_EVTAXAMT

Environmental tax amount line
item

Level3Item→
EnvironmentalTax

L_EVTAXEXEMPTCODE

Environmental tax exemption
code line item

Level3Item→
EnvironmentalTax

XMLPay Developer’s Guide

XMLPay Elements
Credit Card Transaction Parameters
TABLE 3.3

Level 3 (commercial) credit card transaction parameters

Payflow SDK Parameter

Description

XMLPay Element

L_EVTAXPERCENT

Environmental tax rate line item

Level3Item→
EnvironmentalTax

L_LOCALTAXAMT

Local tax amount line item

Level3Item→LocalTax

L_LOCALTAXEXEMPTCODE

Local tax exemption code line
item

Level3Item→LocalTax

L_LOCALTAXPERCENT

Local tax rate line item

Level3Item→LocalTax

L_STATEANDLOCALTAXAMT

State and local tax amount line
item

Level3Item→
StateAndLocalTax

L_STATEANDLOCALTAXEXEMPTCODE

State and local tax exemption
code line item

Level3Item→
StateAndLocalTax

L_STATEANDLOCALTAXPERCENT

State and local tax rate line item

Level3Item→
StateAndLocalTax

L_STATETAXAMT

State tax amount line item

Level3Item→StateTax

L_STATETAXEXEMPTCODE

State tax exemption code line
item

Level3Item→StateTax

L_STATETAXPERCENT

State tax rate line item

Level3Item→StateTax

L_STATEGOODSTAXAMT

State goods tax amount line item

Level3Item→
StateGoodsTax

L_STATEGOODSTAXEXEMPTCODE

State goods tax exemption code
line item

Level3Item→
StateGoodsTax

L_STATEGOODSTAXPERCENT

State goods tax rate line item

Level3Item→
StateGoodsTax

L_STATESALESTAXAMT

State sales tax amount line item

Level3Item→
StateSalesTax

L_STATESALESTAXEXEMPTCODE

State sales tax exemption code
line item

Level3Item→
StateSalesTax

L_STATESALESTAXPERCENT

State sales tax rate line item

Level3Item→
StateSalesTax

L_STATESERVICESTAXAMT

State service tax amount line item

Level3Item→
StateServicesTax

L_STATESERVICESTAXEXEMPTCODE

State service tax exemption code
line item

Level3Item→
StateServicesTax

L_STATESERVICESTAXPERCENT

State service tax rate line item

Level3Item→
StateServicesTax

L_TAXTYPE

Tax type line item

Level3Item→TaxType

XMLPay Developer’s Guide

XMLPay Elements
Buyer Authentication Transaction Parameters
TABLE 3.3

Level 3 (commercial) credit card transaction parameters

Payflow SDK Parameter

Description

XMLPay Element

L_VATAXAMT

Value added tax amount line item

Level3Item→
ValueAddedTax

L_VATAXEXEMPTCODE

Value added tax exemption code
line item

Level3Item→
ValueAddedTax

L_VATAXPERCENT

Value added tax rate line item

Level3Item→
ValueAddedTax

Buyer Authentication Transaction Parameters
Table 3.4 lists the buyer authentication transaction parameters.
TABLE 3.4

Transaction response parameters

Payflow SDK Parameter

Description

XMLPay Element

AUTHENTICATION_ID

Values returned from Buyer Auth
transaction

BuyerAuthResult→
AuthenticationId

AUTHENTICATION_STATUS

Values returned from Buyer Auth
transaction

BuyerAuthResult→Status

CAVV

Values returned from Buyer Auth
transaction

BuyerAuthResult→CAVV

UCAF

Values returned from Buyer Auth
transaction

BuyerAuthResult→CAVV

XID

Values returned from Buyer Auth
transaction

BuyerAuthResult→XID

Credit Card Transaction Response Parameters
Table 3.5 lists the parameters returned for a credit card transaction.
TABLE 3.5

Transaction response parameters

Payflow SDK Parameter

Description

XMLPay Element

ADDLMSGS

Additional messages

ProcessorResult→
AdditionalMessages

AMEXID

Unique identifier to track
American Express transactions.

ProcessorResult→
AMEXID

XMLPay Developer’s Guide

XMLPay Elements
Credit Card Transaction Response Parameters
TABLE 3.5

Transaction response parameters

Payflow SDK Parameter

Description

XMLPay Element

AUTHCODE

Returned for Sale Authorization.

AuthCode

AVSADDR

AVS address verification
response.

AVSResult

AVSZIP

AVS ZIP code verification
response.

AVSResult

BALAMT

Balance on a pre-paid stored value
card for American Express CAPN
transactions

ProcessorResult→
BalanceAmount

CARDSECURE

Raw card secure value

TransactionResult→CardSecure

CVV2MATCH

Result of the card security code
(CVV2) check.

CVResult

HOSTCODE

Raw response from processor

ProcessorResult→HostCode

IAVS

IAVS result code

TransactionResult→IAVSResult

PNREF

Reference ID, a unique number
that identifies the transaction.

PNRef

RESPMSG

The response message returned
with the transaction result.

Message

PROCAVS

Raw processor AVS result code

ProcessorResult→AVSResult

PROCCVV2

Raw processor CVV2 result code

ProcessorResult→CVResult

PROCCARDSECURE

Raw card secure value from
processor

ProcessorResult→CardSecure

RRN

Retrieval reference number
(typically not passed to merchant)

ProcessorResult→RRN

RESPTEXT

Text response returned from
processor (for example, Approval)

ProcessorResult→ResponseText

RESULT

The outcome of the attempted
transaction.

Result

SETTLE_DATE

Date transaction will settle

ProcessorResult→SettleDate

STAN

Unique PayPal-generated
transaction ID for processor
(typically not passed to merchant)

ProcessorResult→STAN

XMLPay Developer’s Guide

XMLPay Elements
ACH Transaction Parameters (Norwest)

ACH Transaction Parameters (Norwest)
Table 3.6 lists the ACH transaction parameters. These parameters are specific to Norwest.
TABLE 3.6

Transaction response parameters

Payflow SDK Parameter

Description

XMLPay Element

TERMCITY

City of terminal that captured the transaction

ACH→TermCity

TERMSTATE

State of terminal that captured the transaction

ACH→TermState

PayPal Express Checkout Request Transaction Parameters
Table 3.7 lists the PayPal Express Checkout request transaction parameters.
TABLE 3.7

Express Checkout request parameters

Express Checkout
Parameter

Description

XMLPay Element

ADDROVERRIDE

PayPal pages display the shipping address set
in the shipping address parameters in the Set
Express Checkout request, not the shipping
address on file with PayPal for this customer.

PayPal→AddressOverride

AMT

Amount (US Dollars) U.S. based currency.
If shipping cost and tax charges are known,
include them in AMT. If not, AMT should be
the current subtotal of the order.

Invoice→TotalAmt

BUTTONSOURCE

Identification code for use by third-party
applications to identify transactions.

PayPal→ButtonSource

CANCELURL

URL to which the customer is returned if the
customer does not approve the use of PayPal to
pay you.

PayPal→CancelURL

CUSTOM

Free-form field for your own use such as a
tracking number or other value you want
PayPal to return in the Get Express Checkout
Details response.

PayPal→ExtData

Customer’s email address.

PayPal→EMail

HANDLINGAMT

Total handling amount.

Item→HandlingAmt

HDRBACKCOLOR

Sets the background color for the header of the
payment page.

PayPal→HeaderBackColor

XMLPay Developer’s Guide

XMLPay Elements
PayPal Express Checkout Request Transaction Parameters
TABLE 3.7

Express Checkout request parameters (Continued)

Express Checkout
Parameter

Description

XMLPay Element

HDRBORDERCOLOR

Sets the border color around the header of the
payment page. The border is a 2-pixel
perimeter around the header space, which is
750 pixels wide by 90 pixels high.

PayPal→HeaderBorderColor

HDRIMG

URL for the image you want to appear at the
top left of the payment page. The image has a
maximum size of 750 pixels wide by 90 pixels
high. PayPal recommends that you provide an
image that is stored on a secure (https) server.

PayPal→HeaderImage

INVNUM

Merchant invoice number. The merchant
invoice number is used for authorizations and
settlements and, depending on your merchant
bank, will appear on your customer's credit
card statement and your bank reconciliation
report. If you do not provide an invoice
number, the transaction ID (PNREF) will be
submitted.

Invoice→InvNum

ITEMAMT

Sum of cost of all items in this order.

Invoice→ItemAmt

L_AMTn

Cost of line item.

Invoice→TotalAmt

L_DESCn

Item description

Item→Description

L_QTYn

Quantity (whole units only)

Item→Quantity

L_TAXAMTn

Line item tax amount

Item→TaxAmt

LOCALECODE

Locale of pages displayed by PayPal during
Express Checkout.

PayPal→LocaleCode

MAXAMT

The expected maximum total amount of the
complete order, including shipping and tax
charges.

PayPal→ExtData

MEMO

Custom memo about the credit.

PayPal→ExtData

NOSHIPPING

Is 1 or 0. 1 indicates that on the PayPal pages,
no shipping address fields should be displayed
whatsoever.

PayPal→NoShipping

NOTE

An informal note about this settlement that is
displayed to the customer in email and in the
customer’s transaction history.

PayPal→ExtData

NOTIFYURL

Your URL for receiving Instant Payment
Notification (IPN) about this transaction.

PayPal→NotifyURL

ORDERDESC

Description of items the customer is
purchasing.

PayPal→ExtData

XMLPay Developer’s Guide

XMLPay Elements
PayPal Express Checkout Request Transaction Parameters
TABLE 3.7

Express Checkout request parameters (Continued)

Express Checkout
Parameter

Description

XMLPay Element

PAGESTYLE

Sets the Custom Payment Page Style for
payment pages associated with this
button/link. PageStyle corresponds to the
HTML variable page_style for customizing
payment pages.

PayPal→PageStyle

PAYERID

Unique encrypted PayPal customer account
identification number.

PayPal→PayerId

PAYFLOWCOLOR

Sets the background color for the payment
page.

PayPal→PayflowColor

REQCONFIRMSHIPPING

Is 1 or 0. The value 1 indicates that you require
that the customer’s shipping address on file
with PayPal be a confirmed address.

PayPal→ReqConfirmShipping

RETURNURL

URL to which the customer’s browser is
returned after approving use of PayPal.

PayPal→ReturnURL

SHIPPINGTOTAL

You must set the currencyID attribute to USD.
Must not exceed $10,000 USD. No currency
symbol. Decimal separator must be a period
(.).

PayPal→ExtData

SHIPTOCITY

Shipping city

ShipTo→Address→City

SHIPTOCOUNTRY

Destination Country Code. (See the appendix
entitled “ISO Country Codes” in the Payflow
Pro Developer’s Guide.)

ShipTo→Address→Country

SHIPTOSTATE

Shipping state.
US = 2-letter state code.
Outside US, use full name.

ShipTo→Address→State

SHIPTOSTREET

Shipping street address

ShipTo→Address→Street

SHIPTOSTREET2

Extended shipping address. Example: Bldg. 6,
Mail Stop 3.

ShipTo→Address→Street2

SHIPTOZIP

Shipping postal code (called ZIP code in the
USA)

ShipTo→Address→Zip

TAXAMT

Sum of tax for all items in this order.

Item→TaxAmt

TOKEN

Value returned in Set Express Checkout
response to identify this request as part of the
same checkout session.

PayPal→Token

XMLPay Developer’s Guide

XMLPay Elements
PayPal Express Checkout Response Transaction Parameters

PayPal Express Checkout Response Transaction Parameters
Table 3.7 lists the PayPal Express Checkout response transaction parameters.
TABLE 3.8

Mapping Express Checkout parameters to XMLPay parameters

Express Checkout
Parameter

Description

XMLPay Element

CUSTOM

Free-form field for your own use such as a tracking
number or other value you want PayPal to return in
the Get Express Checkout Details response.

PayPalResult→Custom

Customer’s email address.

PayPalResult→Custom

FEEAMT

PayPal fee amount charged for the transaction.

PayPalResult→ExtData

INVNUM

Your own unique invoice or tracking number.

PayPalResult→InvNum

PAYERID

Unique encrypted PayPal customer account
identification number.

PayPalResult→PayerId

PAYERSTATUS

Status of customer.

PayPalResult→PayerStatus

PHONENUM

Account holder’s telephone number.

PayPalResult→Phone

PPREF

Unique transaction ID of the payment

PayPalResult→PPRef

SHIPTOBUSINESS

Customer ’s business name.

PayPalResult→ExtData

SHIPTOCITY

Name of ship-to city.

ShipTo→Address→City

SHIPTOCOUNTRY

Ship-to country code. (See the appendix entitled
“ISO Country Codes” in the Payflow Pro
Developer’s Guide.)

ShipTo→Address→Country

SHIPTOCOUNTRYCODE

Customer ’s country of residence in the form of ISO
standard 3166 two-character country codes.

PayPalResult→ExtData

SHIPTOSTATE

Name of ship-to state or province.

ShipTo→Address→State

SHIPTOZIP

U.S. ship-to ZIP code or other country-specific
postal code.

ShipTo→Address→Zip

TOKEN

Value returned in Set Express Checkout response to
identify this request as part of the same checkout
session.

PayPal→Token

XMLPay Developer’s Guide

XMLPay Elements
PayPal Express Checkout Response Transaction Parameters

XMLPay Developer’s Guide

XMLPay Transaction Profiles

The following tables document the transactions supported for each tender, along with the data
elements used for each of those transactions.

ACH Transactions
ACH supports the following transactions: Sale, Credit, and Void.
The following data are used to process ACH transactions:
z

Invoice.TotalAmt

ACH.AcctType

ACH.AcctNum

ACH.ABA

ACH.AuthType

ACH.Prenote

BillTo.Name

Buyer Authentication Transactions
Buyer authentication supports the following transactions: VerifyEnrollment and
ValidateAuthentication.
For VerifyEnrollment, the following data are used to process the transactions (required
elements are in bold text):
z

Invoice.TotalAmt with Currency attribute

Invoice.Description

Card.CardNum

Card.ExpDate

For ValidateAuthentication, the following data are required to process the transactions:
z

PARes

XMLPay Developer’s Guide

XMLPay Transaction Profiles
Card Transactions

Card Transactions
Retail credit and debit cards and corporate purchase cards support the following transactions:
Sale, Authorization, Delay Capture, Credit, and Void.
The following data are used to process card transactions:
z

Invoice.TotalAmt

Card.CardNum

Card.ExpDate

Card.NameOnCard (Defaults to BillTo.Name)

BillTo.Street, ZIP (Required for AVS)

CardInfo.CVNum

Purchase Card Level I
Level I purchase cards use the following additional data:
z

BillTo.PONum

Invoice.TaxAmt

Purchase Card Level II
Level II purchase cards use the following additional data:
z

BillTo.TaxExempt

ShipTo.ZIP

Purchase Card Level III
Level III purchase cards use the following additional data:

Invoice.Date

BillTo.CustCode

ShipTo.Country

ShipFrom.ZIP

Invoice.ShippingAmt

Invoice.DiscountAmt

Item.SKU, UPC, Description, Quantity, UnitOfMeasurement, UnitPrice, ExtAmt,
DiscountAmt, TaxAmt, TotalAmt, DutyAmt, NationalTaxIncl

XMLPay Developer’s Guide

XMLPay Transaction Profiles
Check Transactions

N O T E : Minimum

requirements for describing an item are Description, Quantity, and
UnitPrice.
ExtAmt = Quantity * UnitPrice. TotalAmt = TaxAmt – DiscountAmt

Check Transactions
Checks support the following transaction: Sale. The following data are used to process check
transactions (required elements are in bold text):
z

Invoice.TotalAmt

Check.CheckType

Check.CheckNum

Check.MICR

BillTo.Name

BillTo.Address

BillTo.EMail

BillTo.Phone

BillTo.DL (DL is optional if SS is provided)

BillTo.SS (SS is optional if DL is provided)

BillTo.DOB

Invoice.InvNum

XMLPay Developer’s Guide

XMLPay Transaction Profiles
PayPal Transactions

PayPal Transactions
PayPal Express Checkout supports the following transactions: Sale, Authorization, Delayed
Capture, Void, and Credit.
The following data are used to process PayPal Express Checkout transactions:

PayPal.CancelURL

PayPal.ReturnURL

PayPal.Token

PayPal.PayerId

Invoice.TotalAmt

ShipTo.Address.Street

ShipTo.Address.City

ShipTo.Address.State

ShipTo.Address.Zip

ShipTo.Address.Country

XMLPay Developer’s Guide

XMLPay Examples

This chapter provides several examples of XMLPay documents.
For specific examples of how to submit XML documents using the Payflow SDK client
service, see the Payflow SDK SDKdownload package.
N O T E : To

receive namespaces in the XML response document, you must set the
XMLPayRequest version attribute to “2.0” or “1.1”. Leaving this attribute out or
setting it to any value less than 1.1 leaves the namespace out of the XML response
document, which may cause errors with some XML parsers.

Set the version attribute to “2.0” to enable all the functionality described in this
document.
In this Chapter
z

“ACH Sale Request” on page 70

“Card Authorization Request” on page 71

“Card Capture Request” on page 73

“Card Credit Request” on page 74

“Card Credit Reference Credit Request” on page 75

“Card Force Capture Request” on page 76

“Card Sale Request” on page 77

“Card Secure Request” on page 79

“Card Status Request” on page 80

“Card Void Request” on page 81

“Check Sale Request” on page 82

“Customer IP” on page 83

“Express Checkout Authorization Transaction” on page 84

“IAVS Result Request” on page 88

“Level 3 Invoice” on page 89

“Line Item Sale Request” on page 90

“Merchant Description and Merchant Service Number” on page 92

“Processor Result” on page 93

“Recurring Billing Profile” on page 94

“Shipping Carrier and Shipping Method” on page 96

“Transaction Update” on page 97

XMLPay Developer’s Guide

XMLPay Examples
ACH Sale Request

“ValidateAuthentication Request” on page 98

“ValidateAuthentication Response” on page 98

“VerifyEnrollment Request” on page 99

“VerifyEnrollment Response” on page 99

ACH Sale Request

XMLPayRequest Timeout="30" version = "2.0"
xmlns="http://www.paypal.com/XMLPay">

vendor
partner

1
20020208

billtoname
true

true
24.97

C
6355059797
091000019
false

user
password

XMLPay Developer’s Guide

XMLPay Examples
Card Authorization Request

ACH Sale Response

vendor
partner

Service Not Requested
Service Not Requested

Service Not Requested
Approved
VTHD55395864
0

Card Authorization Request

vendor
partner

123 4th street
San Jose
CA
95032
USA

XMLPay Developer’s Guide

XMLPay Examples
Card Authorization Request

24.97

visa
5105105105105100
200911

user
password

Card Authorization Response

vendor
partner

Service Not Available
Service Not Available

Service Not Requested
Approved
V63A09910356
747PNI
00
0

XMLPay Developer’s Guide

XMLPay Examples
Card Capture Request

Card Capture Request

vendor
partner

V63A09910356

user
password

Card Capture Response

vendor
partner

Service Not Available
Service Not Available

Service Not Requested
Approved
V53A09206640
747PNI
00
0

XMLPay Developer’s Guide

XMLPay Examples
Card Credit Request

Card Credit Request

vendor
VeriSign

10.00

MasterCard
5105105105105100
200911

user
password

XMLPay Developer’s Guide

XMLPay Examples
Card Credit Reference Credit Request

Card Credit Response

vendor
verisign

0
Approved
V18A0FA3CBC2

Card Credit Reference Credit Request

vendor
partner

V53A09206652

user
password

Card Credit Reference Credit Response

XMLPay Developer’s Guide

XMLPay Examples
Card Force Capture Request

vendor
partner

105

Service Not Requested
Service Not Requested

Service Not Requested
Credit error
V54A09206685
0

Card Force Capture Request

vendor
partner

false
24.97

visa
5105105105105100
200911

AUTHCODE

XMLPay Developer’s Guide

XMLPay Examples
Card Sale Request

user
password

Card Force Capture Response

vendor
partner

Service Not Requested
Service Not Requested

Service Not Requested
Approved
V54A09206761
AUTHCO
00
0

/TransactionResults>

Card Sale Request

vendor
partner

XMLPay Developer’s Guide

XMLPay Examples
Card Sale Request

false
24.97

visa
5105105105105100
200911

user
password

Card Sale Response

vendor
partner

Service Not Available
Service Not Available

Service Not Requested
Approved
V64A09909896
968PNI
00
0

XMLPay Developer’s Guide

XMLPay Examples
Card Secure Request

Card Secure Request

vendor
partner

false
24.97

visa
5105105105105100
200911

Y
CTEremezUA7PkaDwP0Qk
5
BwAQAJVyYAQECQJTMnJgAAAAAAA=
8abmK0K1Sf9OujrESKKrKkJCP4I=

user
password

XMLPay Developer’s Guide

XMLPay Examples
Card Status Request

Card Status Request

vendor
partner

V54A09206691

user
password

Card Status Response

vendor
partner

Service Not Requested
Service Not Requested

Service Not Requested
Approved
V54A09206691
0

XMLPay Developer’s Guide

XMLPay Examples
Card Void Request

Card Void Request

vendor
partner

V54A09206691

user
password

Card Void Response

vendor
partner

Service Not Requested
Service Not Requested

Service Not Requested
Approved
V54A09206748
00
0

XMLPay Developer’s Guide

XMLPay Examples
Check Sale Request

Check Sale Request

vendor
partner

1
20020208

billtoname

street
city
NY
67890
US

email
false

true
24.97

P
1001
12345678904390850001001
CA123456
123456789
19000601

user
password

XMLPay Developer’s Guide

XMLPay Examples
Customer IP

Check Sale Response

vendor
partner

Service Not Requested
Service Not Requested

Service Not Requested
Approved
VCNB01775729
0

Customer IP

vendor
partner

192.168.100.31
false
24.97

visa

XMLPay Developer’s Guide

XMLPay Examples
Express Checkout Authorization Transaction

5105105105105100
200911

user
password

Express Checkout Authorization Transaction
Set Express Checkout Request

Vendor
partner

123 4th street
San Jose
CA
95032
USA

10.23

XMLPay Developer’s Guide

XMLPay Examples
Express Checkout Authorization Transaction

emailname@paypal.com
http://www.ebay.com
http://www.yahoo.com

user
password

Set Express Checkout Response

vendor
partner

0
Approved

EC-1R668591NV5623643
0

Get Express Checkout Request

vendor
partner

XMLPay Developer’s Guide

XMLPay Examples
Express Checkout Authorization Transaction

EC-1R668591NV5623643

user
password

Get Express Checkout Response

vendor
partner

Match

Approved

echeung-b1@paypal.com
2BUBWABP28LFL
EC-1R668591NV5623643
0
verified
Joshua

AA Logos
90252 Laurel Crest Drive
San Jose

XMLPay Developer’s Guide

XMLPay Examples
Express Checkout Authorization Transaction

CA
95148
US

Do Express Checkout Request

vendor
partner

1.23

EC-1R668591NV5623643
2BUBWABP28LFL

user
password

XMLPay Developer’s Guide

XMLPay Examples
IAVS Result Request

Do Express Checkout Response

vendor
partner

Match

Approved
EEEPB489DB3B

2BUBWABP28LFL
EC-1R668591NV5623643
9HG32848HD669470X
0
instant
authorization

<
/ResponseData>

IAVS Result Request

vendor
partner

0
Y

Service Not Available
Service Not Available

Service Not Requested
Approved
V63A09910356
747PNI
00
0

XMLPay Developer’s Guide

XMLPay Examples
Level 3 Invoice

Level 3 Invoice

vendor
partner

false
24.97

1.23

visa
Switch
5105105105105100
200911

user
password

XMLPay Developer’s Guide

XMLPay Examples
Line Item Sale Request

Line Item Sale Request

vendor
partner

billtoname

street
city
NY
67890
US

email
1234567890
9876543210
custcode
123456
false

1111
9999
Widget
2
UnitOfMeasurement>INQ
49.99
9.98
3.00
8.00
101.00

500 Main St.
Anytown
NY
67890
US

15:30

XMLPay Developer’s Guide

XMLPay Examples
Line Item Sale Request

20030630
24680

ABC0123

20030714
12:00

54.10.15.05

2222
8888
Gizmo
5
INQ
9.99
2.50
3.00
2.50
52.95

500 Main St.
Anytown
NY
67890
US

09:00
20030628
13579

XYZ7890

20030711
09:00

54.10.16.05

13.47
false
167.42

mastercard
5105105105105100
200912

XMLPay Developer’s Guide

XMLPay Examples
Merchant Description and Merchant Service Number

/Transactions>

user
password

Line Item Sale Response

vendor
partner

Match
Match

Service Not Requested
Approved
VTHA55395881
624PNI
00
0

Merchant Description and Merchant Service Number

vendor
partner

XMLPay Developer’s Guide

XMLPay Examples
Processor Result

false
24.97

visa
5105105105105100
200911

user
password

Processor Result

vendor
partner

Z
T
13523

Service Not Available
Service Not Available

XMLPay Developer’s Guide

XMLPay Examples
Recurring Billing Profile

Service Not Requested
Approved
V63A09910356
747PNI
00
0

Recurring Billing Profile
This section includes a sample ACH recurring billing profile and a sample credit card billing
profile

ACH Recurring Billing Profile

vendor
partner

C
5105105105105100
091000019

Test Profile
1.23
03042004
12
Weekly
a.com

123 4th street
San Jose
CA
95032

XMLPay Developer’s Guide

XMLPay Examples
Recurring Billing Profile

USA

v3test
password

Credit Card Recurring Billing Profile
Payflow XML does not parse certain name-value pair (NVP) tags. For example, to pass a
value for the CURRENCY tag, which is not supported, you must pass it as extended data
(ExtData) as shown below.

vendor
partner

5105105105105100
200803
name

Test Profile

1.23
12122004
12
Weekly
a.com
Sale
12

XMLPay Developer’s Guide

XMLPay Examples
Shipping Carrier and Shipping Method

123 4th street
San Jose
CA
95032

user
password

Shipping Carrier and Shipping Method

vendor
partner

UPS
Next Day
false
24.97

visa
5105105105105100
200911

XMLPay Developer’s Guide

XMLPay Examples
Transaction Update

user
password

Transaction Update

vendor
partner

V53A12345678
Approve

user
password

vendor
partner

0
Approved
V63A09910356
747PNI
00
0

XMLPay Developer’s Guide

XMLPay Examples
ValidateAuthentication Request

ValidateAuthentication Request

vendor
partner

pares bloc

user
password

ValidateAuthentication Response

vendor
partner

0
OK

Y
CTEremezUA7PkaDwP0Qk
5
BwAQAJVyYAQECQJTMnJgAAAAAAA=
8abmK0K1Sf9OujrESKKrKkJCP4I=

XMLPay Developer’s Guide

XMLPay Examples
VerifyEnrollment Request

VerifyEnrollment Request

vendor
partner

12.16

4000000000000002
200411

user
assword

VerifyEnrollment Response

vendor
partner

XMLPay Developer’s Guide

XMLPay Examples
VerifyEnrollment Response

0
OK

E
CTEremezUA7PkaDwP0Qk
pareq bloc
https://bankacs.bank.com/ascurl\
7

100

XMLPay Developer’s Guide

XMLPay Schemas

This appendix contains the XMLPay schema.
N O T E : The

RepeatSale element is defined, but not supported.

XMLPay Schema

XMLPay Developer’s Guide

101

XMLPay Schemas
XMLPay Schema

102

XMLPay Developer’s Guide

XMLPay Schemas
XMLPay Schema

XMLPay Developer’s Guide

103

XMLPay Schemas
XMLPay Schema

"VerbosityEnum" base = "string">
value = "Off"/>
value = "Low"/>
value = "Medium"/>
value = "High"/>

104

= "elementOnly">
= "PayData"/>
= "PayDataAuth" minOccurs = "0" maxOccurs = "1"/>
= "ExtData" minOccurs = "0" maxOccurs = "unbounded"/>

XMLPay Developer’s Guide

XMLPay Schemas
XMLPay Schema

XMLPay Developer’s Guide

105

XMLPay Schemas
XMLPay Schema

"TransactionUpdateActionEnum" base = "string">
value = "Approve"/>
value = "Review"/>
value = "ServiceDecline"/>
value = "MerchantDecline"/>

106

XMLPay Developer’s Guide

XMLPay Schemas
XMLPay Schema

XMLPay Developer’s Guide

107

XMLPay Schemas
XMLPay Schema

name = "HostResponse" type = "string" minOccurs="0" maxOccurs="1"/>
name = "AMEXID" type = "string" minOccurs = "0" maxOccurs = "1"/>
name = "BalanceAmount" type = "string" minOccurs = "0" maxOccurs = "1"/>
ref = "ExtData" minOccurs = "0" maxOccurs = "unbounded"/>

108

XMLPay Developer’s Guide

XMLPay Schemas
XMLPay Schema

value = "E"/>
value = "O"/>
value = "X"/>
value = "I"/>
value = "Y"/>
value = "A"/>
value = "U"/>
value = "N"/>
value = "F"/>

109

XMLPay Schemas
XMLPay Schema

"MatchResultEnum" base = "string">
value = "Match"/>
value = "No Match"/>
value = "Service Not Available"/>
value = "Service Not Requested"/>

110

XMLPay Developer’s Guide

XMLPay Schemas
XMLPay Schema

XMLPay Developer’s Guide

111

XMLPay Schemas
XMLPay Schema

112

XMLPay Developer’s Guide

XMLPay Schemas
XMLPay Schema

"Status" type = "RPStatusType" minOccurs = "0" maxOccurs = "1"/>
"Name" type = "RPNameType" minOccurs="0" maxOccurs="1"/>
"Start" type = "RPDateType" minOccurs="0" maxOccurs="1"/>
"Term" type = "int" minOccurs="0" maxOccurs="1"/>
"End" type = "RPDateType" minOccurs="0" maxOccurs="1"/>
"PayPeriod" type = "PayPeriodType" minOccurs="0" maxOccurs="1"/>
"MaxFailPayments" type = "int" minOccurs="0" maxOccurs="1"/>
"RetryNumDays" type = "int" minOccurs="0" maxOccurs="1"/>
"EMail" type = "EMailType" minOccurs = "0" maxOccurs = "1"/>
"CompanyName" type = "CompanyNameType" minOccurs="0" maxOccurs="1"/>
"Amt" type = "CurrencyAmount" minOccurs = "0" maxOccurs = "1"/>
"PaymentsLeft" type = "int" minOccurs = "0" maxOccurs = "1"/>
"NextPayment" type = "RPDateType" minOccurs = "0" maxOccurs = "1"/>
"AggregateAmt" type = "CurrencyAmount" minOccurs = "0" maxOccurs =

"1"/>

XMLPay Developer’s Guide

113

XMLPay Schemas
XMLPay Types Schema

"PayPeriodType" base = "string">
value = "Weekly"/>
value = "Bi-weekly"/>
value = "Semi-monthly"/>
value = "Every four weeks"/>
value = "Monthly"/>
value = "Quarterly"/>
value = "Semi-yearly"/>
value = "Yearly"/>

XMLPay Types Schema

114

XMLPay Developer’s Guide

XMLPay Schemas
XMLPay Types Schema

ref = "Address" minOccurs = "0" maxOccurs = "1"/>
name = "EMail" type = "EMailType" minOccurs = "0" maxOccurs = "1"/>
name = "Phone" type = "PhoneNumberType" minOccurs = "0" maxOccurs =

"1"/>

XMLPay Developer’s Guide

115

XMLPay Schemas
XMLPay Types Schema

116

XMLPay Developer’s Guide

XMLPay Schemas
XMLPay Types Schema

ref = "AdditionalAmounts" minOccurs = "0" maxOccurs = "1"/>
name = "SKU" type = "SKUType" minOccurs = "0" maxOccurs = "1"/>
name = "CustomerHostName" type = "string" minOccurs = "0" maxOccurs = "1"/>
name = "CustomerBrowser" type = "string" minOccurs = "0" maxOccurs = "1"/>

minOccurs
minOccurs
minOccurs
minOccurs
minOccurs

=
=
=
=
=

"0"
"0"
"0"
"0"
"0"

maxOccurs
maxOccurs
maxOccurs
maxOccurs
maxOccurs

=
=
=
=
=

"1"/>
"1"/>
"1"/>
"1"/>
"1"/>

XMLPay Developer’s Guide

117

XMLPay Schemas
XMLPay Types Schema

118

XMLPay Developer’s Guide

XMLPay Schemas
XMLPay Types Schema

XMLPay Developer’s Guide

119

XMLPay Schemas
XMLPay Types Schema

120

XMLPay Developer’s Guide

XMLPay Schemas
XMLPay Types Schema

XMLPay Developer’s Guide

121

XMLPay Schemas
XMLPay Types Schema

122

XMLPay Developer’s Guide

XMLPay Schemas
XMLPay Types Schema

"HandlingAmt" type = "CurrencyAmount" minOccurs = "0" maxOccurs="1"/>
"ShipmentNumber" type = "ShipmentType" minOccurs = "0" maxOccurs="1"/>
"UNSPSCCode" type = "UNSPSCType" minOccurs = "0" maxOccurs="1"/>
"CatalogNumber" type = "CatalogType" minOccurs = "0" maxOccurs="1"/>
"CommCode" type = "CommodityCodeType" minOccurs = "0" maxOccurs =

"1"/>

XMLPay Developer’s Guide

123

XMLPay Schemas
XMLPay Types Schema

"Zip" type = "ZipType" minOccurs = "0" maxOccurs = "1"/>
"Country" type = "CountryCode" minOccurs = "0" maxOccurs = "1"/>
"AddressLine1" type = "AddressLineType" minOccurs = "0" maxOccurs =

"1"/>

124

XMLPay Developer’s Guide

XMLPay Schemas
XMLPay Types Schema

"TransactionTypeEnum" base = "string">
value = "Authorization"/>
value = "Capture"/>
value = "Sale"/>
value = "Credit"/>
value = "Void"/>
value = "ForceCapture"/>
value = "RepeatSale"/>
value = "GetStatus"/>

XMLPay Developer’s Guide

125

XMLPay Schemas
XMLPay Types Schema

value = "Visa"/>
value = "MasterCard"/>
value = "Amex"/>
value = "JCB"/>
value = "Discover"/>

XMLPay Developer’s Guide

XMLPay Schemas
XMLPay Types Schema

XMLPay Developer’s Guide

127

XMLPay Schemas
XMLPay Types Schema

"CheckTypeEnum" base = "string">
value = "Personal"/>
value = "Corporate"/>
value = "Government"/>

128

XMLPay Developer’s Guide

XMLPay Schemas
XMLPay Types Schema

XMLPay Developer’s Guide

129

XMLPay Schemas
XMLPay Types Schema

"StatusType" base = "string">
value = "New"/>
value = "Update"/>
value = "Replace"/>

130

XMLPay Developer’s Guide

XMLPay DTD

A document type definition (DTD) defines the structure of an XML document. With a DTD
you can define the set and order of tags, as well as the attributes for each. A well-formed XML
document is considered valid when it conforms to its corresponding DTD.
The following is a document type definition (DTD) representation of the XMLPay schema.

XMLPay Developer’s Guide

131

XMLPay DTD

132

XMLPay Developer’s Guide

XMLPay DTD

XMLPay Developer’s Guide

133

XMLPay DTD

134

XMLPay Developer’s Guide

XMLPay DTD

XMLPay Developer’s Guide

135

XMLPay DTD

136

XMLPay Developer’s Guide

XMLPay DTD

XMLPay Developer’s Guide

137

XMLPay DTD

138

XMLPay Developer’s Guide

XMLPay DTD

XMLPay Developer’s Guide

139

XMLPay DTD

140

XMLPay Developer’s Guide

XMLPay DTD

version CDATA #IMPLIED>
request_id CDATA #IMPLIED>
response_id CDATA #IMPLIED>
Timeout CDATA #IMPLIED>

XMLPay Developer’s Guide

141

XMLPay DTD

142

XMLPay Developer’s Guide

XMLPay DTD

XMLPay Developer’s Guide

143

XMLPay DTD

xmlns CDATA #IMPLIED>
version CDATA #IMPLIED>
request_id CDATA #IMPLIED>
response_id CDATA #IMPLIED>

XMLPay Developer’s Guide

Transaction Results

The transaction result status response (RESULT) is the first value returned from the Payflow
SDK server. This value indicates the overall status of the transaction attempt. The response
message (RESPMSG) provides a brief description for decline or error results.
z

A value of 0 (zero) indicates that no errors occurred and the transaction was approved.

A value greater than zero indicates a decline or error. See Table C.1.

A value less than zero indicates that a communication error occurred. In this case, no
transaction is attempted. See Table C.1.

TABLE C.1

Payflow transaction RESULT values and RESPMSG text

RESULT

RESPMSG and Explanation

Approved

User authentication failed. Error is caused by one or more of the following:
z Login information is incorrect. Verify that USER, VENDOR, PARTNER, and
PASSWORD have been entered correctly. VENDOR is your merchant ID and
USER is the same as VENDOR unless you created a Payflow Pro user. All fields
are case sensitive.
z Invalid Processor information entered. Contact merchant bank to verify.
z "Allowed IP Address" security feature implemented. The transaction is coming
from an unknown IP address. See PayPal Manager online help for details on how to
use Manager to update the allowed IP addresses.
z You are using a test (not active) account to submit a transaction to the live PayPal
servers. Change the host address from the test server URL to the live server URL.

Invalid tender type. Your merchant bank account does not support the following
credit card type that was submitted.

Invalid transaction type. Transaction type is not appropriate for this transaction. For
example, you cannot credit an authorization-only transaction.

Invalid amount format. Use the format: “#####.##” Do not include currency
symbols or commas.

Invalid merchant information. Processor does not recognize your merchant account
information. Contact your bank account acquirer to resolve this problem.

Invalid or unsupported currency code

Field format error. Invalid information entered. See RESPMSG.

Not a transaction server

Too many parameters or invalid stream

XMLPay Developer’s Guide

145

Transaction Results

TABLE C.1

146

Payflow transaction RESULT values and RESPMSG text (Continued)

RESULT

RESPMSG and Explanation

Too many line items

Client time-out waiting for response

Declined. Check the credit card number, expiration date, and transaction information to
make sure they were entered correctly. If this does not resolve the problem, have the
customer call their card issuing bank to resolve.

Referral. Transaction cannot be approved electronically but can be approved with a
verbal authorization. Contact your merchant bank to obtain an authorization and submit
a manual Voice Authorization transaction.

Invalid Client Certification ID. Check the HTTP header. If the tag, X-VPS-VITCLIENT-CERTIFICATION-ID, is missing, RESULT code 14 is returned.

Original transaction ID not found. The transaction ID you entered for this
transaction is not valid. See RESPMSG.

Cannot find the customer reference number

Invalid ABA number

Invalid account number. Check credit card number and re-submit.

Invalid expiration date. Check and re-submit.

Invalid Host Mapping. Error is caused by one or more of the following:
z You are trying to process a tender type such as Discover Card, but you are not set up
with your merchant bank to accept this card type.
z You are trying to process an Express Checkout transaction when your account is not
set up to do so. Contact your account holder to have Express Checkout added to
your account.

Invalid vendor account. Login information is incorrect. Verify that USER, VENDOR,
PARTNER, and PASSWORD have been entered correctly. VENDOR is your merchant
ID and USER is the same as VENDOR unless you created a Payflow Pro user. All
fields are case sensitive.

Insufficient partner permissions

Insufficient user permissions

Invalid XML document. This could be caused by an unrecognized XML tag or a bad
XML format that cannot be parsed by the system.

Duplicate transaction

Error in adding the recurring profile

Error in modifying the recurring profile

Error in canceling the recurring profile

XMLPay Developer’s Guide

Transaction Results

TABLE C.1

Payflow transaction RESULT values and RESPMSG text (Continued)

RESULT

RESPMSG and Explanation

Error in forcing the recurring profile

Error in reactivating the recurring profile

OLTP Transaction failed

Invalid recurring profile ID

Insufficient funds available in account

Exceeds per transaction limit

General error. See RESPMSG.

100

Transaction type not supported by host

101

Time-out value too small

102

Processor not available

103

Error reading response from host

104

Timeout waiting for processor response. Try your transaction again.

105

Credit error. Make sure you have not already credited this transaction, or that this
transaction ID is for a creditable transaction. (For example, you cannot credit an
authorization.)

106

Host not available

107

Duplicate suppression time-out

108

Void error. See RESPMSG. Make sure the transaction ID entered has not already been
voided. If not, then look at the Transaction Detail screen for this transaction to see if it
has settled. (The Batch field is set to a number greater than zero if the transaction has
been settled). If the transaction has already settled, your only recourse is a reversal
(credit a payment or submit a payment for a credit).

109

Time-out waiting for host response

110

Referenced auth (against order) Error

111

Capture error. Either an attempt to capture a transaction that is not an authorization
transaction type, or an attempt to capture an authorization transaction that has already
been captured.

112

Failed AVS check. Address and ZIP code do not match. An authorization may still
exist on the cardholder’s account.

113

Merchant sale total will exceed the sales cap with current transaction. ACH
transactions only.

114

Card Security Code (CSC) Mismatch. An authorization may still exist on the
cardholder’s account.

XMLPay Developer’s Guide

147

Transaction Results

TABLE C.1

148

Payflow transaction RESULT values and RESPMSG text (Continued)

RESULT

RESPMSG and Explanation

115

System busy, try again later

116

VPS Internal error. Failed to lock terminal number

117

Failed merchant rule check. One or more of the following three failures occurred:
An attempt was made to submit a transaction that failed to meet the security settings
specified on the PayPal Manager Security Settings page. If the transaction exceeded the
Maximum Amount security setting, then no values are returned for AVS or CSC.
AVS validation failed. The AVS return value should appear in the RESPMSG.
CSC validation failed. The CSC return value should appear in the RESPMSG.

118

Invalid keywords found in string fields

119

General failure within PIM Adapter

120

Attempt to reference a failed transaction

121

Not enabled for feature

122

Merchant sale total will exceed the credit cap with current transaction. ACH
transactions only.

125

Fraud Protection Services Filter — Declined by filters

126

Fraud Protection Services Filter — Flagged for review by filters
Important Note: Result code 126 indicates that a transaction triggered a fraud filter.
This is not an error, but a notice that the transaction is in a review status. The
transaction has been authorized but requires you to review and to manually accept the
transaction before it will be allowed to settle.
Result code 126 is intended to give you an idea of the kind of transaction that is
considered suspicious to enable you to evaluate whether you can benefit from using the
Fraud Protection Services.
To eliminate result 126, turn the filters off.
For more information, see the Fraud Protection Services documentation for your
payments solution. It is available on the PayPal Manager Documentation page.

127

Fraud Protection Services Filter — Not processed by filters

128

Fraud Protection Services Filter — Declined by merchant after being flagged for
review by filters

131

Version 1 Payflow Pro SDK client no longer supported. Upgrade to the most recent
version of the Payflow Pro client.

132

Card has not been submitted for update

133

Data mismatch in HTTP retry request

150

Issuing bank timed out

151

Issuing bank unavailable

XMLPay Developer’s Guide

Transaction Results

TABLE C.1

Payflow transaction RESULT values and RESPMSG text (Continued)

RESULT

RESPMSG and Explanation

200

Reauth error

201

Order error

402

PIM Adapter Unavailable

403

PIM Adapter stream error

404

PIM Adapter Timeout

600

Cybercash Batch Error

601

Cybercash Query Error

1000

Generic host error. This is a generic message returned by your credit card processor.
The RESPMSG will contain more information describing the error.

1001

Buyer Authentication Service unavailable

1002

Buyer Authentication Service — Transaction timeout

1003

Buyer Authentication Service — Invalid client version

1004

Buyer Authentication Service — Invalid timeout value

1011

Buyer Authentication Service unavailable

1012

Buyer Authentication Service unavailable

1013

Buyer Authentication Service unavailable

1014

Buyer Authentication Service — Merchant is not enrolled for Buyer
Authentication Service (3-D Secure).

1016

Buyer Authentication Service — 3-D Secure error response received. Instead of
receiving a PARes response to a Validate Authentication transaction, an error response
was received.

1017

Buyer Authentication Service — 3-D Secure error response is invalid. An error
response is received and the response is not well formed for a Validate Authentication
transaction.

1021

Buyer Authentication Service — Invalid card type

1022

Buyer Authentication Service — Invalid or missing currency code

1023

Buyer Authentication Service — merchant status for 3D secure is invalid

1041

Buyer Authentication Service — Validate Authentication failed: missing or
invalid PARES

1042

Buyer Authentication Service — Validate Authentication failed: PARES format is
invalid

XMLPay Developer’s Guide

149

Transaction Results
AVS Result Codes
TABLE C.1

Payflow transaction RESULT values and RESPMSG text (Continued)

RESULT

RESPMSG and Explanation

1043

Buyer Authentication Service — Validate Authentication failed: Cannot find
successful Verify Enrollment

1044

Buyer Authentication Service — Validate Authentication failed: Signature
validation failed for PARES

1045

Buyer Authentication Service — Validate Authentication failed: Mismatched or
invalid amount in PARES

1046

Buyer Authentication Service — Validate Authentication failed: Mismatched or
invalid acquirer in PARES

1047

Buyer Authentication Service — Validate Authentication failed: Mismatched or
invalid Merchant ID in PARES

1048

Buyer Authentication Service — Validate Authentication failed: Mismatched or
invalid card number in PARES

1049

Buyer Authentication Service — Validate Authentication failed: Mismatched or
invalid currency code in PARES

1050

Buyer Authentication Service — Validate Authentication failed: Mismatched or
invalid XID in PARES

1051

Buyer Authentication Service — Validate Authentication failed: Mismatched or
invalid order date in PARES

1052

Buyer Authentication Service — Validate Authentication failed: This PARES was
already validated for a previous Validate Authentication transaction

AVS Result Codes
For US customers the Address Verification Service (AVS) compares the street address and zip
code submitted with that on file at the cardholder's bank. Any one of the following results can
appear in the AVS Street Match and AVS Zip Match fields on the transaction detail screen:
TABLE C.2

150

AVS ZIP match results

Result

Meaning

MATCH

Information submitted matches information on file with cardholder's
bank.

NO MATCH

Information submitted does not match information on file with the
cardholder's bank.

XMLPay Developer’s Guide

Transaction Results
AVS Result Codes

Results can vary on the same transaction detail screen. In other words, AVS Street Match = Y
and AVS Zip Match = N (and vice versa) could appear on the same transaction detail screen.
When service is unavailable, no code is returned.

XMLPay Developer’s Guide

151

152

Transaction Results
AVS Result Codes

XMLPay Developer’s Guide

Index

Index
A
ABA
ACH attribute 32
AcctNum
ACH attribute 32
AcctType
ACH attribute 32
ACH
transaction parameters 60
transaction profiles 65
ACH attributes 32
ACH sale request example 70
ACH sale response example 71
ACHStatus
TransactionResult attribute 39
ACSUrl
BuyerAuthResult attribute 42
add recurring profile attributes 23
adding a recurring profile 23
AdditionalAmounts
Invoice attribute 28
Address
Invoice attribute 27
PayPalResult attribute 41
RPData attribute 37
Address attributes 30, 31
Address Verification Service 150
AddressOverride
PayPal attribute 35
AggregateAmt
RecurringProfileResult attribute 44
AggregateOptionalTransAmt
RecurringProfileResult attribute 45
Amountn
AdditionalAmounts attribute 31
Amt
RecurringProfileResult attribute 44
AuthCode
ForceCapture transaction attribute 20
TransactionResult attribute 39
AuthenticationId
BuyerAuthResult attribute 42

XMLPay Developer’s Guide

Authorization
DoExpressCheckout attribute 19
GetExpressCheckout attribute 19
SetExpressCheckout attribute 19
authorization transaction attributes 17
AuthType
ACH attribute 32
Automated Clearing House
see ACH
AVS
see Address Verification Service
AVS Result Codes 150
AVSResult
TransactionResult attribute 39
AVSResult attributes 40, 41

B
B2B 12
see Business-to-Business
B2C 11
BillFrom Name
Invoice attribute 27
BillTo
RecurringProfileResult attribute 45
RPData attribute 37, 41
BillTo Name
Invoice attribute 27
RPData attribute 37
BillTo PONum
Invoice attribute 27
BillTo TaxExempt
Invoice attribute 27
business-to-business 12
Business-to-Consumer
see B2C
business-to-consumer 11
ButtonSource
PayPal attribute 35
buyer authentication transaction parameters 58
buyer authentication transactions
profile 65
BuyerAuthResult

153

Index

TransactionResult attribute 39
BuyerAuthResult attributes 42

C
cancel recurring profile attributes 23
cancelling a recurring profile 23
capture transaction attributes 17, 19
Card attributes 33
card authorization request example 71
card capture request example 73
card capture response example 73
card credit request example 75
card credit response example 75
card force capture request example 76
card force capture response example 77
card sale request example 77
card sale response example 78
card secure request example 79
card status request example 80
card status response example 80
card void request example 81
card void response example 81
CardNum
Card attribute 33
CardSecure
TransactionResult attribute 39
CardType
Card attribute 33
CatalogNumber
Item attribute 30
CAVV
BuyerAuthResult attribute 42
Check attributes 33, 34
check sale request example 82
check sale response example 83
check transactions 67
CheckNum
Check attribute 33
CheckType
Check attribute 33
City
Address attribute 31
Comment
Invoice attribute 28
RPData attribute 37
commercial credit card transaction parameters 52 to 58

154

communications results 150
CompanyName
RecurringProfileResult attribute 44
RPData attribute 37
core structures 25
Corporate Purchase Card 32
CorrelationID
PayPalResult attribute 41
CostCenterNumber
Item attribute 30
Country
Address attribute 31
credit card recurring billing profile example 95
credit card transaction parameters 48 to 58
credit card transaction response parameters 58 to 59
Credit transaction 65
credit transaction attributes 18
CustIP
Invoice attribute 27
Custom
Invoice attribute 28
PayPalResult attribute 41
customer IP example 83
CustomerBrowser
Invoice attribute 28
CustomerHostName
Invoice attribute 28
CustRef
TransactionResult element 40
CVNum
Card attribute 33
CVResult
TransactionResult attribute 39

D
Date
Invoice attribute 27
Item attribute 30
deactivating a recurring profile
see cancelling a recurring profile
Delivery Date
Item attribute 30
Delivery Time
Item attribute 30
Description
Invoice attribute 27

XMLPay Developer’s Guide

Index

Item attribute 29
DiscountAmt 30
Invoice attribute 28
Item attribute 29
DL
Check attribute 34
DOB
Check attribute 34
DTD
see document type definition
Duplicate
TransactionResult element 40
DutyAmt
Invoice attribute 28

E
ECI
BuyerAuthResult attribute 42
Electronic Commerce Indicator
see ECI
elements
TransactionResult 39
EMail
Invoice attribute 27
PayPal attribute 34
PayPalResult attribute 41
RecurringProfileResult attribute 44
RPData attribute 37
Email
PayPalResult attribute 41
End
RecurringProfileResult attribute 44
example
ACH sale request 70
ACH sale response 71
card authorization request 71
card capture request 73
card capture response 73
card credit request 75
card 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

XMLPay Developer’s Guide

card status response 80
card void request 81
card void response 81
check sale request 82
check sale response 83
credit card recurring billing profile 95
customer IP 83
IAVS result request 88
level 3 invoice 89
line item sale request 90
line item sale response 92
merchant description 92
merchant service number 92
processor result 93
shipping carrier 96
shipping method 96
transaction update 97
ValidateAuthentication request 98
ValidateAuthentication response 98
VerifyEnrollment request 99
VerifyEnrollment response 84, 99
examples
XMLPay document 69
ExpDate
Card attribute 33
ExtData
ACH attribute 32
authorization transaction attribute 17
capture transaction attribute 17
Card attribute 33
Check attribute 34
credit transaction attribute 18
DoExpressCheckout attribute 19
ForceCapture transaction attribute 20
GetExpressCheckout attribute 19
GetStatus transaction attribute 20
Invoice attribute 28
Item attribute 30
PayPal attribute 35
RecurringProfileResult attribute 43, 45
RPData attribute 37
sale transaction attribute 18
SetExpressCheckout attribute 19
TransactionResult attribute 40
ValidateAuthentication transaction attribute 21
VerifyEnrollment transaction attribute 21
ExtData attribute 37

155

Index

ExtData example 95
ExtData, using 47
Extensible Markup Language 9
eXtensible Markup Language
see XML

PayPalResult attribute 41
Invoice attribute 27
RPData attribute 37
FeeAmount
PayPalResult attribute 41
ForceCapture transaction attributes 20
Fraud Prevention Service transaction
parameters 60 to ??
FraudPostprocessorResult
TransactionResult attribute 39
FraudPreprocessorResult
TransactionResult attribute 39
FreightAmt 30
Invoice attribute 28
Item attribute 30

IAVS result request example 88
IAVSResult
TransactionResult attribute 39
Id
RecurringProfile attribute 22
RecurringProfileResult attribute 43
XMLPay transaction attribute 16
including parameter data not supported by schema 47
Inquiry recurring profile 24
Inquiry recurring profile attributes 24
InvNum
Invoice attribute 27
PayPalResult attribute 41
Invoice
capture transaction attribute 17
credit transaction attribute 18
PayData attribute 25
Invoice attributes 27
Item attributes 29
ItemAmt
Invoice attribute 28
Items
Invoice attribute 27

GetStatus transaction attributes 20

level 3 credit card transaction parameters 52 to 58
level 3 invoice example 89
level I purchase card transactions 66
level II purchase card transactions 66
level III purchase card transactions 66
Level3Invoice
Invoice attribute 28
line item sale request example 90
line item sale response example 92
LocaleCode
PayPal attribute 35

F
Fax

H
HandlingAmt 30
Invoice attribute 28
Item attribute 30
HeaderBackColor
PayPal attribute 35
HeaderBorderColor
PayPal attribute 35
HeaderImage
PayPal attribute 35
HostCode
TransactionResult attribute 39
HostURL
TransactionResult attribute 39
HTML 9
HyperText Markup Language 9

156

M
MagData
Card attribute 33
MaxFailPayments
RecurringProfileResult attribute 44
RPData attribute 36

XMLPay Developer’s Guide

Index

MechantServiceNum
Invoice attribute 27
Memo
Invoice attribute 28
merchant description example 92
Merchant ID 13
merchant service number example 92
MerchantCity
MerchantInfo attribute 30
MerchantDescripton
Invoice attribute 27
MerchantInfo
Invoice attribute 28
MerchantState
MerchantInfo attribute 30
MerchantStreet
MerchantInfo attribute 30
MerchantZip
MerchantInfo attribute 31
Message
RecurringProfileResult attribute 43, 44
TransactionResult attribute 39
MICR
Check attribute 34
modify recurring profile attributes 23
modifying recurring profile 23

N
Name
ExtData attribute 37
RecurringProfileResult attribute 44
RPData attribute 36
NameOnCard
Card attribute 33
NationalTaxIncl
Invoice attribute 28
NextPayment
RecurringProfileResult attribute 44
Norwest transaction parameters 60
NoShipping
PayPal attribute 35
NotifyURL
PayPal attribute 35
Number
Item attribute 29
NumFailedPayments

XMLPay Developer’s Guide

RecurringProfileResult attribute 45
NVP tags, passing unsupported 95

O
OptionalTrans
RPData attribute 37
OptionalTransAmt
RPData attribute 37
OrderDesc
Invoice attribute 28
OrigInvNum
Invoice attribute 27
OrigMessage
TransactionResult attribute 39
OrigPNRef
TransactionResult attribute 39
OrigProfileID
RPData attribute 37
OrigResult
TransactionResult attribute 39

P
PageStyle
PayPal attribute 35
PAReq
BuyerAuthResult attribute 42
PARes
ValidateAuthentication transaction attribute 21
Partner
RecurringProfile transaction attribute 22
XMLPayRequest attribute 16
XMLPayResponse attribute 42
XMLPayResponse transaction attribute 38
passing values as extended data 95
Password
UserPass attribute 21
PayData
authorization transaction attribute 17
ForceCapture transaction attribute 20
sale transaction attribute 17
VerifyEnrollment transaction attribute 20
PayData attributes 25
PayDataAuth element 25
PayerID
PayPalResult attribute 41

157

Index

PayerId
PayPal attribute 34
PayerStatus
PayPalResult attribute 41
Payflow Pro
ACH transaction parameters 60
buyer authentication transaction parameters 58
credit card transaction parameters 48 to 58
credit card transaction response parameters 58 to 59
Fraud Prevention Service transaction
parameters 60 to ??
level 3 credit card transaction parameters 52 to 58
retail credit card transaction parameters 48 to 52
Payflow Pro general parameters ?? to 47
PayflowColor
PayPal attribute 35
Payment recurring profile attributes 24
PaymentNum
RPData attribute 37
PaymentsLeft
RecurringProfileResult attribute 44
PaymentTyp
PayPalResult attribute 41
PayPalResult
TransactionResult attribute 39
PayPeriod
RecurringProfileResult attribute 44
RPData attribute 36
PendingReason
PayPalResult attribute 41
Phone
Invoice attribute 27
PayPalResult attribute 41
RPData attribute 37
PickUp Address
Item attribute 30
PKCS-7 25
PNRef
credit transaction attribute 18
GetStatus transaction attribute 20
TransactionResult attribute 39
void transaction attribute 18
PPRef
PayPalResult attribute 41
Prenote
ACH attribute 32
processor result example 93

158

ProcessorResult
TransactionResult attribute 39
profile
ACH transactions 65
buyer authentication 65
check transaction 67
example recurring billing 94
level I purchase card transactions 66
level II purchase card transactions 66
level III purchase card transactions 66
retail credit card transaction 66
retail debit card transaction 66
ProfileID
cancel recurring profile attribute 23
Inquiry recurring profile attribute 24
modify recurring profile attribute 23
Payment recurring profile attribute 24
reactivate recurring profile attribute 24
RecurringProfileResult attribute 43, 44
purchase card level I transactions 66
purchase card level II transactions 66
purchase card level III transactions 66

Q
Quantity
Item attribute 29

R
reactivate recurring profile attributes 24
reactivating a recurring profile 23
ReceiptURL
TransactionResult attribute 39
RecordNumber
Item attribute 30
Recurring
Invoice attribute 27
recurring billing profile example 94
recurring profile
adding 23
cancelling 23
Inquiry 24
modifying 23
payment 24
reactivating 23
RecurringProfile

XMLPay Developer’s Guide

Index

RecurringProfile transaction attribute 22
RecurringProfile attributes 22
RecurringProfile transaction attributes 22
RecurringProfileResult
XMLPayResponse attribute 42
RecurringProfileResult attributes
inquiry 44
non-inquiry 43
RecurringProfileResult element 43
RepeatSale element 101
ReqConfirmShippingPayerId
PayPal attribute 35
RequestAuth 13
RecurringProfile transaction attribute 22
XMLPayRequest attribute 16
RequestAuth element 21
RESPMSG
see also response message 145
response message 145
ResponseData 42
RESULT
see also transaction result status response 145
Result
RecurringProfileResult attribute 43, 44
TransactionResult attribute 39, 40
retail credit card transaction parameters 48 to 52
retail credit card transaction profile 66
retail debit card transaction 66
RetryNumDays
RecurringProfileResult attribute 44
RPData attribute 36
ReturnURL
PayPal attribute 35
RPData
add recurring profile attribute 23
modify recurring profile attribute 23
Payment recurring profile attribute 24
reactivate recurring profile attribute 24
RPData attributes 36
RPRef
RecurringProfileResult attribute 43, 44

S
Sale transaction 65
sale transaction attributes 17
Sale transactions 67

XMLPay Developer’s Guide

SGML 9
ShipCarrier
Invoice attribute 27
ShipFrom
Invoice attribute 27
ShipMethod
Invoice attribute 27
shipping carrier example 96
shipping method example 96
ShippingAmt
Invoice attribute 28
Item attribute 30
ShipTo
Invoice attribute 27
RecurringProfileResult attribute 45
ShipTo Name
PayPalResult attribute 41
RPData attribute 37
ShipToEU
PayPalResult attribute 41
Signature 14
XMLPayResponse attribute 42
XMLPayResponse transaction attribute 38
SKU
Invoice attribute 28
Item attribute 29
SS
Check attribute 34
Standardized General Markup Language 9
Start
RecurringProfileResult attribute 44
RPData attribute 36
State
Address attribute 31
Status
BuyerAuthResult attribute 42
RecurringProfileResult attribute 44
TransactionResult attribute 39
Street
Address attribute 31
StreetMatch
AVSResult attribute 40
syntax
notation 15
notation element 15
XMLPay 15

159

Index

T
TaxAmt 30
Invoice attribute 28
Item attribute 29
Tender
add recurring profile attribute 23
modify recurring profile attribute 23
PayData attribute 25
Payment recurring profile attribute 24
reactivate recurring profile attribute 24
RecurringProfileResult attribute 45
Tender element 32
Term
RecurringProfileResult attribute 44
RPData attribute 36
test and live URLs 8
Time
Item attribute 30
Timeout
RecurringProfile transaction attribute 22
XMLPayRequest attribute 16
Token
PayPal attribute 34
PayPalResult attribute 41
TotalAmt
Invoice attribute 28
Item attribute 30
RPData attribute 36
TrackingNumber
Item attribute 30
Transaction
XMLPayRequest attribute 16
transaction 13
transaction requests 12
transaction responses 12
transaction result status response 145
transaction update example 97
TransactionReceipts 14
XMLPayResponse attribute 42
XMLPayResponse transaction attribute 38
TransactionResult
RecurringProfileResult attribute 43
XMLPayResponse transaction attribute 38
TransactionResult attributes 40
TransactionResult elements 39
transactions

160

ACH 65
buyer authentication 65
check 67
Credit 65
level I purchase card 66
level II purchase card 66
level III purchase card transactions 66
retail credit card 66
retail debit card 66
Sale 65, 67
ValidateAuthentication 65
VerifyEnrollment 65
Void 65

U
UnitOfMeasurement 29
UnitPrice
Item attribute 29
UNSPSCCode
Item attribute 30
unsupported NVP tags, passing values for 95
UPC
Item attribute 29
URL
Invoice attribute 27
URLs, test and live 8
User
UserPass attribute 21
UserDomain
UserPass attribute 21
UserPass attributes 21
using ExtData 95

V
ValidateAuthentication request example 98
ValidateAuthentication response example 98
ValidateAuthentication transaction attributes 21
ValidateAuthentication transactions 65
Value
ExtData attribute 37
Vendor
RecurringProfile transaction attribute 22
XMLPayRequest attribute 16
XMLPayResponse attribute 42
XMLPayResponse transaction attribute 38

XMLPay Developer’s Guide

Index

VerifyEnrollment request example 99
VerifyEnrollment response example 84, 99
VerifyEnrollment transaction attributes 20
VerifyEnrollment transactions 65
Void transaction 65
void transaction attributes 18

Z
Zip
Address attribute 31
ZipMatch
AVSResult attribute 40

W
W3C XML Signature 25, 42
Where to Go For More Information 7

X
XID
BuyerAuthResult attribute 42
XML 9
about 9
benefits of 9
well-formed 9, 131
XMLPay
core structures 25
instruments 10
messaging 12
operations 11
processing models 11
syntax 15
transaction attributes 16
using 10
XMLPay document
examples 69
XMLPayRequest 13
XMLPayRequest attributes 16
XMLPayRequest document 15 to 21
XMLPayRequest document (recurring
profiles) 22 to 24
XMLPayResponse 13
Signature not supported in 14
TransactionReceipts not supported in 14
XMLPayResponse attributes 42
XMLPayResponse document 37, 37 to 40
XMLPayResponse document (recurring
profiles) 41 to 45
XMLPayResponse transaction attributes 38

XMLPay Developer’s Guide

161

Index

162

XMLPay Developer’s Guide

Source Exif Data:

File Type                       : PDF
File Type Extension             : pdf
MIME Type                       : application/pdf
PDF Version                     : 1.4
Linearized                      : Yes
Page Mode                       : UseOutlines
XMP Toolkit                     : Adobe XMP Core 4.0-c316 44.253921, Sun Oct 01 2006 17:14:39
Format                          : application/pdf
Creator                         : PayPal, Inc.
Title                           : XMLPay Developer’s Guide
Create Date                     : 2010:01:14 12:25:45Z
Creator Tool                    : FrameMaker 7.2
Modify Date                     : 2010:01:14 12:25:45Z
Producer                        : Acrobat Distiller 8.1.0 (Windows)
Document ID                     : uuid:5c6b25d9-f90b-46ec-a32f-2aae4e34426d
Instance ID                     : uuid:8df428e2-ab18-4b09-819b-cb7429b91d68
Page Count                      : 162
Author                          : PayPal, Inc.

EXIF Metadata provided by EXIF.tools

Paypal Xmlpay 2009 Developers Guide Developer’s

XMLPay - 2009 - Developer’s Guide PP_PayflowPro_XMLPay_2009 Free User Guide for PayPal Software, Manual

Navigation menu

Versions of this User Manual:

Views

Navigation