PayPal Direct Payment API Operations

The PayPal NVP API uses only one method related to Direct Payment: DoDirectPayment. This one method initializes the payment and returns the results all in one operation. Table 5-1 outlines the DoDirectPayment request fields, and Table 5-2 outlines the method’s response fields.

Table 5-1. DoDirectPayment request fields

FieldDescription
METHODMust be DoDirectPayment (required).
PAYMENTACTIONIndicates how you want to obtain payment:
  • Authorization: This payment is a basic authorization subject to settlement with PayPal Authorization and Capture.

  • Sale: This is the default value, indicating that it is a final sale.

Limitation: Up to 13 single-byte characters.
IPADDRESSThe IP address of the buyer’s browser (required). PayPal records this IP address to detect possible fraud. Limitation: Up to 15 single-byte characters, including periods. Must be an IPv4 address.
RETURNFMFDETAILSFlag that indicates whether you want the results returned by the Fraud Management Filters:
  • 0: Do not receive FMF details (default)

  • 1: Receive FMF details

CREDITCARDTYPEThe type of credit card being used. Allowed values are:
  • Visa

  • MasterCard

  • Discover

  • Amex

  • Maestro *

  • Solo *

* If using Maestro or Solo, the CURRENCYCODE must be GBP. Additionally, either STARTDATE or ISSUENUMBER must be specified.

Limitation: Up to 10 single-byte alphabetic characters. For the UK, only Maestro, Solo, MasterCard, Discover, and Visa are allowed. For Canada, only MasterCard and Visa are allowed.
ACCTThe customer’s credit card number. Limitations: Numeric characters only, with no spaces or punctuation. Must conform with the modulo and length required by each card type.
EXPDATEThe credit card expiration date, in the format MMYYYY. Limitations: Six single-byte alphanumeric characters, including the leading 0.
CVV2

The card verification value, version 2. This field may or may not be required, depending on your merchant account settings.

The character length for Visa, MasterCard, and Discover is three digits. The character length for American Express is four digits. To adhere to credit card processing regulations, you cannot store this value after a transaction is complete.
STARTDATEThe month and year that a Maestro or Solo card was issued, in MMYYYY format. This value must be six digits, including the leading zero.
ISSUENUMBERThe issue number of a Maestro or Solo card. Two numeric digit maximum.
EMAILThe email address of the buyer. Limited to 127 single-byte characters.
FIRSTNAMEThe buyer’s first name (required). Limited to 25 single-byte characters.
LASTNAMEThe buyer’s last name (required). Limited to 25 single-byte characters.
STREETThe first street address (required). Limited to 100 single-byte characters.
STREET2The second street address (required). Limited to 100 single-byte characters.
CITYThe name of the city (required). Limited to 40 single-byte characters.
STATEThe state or province (required). Limited to 40 single-byte characters.
COUNTRYCODEThe country code (required). Limited to two single-byte characters.
ZIPThe US zip code or another country-specific postal code (required). Limited to 20 single-byte characters.
SHIPTOPHONENUMThe phone number. Limited to 20 single-byte characters.
AMT

The total cost of the transaction to the customer (required).

If the 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. Set this field to 0 if the transaction does not include a one-time purchase, for example, when you set up a billing agreement for a recurring payment that is not charged immediately. Purchase-specific fields will be ignored.

Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,).

CURRENCYCODEA three-character currency code. The default is USD.
ITEMAMTSum of the cost of all items in this order. ITEMAMT is required if you specify L_AMTn. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
SHIPPINGAMTTotal shipping cost for this order. If you specify a value for SHIPPINGAMT, you are required to specify a value for ITEMAMT as well. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
HANDLINGAMTTotal handling costs for this order. If you specify a value for HANDLINGAMT, you are required to specify a value for ITEMAMT as well. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
TAXAMTSum of the tax for all items in this order. TAXAMT is required if you specify L_TAXAMTn. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
DESCA description of the items the customer is purchasing. Limited to 127 single-byte alphanumeric characters.
CUSTOMA free-form field for your own use. Limited to 256 single-byte alphanumeric characters.
INVNUMYour own internal invoice or tracking number. Limited to 127 single-byte alphanumeric characters.
BUTTONSOURCEAn identification code for use by third-party applications to identify transactions. Limited to 32 single-byte alphanumeric characters.
L_NAME nThe item name. Limited to 127 single-byte characters.
L_DESC nThe item description. Limited to 127 single-byte characters.
L_AMT nThe cost of the item. If you specify a value for L_AMTn, you must specify a value for ITEMAMT. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
L_NUMBER nThe item number. Limited to 127 single-byte characters.
L_QTY nThe item quantity. Can be any positive integer.
L_TAXAMT nThe item’s sales tax. Limitations: Must not exceed $10,000 USD in any currency. No currency symbol. Must have two decimal places, the decimal separator must be a period (.), and the optional thousands separator must be a comma (,).
SHIPTONAMEThe person’s name associated with the shipping address. Required if using a shipping address. Limited to 32 single-byte characters.
SHIPTOSTREETThe first street address. Required if using a shipping address. Limited to 100 single-byte characters.
SHIPTOSTREET2The second street address. Limited to 100 single-byte characters.
SHIPTOCITYThe name of the city. Required if using a shipping address. Limited to 40 single-byte characters.
SHIPTOSTATEThe state or province. Required if using a shipping address. Limited to 40 single-byte characters.
SHIPTOZIPThe US zip code or other country-specific postal code. Required if using a US shipping address and might be required for other countries. Limited to 20 single-byte characters.
SHIPTOCOUNTRYThe country code. Required if using a shipping address. Limited to two single-byte characters.
SHIPTOPHONENUMThe phone number. Limited to 20 single-byte characters.

Table 5-2. DoDirectPayment response fields

FieldDescription
TRANSACTIONIDThe unique transaction ID of the payment. If the PaymentAction of the request was Authorization, the value of TransactionID is your AuthorizationID for use with the Authorization and Capture API.
AMTThis value is the amount of the payment you specified in the DoDirectPayment request.
AVSCODEThe Address Verification System response code. Limited to one single-byte alphanumeric character.
CVV2MATCHThe results of the CVV2 check by PayPal.
L_FMF filterID nThe filter ID, including the filter type (PENDING, REPORT, or DENY), the filterID, and the entry number, n, starting from 0. filterID is one of the following values [AVS stands for Address Verification System]:
  • 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

L_FMF filterNAME nThe filter name, including the filter type, (PENDING, REPORT, or DENY), the filterNAME, and the entry number, n, starting from 0.