Notice of non-liability:
PayPal, Inc. is providing the information i n this document t o you “AS-IS” with all faults. PayPal, Inc. makes no warranties of any kind (whether express,
implied or statutory) with respect to the information co ntained herein. PayPal, Inc. assumes no liability for damages (whether direct or indirect), caused
by errors or omissions, or resulting from the use of this document or the information contained in this document or resulting f rom 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.
Maintenance release. New 10486 error code added for redirects when the process declines the
transaction: The transaction couldn’t be completed. Please redirect your customer to PayPal.
SOAP API Developer ReferenceAugust 201211
What’s New in Version 93.0
12August 2012SOAP API Developer Reference
Preface
About This Guide
The SOAP API Developer Reference describes the PayPal SOAP API.
Intended Audience
This guide is written for developers who are implementing solutions using the SOAP API. It is
written for developers who are implementing solutions using the SOAP API.
Where to Go for More Information
Express Checkout Integration Guide
Express Checkout Advanced Features Guide
Merchant Setup and Administration Guide
Documentation Feedback
Help us improve this guide by sending feedback to:
documentationfeedback@paypal.com
SOAP API Developer ReferenceAugust 201213
Documentation Feedback
14August 2012SOAP API Developer Reference
PayPal SOAP API Basics
1
The PayPal SOAP API is based on open standards known collectively as web services, which
include the Simple Object Access Protocol (SOAP), Web Services Definition Language
(WSDL), and the XML Schema Definition language (XSD). A wide range of development
tools on a variety of platforms support web services.
Like many web services, PayPal SOAP is a combination of client-side and server-side
schemas, hardware and software servers, and core services.
PayPal SOAP High-level Diagram
In an object-oriented processing model, the interface to SOAP requests/responses is an object
in your application’s native programming language. Your third-party SOAP client generates
business-object interfaces and network stubs from PayPal-provided WSDL and XSD files that
specify the PayPal SOAP message structure, its contents, and the PayPal API service bindings.
A business application works with data in the form of object properties to send and receive
data by calling object methods. The SOAP client handles the details of building the SOAP
request, sending it to the PayPal service, and converting the response back to an object.
SOAP API Developer ReferenceAugust 201215
PayPal SOAP API Basics
1
PayPal WSDL/XSD Schema Definitions
PayPal WSDL/XSD Schema Definitions
The PayPal Web Services schema and its underlying eBay Business Language (eBL) base and
core components are required for developing applications with the PayPal Web Services API.
The following are the locations of the WSDL and XSD files.
Location of PayPal WSDL and XSD Files
Development and Test with the PayPal Sandbox API Service
PayPal Schemahttps://www.sandbox.paypal.com/wsdl/PayPalSvc.wsdl
eBL Base Components and
Component Types
Production with Live PayPal Web Services API Service
PayPal Schemahttps://www.paypal.com/wsdl/PayPalSvc.wsdl
eBL Base Components and
The PayPal SOAP API comprises individual API definitions for specific business functions.
As a foundation, the API relies on eBay Business Language (eBL) base and core components.
The core eBL structures AbstractRequestType and AbstractResponseType are the
basis of the SOAP request and response of each PayPal API. AbstractResponseType is
also the framework for error messages common across all PayPal APIs.
PayPal has made some schema design decisions that can affect how businesses design their
own applications.
Enumerations: Enumerations are defined directly in the PayPal API schema.
Troubleshooting information: The PayPal API returns information about elements that
trigger errors.
Backward compatibility: The PayPal API is versioned so that business applications are
backward compatible when new elements are introduced to the server-side schema.
NOTE: eBL defines many structures that are specific to processing auctions. PayPal’s SOAP
schema includes these definitions to maintain compatibility with eBay’s SOAP and
for possible future joint use of SOAP across both eBay and PayPal. The material
focuses only on those SOAP definitions pertinent to use of the PayPal SOAP API.
16August 2012SOAP API Developer Reference
Security
PayPal SOAP API Basics
Security
The PayPal SOAP API service is protected to ensure that only authorized PayPal members use
it. There are four levels of security:
1. A required API username (Username field) and API password (Password field).
2. A third required authentication mechanism, which is either one of the following:
– Client-side request signing using a PayPal-issued API Certificate
– Request authentication using an API Signature included in the request (Signature
field)
3. An optional third-party authorization to make the API call on some other account’s behalf
(the optional Subject field).
4. Secure Sockets Layer (SSL) data transport.
A failure of authenticated security at any one of these levels denies access to the PayPal SOAP
For the security of your business, PayPal must verify that merchants or third-party developers
are permitted to initiate a transaction before they make one. PayPal authenticates each request.
If the request cannot be authenticated, a SOAP security fault is returned.
In the SOAP request header, your SOAP client must set the Username, Password elements
to pass an API username/password combination. In addition, you can set the Signature or
Subject elements to specify your API signature string and an optional third-party account
email address for authentication.
The following example shows part of the RequesterCredentials elements. These
elements are required for all SOAP requests.
RequesterCredentials Authentication Elements in SOAP Header
ElementValueDescription
<Username>api_usernameYour API usernam e, which is auto-generated by PayPal when you
apply for a digital certificate to use the PayPal SOAP API. You can
see this value on
API Access > API Certificate Information.
<Password>api_passwordY our API password, which you specify when you apply for a digital
certificate to use the PayPal SOAP API.
<Signature>api_signatureYour API si gnat ure, if you use one instead of an API Certificate.
https://www.paypal.com/ in your Profile under
<Subject>authorizing_
account_
emailaddress
The email address of a third-party for whom you are sending
requests to the PayPal SOAP API. Yo ur API username m ust have
been granted permission by this third-party to make any particular
PayPal API request.
Related information:
Request Structure
SOAP Service Endpoints
Depending on your chosen authentication mechanism, your SOAP requests must be processed
by different service endpoints.
SOAP Service Endpoints
Authentication
Mechanism
API Signaturehttps://api-3t.paypal.com/2.0/https://api-3t.sandbox.paypal.com/2.0/
API Certificatehttps://api.paypal.com/2.0/https://api.sandbox.paypal.com/2.0/
Live Production EndpointTest (Sandbox) Endpoint
SOAP Request Envelope
The following diagram illustrates the contents of a PayPal SOAP request envelope.
All PayPal APIs are based on two core structures: AbstractRequestType and
AbstractResponseType.
18August 2012SOAP API Developer Reference
Diagram of SOAP Request Envelope
PayPal SOAP API Basics
Request Structure
1
Request Structure
The following annotated description of the SOAP request structure shows the elements
required by the PayPal SOAP API.
12, 13The <Username> and <Password> fields are part of the PayPal SOAP API
<RequesterCredentials> security authentication mechanism you must construct for
every SOAP request header.
14The <Signature> element should include your API signature string if that is the kind of API
credential you are using.
15The <Subject> element can specify a third-party PayPal account by whom you are
authorized to make this request.
19 through 27The SOAP request for every PayPal API follows this element-naming pattern. The API’s
specific name is appended with Req, and in this element the specific_api_name_Request is
nested. Each specific_api_name_Request has a corresponding
specific_api_name_RequestType.
22The number of the PayPal SOAP API version is required on each SOAP request.
This version number is the value of ns:version in
https://www.paypal.com/wsdl/PayPalSvc.wsdl.
24For details about required and optional elements and values for specific requests, see the
description of individual APIs.
Related information:
SOAP RequesterCredentials: Username, Password, Signature, and Subject
20August 2012SOAP API Developer Reference
SOAP Message Style: doc-literal
PayPal uses doc-literal SOAP messaging, not rpc-encoding. With doc-literal, a
single service interface call passes an XML document in the request to the PayPal API server,
which responds with an XML document instance.
Response Structure
The following is an annotated description of the structure of a SOAP response from the PayPal
API where response is Success:
<element s_for_specific_ap i_response> dat a
</elements_for_specific_api_response>
</specific_api_name_Response>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
Annotation of Generic SOAP Response
LinesComment
22 and 31The specific_api_name_Response start and end elements.
23Each API response contains a timestamp with its date and time in UTC/GMT.
24The <Ack> element contains the string Success after the corresponding request has been
successfully processed.
In the case of errors, Ack is set to a value other than Success, and the response body contains
an <Errors> element with information to help you troubleshoot the cause of the error. See
“Error Responses” on page 22.
26The <CorrelationID> element contains information about the PayPal application that
processed the request.
Use the value of this element if you need to troubleshoot a problem with one of your requests.
27 through 30The different PayPal APIs return different structures depending on their response definitions.
For detailed information, see the description of the individual APIs.
NOTE: Because a field is defined in the formal structure of an API response, this does not
mean that the field is necessarily returned. Data are returned in a response only if
PayPal has recorded data that corresponds to the field.
Related information:
Error Responses
Error Responses
If a request is malformed or contains some other error, the body of the SOAP response
contains an <Errors> element with other elements that can help you troubleshoot the cause
of the error.
The structure of error messages are as follows:
22August 2012SOAP API Developer Reference
PayPal SOAP API Basics
Error Responses
The most important of these additional elements are as follows:
ShortMessage
LongMessage
ErrorCode
Additional information can appear as part of ErrorParametersType. For example, if the
error in ParamID is ProcessorResponse, the Value would contain the processor-specific
error, such as 0091. Values set in the ErrorParametersType are not set by PayPal; rather,
they are passed through from the source.
1
NOTE: PayPal only passes selected values in ErrorParametersType.
The following example shows the error response if your API username and password do not
match a legitimate API username and password on file with PayPal.
Example of SOAP Error Response: Bad Username or Password
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV: Envelope details not shown >
<S OAP-ENV:Header>... details not shown.</SOAP-ENV:Header>
The value returned in CorrelationID is important for PayPal to determine the precise cause
of any error you might encounter. If you have to troubleshoot a problem with your requests,
we suggest that you capture the value of CorrelationID so you can report it to PayPal.
UTF-8 Character Encoding
The PayPal API assumes that all data in requests is in Unicode, specifically, the Unicode (or
UCS) Transformation Format, 8-bit encoding form (UTF-8).
In responses, the API always returns data in UTF-8.
Date/Time Formats
The PayPal SOAP API schema defines date/time values as Coordinated Universal Time
(UTC/GMT), using ISO 8601 format, and of type ns:dateTime. An example date/time
stamp is 2006-08-24T05:38:48Z
Core Currency Amount Data Type
The core currency amount data type is called BasicAmountType and is derived from
string. All currency amount fields have the following structure:
1. The currencyID attribute is required.
2. The amount must have two decimal places.
24August 2012SOAP API Developer Reference
PayPal SOAP API Basics
Core Currency Amount Data Type
3. The decimal separator must be a period (“.”).
4. You must not use any thousands separator.
5. BasicAmountType has a data type of ebl:CurrencyCodeType, which defines a large
number of different currency codes. However, for your processing to succeed, you must set
currencyCode to a valid currency code. Some APIs support only a subset of currencies.
Here is an example. (The field name Amount is an example; actual field names can vary
depending on the specific API.)
<Amount currencyID=”currencyCode”>3.00</Amount>
1
SOAP API Developer ReferenceAugust 201225
PayPal SOAP API Basics
1
Core Currency Amount Data Type
26August 2012SOAP API Developer Reference
AddressVerify API Operation
2
The AddressVerify API operation confirms whether a postal address and postal code match
those of the specified PayPal account holder.
AddressVerify Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
AddressVerifyRequest Fields
FieldDescription
Emailebl:EmailAddressType
(Required) Email address of a PayPal member to verify.
Character length and limitations: 255 single-byte characters maximum with the input
mask: ?@?.??
SOAP API Developer ReferenceAugust 201227
AddressV erify API Operation
2
AddressVerify Response Message
FieldDescription
Streetxs:string
(Required) First line of the billing or shipping postal address to verify. To pass
verification, the value of Street must match the first 3 single-byte characters of a
postal address on file for the PayPal member.
Character length and limitations: 35 single-byte characters maximum, including
alphanumeric plus - , . ‘ # \. Whitespace and case of input value are ignored.
Zipxs:string
(Required) Postal code to verify. To pass verification, the value of Zip must match
the first 5 single-byte characters of the postal code of the verified postal address for
the verified PayPal member.
Character length and limitations: 16 single-byte characters maximum. Whitespace
and case of input value are ignored.
AddressVerify Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
28August 2012SOAP API Developer Reference
AddressVerify Response Fields
FieldDescription
ConfirmationCodeebl:AddressStatuscodeType
Indicates whether the address is a confirmed address on file at PayPal. It is one of the
following values:
None – The request value of the Email element does not match any email address
on file at PayPal.
Confirmed – If the response value of the StreetMatch element is Matched,
the entire postal address is confirmed.
Unconfirmed – PayPal responds that the postal address is unconfirmed.
NOTE: The values Confirmed and Unconfirmed both indicate that the member
email address passed verification.
StreetMatchebl:MatchStatusCodeType
Indicates whether the street address matches address information on file at PayPal. It
is one of the following values:
None – The request value of the Email element does not match any email address
on file at PayPal. No comparison of other request values was made.
Matched – The request value of the Street element matches the first 3 single-byte
characters of a postal address on file for the PayPal member.
Unmatched – The request value of the Street element does not match any
postal address on file for the PayPal member.
AddressVerify API Operation
AddressVerify Response Message
2
ZipMatchebl:MatchStatusCodeType
Indicates whether the zip address matches address information on file at PayPal. It is
one of the following values:
None – The request value of the Street element was unmatched. No comparison
of the Zip element was made.
Matched – The request value of the Zip element matches the zip code of the
postal address on file for the PayPal member.
Unmatched – The request value of the Zip element does not match the zip code
of the postal address on file for the PayPal member.
CountryCodeebl:CountryCodeType
Country code (ISO 3166) on file for the PayPal email address.
Character length and limitations: 2 single-byte characters
PayPalTokenxs:string
The token contains encrypted information about the member’s email address and
postal address. If you pass the value of the token in the HTML variable
address_api_token of Buy Now buttons, PayPal prevents the buyer from using
an email address or postal address other than those that PayPal verified with this API
call. The token is valid for 24 hours.
Character length and limitations: 94 single-byte characters
SOAP API Developer ReferenceAugust 201229
AddressV erify API Operation
2
AddressVerify Response Message
30August 2012SOAP API Developer Reference
Authorization and Capture API
3
Operation Reference
The Authorization and Capture API operations describe the PayPal API operations related to
delayed payment settlement:
DoCapture API Operation
Captures an authorized payment.
DoCapture Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer ReferenceAugust 201231
Authorization and Capture API Operation Reference
3
DoCapture API Operation
DoCapture Request Fields
FieldDescription
AuthorizationIDxs:string
(Required) Authorization identification number of the payment you want to capture.
This is the transaction ID returned from DoExpressCheckoutPayment, DoDirectPayment, or CheckOut. For point-of-sale transactions, this is the
transaction ID returned by the CheckOut call when the payment action is
Authorization.
Character length and limitations: 19 single-byte characters maximum
Amountebl:BasicAmountType
(Required) Amount to capture.
NOTE: You must set the currencyID attribute to one of the three-character
currency codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
CompleteTypeebl:CompleteCodeType
(Required) Indicates whether or not this is your last capture. It is one of the following
values:
Complete – This is the last capture you intend to make.
NotComplete – You intend to make additional captures.
NOTE: If Complete, any remaining amount of the original authorized transaction is
automatically voided and all remaining open authorizations are voided.
InvoiceIDxs:string
(Optional) Your invoice number or other identification number that is displayed to
you and to the buyer in their transaction history. The value is recorded only if the
authorization you are capturing is an Express Checkout order authorization.
NOTE: This value on DoCapture overwrites a value previously set on
DoAuthorization.
Character length and limitations: 127 single-byte alphanumeric characters
Notexs:string
(Optional) An informational note about this settlement that is displayed to the buyer
in email and in their transaction history.
Character length and limitations: 255 single-byte characters
32August 2012SOAP API Developer Reference
FieldDescription
SoftDescriptorxs:string
(Optional) Per transaction description of the payment that is passed to the buyer’s
credit card statement.
If you provide a value in this field, the full descriptor displayed on the buyer’s
statement has the following format:
<PP * | PAYPAL *><Merchant descriptor as set in the Payment
Receiving Preferences><1 space><soft descriptor>
Character length and limitations: The soft descriptor can contain only the following
characters:
If you pass any other characters (such as “,”), PayPal returns an error code.
The soft descriptor does not include the phone number, which can be toggled between
your customer service number and PayPal’s Customer Service number.
The maximum length of the soft descriptor is 22 characters. Of this, the PayPal prefix
uses either 4 or 8 characters of the data format. Thus, the maximum length of the soft
descriptor information that you can pass in this field is:
22 - len(<PP * | PAYPAL *>) - len(<Descriptor set in Payment
Receiving Preferences> + 1)
For example, assume the following conditions:
The PayPal prefix toggle is set to PAYPAL * in PayPal’s administration tools.
The merchant descriptor set in the Payment Receiving Preferences is set to EBAY.
The soft descriptor is passed in as JanesFlowerGifts LLC.
The resulting descriptor string on the credit card is:
PAYPAL *EBAY JanesFlow
Authorization and Capture API Operation Reference
DoCapture API Operation
3
MerchantStoreDetailsns:MerchantStoreDetailsType
(Optional) Information about the merchant store.
This field is available since version 82.0.
MsgSubIdxs:string
(Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
SOAP API Developer ReferenceAugust 201233
Authorization and Capture API Operation Reference
3
DoCapture API Operation
MerchantStoreDetailsTypeFields
FieldDescription
StoreIDxs:string
Identifier of the merchant store at which the refund is given. This field is
required for point-of-sale transactions.
Character length and limitations: 50 single-byte characters
This field is available since version 82.0.
TerminalIDxs:string
(Optional) ID of the terminal.
Character length and limitations: 50 single-byte characters
This field is available since version 82.0.
DoCapture Response Message
NOTE: If you use version 56.0 or later of the DoCaptue API, only the authorization ID,
transaction ID, transaction type, payment date, gross amount, and payment status are
guaranteed to be returned. If you need the values of other fields and they are not
returned, you can obtain their values later by calling
by using the reporting mechanism. Not applicable to point of sale transactions.
GetTransactionDetails or
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
34August 2012SOAP API Developer Reference
Authorization and Capture API Operation Reference
DoCapture API Operation
3
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoCapture Response Fields
FieldDescription
AuthorizationIDxs:string
Authorization identification number you specified in the request.
Character length and limits: 19 single-byte characters maximum
PaymentInfoebl:PaymentInfoType
Information about the payment.
SOAP API Developer ReferenceAugust 201235
Authorization and Capture API Operation Reference
3
DoCapture API Operation
FieldDescription
MsgSubIdxs:string
(Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
PaymentInfoTypeFields
FieldDescription
TransactionIDxs:string
Unique transaction ID of the payment.
Character length and limitations: 17 single-byte characters
ParentTransactionIDxs:string
Parent or related transaction identification number. This field is populated for the
following transaction types:
Reversal. Capture of an authorized transaction.
Reversal. Reauthorization of a transaction.
Capture of an order. The value of ParentTransactionID is the original
OrderID.
Authorization of an order. The value of ParentTransactionID is the original
OrderID.
Capture of an order authorization.
Void of an order. The value of ParentTransactionID is the original OrderID.
Character length and limitations: 16 digits
Only authorization of an order and capture of an order authorization apply to point-
of-sale transactions.
ReceiptIDxs:string
Receipt identification number.
Character length and limitations: 16 digits
Empty for point-of-sale transactions.
TransactionTypens:PaymentTransactionCodeType
The type of transaction. It is one of the following values:
cart
express-checkout
Character length and limitations:15 single-byte characters
36August 2012SOAP API Developer Reference
Authorization and Capture API Operation Reference
FieldDescription
PaymentTypeebl:PaymentCodeType
Indicates whether the payment is instant or delayed. It is one of the following values:
none
echeck
instant
Character length and limitations: 7 single-byte characters
PaymentDatexs:dateTime
Time/date stamp of payment. For example: 2006-08-15T17:23:15Z
GrossAmountebl:BasicAmountType
The final amount charged, including any shipping and taxes from your Merchant
Profile. Shipping and taxes do not apply to point-of-sale transactions.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,). Equivalent to 9 characters maximum for USD.
DoCapture API Operation
3
FeeAmountebl:BasicAmountType
PayPal fee amount charged for the transaction.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,). Equivalent to 9 characters maximum for USD.
SettleAmountebl:BasicAmountType
Amount deposited in your PayPal account after a currency conversion.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,). Equivalent to 9 characters maximum for USD.
TaxAmountebl:BasicAmountType
Tax charged on the transaction.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,). Equivalent to 9 characters maximum for USD.
ExchangeRatexs:string
Exchange rate if a currency conversion occurred. Relevant only if your are billing in
their non-primary currency . If the customer chooses to pay with a currency other than
the non-primary currency, the conversion occurs in the buyer’s account.
Character length and limitations: A decimal that does not exceed 17 characters,
including decimal point
SOAP API Developer ReferenceAugust 201237
Authorization and Capture API Operation Reference
3
DoCapture API Operation
FieldDescription
PaymentStatusebl:PendingStatusCodeType
Status of the payment. It is one of the following values:
NOTE: In a successful DoCapture response for a point-of-sale authorization, the only
value value is
None – No status
Canceled-Reversal – This means a reversal has been canceled. For example,
Completed.
you won a dispute with the customer, and the funds for the transaction that was
reversed have been returned to you.
Completed – The payment has been completed, and the funds have been added
successfully to your account balance. This is the only value status for point-ofsale transactions.
Denied – You denied the paym ent. Th is ha ppens onl y if the payment was
previously pending because of possible reasons described for the PendingReason
element.
Expired – The authorization period for this payment has been reached.
Failed – The payment has failed. This happens only if the payment was made
from your customer’s bank account.
Pending – The payment is pending. See the PendingReason field for more
information.
Refunded – You refunded the payment.
Reversed – A payment was reversed due to a chargeback or other type of
reversal. The funds have been removed from your account balance and returned to
the buyer. The reason for the reversal is specified in the ReasonCode element.
Processed – A payment has been accepted.
Voided – An authorization for this transaction has been voided.
38August 2012SOAP API Developer Reference
Authorization and Capture API Operation Reference
FieldDescription
PendingReasonebl:PendingStatusCodeType
NOTE: PendingReason is returned in the response only if PaymentStatus is
Pending. This field does not apply to capturing point-of-sale authorizations,
which do not create pending payments.
Reason the payment is pending. It is one of the following values:
none: – No pending reason.
address – The payment is pending because your customer did not include a
confirmed shipping address and your Payment Receiving Preferences is set such
that you want to manually accept or deny each of these payments. To change your
preference, go to the Preferences section of your Profile.
echeck – The payment is pending because it was made by an eCheck that has not
yet cleared.
intl –The payment is pending because you hold a non-U.S. account and do not
have a withdrawal mechanism. You must manually accept or deny this payment
from your Account Overview.
multi-currency – You do not have a balance in the currency sent, and you do
not have your Payment Receiving Preferences set to automatically
convert and accept this payment. You must manually accept or deny this payment.
verify – The payment is pending because you are not yet verified. You must
verify your account before you can accept this payment.
other – The payment is pending for a reason other than those listed above. For
more information, contact PayPal Customer Service.
DoCapture API Operation
3
SOAP API Developer ReferenceAugust 201239
Authorization and Capture API Operation Reference
3
DoAuthorization API Operation
DoAuthorization API Operation
Authorize a payment.
DoAuthorization Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoAuthorization Request Fields
FieldDescription
TransactionIDxs:string
(Required) Value of the order’s transaction identification number returned by PayPal.
Character length and limitations: 19 single-byte characters
Amountebl:BasicAmountType
(Required) Amount to authorize.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
TransactionEntityebl:TransactionEntityType
(Optional) Type of transaction to authorize. The only allowable value is Order,
which means that the transaction represents a buyer order that can be fulfilled over 29
days.
40August 2012SOAP API Developer Reference
Authorization and Capture API Operation Reference
FieldDescription
MsgSubIdxs:string
(Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
DoAuthorization Response Message
DoAuthorization API Operation
3
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoAuthorization Response Fields
FieldDescription
TransactionIDxs:string
Authorization identification number.
Amountebl:BasicAmountType
Amount you specified in the request.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency . It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
SOAP API Developer ReferenceAugust 201241
Authorization and Capture API Operation Reference
3
DoAuthorization API Operation
FieldDescription
MsgSubIdxs:string
(Optional) A message ID used for idempotence to uniquely identify a message. This
ID can later be used to request the latest results for a previous request without
generating a new request. Examples of this include requests due to timeouts or errors
during the original request.
Character length and limitations: string of up to 38 single-byte characters.
This field is available since version 92.0.
AuthorizationInfo Fields
FieldDescription
PaymentStatusebl:PaymentStatusCodeType
Status of the payment. It is one of the following values:
None – No status.
Canceled-Reversal – A reversal has been canceled. For example, when
you win a dispute, PayPal returns the funds for the reversal to you.
Completed – The payment has been completed, and the funds have been
added successfully to your account balance.
Denied – You denied th e payment. This happens only if the payment was
previously pending because of possible reasons described for the
PendingReason element.
Expired – The authorization period for this payment has been reached.
Failed – The payment has failed. This happens only if the payment was made
from the buyer’s bank account.
In-Progress – The transaction has not terminated. For example, an
authorization may be awaiting completion.
Partially-Refunded – The payment has been partially refunded.
Pending – The payment is pending. See the PendingReason field for more
information.
Refunded – You refunded the payment.
Reversed– A payment was reversed due to a chargeback or other type of
reversal. PayPal removes the funds from your account balance and returns
them to the buyer. The ReasonCode element spec ifies the reason for the
reversal.
Processed – A payment has been accepted.
Voided – An authorization for this transaction has been voided.
42August 2012SOAP API Developer Reference
Authorization and Capture API Operation Reference
FieldDescription
PendingReasonebl:PendingStatusCodeType
Reason the payment is pending. It is one of the following values:
none – No pending reason.
address – The payment is pending because your customer did not include a
confirmed shipping address and your Payment Receiving Preferences is set
such that you want to manually accept or deny each of these payments. To
change your preference, go to the Preferences section of your Profile.
authorization – The payment is pending because it has been authorized but
not settled. You must capture the funds first.
echeck – The payment is pending because it was made by an eCheck that has
not yet cleared.
intl – The payment is pending because you hold a non-U.S. account and do
not have a withdrawal mechanism. You must manually accept or deny this
payment from your Account Overview.
multi-currency – You do not have a balance in the currency sent, and you
do not have your Payment Receiving Preferences set to automatically
convert and accept this payment. You must manually accept or deny this
payment.
order – The payment is pending because it is part of an order that has been
authorized but not settled.
paymentreview – The payment is pending while it is being reviewed by
PayPal for risk.
unilateral – The payment is pending because it was made to an email
address that is not yet registered or confirmed.
verify – The payment is pending because you are not yet verified. You must
verify your account before you can accept this payment.
other – The payment is pending for a reason other than those listed above. For
more information, contact PayPal Customer Service.
NOTE: PendingReason is returned in the response only if PaymentStatus is
Pending.
DoAuthorization API Operation
3
ProtectionEligibilityxs:string
Prior to version 64.4, the kind of seller protection in force for the transaction. It is
one of the following values:
Eligible – Merchant is protected by PayPal's Seller Protection Policy for
Unauthorized Payment and Item Not Received.
PartiallyEligible – Merchant is protected by PayPal's Seller Protection
Policy for Item Not Received.
Ineligible – Merchant is not protected under the Seller Protection Policy.
SOAP API Developer ReferenceAugust 201243
Authorization and Capture API Operation Reference
3
DoReauthorization API Operation
FieldDescription
ProtectionEligibility
Type
xs:string
Since version 64.4, the kind of seller protection in force for the transaction. It is
one of the following values:
Eligible – Merchant is protected by PayPal's Seller Protection Policy for
both Unauthorized Payment and Item Not Received.
ItemNotReceivedEligible – Merchant is protected by PayPal's Seller
Protection Policy for Item Not Received.
UnauthorizedPaymentEligible – Merchant is protected by PayPal's
Seller Protection Policy for Unauthorized Payment.
Ineligible – Merchant is not protected under the Seller Protection Policy.
This field is available since version 64.4.
DoReauthorization API Operation
DoReauthorization Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
44August 2012SOAP API Developer Reference
Authorization and Capture API Operation Reference
DoReauthorization Request Fields
FieldDescription
AuthorizationIDxs:string
(Required) Value of a previously authorized transaction identification number
returned by PayPal.
Character length and limitations: 19 single-byte characters
Amountebl:BasicAmountType
(Required) Amount to reauthorize.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
DoReauthorization Response Message
DoReauthorization API Operation
3
NOTE: Not all fields shown are available for use. Only use fields described in the
documentation.
DoReauthorization Response Fields
FieldDescription
AuthorizationIDxs:string
New authorization identification number.
Character length and limits:19 single-byte characters
SOAP API Developer ReferenceAugust 201245
Authorization and Capture API Operation Reference
3
DoReauthorization API Operation
AuthorizationInfo Fields
FieldDescription
PaymentStatusebl:PaymentStatusCodeType
Status of the payment. It is one of the following values:
None – No status.
Canceled-Reversal – A reversal has been canceled. For example, when
you win a dispute, PayPal returns the funds for the reversal to you.
Completed – The payment has been completed, and the funds have been
added successfully to your account balance.
Denied – You denied th e payment. This happens only if the payment was
previously pending because of possible reasons described for the
PendingReason element.
Expired – The authorization period for this payment has been reached.
Failed – The payment has failed. This happens only if the payment was made
from the buyer’s bank account.
In-Progress – The transaction has not terminated. For example, an
authorization may be awaiting completion.
Partially-Refunded – The payment has been partially refunded.
Pending – The payment is pending. See the PendingReason field for more
information.
Refunded – You refunded the payment.
Reversed– A payment was reversed due to a chargeback or other type of
reversal. PayPal removes the funds from your account balance and returns
them to the buyer. The ReasonCode element spec ifies the reason for the
reversal.
Processed – A payment has been accepted.
Voided – An authorization for this transaction has been voided.
46August 2012SOAP API Developer Reference
Authorization and Capture API Operation Reference
FieldDescription
PendingReasonebl:PendingStatusCodeType
Reason the payment is pending. It is one of the following values:
none – No pending reason.
address – The payment is pending because your customer did not include a
confirmed shipping address and your Payment Receiving Preferences is set
such that you want to manually accept or deny each of these payments. To
change your preference, go to the Preferences section of your Profile.
authorization – The payment is pending because it has been authorized but
not settled. You must capture the funds first.
echeck – The payment is pending because it was made by an eCheck that has
not yet cleared.
intl – The payment is pending because you hold a non-U.S. account and do
not have a withdrawal mechanism. You must manually accept or deny this
payment from your Account Overview.
multi-currency – You do not have a balance in the currency sent, and you
do not have your Payment Receiving Preferences set to automatically
convert and accept this payment. You must manually accept or deny this
payment.
order – The payment is pending because it is part of an order that has been
authorized but not settled.
paymentreview – The payment is pending while it is being reviewed by
PayPal for risk.
unilateral – The payment is pending because it was made to an email
address that is not yet registered or confirmed.
verify – The payment is pending because you are not yet verified. You must
verify your account before you can accept this payment.
other – The payment is pending for a reason other than those listed above. For
more information, contact PayPal Customer Service.
NOTE: PendingReason is returned in the response only if PaymentStatus is
Pending.
DoReauthorization API Operation
3
ProtectionEligibilityxs:string
Prior to version 64.4, the kind of seller protection in force for the transaction. It is
one of the following values:
Eligible – Merchant is protected by PayPal's Seller Protection Policy for
Unauthorized Payment and Item Not Received.
PartiallyEligible – Merchant is protected by PayPal's Seller Protection
Policy for Item Not Received.
Ineligible – Merchant is not protected under the Seller Protection Policy.
SOAP API Developer ReferenceAugust 201247
Authorization and Capture API Operation Reference
3
DoVoid API Operation
FieldDescription
ProtectionEligibility
Type
xs:string
Since version 64.4, the kind of seller protection in force for the transaction. It is
one of the following values:
Eligible – Merchant is protected by PayPal's Seller Protection Policy for
both Unauthorized Payment and Item Not Received.
ItemNotReceivedEligible – Merchant is protected by PayPal's Seller
Protection Policy for Item Not Received.
UnauthorizedPaymentEligible – Merchant is protected by PayPal's
Seller Protection Policy for Unauthorized Payment.
Ineligible – Merchant is not protected under the Seller Protection Policy.
This field is available since version 64.4.
DoVoid API Operation
Void an order or an authorization.
DoVoid Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
48August 2012SOAP API Developer Reference
DoVoid Request Fields
FieldDescription
AuthorizationIDxs:string
(Required) Original authorization ID specifying the authorization to void or, to void
an order, the order ID.
IMPORTANT: If you are voiding a transaction that has been reauthorized, use the ID
Character length and limitations: 19 single-byte characters
Notexs:string
(Optional) Informational note about this void that is displayed to the buyer in email
and in their transaction history.
Character length and limitations: 255 single-byte characters
DoVoid Response Message
Authorization and Capture API Operation Reference
DoVoid API Operation
from the original authorization, and not the reauthorization.
3
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer ReferenceAugust 201249
Authorization and Capture API Operation Reference
3
DoVoid API Operation
DoVoidResponse Fields
FieldDescription
AuthorizationIDxs:string
Authorization identification number you specified in the request.
Character length and limitations: 19 single-byte characters
50August 2012SOAP API Developer Reference
DoDirectPayment API Operation
4
The DoDirectPayment API Operation enables you to process a credit card payment.
DoDirectPayment Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer ReferenceAugust 201251
DoDirectPayment API Operation
4
DoDirectPayment Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
52August 2012SOAP API Developer Reference
DoDirectPayment API Operation
DoDirectPayment Request Message
4
SOAP API Developer ReferenceAugust 201253
DoDirectPayment API Operation
4
DoDirectPayment Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
54August 2012SOAP API Developer Reference
DoDirectPayment API Operation
DoDirectPayment Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
4
SOAP API Developer ReferenceAugust 201255
DoDirectPayment API Operation
4
DoDirectPayment Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoDirectPayment Request Fields
FieldDescription
PaymentActionebl:PaymentActionCodeType
(Optional) How you want to obtain payment. It is one of the following values:
Authorization – This payment is a basic authorization subject to settlement
with PayPal Authorization and Capture.
Sale – This is a final sale for which you are requesting payment (default).
NOTE: Order is not allowed for Direct Payment.
Character length and limit: Up to 13 single-byte alphabetic characters
56August 2012SOAP API Developer Reference
FieldDescription
CreditCardebl:CreditCardDetailsType
(Required) Information about the credit card to be charged.
PaymentDetailsebl:PaymentDetailsType
(Required) Information about the credit card to be charged.
IPAddressxs:string
(Required) IP address of the buyer’s browser.
NOTE: PayPal records this IP addresses as a means to detect possible fraud.
Character length and limitations: 15 single-byte characters, including periods, for
example, 255.255.255.255
MerchantSessionIdxs:string
(Optional) Your customer session identification token.
NOTE: PayPal records this optional session identification token as an additional
means to detect possible fraud.
Character length and limitations: 64 single-byte numeric characters
DoDirectPayment API Operation
DoDirectPayment Request Message
4
ReturnFMFDetailsxs:boolean
(Optional) Flag to indicate whether you want the results returned by Fraud
Management Filters. By default, you do not receive this information. It is one of the
following values:
0 – Do not receive FMF details (default).
1 – Receive FMF details.
ThreeDSecureRequestns:ThreeDSecureRequestType
(Optional) Information about 3-D Secure settings (UK only).
SOAP API Developer ReferenceAugust 201257
DoDirectPayment API Operation
4
DoDirectPayment Request Message
CreditCardDetailsType Fields
FieldDescription
CreditCardTypeebl:CreditCardType
(Optional) Type of credit card. For UK, only Maestro, MasterCard, Discover,
and Visa are allowable. For Canada, only MasterCard and Visa are allowable and
Interac debit cards are not supported. It is one of the following values:
Visa
MasterCard
Discover
Amex
Maestro: See note.
NOTE: If the credit card type is Maestro, you must set currencyId to GBP. In
addition, you must specify either
IssueNumber.
Character length and limitations: Up to 10 single-byte alphabetic characters
CreditCardNumberxs:string
(Required) Credit card number.
Character length and limitations: Numeric characters only with no spaces or
punctutation. The string must conform with modulo and length required by each
credit card type.
StartMonth and StartYear or
ExpMonthxs:int
(Required) Credit card expiration month.
Character length and limitations: 2 single-byte numeric characters, including leading
zero
ExpYearxs:int
(Required) Credit card expiration year.
Character length and limitations: 4 single-byte numeric characters
CVV2xs:string
Card Verification Value, version 2. Your Merchant Account settings determine
whether this field is required. To comply with credit card processing regulations, you
must not store this value after a transaction has been completed.
Character length and limitations: For Visa, MasterCard, and Discover, the value is
exactly 3 digits. For American Express, the value is exactly 4 digits.
CardOwnerns:PayerInfoType
(Required) Details about the owner of the credit card.
StartMonthxs:int
(Optional) Month that Maestro card was issued.
Character length and limitations: 2-digit, zero-filled if necessary
58August 2012SOAP API Developer Reference
FieldDescription
StartYearxs:int
(Optional) Year that Maestro card was issued.
Character length and limitations: 4 digits
IssueNumberxs:string
(Optional) Issue number of Maestro card.
Character length and limitations: 2 numeric digits maximum
PayerInfoType Fields
FieldDescription
Payerebl:EmailAddressType
(Required) Email address of buyer.
Character length and limitations: 127 single-byte characters
PayerIDebl:UserIDType
(Optional) Unique PayPal Customer Account identification number.
Character length and limitations:13 single-byte alphanumeric characters
DoDirectPayment API Operation
DoDirectPayment Request Message
4
PayerStatusebl:PayPalUserStatusCodeType
(Optional) Status of buyer. It is one of the following values:
verified
unverified
Character length and limitations: 10 single-byte alphabetic characters
PayerNameebl:PersonNameType
(Optional) First and last name of buyer.
PayerCountryebl:CountryCodeType
(Optional) Buyer’s country of residence in the form of ISO standard 3166 twocharacter country codes.
Character length and limitations: 2 single-byte characters
PayerBusinessxs:string
(Optional) Buyer’s business name.
Character length and limitations: 127 single-byte characters
Addressxs:string
(Optional) Buyer’s shipping address information.
SOAP API Developer ReferenceAugust 201259
DoDirectPayment API Operation
4
DoDirectPayment Request Message
PayerNameType Fields
FieldDescription
Salutationxs:string
(Optional) Buyer’s salutation.
Character length and limitations: 20 single-byte characters
FirstNameebl:PersonNameType
(Required) Buyer’s first name.
Character length and limitations: 25 single-byte characters
MiddleNameebl:NameUser
(Optional) Buyer’s middle name.
Character length and limitations: 25 single-byte characters
LastNameebl:NameType
(Required) Buyer’s last name.
Character length and limitations: 25 single-byte characters
Suffixebl:SuffixType
(Optional) Buyer’s suffix.
Character length and limitations: 12 single-byte characters
AddressType Fields
FieldDescription
Street1xs:string
(Required) First street address.
Character length and limitations: 100 single-byte characters
Street2xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters
CityNamexs:string
(Required) Name of city.
Character length and limitations: 40 single-byte characters
StateOrProvincexs:string
(Required) State or province.
Character length and limitations: 40 single-byte characters
Countryebl:CountryCodeType
(Required) Country code.
Character length and limitationst: 2 single-byte characters
60August 2012SOAP API Developer Reference
FieldDescription
PostalCodexs:string
(Required) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
Phonexs:string
(Optional) Phone number.
Character length and limitations: 20 single-byte characters
PaymentDetailsType Fields
FieldDescription
OrderTotalebl:BasicAmountType
(Required) The total cost of the transaction to the buyer. If shipping cost and tax
charges are known, include them in this value. If not, this value should be the current
subtotal of the order. If the transaction includes one or more one-time purchases, this
field must be equal to the sum of the purchases. This field must be set to a value
greater than 0.
DoDirectPayment API Operation
DoDirectPayment Request Message
4
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
ItemTotalebl:BasicAmountType
(Optional) Sum of cost of all items in this order.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
ShippingTotalebl:BasicAmountType
(Optional) Total shipping costs for this order.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
SOAP API Developer ReferenceAugust 201261
DoDirectPayment API Operation
4
DoDirectPayment Request Message
FieldDescription
InsuranceTotalebl:BasicAmountType
(Optional) Total shipping insurance costs for this order. The value must be a nonnegative currency amount or null if you offer insurance options .
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
InsuranceTotal is available since version 53.0.
ShippingDiscountebl:BasicAmountType
(Optional) Shipping discount for this order, specified as a negative number.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
ShippingDiscount is available since version 53.0.
HandlingTotalebl:BasicAmountType
(Optional) Total handling costs for this order .
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
TaxTotalebl:BasicAmountType
(Optional) Sum of tax for all items in this order.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
OrderDescriptionxs:string
(Optional) Description of items the buyer is purchasing.
NOTE: The value you specify is available only if the transaction includes a purchase.
This field is ignored if you set up a billing agreement for a recurring payment
that is not immediately charged.
Character length and limitations: 127 single-byte alphanumeric characters
62August 2012SOAP API Developer Reference
FieldDescription
Customxs:string
(Optional) A free-form field for your own use.
NOTE: The value you specify is available only if the transaction includes a purchase.
This field is ignored if you set up a billing agreement for a recurring payment
that is not immediately charged.
Character length and limitations: 256 single-byte alphanumeric characters
InvoiceIDxs:string
(Optional) Your own invoice or tracking number.
NOTE: The value you specify is available only if the transaction includes a purchase.
This field is ignored if you set up a billing agreement for a recurring payment
that is not immediately charged.
Character length and limitations: 256 single-byte alphanumeric characters
ButtonSourcexs:string
(Optional) An identification code for use by third-party applications to identify
transactions.
Character length and limitations: 32 single-byte alphanumeric characters
DoDirectPayment API Operation
DoDirectPayment Request Message
4
NotifyURL xs:string
(Optional) Your URL for receiving Instant Payment Notification (IPN) about this
transaction. If you do not specify this value in the request, the notification URL from
your Merchant Profile is used, if one exists.
IMPORTANT: The notify URL applies only to DoExpressCheckoutPayment.
This value is ignored when set in
GetExpressCheckoutDetails.
Character length and limitations: 2,048 single-byte alphanumeric characters
ShipToAddressns:AddressType
(Optional) Address to which the order is shipped.
PaymentDetailsItemebl:PaymentDetailsItemType
(Optional) Details about each individual item included in the order.
Recurringns:RecurringFlagType
(Optional) Flag to indicate a recurring transaction. It is one of the following values:
Any value other than Y – This is not a recurring transaction (default).
Y – This is a recurring transaction.
NOTE: To pass Y in this field, you must have established a billing agreement with the
buyer specifying the amount, frequency, and duration of the recurring
payment.
This field is introduced in version 80.0 of the API.
SetExpressCheckout or
SOAP API Developer ReferenceAugust 201263
DoDirectPayment API Operation
4
DoDirectPayment Request Message
PaymentDetailsItemType Fields
FieldDescription
Namexs:string
(Optional) Item name.
Character length and limitations: 127 single-byte characters
Descriptionxs:string
(Optional) Item description.
Description is available since version 53.0.
Character length and limitations: 127 single-byte characters
Amountebl:BasicAmountType
(Optional) Cost of item.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
Numberxs:string
(Optional) Item number.
Character length and limitations: 127 single-byte characters
Quantityxs:integer
(Optional) Item quantity.
Character length and limitations: Any positive integer
Taxebl:BasicAmountType
(Optional) Item sales tax.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
EbayItemPayment
DetailsItem
eBl:ebayItemPaymentDetailsItemType
(Optional) Information relating to an auction sale on eBay.
64August 2012SOAP API Developer Reference
EbayItemPaymentDetailsItemType Fields
FieldDescription
ItemNumberxs:string
(Optional) Auction item number.
Character length: 765 single-byte characters
AuctionTransaction Idxs:string
(Optional) Auction transaction identification number.
Character length: 255 single-byte characters
OrderIDxs:string
(Optional) Auction order identification number.
Character length: 64 single-byte characters
AddressType (Shipping) Fields
DoDirectPayment API Operation
DoDirectPayment Request Message
4
FieldDescription
Namexs:string
Person’s name associated with this shipping address. It is required if using a
shipping address.
Character length and limitations: 32 single-byte characters
Street1xs:string
First street address. It is required if using a shipping address.
Character length and limitations: 100 single-byte characters
Street2xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters
CityNamexs:string
Name of city. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
StateOrProvincexs:string
State or province. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
PostalCodexs:string
U.S. ZIP code or other country-specific postal code. It is required if using a
U.S. shipping address; may be required for other countries.
Character length and limitations: 20 single-byte characters
SOAP API Developer ReferenceAugust 201265
DoDirectPayment API Operation
4
DoDirectPayment Request Message
FieldDescription
Countryebl:CountryCodeType
Country code. It is required if using a shipping address.
Character length and limitations: 2 single-byte characters
Phonexs:string
(Optional) Phone number.
Character length and limitations: 20 single-byte characters
ThreeDSecureRequest Fields (U.K. Merchants Only)
FieldDescription
AuthStatus3dsxs:string
(Optional) A value returned by the Cardinal Centinel. If the cmpi_lookup
request returns Y for Enrolled, set this field to the PAResStatus value
returned by cmpi_authenticate. Otherwise, set this field to blank.
MpiVendor3dsxs:string
(Optional) A value returned by the Cardinal Centinel. Set this field to th e
Enrolled value returned by cmpi_lookup.
Cavvxs:string
(Optional) A value returned by the Cardinal Centinel. If the cmpi_lookup
request returns Y for Enrolled, set this field to the Cavv value returned by
cmpi_authenticate. Otherwise, set this field to blank.
Eci3dsxs:string
(Optional) A value returned by the Cardinal Centinel. If the cmpi_lookup
request returns Y for Enrolled, set t his field to the EciFlag value returned
by cmpi_authenticate. Otherwise, set this field to the EciFlag value
returned by cmpi_lookup.
XIDxs:string
(Optional) A value returned by the Cardinal Centinel. If the cmpi_lookup
request returns Y for Enrolled, set this field to the Xid value returned by cmpi_authenticate. Otherwise, set this field to blank.
66August 2012SOAP API Developer Reference
DoDirectPayment Response Message
DoDirectPayment API Operation
DoDirectPayment Response Message
4
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer ReferenceAugust 201267
DoDirectPayment API Operation
4
DoDirectPayment Response Message
DoDirectPayment Response Fields
FieldDescription
TransactionIDxs:string
Unique transaction ID of the payment.
NOTE: If the PaymentAction of the request was Authorization, the value of
TransactionID is your AuthorizationID for use with the Authorization and
Capture APIs.
Character length and limitations: 19 single-byte characters
Amountebl:BasicAmountType
This value is the amount of the payment as specified by you on
DoDirectPaymentRequest for reference transactions with direct payments.
AVSCodexs:string
Address Verification System response code.
Character length and limitations: 1 single-byte alphanumeric character
CVV2Codexs:string
Result of the CVV2 check by PayPal.
FMFDetailsebl:FMFDetailsType
Fraud filter details.
PaymentAdviceCodexs:string
Response code from the processor when a recurrng transaction is declined. For details
on the codes, see https://merchant.paypal.com/us/cgi-bin/?&cmd=_rendercontent&content_ID=merchant/cc_compliance_error_codes
Related information:
AVS Response Codes
AVS Response Codes for Visa, MasterCard, Discover, and American Express
AVS Response Codes for Maestro
FMFDetailsType Fields
FieldDescription
AcceptFiltersxs:RiskFilterListType
List of filters that recommend acceptance of the payment.
DenyFiltersxs:RiskFilterListType
List of filters that recommend denial of the payment.
PendingFiltersxs:RiskFilterListType
List of filters that caused the payment to become pending.
68August 2012SOAP API Developer Reference
FieldDescription
ReportsFiltersxs:RiskFilterListType
List of filters that caused the payment to become flagged.
RiskFilterListType Fields
FieldDescription
IDxs:int
Filter ID. It is one of the following values:
1 - AVS No Match
2 - AVS Partial Match
3 - AVS Unavailable/Unsupported
4 - Card Security Code (CSC) Mismatch
5 - Maximum Transaction Amount
6 - Unconfirme d Add ress
7 - Country Monitor
8 - Large Order Number
9 - Billing/Ship ping A ddress Mism atch
10 - Risky ZIP Code
11 - Suspected Freight Forwarder Check
12 - Total Purchase Price Minimum
13 - IP Addr ess Velocity
14 - Risky Email Address Domain Check
15 - Risky Bank Identification Number (BIN) Check
16 - Risky IP Address Range
17 - PayPal Fraud Model
DoDirectPayment API Operation
DoDirectPayment Response Message
4
Namexs:string
Filter name.
Descriptionxs:string
Filter description.
SOAP API Developer ReferenceAugust 201269
DoDirectPayment API Operation
4
DoDirectPayment Response Message
ThreeDSecure Response Fields
FieldDescription
VPASVisa Payer Authentication Service status. The value indicates whether
Verified by Visa confirms that the information received is acceptable. It is
eturned only for Verified by Visa transactions.
Authentication:
Good result – 2 or D
Bad result – 1
Attempted authentication:
Good result – 3, 6, 8, A, or C
Bad result – 4, 7, or 9
No liability shift: Blank, 0, or B
EciSubmitted3dsElectronic Commerce Indicator (ECI) that PayPal submitted with the
payment authorisation request. This might not be the same value received
from the merchant. In rare cases, PayPal is required to use a different ECI
for authorisation based on the full set of 3-D Secure values provided from
the cmpi_authenticate request.
The DoNonReferencedCredit API issues a credit to a card not referenced by the original
transaction.
DoNonReferencedCredit Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer ReferenceAugust 201271
DoNonReferencedCredit API Operation
5
DoNonReferencedCredit Request Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
72August 2012SOAP API Developer Reference
DoNonReferencedCredit API Operation
DoNonReferencedCredit Request Message
5
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoNonReferencedCredit Request Fields
FieldDescription
Amountns:BasicAmountType
(Required) Total of order, including shipping, handling, and tax. Amount =
NetAmount + ShippingAmount + TaxAmount
Character length and limitations: Must not exceed $10,000 USD in any currency. No
currency symbol. Must have 2 decimal places, decimal separator must be a period (.),
and the optional thousands separator must be a comma (,).
SOAP API Developer ReferenceAugust 201273
DoNonReferencedCredit API Operation
5
DoNonReferencedCredit Request Message
FieldDescription
NetAmountns:BasicAmountType
(Optional) Total amount of all items in this transaction.
NOTE: The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.
Character length and limitations: Must not exceed $10,000 USD in any currency. No
currency symbol. Must have 2 decimal places, decimal separator must be a period (.),
and the optional thousands separator must be a comma (,).
TaxAmountns:BasicAmountType
(Optional) Sum of tax for all items in this order.
NOTE: The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.
Character length and limitations: The value must be zero or greater and cannot exceed
$10,000 USD in any currency. No currency symbol. Must have 2 decimal places,
decimal separator must be a period (.), and the optional thousands separator must be a
comma (,).
ShippingAmountns:BasicAmountType
(Optional) Total shipping costs in this transaction.
NOTE: The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.
Character length and limitations: Value must be zero or greater and cannot exceed
$10,000 USD in any currency. No currency symbol. Must have 2 decimal places,
decimal separator must be a period (.), and the optional thousands separator must be a
comma (,). The only valid currencies are AUD, CAD, EUR, GBP, JPY, and USD.
CreditCardebl:CreditCardDetailsType
(Required) Information about the credit card to be charged.
ReceiverEmailxs:string
Commentxs:string
(Optional) Field used by merchant to record why this credit was issued to a buyer. It
is similar to a “memo” field (freeform text or string field).
74August 2012SOAP API Developer Reference
CreditCardDetailsType Fields
FieldDescription
CreditCardTypeebl:CreditCardType
(Optional) Type of credit card. For UK, only Maestro, MasterCard, Discover,
and Visa are allowable. For Canada, only MasterCard and Visa are allowable and
Interac debit cards are not supported. It is one of the following values:
Visa
MasterCard
Discover
Amex
Maestro: See note.
NOTE: If the credit card type is Maestro, you must set currencyId to GBP. In
addition, you must specify either
IssueNumber.
Character length and limitations: Up to 10 single-byte alphabetic characters
CreditCardNumberxs:string
(Required) Credit card number.
Character length and limitations: Numeric characters only with no spaces or
punctutation. The string must conform with modulo and length required by each
credit card type.
DoNonReferencedCredit API Operation
DoNonReferencedCredit Request Message
StartMonth and StartYear or
5
ExpMonthxs:int
(Required) Credit card expiration month.
Character length and limitations: 2 single-byte numeric characters, including leading
zero
ExpYearxs:int
(Required) Credit card expiration year.
Character length and limitations: 4 single-byte numeric characters
CVV2xs:string
Card Verification Value, version 2. Your Merchant Account settings determine
whether this field is required. To comply with credit card processing regulations, you
must not store this value after a transaction has been completed.
Character length and limitations: For Visa, MasterCard, and Discover, the value is
exactly 3 digits. For American Express, the value is exactly 4 digits.
CardOwnerns:PayerInfoType
(Required) Details about the owner of the credit card.
StartMonthxs:int
(Optional) Month that Maestro card was issued.
Character length and limitations: 2-digit, zero-filled if necessary
SOAP API Developer ReferenceAugust 201275
DoNonReferencedCredit API Operation
5
DoNonReferencedCredit Request Message
FieldDescription
StartYearxs:int
(Optional) Year that Maestro card was issued.
Character length and limitations: 4 digits
IssueNumberxs:string
(Optional) Issue number of Maestro card.
Character length and limitations: 2 numeric digits maximum
PayerNameType Fields
FieldDescription
Salutationxs:string
(Optional) Buyer’s salutation.
Character length and limitations: 20 single-byte characters
FirstNameebl:PersonNameType
(Optional) Buyer’s first name.
Character length and limitations: 25 single-byte characters
MiddleNameebl:NameUser
(Optional) Buyer’s middle name.
Character length and limitations: 25 single-byte characters
LastNameebl:NameType
(Optional) Buyer’s last name.
Character length and limitations: 25 single-byte characters
Suffixebl:SuffixType
(Optional) Buyer’s suffix.
Character length and limitations: 12 single-byte characters
PayerInfoType Fields
FieldDescription
Payerns:EmailAddressType
(Optional) Email address of buyer.
Character length and limitations: 127 single-byte characters
FirstNamens:PersonNameType
(Required) Buyer’s first name.
Character length and limitations: 25 single-byte characters
76August 2012SOAP API Developer Reference
FieldDescription
LastNamens:PersonNameType
(Required) Buyer’s last name.
Character length and limitations: 25 single-byte characters
Addressns:AddressType
(Required) Buyer’s billing address information.
AddressType Fields
FieldDescription
Street1xs:string
(Required) First street address.
Character length and limitations: 100 single-byte characters
Street2xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters
DoNonReferencedCredit API Operation
DoNonReferencedCredit Request Message
5
CityNamexs:string
(Required) Name of city.
Character length and limitations: 40 single-byte characters
StateOrProvincexs:string
(Required) State or province.
Character length and limitations: 40 single-byte characters
Countryebl:CountryCodeType
(Required) Country code.
Character length and limitationst: 2 single-byte characters
PostalCodexs:string
(Required) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
Phonexs:string
(Optional) Phone number.
Character length and limitations: 20 single-byte characters
SOAP API Developer ReferenceAugust 201277
DoNonReferencedCredit API Operation
5
DoNonReferencedCredit Response Message
DoNonReferencedCredit Response Message
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
DoNonReferencedCredit Response Fields
FieldDescription
TransactionIDns:TransactionId
Unique identifier of a transaction.
Character length and limitations: 17 single-byte alphanumeric characters.
Amountns:BasicAmountType
Total of order, including shipping, handling, and tax.
Character length and limitations: Must not exceed $10,000 USD in any currency. No
currency symbol. Must have 2 decimal places, decimal separator must be a period (.),
and the optional thousands separator must be a comma (,).
78August 2012SOAP API Developer Reference
ExpressCheckout API Operations
6
Express Checkout API operations include SetExpressCheckout,
GetExpressCheckoutDetails, and DoExpressCheckoutPayment.
SetExpressCheckout API Operation
The SetExpressCheckout API operation initiates an Express Checkout transaction.
SetExpressCheckout Request Message
SOAP API Developer ReferenceAugust 201279
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
80August 2012SOAP API Developer Reference
ExpressCheckout API Operations
SetExpressCheckout API Operation
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
6
SOAP API Developer ReferenceAugust 201281
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
82August 2012SOAP API Developer Reference
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
SOAP API Developer ReferenceAugust 201283
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
84August 2012SOAP API Developer Reference
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
NOTE: Not all fields shown are available for use. Use only the fields described in the
documentation.
SOAP API Developer ReferenceAugust 201285
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
SetExpressCheckout Request Fields
FieldDescription
OrderTotal
(deprecated)
ebl:BasicAmountType
(Required) The total cost of the transaction to the buyer. If shipping cost and tax
charges are known, include them in this value. If not, this value should be the current
subtotal of the order. If the transaction includes one or more one-time purchases, this
field must be equal to the sum of the purchases. If the transaction does not include a
one-time purchase such as when you set up a billing agreement for a recurring
payment, set this field to 0.
NOTE: You must set the currencyID attribute to one of the three-character
currency codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
This field is deprecated since version 53.0. Use OrderTotal in
PaymentDetailsType instead.
MaxAmountebl:BasicAmountType
(Optional) The expected maximum total amount of the complete order, including
shipping cost and tax charges. If the transaction includes one or more one-time
purchases, this field is ignored.
For recurring payments, you should pass the expected average transaction amount
(default 25.00). PayPal uses this value to validate the buyer’s funding source.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
NOTE: This field is required when implementing the Instant Update API callback.
PayPal recommends that the maximum total amount be slightly greater than
the sum of the line-item order details, tax, and the shipping options of greatest
value.
NOTE: You must set the currencyID attribute to one of the three-character
currency codes for any of the supported PayPal currencies.
OrderDescription
(deprecated)
xs:string
(Optional) Description of items the buyer is purchasing.
Character length and limitations: 127 single-byte alphanumeric characters
This field is deprecated since version 53.0. Use OrderDescription in
PaymentDetailsType instead.
86August 2012SOAP API Developer Reference
FieldDescription
Custom (deprecated)xs:string
(Optional) A free-form field for your own use, such as a tracking number or other
value you want PayPal to return on GetExpressCheckoutDetails response and
response.
Character length and limitations: 256 single-byte alphanumeric characters
This field is deprecated since version 53.0. Use Custom in PaymentDetailsType
instead.
InvoiceID (deprecated)xs:string
(Optional) Your own unique invoice or tracking number. PayPal returns this value to
you on DoExpressCheckoutPayment response. If the transaction does not include
a one-time purchase, this field is ignored.
Character length and limitations: 127 single-byte alphanumeric characters
This field is deprecated since version 53.0. Use InvoiceID in
PaymentDetailsType instead.
ReturnURLxs:string
(Required) URL to which the buyer’s browser is returned after choosing to pay with
PayPal. For digital goods, you must add JavaScript to this page to close the in-context
experience.
NOTE: PayPal recommends that the value be the final review page on which the
buyer confirms the order and payment or billing agreement.
Character length and limitations: 2048 single-byte characters
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
CancelURLxs:string
(Required) URL to which the buyer is returned if the buyer does not approve the use
of PayPal to pay you. For digital goods, you must add JavaScript to this page to close
the in-context experience.
NOTE: PayPal recommends that the value be the original page on which the buyer
chose to pay with PayPal or establish a billing agreement.
Character length and limitations: 2048 single-byte characters
CallbackURLxs:string
(Optional) URL to which the callback request from PayPal is sent. It must start with
HTTPS for production integration. It can start with HTTPS or HTTP for sandbox
testing.
Character length and limitations: 1024 single-byte characters
This field is available since version 53.0.
CallbackTimeoutint
(Optional) An override for you to request more or less time to be able to process the
callback request and respond. The acceptable range for the override is 1 to 6 seconds.
If you specify a value greater than 6, PayPal uses the default value of 3 seconds.
Character length and limitations: An integer between 1 and 6
SOAP API Developer ReferenceAugust 201287
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
FieldDescription
Address (deprecated)ebl:AddressType
(Optional) Buyer’s shipping address.If you include a shipping address and set the
AddressOverride element on the request, PayPal returns this same address in
GetExpressCheckoutDetailsResponse.
This field is deprecated since version 53.0. Use ShipToAddress in
PaymentDetailsType instead.
ReqConfirmShippingxs:string
Indicates whetheror not you require the buyer’s shipping address on file with PayPal
be a confirmed address. For digital goods, this field is required, and you must set it to
0. It is one of the following values:
0 – You do not require the buyer’s shipping address be a confirmed address.
1 – You require the buyer’s shipping address be a confirmed address.
NOTE: Setting this field overrides the setting you specified in your Merchant
Character length and limitations: 1 single-byte numeric character
NoShippingxs:string
Determines where or not PayPal displays shipping address fields on the PayPal pages.
For digital goods, this field is required, and you must set it to 1. It is one of the
following values:
0 – PayPal displays the ship ping address on the PayPal pages.
1 – PayPal does not displ ay shippi ng address fields whatsoever.
2 – If you do not pass the shippin g address, PayPal ob tains it from the buyer’s
account profile.
Character length and limitations: 4 single-byte numeric characters
Account Profile.
FlatRateShippingOpt
ions
ebl:ShippingOptionsType
Flat rate shipping options. This field is required if you are specifying the Callback
URL.
AllowNotexs:string
(Optional) Enables the buyer to enter a note to the merchant on the PayPal page
during checkout. The note is returned in the GetExpressCheckoutDetails
response and the DoExpressCheckoutPayment respon se. It is one of th e followin g
values:
0 – The buyer is unable to enter a note to the merch ant.
1 – The buyer is able to enter a note to the merchant.
Character length and limitations: 1 single-byte numeric character
This field is available since version 53.0.
PaymentDetailsebl:PaymentDetailsType
(Required) Information about the payment.
88August 2012SOAP API Developer Reference
FieldDescription
AddressOverridexs:string
(Optional) Determines whether or not the PayPal pages should display the shipping
address set by you in this SetExpressCheckout request, not the shipping address on
file with PayPal for this buyer. Displaying the PayPal street address on file does not
allow the buyer to edit that address. It is one of the following values:
0 – The PayPal pages should not di splay th e shipping address.
1 – The PayPal pages should displ ay the sh ipping address.
Character length and limitations: 1 single-byte numeric character
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
SOAP API Developer ReferenceAugust 201289
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
FieldDescription
LocaleCodexs:string
(Optional) Locale of pages displayed by PayPal during Express Checkout. It is one of
the following country code values supported by PayPal (default is US):
da_DK – Danish (for Denmark only)
he_IL – Hebrew (all)
id_ID – Indonesian (for Indonesia only)
jp_JP – Japanese (for Japan only)
no_NO – Norwegian (for Norway only)
pt_BR – Brazilian Portuguese (for Portugal and Brazil only)
ru_RU – Russian (for Lithuania, Latvia, and Ukraine only)
sv_SE – Swedish (for Sweden only)
th_TH – Thai (for Thailand only)
tr_TR – Turkish (for Turkey only)
zh_CN – Simplified Chinese (for China only)
zh_HK – Traditional Chinese (for Hong Kong only)
zh_TW – Traditional Chinese (for Taiwan only)
Character length and limitations: 2-character country code
AU – Au st ralia
AT – Au stria
BE – Belg i um
BR – Brazil
CA – Canada
CH – Switzerland
CN – Chi na
DE – Germany
ES – Spain
GB – United Kingdom
FR – France
IT – It al y
NL – Netherlands
PL – Po land
PT – Po rt ugal
RU – Russia
US – Un ited States
The following 5-character codes are also supported for languages in specific
countries:
PageStylexs:string
(Optional) Name of the Custom Payment Page Style for payment pages associated
with this button or link. It corresponds to the HTML variable page_style for
customizing payment pages. It is the same name as the Page Style Name you chose to
add or edit the page style in your PayPal Account profile.
Character length and limitations: 30 single-byte alphabetic characters
90August 2012SOAP API Developer Reference
FieldDescription
cpp-header-imagexs:string
(Optional) 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. If you
do not specify an image, the business name displays.
Character length and limitations: 127 single-byte alphanumeric characters
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
cpp-header-bordercolor
xs:string
(Optional) 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. By default, the color is black.
Character length and limitations: 6-character HTML hexadecimal ASCII color code
cpp-header-backcolor
xs:string
(Optional) Sets the background color for the header of the payment page. By default,
the color is white.
Character length and limitations: 6-character HTML hexadecimal ASCII color code
cpp-payflow-colorxs:string
(Optional) Sets the background color for the payment page. By default, the color is
white.
Character length and limitations: 6-character HTML hexadecimal ASCII color code
PaymentAction
(deprecated)
ebl:PaymentActionCodeType
(Optional) How you want to obtain payment. If the transaction does not include a
one-time purchase, this field is ignored. It is one of the following values:
Sale – This is a final sale for which you are requesting payment (default).
Authorization – This payment is a basic authorization subject to settlement
with PayPal Authorization and Capture.
Order – This payment is an order authorization subject to settlement with PayPal
Authorization and Capture.
NOTE: You cannot set this field to Sale in SetExpressCheckout request and then
change this value to
DoExpressCheckoutPayment request. If you set the field to
Authorization or Order in SetExpressCheckout, you may set the
field to
Authorization or Order in the
Sale.
Character length and limitations: Up to 13 single-byte alphabetic characters
This field is deprecated. Use PaymentAction in PaymentDetailsType instead.
BuyerEmailebl:EmailAddressType
(Optional) Email address of the buyer as entered during checkout. PayPal uses this
value to pre-fill the PayPal membership sign-up portion on the PayPal pages.
Character length and limitations: 127 single-byte alphanumeric characters
SOAP API Developer ReferenceAugust 201291
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
FieldDescription
SolutionTypeebl:SolutionTypeType
(Optional) Type of checkout flow. It is one of the following va lues:
Sole – Buyer does not need to create a PayPal account to check out. This is
referred to as PayPal Account Optional.
Mark – Buyer must have a PayPal account to check out.
NOTE: You can pass Mark to selectively override the PayPal Account Optional
setting if PayPal Account Optional is turned on in your merchant account.
Passing
account
LandingPageebl:LandingPageType
(Optional) Type of PayPal page to display. It is one of the following values:
(Optional) List of other payment methods with which the buyer can pay.
92August 2012SOAP API Developer Reference
FieldDescription
BuyerDetailsns:BuyerDetailsType
(Optional) Details about the buyer's account.
BrandNamexs:string
(Optional) A label that overrides the business name in the PayPal account on the
PayPal hosted checkout pages.
Character length and limitations: 127 single-byte alphanumeric characters
FundingSourceDetailsns:FundingSourceDetailsType
(Optional) Funding source preferences.
CustomerServiceNumberxs:string
(Optional) Merchant Customer Service number displayed on the PayPal pages.
Character length and limitations: 16 single-byte characters
GiftMessageEnablexs:string
(Optional) Enables the gift message widget on the PayPal pages. It is one of the
following values:
0 – Do not enable gift message widget.
1 – Enable gift message widget.
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
GiftReceiptEnablexs:string
(Optional) Enable gift receipt widget on the PayPal pages. It is one of the following
values:
0 – Do not enable gift receipt widget.
1 – Enable gift receipt widget.
GiftWrapEnablexs:string
(Optional) Enable gift wrap widget on the PayPal pages. It is one of the following
values:
0 – Do not enable gift wrap widget.
1 – Enable gift wrap widget.
NOTE: If you pass the value 1 in this field, values for the gift wrap amount and gift
wrap name are not passed, the gift wrap name is not displayed, and the gift
wrap amount displays as 0.00.
GiftWrapNamexs:string
(Optional) Label for the gift wrap option such as “Box with ribbon”.
Character length and limitations: 25 single-byte characters
GiftWrapAmountebl:BasicAmounttype
(Optional) Amount to be charged to the buyer for gift wrapping..
NOTE: You must set the currencyID attribute to one of the three-character
currency codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2 decimal
places, the decimal separator must be a period (.), and the optional thousands
separator must be a comma (,).
SOAP API Developer ReferenceAugust 201293
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
FieldDescription
BuyerEmailOptinEnablexs:string
(Optional) Enables the buyer to provide their email address on the PayPal pages to be
notified of promotions or special events. Is one of the following values:
SurveyQuestionxs:string
(Optional) Text for the survey question on the PayPal pages. If the survey question is
present, at least 2 survey answer options must be present.
Character length and limitations: 50 single-byte characters
SurveyEnablexs:string
(Optional) Enables survey functionality. It is one of the following values:
SurveyChoicexs:string
(Optional) Possible options for the survey answers on the PayPal pages. Answers are
displayed only if a valid survey question is present.
Character length and limitations: 15 single-byte characters
0 – Do not enable buyer to provide email address.
1 – Enable the buyer to provide email address.
(Optional) Enables display of “Estimated Total” instead of “Total” in the cart review
area. It is one of the following values:
Total
EstimatedTotal
Character length and limitations: 14 single-byte characters
This field is available with API Version 64.0 or later.
NoteToBuyerxs:string
(Optional) Displays a note to buyers in the cart review area below the total amount.
Use the note to tell buyers about items in the cart, such as your return policy or that
the total excludes shipping and handling.
Character length and limitations: 127 single-byte characters
This field is available with API Version 64.0 or later.
PaymentReasonns:PaymentReasonType
Indicates the type of transaction. It is one of the following values:
None – Transaction is not identified as a particular type.
Refund – Identifies the transaction as a refund.
94August 2012SOAP API Developer Reference
AddressType Fields
FieldDescription
Namexs:string
Person’s name associated with this shipping address. It is required if using a
shipping address.
Character length and limitations: 32 single-byte characters
Street1xs:string
First street address. It is required if using a shipping address.
Character length and limitations: 100 single-byte characters
Street2xs:string
(Optional) Second street address.
Character length and limitations: 100 single-byte characters
CityNamexs:string
Name of city. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
StateOrProvincexs:string
State or province. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
PostalCodexs:string
U.S. ZIP code or other country-specific postal code. It is required if using a
U.S. shipping address and may be required for other countries.
Character length and limitations: 20 single-byte characters
Countryebl:CountryCodeType
Country code. It is required if using a shipping address.
Character length and limitations: 2 single-byte characters
Phonexs:string
(Optional) Phone number.
Character length and limitations: 20 single-byte characters
PaymentDetailsType Fields
When implementing parallel payments, you can create up to 10 sets of payment details type
parameter fields, each representing one payment you are hosting on your marketplace.
SOAP API Developer ReferenceAugust 201295
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
FieldDescription
OrderTotalebl:BasicAmountType
(Required) Total cost of the transaction to the buyer. If shipping cost and tax
charges are known, include them in this value. If not, this value should be the
current sub-total of the order. If the transaction includes one or more one-time
purchases, this field must be equal to the sum of the purchases. Set this field to 0 if
the transaction does not include a one-time purchase such as when you set up a
billing agreement for a recurring payment that is not immediately charged. When
the field is set to 0, purchase-specific fields are ignored.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
ItemTotalebl:BasicAmountType
Sum of cost of all items in this order. For digital goods, this field is required.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
ShippingTotalebl:BasicAmountType
(Optional) Total shipping costs for this order.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
InsuranceTotalebl:BasicAmountType
(Optional) Total shipping insurance costs for this order. The value must be a nonnegative currency amount or null if you offer insurance options .
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
InsuranceTotal is available since version 53.0.
96August 2012SOAP API Developer Reference
FieldDescription
ShippingDiscountebl:BasicAmountType
(Optional) Shipping discount for this order, specified as a negative number.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
ShippingDiscount is available since version 53.0.
InsuranceOptionOfferedxs:boolean
(Optional) Indicates whether insurance is available as an option the buyer can
choose on the PayPal Review page. Is one of the following values:
true – The Insurance option displays the string ‘Yes’ and the insurance
amount. If true, the total shipping insurance for this order must be a positive
number.
false – The Insurance option displays ‘No.’
ExpressCheckout API Operations
SetExpressCheckout API Operation
6
HandlingTotalebl:BasicAmountType
(Optional) Total handling costs for this order .
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
TaxTotalebl:BasicAmountType
(Optional) Sum of tax for all items in this order.
NOTE: You must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
OrderDescriptionxs:string
(Optional) Description of items the buyer is purchasing.
NOTE: The value you specify is available only if the transaction includes a
purchase. This field is ignored if you set up a billing agreement for a
recurring payment that is not immediately charged.
Character length and limitations: 127 single-byte alphanumeric characters
SOAP API Developer ReferenceAugust 201297
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
FieldDescription
Customxs:string
InvoiceIDxs:string
NotifyURL xs:string
(Optional) A free-form field for your own use.
NOTE: The value you specify is available only if the transaction includes a
purchase. This field is ignored if you set up a billing agreement for a
recurring payment that is not immediately charged.
Character length and limitations: 256 single-byte alphanumeric characters
(Optional) Your own invoice or tracking number.
NOTE: The value you specify is available only if the transaction includes a
purchase. This field is ignored if you set up a billing agreement for a
recurring payment that is not immediately charged.
Character length and limitations: 256 single-byte alphanumeric characters
(Optional) Your URL for receiving Instant Payment Notification (IPN) about this
transaction. If you do not specify this value in the request, the notification URL
from your Merchant Profile is used, if one exists.
IMPORTANT: The notify URL applies only to DoExpressCheckoutPayment.
This value is ignored when set in
SetExpressCheckout or
GetExpressCheckoutDetails.
Character length and limitations: 2,048 single-byte alphanumeric characters
ShipToAddressns:AddressType
(Optional) Address to which the order is shipped.
PaymentDetailsItemebl:PaymentDetailsItemType
(Optional) Details about each individual item included in the order.
EnhancedPaymentDataed:EnhancedPaymentDataType
(Optional) Enhanced Data section to accept channel-specific data (eBay).
NoteTextxs:string
(Optional) Note to the merchant.
Character length and limitations: 255 single-byte characters
SellerDetailsns:SellerDetailsType
(Optional) Details about the merchant. This information is used for emails sent out
for eBay transactions.
TransactionIdxs:string
(Optional) Transaction identification number of the transaction that was created.
NOTE: This field is only returned after a successful transaction for
DoExpressCheckout has occurred.
AllowedPaymentMethod
Type
xs:string
(Optional) The payment method type. Specify the value InstantPaymentOnly.
98August 2012SOAP API Developer Reference
FieldDescription
PaymentActionebl:PaymentActionCodeType
How you want to obtain payment. When implementing parallel payments, this field
is required and must be set to Order. When implementing digital goods, this field
is required and must be set to Sale. If the transaction does not include a one-time
purchase, this field is ignored. It is one of the following values:
Sale – This is a final sale for which you are requesting payment (default).
Authorization – This payment is a basic authorization subject to settlement
with PayPal Authorization and Capture.
Order – This payment is an order authorization subject to settlement with
PayPal Authorization and Capture.
NOTE: You cannot set this field to Sale in SetExpressCheckout request and
then change the value to
DoExpressCheckoutPayment request. If you set the field to
Authorization or Order in SetExpressCheckout, you may set the
field to
Sale.
Character length and limitations: Up to 13 single-byte alphabetic characters
PaymentRequestIDxs:string
A unique identifier of the specific payment request, which is required for parallel
payments.
Character length and limitations: Up to 127 single-byte characters
ExpressCheckout API Operations
SetExpressCheckout API Operation
Authorization or Order in the
6
PaymentDetailsItemType Fields
FieldDescription
Namexs:string
Item name. This field is required when you pass a value for ItemCategory.
Character length and limitations: 127 single-byte characters
This field is introduced in version 53.0.
Descriptionxs:string
(Optional) Item description.
Character length and limitations: 127 single-byte characters
This field is introduced in version 53.0.
Amountebl:BasicAmountType
Cost of item. This field is required when you pass a value for ItemCategory.
NOTE: Y ou must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
This field is introduced in version 53.0.
SOAP API Developer ReferenceAugust 201299
ExpressCheckout API Operations
6
SetExpressCheckout API Operation
FieldDescription
Numberxs:string
(Optional) Item number.
Character length and limitations: 127 single-byte characters
This field is introduced in version 53.0.
Quantityxs:integer
Item quantity. This field is required when you pass a value for ItemCategory.
For digital goods (ItemCategory=Digital), this field is required.
Character length and limitations: Any positive integer
This field is introduced in version 53.0.
Taxebl:BasicAmountType
(Optional) Item sales tax.
NOTE: Y ou must set the currencyID attribute to one of the 3-character currency
codes for any of the supported PayPal currencies.
Character length and limitations: Value is a positive number which cannot exceed
$10,000 USD in any currency. It includes no currency symbol. It must have 2
decimal places, the decimal separator must be a period (.), and the optional
thousands separator must be a comma (,).
ItemWeightxs:integer
(Optional) Item weight corresponds to the weight of the item. You can pass this
data to the shipping carrier as is without having to make an addi tional database
query.
Character length and limitations: Any positive integer
ItemLengthxs:integer
(Optional) Item length corresponds to the length of the item. You can pass this
data to the shipping carrier as is without having to make an addi tional database
query.
Character length and limitations: Any positive integer
ItemWidthxs:integer
(Optional) Item width corresponds to the width of the item. You can pass this data
to the shipping carrier as is without having to make an additional database query.
Character length and limitations: Any positive integer
ItemHeightxs:integer
(Optional) Item height corresponds to the height of the item. You can pass this
data to the shipping carrier as is without having to make an addi tional database
query.
Character length and limitations: Any positive integer
EbayItemPayment
DetailsItem
eBl:ebayItemPaymentDetailsItemType
(Optional) Information relating to an auction sale on eBay.
ItemURLxs:string
(Optional) URL for the item.
100August 2012SOAP API Developer Reference
Loading...
+ hidden pages
You need points to download manuals.
1 point = 1 manual.
You can buy points or you can get point for every manual you upload.