DoDirectPayment API Operation (NVP)

API

Last updated: Sept 18th, 6:01pm

Important: NVP/SOAP is a legacy integration method. We accept new integrations and support existing integrations, but there are newer solutions. If you're starting an integration, we recommend our latest solutions.

Processes a credit card payment.

Only available to: Website Payments Pro accounts

Important: PayPal isn't accepting new users for this feature, and we require existing users to upgrade to our Advanced Debit and Credit solution that supports EMV 3DS (3DS 2.0) for PSD2. Our Advanced Debit and Credit solution enables highly customizable custom-card fields and reduced PCI Compliance requirements. For more information, see Set up advanced credit and debit card payments.

DoDirectPayment Request Message

DoDirectPayment Request Fields

Field	Description
`METHOD`	(Required) Must be DoDirectPayment.
`PAYMENTACTION`	(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
`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. Value is: `0` – Do not receive FMF details (default). `1` – Receive FMF details.
`SOFTDESCRIPTOR`	(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`.

Credit Card Details Fields

Field	Description
`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 `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`	(Optional) Buyer's first name. (Required) when certain FMF settings are enabled. Character length and limitations: 64 double-byte characters
`LASTNAME`	(Optional) Buyer's last name. (Required) when certain FMF settings are enabled. Character length and limitations: 64 double-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

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 (or `0` in the case of Card Verifications or Zero amount Auths). The amount cannot exceed nine (9) digits in the SOAP request and response for USD, CLP, or JPY 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.
`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 (or `0` in the case of Card Verifications or Zero amount Auths). The amount cannot exceed nine (9) digits in the SOAP request and response for USD, CLP, or JPY 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.
`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 (or `0` in the case of Card Verifications or Zero amount Auths). The amount cannot exceed nine (9) digits in the SOAP request and response for USD, CLP, or JPY 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.
`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 (or `0` in the case of Card Verifications or Zero amount Auths). The amount cannot exceed nine (9) digits in the SOAP request and response for USD, CLP, or JPY 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.
`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 (or `0` in the case of Card Verifications or Zero amount Auths). The amount cannot exceed nine (9) digits in the SOAP request and response for USD, CLP, or JPY 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.
`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 (or `0` in the case of Card Verifications or Zero amount Auths). The amount cannot exceed nine (9) digits in the SOAP request and response for USD, CLP, or JPY 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.
`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.
`RECURRING`	`ns:RecurringFlagType` (Deprecated, 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. Value is: `1` - International shipping `2` - Local delivery
`PAYMENTINITIATOR`	`CUSTOMER` (default) - Customer initiates the payment. Also referred to as a Customer Initiated Transaction (CIT). `MERCHANT` - Merchant initiates the transaction and the merchant has established consent to charge the buyer. Also referred to as a Merchant Initiated Transaction (MIT).
`PAYMENTCATEGORY`	`UNSCHEDULED` - Payments that the merchant initiates and are not on a specified schedule. For example, this includes preauthorized transactions where the merchant can charge the buyer once a balance falls within a specified range. These transactions are also referred to as top-up. `RECURRING` - Merchant initiates a payment as part of a series of recurring payments. The payment amounts can be variable and are on a fixed time interval. `ONE_TIME` - Single, one-time payment.
`CARDONFILE`	`FIRST` - Save card information or payment token to use in subsequent transactions. Collect consent from the buyer that you intend to save their payment information. `SUBSEQUENT` - Card information or payment token was previously saved and is used in the transaction.
`PREVIOUSTRANSACTIONREFERENCE`	PayPal transaction ID previously used to charge the buyer. Shows payment processors that you have established a contract with the buyer.
`PREVIOUSNETWORKTRANSACTIONREFERENCE`	`PREVIOUSNETWORKTRANSACTIONID` - Transaction ID from a non-PayPal payment processor that you have previously used to process the payment. `Network` - TransactionID from a non-PayPal payment processor that you have previously used to process the payment.

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: @items['/shared/cl_currencylimit_ppp/'].compiled_content
`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 either a positive number or, for card verifications or zero amount authorizations, `0`. The amount cannot exceed $10,000 USD or the per transaction limit for the currency. Omit the currency symbol from the value. Most currencies require two decimal places. Specify the period (`.`) character for the decimal separator and, optionally, the comma (`,`) character for the thousands separator. Some currencies do not allow decimals. For details, see currency codes.

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 double-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. Required for transactions only if the address is in one of the following countries: Argentina, Brazil, Canada, China, Indonesia, India, Japan, Mexico, Thailand or USA. See the list of PayPal state codes. 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

DoDirectPayment Response Message

DoDirectPayment Response Fields

Field	Description
`TRANSACTIONID`	(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. Orders transactions have 19 characters.
`AMT`	This value is the amount of the payment as specified in the `DoDirectPaymentRequest` request.
`AVSCODE`	Address Verification System response code resulting from the AVS verification. See AVS Response Codes for details. Character length and limitations: One single-byte alphanumeric character
`CVV2MATCH`	Result of the CVV2 verification. See CVV2 Response Codes for details.
`PENDING_REASON`	`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`.
`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 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 who use 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 if the Payment Advice `03` and `21` codes are returned.

ThreeDSecure Response Fields

Field Description

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

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

API error codes