DoDirectPayment Request Message

DoDirectPayment Request Fields

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

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.

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 a 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 will be changed to NewYork. Added in version 115 of the API.

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. It is one of the following values:

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

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

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

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.

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

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

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

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

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.

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