DoDirectPayment API Operation (NVP)

The DoDirectPayment API Operation enables you to process a credit card payment.

Only available to: PayPal Payments Pro (Direct Payment) (Website Payments Pro in Canada & UK) accounts.

DoDirectPayment Request Message

DoDirectPayment Request Fields

Field Description
METHOD (Required) Must be DoDirectPayment.
PAYMENTACTION (Optional) How you want to obtain payment. It is one of the following values:
  • 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
IPADDRESS (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
RETURNFMFDETAILS (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.

Credit Card Details Fields

Field Description
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 CURRENCYCODE to GBP. In addition, you must specify either STARTDATE or ISSUENUMBER.


Character length and limitations: Up to 10 single-byte alphabetic characters
ACCT (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.
EXPDATE Credit card expiration date. This field is required if you are using recurring payments with direct payments.
Character length and limitations: 6 single-byte alphanumeric characters, including leading zero, in the format MMYYYY
CVV2 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.
STARTDATE (Optional) Month and year that Maestro card was issued.
Character length and limitations: Must be 6 digits, including leading zero, in the format MMYYYY
ISSUENUMBER (Optional) Issue number of Maestro card.
Character length and limitations: 2 numeric digits maximum

Payer Information Fields

Field Description
EMAIL (Optional) Email address of buyer.
Character length and limitations: 127 single-byte characters
FIRSTNAME (Required) Buyer's first name.
Character length and limitations: 25 single-byte characters
LASTNAME (Required) Buyer's last name.
Character length and limitations: 25 single-byte characters

Address Fields

Field Description
STREET (Required) First street address.
Character length and limitations: 100 single-byte characters
STREET2 (Optional) Second street address.
Character length and limitations: 100 single-byte characters
CITY (Required) Name of city.
Character length and limitations: 40 single-byte characters
STATE (Required) State or province.
Character length and limitations: 40 single-byte characters
COUNTRYCODE (Required) Country code.
Character length and limitations: 2 single-byte characters
ZIP (Required) U.S. ZIP code or other country-specific postal code.
Character length and limitations: 20 single-byte characters
SHIPTOPHONENUM (Optional) Phone number.
Character length and limitations: 20 single-byte characters

Payment Details Fields

Field Description
AMT

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

Character length and limitations: Value is a positive number which cannot exceed $10,000 USD or the limit for the transaction 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 (,).

CURRENCYCODE (Optional) A 3-character currency code (default is USD).
ITEMAMT

(Optional) Sum of cost of all items in this order.

Note ITEMAMT is required if you specify L_AMTn.

Character length and limitations: Value is a positive number which cannot exceed $10,000 USD or the limit for the transaction 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 (,).

SHIPPINGAMT

(Optional) Total shipping costs for this order.

Note If you specify a value for SHIPPINGAMT, you must also specify a value for ITEMAMT.

Character length and limitations: Value is a positive number which cannot exceed $10,000 USD or the limit for the transaction 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 (,).

INSURANCEAMT

(Optional) Total shipping insurance costs for this order. The value must be a non-negative currency amount or null if you offer insurance options.

Character length and limitations: Value is a positive number which cannot exceed $10,000 USD or the limit for the transaction 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 (,).

SHIPDISCAMT

(Optional) Shipping discount for this order, specified as a negative number.

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.

HANDLINGAMT

(Optional) Total handling costs for this order.

Note

If you specify a value for HANDLINGAMT, you must also specify a value for ITEMAMT.

Character length and limitations: Value is a positive number which cannot exceed $10,000 USD or the limit for the transaction 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 (,).

TAXAMT

(Optional) Sum of tax for all items in this order.

Note TAXAMT is required if you specify L_TAXAMTn

Character length and limitations: Value is a positive number which cannot exceed $10,000 USD or the limit for the transaction 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 (,).

DESC (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 (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
INVNUM (Optional) Your own invoice or tracking number.

Note PayPal recommends using the INVNUM 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 (Optional) An identification code for use by third-party applications to identify transactions.
Character length and limitations: 32 single-byte alphanumeric characters
NOTIFYURL (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
RECURRING ns: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.

BUCKETCATEGORYTYPE (Optional) The category of a payment. It is one of the following values:
  • 1 - International shipping
  • 2 - Local delivery

Payment Details Item Fields

Field Description
L_NAMEn (Optional) Item name. These parameters must be ordered sequentially beginning with 0 (for example L_NAME0, L_NAME1).
Character length and limitations: 127 single-byte characters
L_DESCn (Optional) Item description.
Character length and limitations: 127 single-byte characters
L_AMTn

(Optional) Cost of item. These parameters must be ordered sequentially beginning with 0 (for example L_AMT0, L_AMT1).

Note If you specify a value for L_AMTn, you must specify a value for ITEMAMT.

Character length and limitations: Value is a positive number which cannot exceed $10,000 USD or the limit for the transaction 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 (,).

L_NUMBERn (Optional) Item number. These parameters must be ordered sequentially beginning with 0 (for example L_NUMBER0, L_NUMBER1).
Character length and limitations: 127 single-byte characters
L_QTYn (Optional) Item quantity. These parameters must be ordered sequentially beginning with 0 (for example L_QTY0, L_QTY1).
Character length and limitations: Any positive integer
L_TAXAMTn

(Optional) Item sales tax. These parameters must be ordered sequentially beginning with 0 (for example L_TAXAMT0, L_TAXAMT1).

Character length and limitations: Value is a positive number which cannot exceed $10,000 USD or the limit for the transaction 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 (,).

Ebay Item Payment Details Item Fields

Field Description
L_EBAYITEMNUMBERn (Optional) Auction item number. These parameters must be ordered sequentially beginning with 0 (for example L_EBAYITEMNUMBER0, L_EBAYITEMNUMBER1).
Character length: 765 single-byte characters
L_EBAYITEMAUCTIONTXNIDn (Optional) Auction transaction identification number. These parameters must be ordered sequentially beginning with 0 (for example L_EBAYITEMAUCTIONTXNID0, L_EBAYITEMAUCTIONTXNID1).
Character length: 255 single-byte characters
L_EBAYITEMORDERIDn (Optional) Auction order identification number. These parameters must be ordered sequentially beginning with 0 (for example L_EBAYITEMORDERID0, L_EBAYITEMORDERID1).
Character length: 64 single-byte characters

Ship To Address Fields

Field Description
SHIPTONAME Person's name associated with this shipping address. It is required if using a shipping address.
Character length and limitations: 32 single-byte characters
SHIPTOSTREET First street address. It is required if using a shipping address.
Character length and limitations: 100 single-byte characters
SHIPTOSTREET2 (Optional) Second street address.
Character length and limitations: 100 single-byte characters
SHIPTOCITY Name of city. It is required if using a shipping address.
Character length and limitations: 40 single-byte characters
SHIPTOSTATE State or province.
It is required if the address is in one of the following countries: Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand or USA. PayPal accepts State codes for some countries.
Character length and limitations: 40 single-byte characters
SHIPTOZIP 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
SHIPTOCOUNTRY Country code. It is required if using a shipping address.
Character length and limitations: 2 single-byte characters
SHIPTOPHONENUM (Optional) Phone number.
Character length and limitations: 20 single-byte characters

3D Secure Request Fields (U.K. Merchants Only)

Field Description
AUTHSTATUS3DS (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 (Optional) A value returned by the Cardinal Centinel. Set this field to the Enrolled value returned by cmpi_lookup.
CAVV (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 (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 (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 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
AMT This value is the amount of the payment as specified by you on DoDirectPaymentRequest for reference transactions with direct payments.
AVSCODE Address Verification System response code.
Character length and limitations: 1 single-byte alphanumeric character
CVV2MATCH Result of the CVV2 check by PayPal.
L_FMFfilterIDn Filter ID, including the filter type (PENDING, REPORT, or DENY), the filter ID, and the entry number, n, starting from 0. Filter ID 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 - 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_FMFfilterNAMEn Filter name, including the filter type, (PENDING, REPORT, or DENY), the filter NAME, and the entry number, n, starting from 0.
PAYMENTADVICECODE

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 chargebacks. For details on the meanings of these codes, see:
https://merchant.paypal.com/us/cgi-bin/?&cmd=_render-content&content_ID=merchant/cc_compliance_error_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 cardholder 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 PayPal Payments Pro merchants (outside of PayPal Recurring Payments) are responsible for stopping the subscription and should not try again with the same card if the Payment Advice codes 03 and 21 are returned.

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 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.
MasterCard:
  • 01 – Merchant Liability
  • 02 – Issuer Liability

Visa:

  • 05 – Issuer Liability
  • 06 – Issuer Liability
  • 07 – Merchant Liability