DoDirectPayment API Operation (SOAP)

Processes a credit card payment.

Only available to: Website Payments Pro.

DoDirectPayment Request Message

DoDirectPayment Request Fields

Field Description

PaymentAction

ebl:PaymentActionCodeType

(Optional) How you want to obtain payment. Value is:

  • Sale – This is a final sale for which you are requesting payment (default).
  • Authorization – Authorization can be a basic authorization subject to settlement with the DoCapture API operation or a manual capture. Authorization can also be a zero amount authorization used for card verifications.
Note: Order is not allowed for Direct Payment.

Character length and limit: Up to 13 single-byte alphabetic characters

CreditCard

ebl:CreditCardDetailsType

(Required) Information about the credit card to be charged.

PaymentDetails

ebl:PaymentDetailsType

(Required) Information about the credit card to be charged.

IPAddress

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

MerchantSessionId

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

ReturnFMFDetails

xs:int

(Optional) Flag to indicate whether you want the results returned by Fraud Management Filters. By default, you do not receive this information. Value is:

  • 0 — Do not receive FMF details (default).

  • 1 — Receive FMF details.

SoftDescriptor

xs:string

(Optional) Information that is usually displayed in the account holder's statement, for example, <Your-Not-For-Profit> <State>, <Your-Not-For-Profit> <Branch-Name>, <Your-Website> dues or <Your-Website> list fee.

Character length and limitations: 23 alphanumeric characters, can include the special characters dash (-) and dot (.) only. Asterisks (*) are NOT permitted. If it includes a space character (), enclose the "<Soft-Descriptor>" value in double quotes.

Note: For US Website Payments Pro AMEX cards only and only for merchants passing dynamic soft descriptors, the dynamic soft descriptors for AMEX cards are only guaranteed once the transaction settles. This means that during the authorization time the card issuing bank might show their customer the registered business or legal name for the merchant versus the dynamic soft descriptor passed on a per API transaction.

SoftDescriptorCity

(Optional) A unique phone number, email address or URL, which is displayed on the account holder's statement. PayPal recommends passing a toll-free phone number because, typically, this is the easiest way for a buyer to contact the seller in the case of an inquiry.
Character length and limitations: 13 characters including special characters, such as, space, !, ", #, $, %, &, ', (, ), +, -,*, /, :, ;, <, =, >, ?, @, comma and period.

If it includes the space character (), enclose the "<Soft-Descriptor-City>" value in double quotes.

Note: Underscore (_) is an illegal character for this field. If it is passed, then it will be removed leaving the remaining characters in the same order. For example, New_York changes to NewYork.

Added in version 115 of the API.

CreditCardDetailsType Fields

Field Description

CreditCardType

ebl:CreditCardType

(Optional) Type of credit card. For UK, only Maestro, MasterCard, and Visa are allowable. For Canada, only MasterCard and Visa are allowable, and Interac debit cards are not supported. Value is:

  • Visa
  • MasterCard
  • Discover
  • Amex
  • JCB
  • Maestro: See note.
Note: If the credit card type is Maestro, you must set currencyId to GBP. In addition, you must specify either StartMonth and StartYear or IssueNumber.

Character length and limitations: Up to 10 single-byte alphabetic characters

CreditCardNumber

xs:string

(Required) Credit card number.

Character length and limitations: Numeric characters only with no spaces or punctuation. The string must conform with modulo and length required by each credit card type.

ExpMonth

xs:int

(Required) Credit card expiration month.

Character length and limitations: 2 single-byte numeric characters, including leading zero

ExpYear

xs:int

(Required) Credit card expiration year.

Character length and limitations: 4 single-byte numeric characters

CVV2

xs: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.

CardOwner

ns:PayerInfoType

(Required) Details about the owner of the credit card.

StartMonth

xs:int

(Optional) Month that Maestro card was issued.

Character length and limitations: 2-digit, zero-filled if necessary

StartYear

xs:int

(Optional) Year that Maestro card was issued.

Character length and limitations: 4 digits

IssueNumber

xs:string

(Optional) Issue number of Maestro card.

Character length and limitations: 2 numeric digits maximum

ThreeDSecureRequest

ns:ThreeDSecureRequestType

(Optional) Information about 3-D Secure settings (UK only).

PayerInfoType Fields

Field Description

Payer

ebl:EmailAddressType

(Required) Email address of buyer.

Character length and limitations: 127 single-byte characters

PayerID

ebl:UserIDType

(Optional) Unique PayPal Customer Account identification number.

Character length and limitations: 13 single-byte alphanumeric characters

PayerStatus

ebl:PayPalUser StatusCodeType

(Optional) Status of buyer. Value is:

  • verified

  • unverified

Character length and limitations: 10 single-byte alphabetic characters

PayerName

ebl:PersonNameType

(Optional) First and last name of buyer.

PayerCountry

ebl:CountryCodeType

(Optional) Buyer's country of residence in the form of ISO standard 3166 two-character country codes.

Character length and limitations: 2 single-byte characters

PayerBusiness

xs:string

(Optional) Buyer's business name.

Character length and limitations: 127 single-byte characters

Address

xs:string

(Optional) Buyer's shipping address information.

PayerNameType Fields

Field Description

Salutation

xs:string

(Optional) Buyer's salutation.

Character length and limitations: 20 single-byte characters

FirstName

ebl:PersonNameType

(Required) Buyer's first name.

Character length and limitations: 64 double-byte characters

MiddleName

ebl:NameUser

(Optional) Buyer's middle name.

Character length and limitations: 64 double-byte characters

LastName

ebl:NameType

(Required) Buyer's last name.

Character length and limitations: 64 double-byte characters

Suffix

ebl:SuffixType

(Optional) Buyer's suffix.

Character length and limitations: 12 single-byte characters

AddressType Fields

Field Description

Street1

xs:string

(Required) First street address.

Character length and limitations: 100 single-byte characters

Street2

xs:string

(Optional) Second street address.

Character length and limitations: 100 single-byte characters

CityName

xs:string

(Required) Name of city.

Character length and limitations: 40 single-byte characters

StateOrProvince

xs:string

State or province.

It is required for direct credit card transactions only if the address is in one of the following countries: Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand or USA, and it is required for Express Checkout transactions only if the address is a U.S. address. See the list of PayPal State codes.

Character length and limitations: 40 single-byte characters

Country

ebl:CountryCodeType

(Required) Country code.

Character length and limitations: 2 single-byte characters

PostalCode

xs:string

(Required) U.S. ZIP code or other country-specific postal code.

Character length and limitations: 20 single-byte characters

PaymentDetailsType Fields

Field Description

OrderTotal

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. This field must be set to a value greater than 0.

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 (or 0 in the case of Card Verifications or Zero amount Auths. The amount cannot exceed $10,000 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places; the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

ItemTotal

ebl: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 (or 0 in the case of Card Verifications or Zero amount Auths. The amount cannot exceed $10,000 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places; the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

ShippingTotal

ebl: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 (or 0 in the case of Card Verifications or Zero amount Auths. The amount cannot exceed $10,000 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places; the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

InsuranceTotal

ebl:BasicAmountType

(Optional) Total shipping insurance costs for this order. The value must be a non-negative 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 (or 0 in the case of Card Verifications or Zero amount Auths. The amount cannot exceed $10,000 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places; the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

InsuranceTotal is available since version 53.0.

ShippingDiscount

ebl: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 negative number. It includes no currency symbol. Most currencies require 2 decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

ShippingDiscount is available since version 53.0.

HandlingTotal

ebl: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 (or 0 in the case of Card Verifications or Zero amount Auths. The amount cannot exceed $10,000 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places; the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

TaxTotal

ebl: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 (or 0 in the case of Card Verifications or Zero amount Auths. The amount cannot exceed $10,000 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places; the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

OrderDescription

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

Custom

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

InvoiceID

xs:string

(Optional) Your own invoice or tracking number.

Note: PayPal recommends using the InvoiceID field to associate transactions with your internal tracking IDs or invoice numbers; populating the invoice ID field will help you pull transaction information at a later date using only your internal ID.
Important: 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

ButtonSource

xs:string

(Optional) An identification code for use by third-party applications to identify transactions.

Character length and limitations: 32 single-byte alphanumeric characters

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.

Character length and limitations: 2,048 single-byte alphanumeric characters

ShipToAddress

ns:AddressType

(Optional) Address to which the order is shipped.

PaymentDetailsItem

ebl:PaymentDetailsItemType

(Optional) Details about each individual item included in the order.

Recurring

ns:RecurringFlagType

(Optional) Flag to indicate a recurring transaction. Value is:


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

PaymentCategoryType

ebl:PaymentCategoryType

(Optional) Category of a payment. Value is:
InternationalShipping
LocalDelivery

PaymentDetailsItemType Fields

Field Description

Name

xs:string

(Optional) Item name.

Character length and limitations: 127 single-byte characters

Description

xs:string

(Optional) Item description.

Description is available since version 53.0.

Character length and limitations: 127 single-byte characters

Amount

ebl: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 (or 0 in the case of Card Verifications or Zero amount Auths. The amount cannot exceed $10,000 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places; the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

Number

xs:string

(Optional) Item number.

Character length and limitations: 127 single-byte characters

Quantity

xs:integer

(Optional) Item quantity.

Character length and limitations: Any positive integer

Tax

ebl: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 (or 0 in the case of Card Verifications or Zero amount Auths. The amount cannot exceed $10,000 USD or the per transaction limit for the currency. It includes no currency symbol. Most currencies require two decimal places; the decimal separator must be a period (.), and the optional thousands separator must be a comma (,). Some currencies do not allow decimals. See the currency codes page for details.

EbayItemPayment DetailsItem

eBl:ebayItemPaymentDetailsItemType

(Optional) Information relating to an auction sale on eBay.

EbayItemPaymentDetailsItemType Fields

Field Description

ItemNumber

xs:string

(Optional) Auction item number.

Character length: 765 single-byte characters

AuctionTransaction Id

xs:string

(Optional) Auction transaction identification number.

Character length: 255 single-byte characters

OrderID

xs:string

(Optional) Auction order identification number.

Character length: 64 single-byte characters

AddressType (Shipping) Fields

Field Description

Name

xs:string

Person's name associated with this shipping address. It is required if using a shipping address.

Character length and limitations: 32 double-byte characters

Street1

xs:string

First street address. It is required if using a shipping address.

Character length and limitations: 100 single-byte characters

Street2

xs:string

(Optional) Second street address.

Character length and limitations: 100 single-byte characters

CityName

xs:string

Name of city. It is required if using a shipping address.

Character length and limitations: 40 single-byte characters

StateOrProvince

xs:string

State or province.

It is required for direct credit card transactions only if the address is in one of the following countries: Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand or USA, and it is required for Express Checkout transactions only if the address is a U.S. address. See the list of PayPal State codes.

Character length and limitations: 40 single-byte characters

PostalCode

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

Country

ebl:CountryCodeType

Country code. It is required if using a shipping address.

Character length and limitations: 2 single-byte characters

ThreeDSecureRequest Fields (U.K. Merchants Only)

Field Description

AuthStatus3ds

xs: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.

MpiVendor3ds

xs:string

(Optional) A value returned by the Cardinal Centinel. Set this field to the Enrolled value returned by cmpi_lookup.

Cavv

xs: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.

Eci3ds

xs:string

(Optional) A value returned by the Cardinal Centinel. If the cmpi_lookup request returns Y for Enrolled, set this field to the EciFlag value returned by cmpi_authenticate. Otherwise, set this field to the EciFlag value returned by cmpi_lookup.

Xid

xs: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.

DoDirectPayment Response Message

DoDirectPayment Response Fields

Field Description

TransactionID

xs:string

(Optional) 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 DoAuthorization and DoCapture API operations.

Character length and limitations: 17 characters except for transactions of the type Order have a character length of 19.

Amount

ebl:BasicAmountType

This value is the payment amount specified in the DoDirectPaymentRequest request.

AVSCode

xs:string

Address Verification System response code resulting from the AVS verification. See AVS Response Codes for details.

Character length and limitations: 1 single-byte alphanumeric character

CVV2Code

xs:string

Result of the CVV2 verification. See CVV2 Response Codes for details.

TransactionPendingReason

xs:string

Transaction is pending the Interchange Plus (IC+) processing. For merchants who opt in to IC+, PayPal waits to receive funding and the fee amount from the bank before settling the transaction to the merchant's PayPal account. While the transaction is awaiting funding, the value returned in this field is: delayed-disbursement.

FMFDetails

ebl:FMFDetailsType

Fraud filter details.

PaymentAdviceCode

xs:string

A processor response code typically returned on declined Website Payments Pro recurring transactions. Its purpose is to provide merchants with information and specific instructions on how to handle the decline. It is the merchant's responsibility to follow the instructions provided in order to avoid charge backs. For details on the meanings of these codes, see AVS, CVV2, and payment advice response codes.

Note: If a recurring transaction is declined with a returned PaymentAdviceCode value of 03 or 21, PayPal will cancel the recurring transaction and send a cancellation email notification to the merchant. These payment advice codes indicate that either the account was closed, fraud was involved, or the card holder has asked their bank to stop this payment for another reason.

Developers or partners using reference transactions to provide recurring payment or subscription support for Website Payments Pro merchants (outside of PayPal Recurring Payments) are responsible for stopping the subscription and should not try again with the same card same card if the Payment Advice 03 and 21 codes are returned.

FMFDetailsType Fields

Field Description

AcceptFilters

xs:RiskFilterListType

List of filters that recommend acceptance of the payment.

DenyFilters

xs:RiskFilterListType

List of filters that recommend denial of the payment.

PendingFilters

xs:RiskFilterListType

List of filters that caused the payment to become pending.

ReportsFilters

xs:RiskFilterListType

List of filters that caused the payment to become flagged.

RiskFilterListType Fields

Field Description

ID

xs:int

Filter ID. Value is:

  • 1 - AVS No Match

  • 2 - AVS Partial Match

  • 3 - AVS Unavailable/Unsupported

  • 4 - Card Security Code (CSC) Mismatch

  • 5 - Maximum Transaction Amount

  • 6 - Unconfirmed Address

  • 7 - Country Monitor

  • 8 - Large Order Number

  • 9 - Billing/Shipping Address Mismatch

  • 10 - Risky ZIP Code

  • 11 - Suspected Freight Forwarder Check

  • 12 - Total Purchase Price Minimum

  • 13 - IP Address Velocity

  • 14 - Risky Email Address Domain Check

  • 15 - Risky Bank Identification Number (BIN) Check

  • 16 - Risky IP Address Range

  • 17 - PayPal Fraud Model

Name

xs:string

Filter name.

Description

xs:string

Filter description.

ThreeDSecure Response Fields

Field Description

VPAS

Visa Payer Authentication Service status. The value indicates whether Verified by Visa confirms that the information received is acceptable. It is returned 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

EciSubmitted3ds

Electronic Commerce Indicator (ECI) that PayPal submitted with the payment authorization request. This might not be the same value received from the merchant. In rare cases, PayPal is required to use a different ECI for authorization based on the full set of 3-D Secure values provided from the cmpi_authenticate request.

MasterCard:

  • 01 — Merchant Liability

  • 02 — Issuer Liability

Visa:

  • 05 — Issuer Liability

  • 06 — Issuer Liability

  • 07 — Merchant Liability

Additional information