Direct Payment API

With the Direct Payment API, you can obtain payment through PayPal directly from a buyer’s credit card without the buyer logging into PayPal.

Diagram of DoDirectPayment Types

The following diagram represents the composition of the DoDirectPaymentRequestType and DoDirectPaymentResponseType elements. Elements required in the request are indicated with an asterisk.

Figure 4.1

DoDirectPayment Types

DoDirectPaymentRequest

Request to use PayPal Direct Payment to charge or authorize a credit card.

You must include the PaymentAction element in DoDirectPaymentRequest. Allowable values for the PaymentAction element are Sale or Authorization:

l	Set PaymentAction to Sale if the buyer’s order is final (for example, if the total cost of the order is complete with shipping, handling and tax charges). This transaction is your payment, and you expect no additional charge to the buyer.

l	Set PaymentAction to Authorization if the total cost of the order at point of sale is not complete for some reason (such as unknown shipping charges) and you expect to capture funds after checkout is complete. You can then use PayPal Authorization & Capture to obtain payment.

In either case, besides the PaymentAction element, DoDirectPaymentRequest requires additional elements, such as the amount of the transaction, IP address of the buyer’s browser, credit card number, type, and expiration date, and information about both the payer and the payment.

Table 4.1

DoDirectPaymentRequest Fields

Field	Description	Required?
PaymentAction	ebl:PaymentActionCodeType How you want to obtain payment: l Authorization indicates that this payment is a basic authorization subject to settlement with PayPal Authorization & Capture. l Sale indicates that this is a final sale for which you are requesting payment. Character length and limit: Up to 13 single-byte alphabetic characters Default: Sale Note: Order is not allowed for Direct Payment.	No
CreditCard	ebl:CreditCardDetailsType Information about the credit card to be charged. See Table 4.2.	Yes
PaymentDetails	ebl:PaymentDetailsType Information about the payment See Table 4.3.	Yes
IPAddress	xs:string IP address of the payer’s browser. Important: 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.	Yes
ReturnFMFDetails	xs:boolean Flag to indicate whether you want the results returned by Fraud Management Filters. By default, you do not receive this information.	No

Table 4.2

CreditCardDetailsType Fields

Field	Description	Required?
CreditCardType	ebl:CreditCardType Type of credit card. Character length and limitations: Up to ten single-byte alphabetic characters. Allowable values: l Visa l MasterCard l Discover l Amex l Switch: See important note. l Solo: See important note. Important: If the credit card type is Switch or Solo, the currencyId must be GBP. In addition, either StartMonth and StartYear or IssueNumber must be specified.	Yes
CreditCardNumber	xs:string Credit card number Character length and limitations: numeric characters only. No spaces or punctutation. Must conform with modulo and length required by each credit card type.	Yes
ExpMonth	xs:int Credit card expiration month Character length and limitations: Two single-byte numeric characters, including leading zero.	Yes
ExpYear	xs:int Credit card expiration year Character length and limitations: Four single-byte numeric characters.	Yes
CVV2	xs:string Card Verification Value, version 2. Note: Your Merchant Account settings determine whether this field is required. Character length for Visa, MasterCard, and Discover: exactly three digits. Character length for American Express: exactly four digits. Important: To comply with credit card processing regulations, once a transaction has been completed, you must not store the value of CVV2.	See note in description.
CardOwner	ns:PayerInfoType Details about the owner of the credit card. See Table 4.6.	Yes
StartMonth	xs:int Month that Switch or Solo card was issued. Character length: two-digit, zero-filled if necessary.	No.
StartYear	xs:int Year that Switch or Solo card was issued. Character length: four digits.	No.
IssueNumber	xs:int Issue number of Switch or Solo card. Character length: two numeric digits maximum.	No.

Table 4.3

Request: PaymentDetailsType Fields

Field	Description	Required?
OrderTotal	ebl:BasicAmountType Total of order, including shipping, handling, and tax. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). The only valid currencies are as follows: l AUD: Australian Dollar l CAD: Canadian Dollar l EUR: Euro l GBP: Pound Sterling l JPY: Japanese Yen l USD: U.S. Dollar	Yes
ItemTotal	ebl:BasicAmountType Sum of cost of all items in this order. Limitations: The value must be a positive number and cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Note: You must specify this value if you specify Amount in PaymentDetailsItem or if you specify values for ShippingTotal or HandlingTotal.	No
ShippingTotal	ebl:BasicAmountType Total shipping costs for this order. Limitations: The value must be zero or greater and cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). The only valid currencies are as follows: l AUD: Australian Dollar l CAD: Canadian Dollar l EUR: Euro l GBP: Pound Sterling l JPY: Japanese Yen l USD: U.S. Dollar Note: If you specify a value for ShippingTotal, you must also specify a value for ItemTotal.	No
HandlingTotal	ebl:BasicAmountType Total handling costs for this order. Limitations: The value must be zero or greater and cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). The only valid currencies are as follows: l AUD: Australian Dollar l CAD: Canadian Dollar l EUR: Euro l GBP: Pound Sterling l JPY: Japanese Yen l USD: U.S. Dollar Note: If you specify a value for HandlingTotal, you must also specify a value for ItemTotal.	No
TaxTotal	ebl:BasicAmountType Sum of tax for all items in this order. Limitations: The value must be zero or greater and cannot exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). The only valid currencies are as follows: l AUD: Australian Dollar l CAD: Canadian Dollar l EUR: Euro l GBP: Pound Sterling l JPY: Japanese Yen l USD: U.S. Dollar	No
OrderDescription	xs:string Description of items the customer is purchasing. Character length and limitations: 127 single-byte alphanumeric characters	No
Custom	xs:string A free-form field for your own use. Character length and limitations: 256 single-byte alphanumeric characters	No
InvoiceID	xs:string Your own invoice or tracking number. Character length and limitations: 127 single-byte alphanumeric characters	No
ButtonSource	xs:string An identification code for use by third-party applications to identify transactions. Character length and limitations: 32 single-byte alphanumeric characters	No
NotifyURL	xs:string Your URL for receiving Instant Payment Notification (IPN) about this transaction. Note: If you do not specify this URL in the request, the notification URL from your Merchant Profile is used, if one exists. Character length and limitations: 2,048 single-byte alphanumeric characters	No
ShipToAddress	ebl:AddressType Address the order will be shipped to. See Table 4.4.	No
PaymentDetailsItem	ebl:PaymentDetailsItemType Details about each individual item included in the order See Table 4.5.	No

IMPORTANT:

In the following table, any fields in the WSDL or XSD files that are not described here are ignored. For example, do not set CountryName.

Table 4.4

Request: ShipToAddress: AddressType Fields

Field	Descriptions	Required?
Name	xs:string Person’s name associated with this address. Character length and limitations: 32 single-byte characters	Yes
Street1	xs:string First street address. Character length and limitations: 100 single-byte characters	Yes
Street2	xs:string Second street address. Character length and limitations: 100 single-byte characters	No
CityName	xs:string Name of city. Character length and limitations: 40 single-byte characters	Yes
StateOrProvince	xs:string State or province. Character length and limitations: 40 single-byte characters See Appendix E, “State and Province Abbreviations.”	Yes
PostalCode	xs:string U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters	Yes
Country	ebl:CountryCodeType Country code. Character limit: Two single-byte characters See Appendix F, “Country Codes.	Yes
Phone	xs:string Phone number. Character length and limit: 20 single-byte characters	No

Table 4.5

Request: PaymentDetailsItemType Fields

Field	Description	Required?
Name	xs:string Item name. Character length and limitations: 127 single-byte characters	No
Amount	ebl:BasicAmountType Cost of item Limitations: Value can be positive, negative or zero and must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Note: You must set the currencyID attribute to one of the three-character currency codes for any of the supported PayPal currencies. See “PayPal-Supported Transactional Currencies”. Note: If you specify this value, you must specify a value for ItemTotal.	No
Number	xs:string Item number. Character length and limitations: 127 single-byte characters	No
Quantity	xs:string Item quantity. Character length and limitations: Any positive integer	No
Tax	ebl:BasicAmountType Item sales tax. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Currency code is set the same as for OrderTotal.	No

Table 4.6

CardOwner: PayerInfoType Fields

Field	Description	Required?
Payer	ns:EmailAddressType Email address of payer. Character length and limitations: 127 single-byte characters	No
FirstName	ns:PersonName Type Payer’s first name. Character length and limitations: 25 single-byte characters	Yes
LastName	ns:PersonName Type Payer’s last name. Character length and limitations: 25 single-byte characters	Yes
Address	ns:AddressType Payer’s billing address information See Table 4.7.	Yes

Table 4.7

CardOwner: AddressType Fields

Field	Description	Required?
Street1	xs:string First street address. Character length and limitations: 100 single-byte characters	Yes
Street2	xs:string Second street address. Character length and limitations: 100 single-byte characters	No
CityName	xs:string Name of city. Character length and limitations: 40 single-byte characters	Yes
StateOrProvince	xs:string State or province. Character length and limitations: 40 single-byte characters See Appendix E, “State and Province Abbreviations.”	Yes
Country	ebl:CountryCodeType Country code. Character limit: Two single-byte characters See Appendix F, “Country Codes.	Yes
PostalCode	xs:string U.S. ZIP code or other country-specific postal code. Character length and limitations: 20 single-byte characters	Yes
Phone	xs:string Phone number. Character length and limit: 20 single-byte characters	No

DoDirectPaymentResponse

Response to DoDirectPaymentRequest.

The Direct Payment API response contains the TransactionID element. In the case of a final Sale, TransactionID is your record of the transaction processed with PayPal. In the case of an Authorization, TransactionID is your key to capturing funds with PayPal Authorization & Capture.

DoDirectPaymentResponse also returns the result of checking the buyer’s billing address and credit card number (as submitted by you with DoDirectPaymentRequest) against the following U.S. banking industry standards:

l	Address Verification System (AVS)

l	Credit Card Verification (CVV2) system

If you specified ReturnFMFDetails in your request, additional information is provided in the FMFDetails element:

Table 4.8

FMFDetailsType Fields

Field	Descriptions
AcceptFilters	ns:RiskFilterListType List of filters that recommend acceptance the payment
DenyFilters	ns:RiskFilterListType List of filters that recommend denial of the payment
PendingFilters	ns:RiskFilterListType List of filters that caused the payment to become pending
ReportFilters	ns:RiskFilterListType List of filters that caused the payment to become flagged

The FMFDetailsType element’s fields contain lists of filters, each with the following information:

Table 4.9

RiskFilterDetailsType Fields

Field	Descriptions
Id	xs:int Filter ID, which is one of the following values: l 1 = AVS No Match l 2 = AVS Partial Match l 3 = AVS Unavailable/Unsupported l 4 = Card Security Code (CSC) Mismatch l 5 = Maximum Transaction Amount l 6 = Unconfirmed Address l 7 = Country Monitor l 8 = Large Order Number l 9 = Billing/Shipping Address Mismatch l 10 = Risky ZIP Code l 11 = Suspected Freight Forwarder Check l 12 = Total Purchase Price Minimum l 13 = IP Address Velocity l 14 = Risky Email Address Domain Check l 15 = Risky Bank Identification Number (BIN) Check l 16 = Risky IP Address Range l 17 = PayPal Fraud Model
Name	xs:string Filter name
Description	xs:string Filter description

AVS Response Codes

Table 4.10

DoDirectPaymentResponse Fields

Field	Description
TransactionID	xs: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 & Capture APIs. Character length and limitations: 19 single-byte characters
Amount	ebl:BasicAmountType This value is the amount of the payment as specified by you on DoDirectPaymentRequest.
AVSCode	xs:string Address Verification System response code. Character limit: One single-byte alphanumeric character See “AVS Response Codes”.
CVV2Code	xs:string Result of the CVV2 check by PayPal. See “CVV2 Response Codes”.

The following tables list the AVS response codes.

 

Table 4.11

AVS Response Codes for Visa, MasterCard, Discover, and American Express

AVS Code	Meaning	Matched Details
A	Address	Address only (no ZIP)
B	International “A”	Address only (no ZIP)
C	International “N”	None Note: The transaction is declined.
D	International “X”	Address and Postal Code
E	Not allowed for MOTO (Internet/Phone) transactions	Not applicable Note: The transaction is declined.
F	UK-specific “X”	Address and Postal Code
G	Global Unavailable	Not applicable
I	International Unavailable	Not applicable
N	No	None Note: The transaction is declined.
P	Postal (International “Z”)	Postal Code only (no Address)
R	Retry	Not applicable
S	Service not Supported	Not applicable
U	Unavailable	Not applicable
W	Whole ZIP	Nine-digit ZIP code (no Address)
X	Exact match	Address and nine-digit ZIP code
Y	Yes	Address and five-digit ZIP
Z	ZIP	Five-digit ZIP code (no Address)
All others	Error	Not applicable

 

Table 4.12

AVS Response Codes for Switch and Solo

0	All the address information matched.	All information matched
1	None of the address information matched.	None Note: The transaction is declined.
2	Part of the address information matched.	Partial
3	The merchant did not provide AVS information. Not processed.	Not applicable
4	Address not checked, or acquirer had no response. Service not available.	Not applicable
Null	No AVS response was obtained. Default value of field.	Not applicable

CVV2 Response Codes

The following tables list the CVV2 response codes.

 

Table 4.13

CVV2 Response Codes for Visa, MasterCard, Discover, and American Express

CVV2 Code	Meaning	Matched Details
M	Match	CVV2
N	No match	None
P	Not processed	Not applicable
S	Service not supported	Not applicable
U	Service not available	Not applicable
X	No response	Not applicable

 

Table 4.14

CVV2 Response Codes for Switch and Solo

0	Matched	CVV2
1	No match	None
2	The merchant has not implemented CVV2 code handling	Not applicable
3	Merchant has indicated that CVV2 is not present on card	Not applicable
4	Service not available	Not applicable
All others	Error	Not applicable