PayPal’s Website Payments Pro allows you API access to two components: Express Checkout (covered in Chapter 2) and Direct Payment. Direct Payment allows you to accept debit and credit cards directly from your site. Direct Payment, unlike Express Pay, requires the buyer to enter payment, billing, and shipping information, and does not require the buyer to have a PayPal Account. In addition, Website Payments Pro accounts do not show up as “PayPal” on your customer’s credit card statements: your company’s name shows up instead.
Direct Payment allows your customers to pay via credit or debit
cards during your checkout flow. This gives the seller complete control
over the buyer’s transaction experience. When a buyer chooses to pay with
a credit or debit card, he enters his card number and other information
directly on your site. This arrangement makes the seller/merchant
responsible for maintaining the security of the transaction, rather than
PayPal, and it is highly recommended that you provide the checkout
experience under an SSL connection. After the buyer confirms his order and
clicks the Pay button, you complete the transaction by invoking the
DoDirectPayment
API operation.
Figure 3-1 shows the checkout workflow a user experiences with Direct Payment:
The buyer clicks the Checkout button on your website, provides shipping and billing information, and clicks Continue.
The buyer reviews the order for accuracy and clicks Pay.
Information is handed off to PayPal via the
DoDirectPayment
API operation, and the buyer’s card
is charged.
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 3-1 outlines the
DoDirectPayment
request fields, and Table 3-2 outlines the method’s
response fields.
Field | Description |
METHOD | Must be DoDirectPayment
(required). |
PAYMENTACTION | Indicates how you want to obtain payment:
|
IPADDRESS | The 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. |
RETURNFMFDETAILS | Flag that indicates whether you want the results returned
by the Fraud Management Filters:
|
CREDITCARDTYPE | The type of credit card being used. Allowed values
are:
* If using Maestro , Solo , MasterCard ,
Discover , and Visa are
allowed. For Canada, only MasterCard and
Visa are allowed. |
ACCT | The 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. |
EXPDATE | The 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. |
STARTDATE | The month and year that a Maestro or Solo card was issued, in MMYYYY format. This value must be six digits, including the leading zero. |
ISSUENUMBER | The issue number of a Maestro or Solo card. Two numeric digit maximum. |
EMAIL | The email address of the buyer. Limited to 127 single-byte characters. |
FIRSTNAME | The buyer’s first name (required). Limited to 25 single-byte characters. |
LASTNAME | The buyer’s last name (required). Limited to 25 single-byte characters. |
STREET | The first street address (required). Limited to 100 single-byte characters. |
STREET2 | The second street address (required). Limited to 100 single-byte characters. |
CITY | The name of the city (required). Limited to 40 single-byte characters. |
STATE | The state or province (required). Limited to 40 single-byte characters. |
COUNTRYCODE | The country code (required). Limited to two single-byte characters. |
ZIP | The U.S. zip code or another country-specific postal code (required). Limited to 20 single-byte characters. |
SHIPTOPHONENUM | The 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 to0 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 (,). |
CURRENCYCODE | A three-character currency code. The default is
USD . |
ITEMAMT | Sum of the cost of all items in this order.
ITEMAMT is required if you specify
L_AMT n . 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 (,). |
SHIPPINGAMT | Total 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
(,). |
HANDLINGAMT | Total 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
(,). |
TAXAMT | Sum of the tax for all items in this order.
TAXAMT is required if you specify
L_TAXAMT n .
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 (,). |
DESC | A description of the items the customer is purchasing. Limited to 127 single-byte alphanumeric characters. |
CUSTOM | A free-form field for your own use. Limited to 256 single-byte alphanumeric characters. |
INVNUM | Your own internal invoice or tracking number. Limited to 127 single-byte alphanumeric characters. |
BUTTONSOURCE | An identification code for use by third-party applications to identify transactions. Limited to 32 single-byte alphanumeric characters. |
L_NAME n | The item name. Limited to 127 single-byte characters. |
L_DESC n | The item description. Limited to 127 single-byte characters. |
L_AMT n | The cost of the item. If you specify a value for
L_AMT n , 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 n | The item number. Limited to 127 single-byte characters. |
L_QTY n | The item quantity. Can be any positive integer. |
L_TAXAMT n | The 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 (,). |
SHIPTONAME | The person’s name associated with the shipping address. Required if using a shipping address. Limited to 32 single-byte characters. |
SHIPTOSTREET | The first street address. Required if using a shipping address. Limited to 100 single-byte characters. |
SHIPTOSTREET2 | The second street address. Limited to 100 single-byte characters. |
SHIPTOCITY | The name of the city. Required if using a shipping address. Limited to 40 single-byte characters. |
SHIPTOSTATE | The state or province. Required if using a shipping address. Limited to 40 single-byte characters. |
SHIPTOZIP | The U.S. zip code or other country-specific postal code. Required if using a U.S. shipping address and might be required for other countries. Limited to 20 single-byte characters. |
SHIPTOCOUNTRY | The country code. Required if using a shipping address. Limited to two single-byte characters. |
SHIPTOPHONENUM | The phone number. Limited to 20 single-byte characters. |
Field | Description |
TRANSACTIONID | The 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. |
AMT | This value is the amount of the payment you specified in
the DoDirectPayment request. |
AVSCODE | The Address Verification System response code. Limited to one single-byte alphanumeric character. |
CVV2MATCH | The results of the CVV2 check by PayPal. |
L_FMF filterID n | The 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:
|
L_FMF filterNAME n | The filter name, including the filter type,
(PENDING , REPORT , or
DENY ), the
filterNAME , and the entry number,
n , starting from
0 . |
To implement a Direct Payment transaction, you need to invoke
the DoDirectPayment
API and provide information to
identify the buyer’s credit or debit card and the amount of the payment.
Setting up the transaction is accomplished through the following
steps:
Specify the amount of the transaction, including the currency if it is not in U.S. dollars. You should specify the total amount of the transaction if it is known; otherwise, specify the subtotal.
AMT=
amount
CURRENCYCODE=
currencyID
Specify the payment action. It is best practice to explicitly specify the payment action as one of the following values:
PAYMENTACTIO
N=
Sale
PAYMENTACTION=
Authorization
Specify the IP address of the buyer’s computer:
IPADDRESS=
xxx.xxx.xxx.xxx
Specify information about the card being used. You must specify the type of card as well as the account number:
CREDITCARDTYPE=Visa
ACCT=
1234567891011123
The type of credit/debit card being used, the card issuer, and the Payment Receiving Preferences setting on your PayPal Profile might require that you set the following fields as well:
EXPDATE=
012010
CVV2=
123
Specify information about the card holder. You must provide the first and last name of the card holder, as well as the billing address associated with the card:
FIRSTNAME=
John
LASTNAME=
Doe
STREET=
1313 Mockingbird
Lane
CITY=
Any
town
STATE=
Any
state
ZIP=
11111
COUNTRYCODE=
US
Direct Payment is probably the easiest component to integrate for
NVP access. You can add DoDirectPayment functionality to your checkout
processor by adding the code in Example 3-1 and providing your API
credentials. For instructions on creating those credentials, refer to
Creating an API Signature. Additionally, after you have
completed testing and are ready to go live, change $environment = 'sandbox'
to
$environment='live'
.
<?php /** DoDirectPayment NVP example; last modified 08MAY23. * * Process a credit card payment. */ $environment = 'sandbox'; // or 'beta-sandbox' or 'live' /** * Send HTTP POST Request * * @param string The API method name * @param string The POST Message fields in &name=value pair format * @return array Parsed HTTP Response body */ function PPHttpPost($methodName_, $nvpStr_) { global $environment; // Set up your API credentials, PayPal end point, and API version. $API_UserName = urlencode('my_api_username'), $API_Password = urlencode('my_api_password'), $API_Signature = urlencode('my_api_signature'), $API_Endpoint = "https://api-3t.paypal.com/nvp"; if("sandbox" === $environment || "beta-sandbox" === $environment) { $API_Endpoint = "https://api-3t.$environment.paypal.com/nvp"; } $version = urlencode('51.0'), // Set the curl parameters. $ch = curl_init(); curl_setopt($ch, CURLOPT_URL, $API_Endpoint); curl_setopt($ch, CURLOPT_VERBOSE, 1); // Turn off the server and peer verification (TrustManager Concept). curl_setopt($ch, CURLOPT_SSL_VERIFYPEER, FALSE); curl_setopt($ch, CURLOPT_SSL_VERIFYHOST, FALSE); curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1); curl_setopt($ch, CURLOPT_POST, 1); // Set the API operation, version, and API signature in the request. $nvpreq = "METHOD=$methodName_&VERSION=$version&PWD=$API_Password&USER=$API_UserName". "&SIGNATURE=$API_Signature$nvpStr_"; // Set the request as a POST FIELD for curl. curl_setopt($ch, CURLOPT_POSTFIELDS, $nvpreq); // Get response from the server. $httpResponse = curl_exec($ch); if(!$httpResponse) { exit("$methodName_ failed: ".curl_error($ch).'('.curl_errno($ch).')'), } // Extract the response details. $httpResponseAr = explode("&", $httpResponse); $httpParsedResponseAr = array(); foreach ($httpResponseAr as $i => $value) { $tmpAr = explode("=", $value); if(sizeof($tmpAr) > 1) { $httpParsedResponseAr[$tmpAr[0]] = $tmpAr[1]; } } if((0 == sizeof($httpParsedResponseAr))||!array_key_exists('ACK', $httpParsedResponseAr)) { exit("Invalid HTTP Response for POST request($nvpreq) to $API_Endpoint."); } return $httpParsedResponseAr; } // Set request-specific fields. $paymentType = urlencode('Authorization'), // or 'Sale' $firstName = urlencode('customer_first_name'), $lastName = urlencode('customer_last_name'), $creditCardType = urlencode('customer_credit_card_type'), $creditCardNumber = urlencode('customer_credit_card_number'), $expDateMonth = 'cc_expiration_month'; // Month must be padded with leading zero $padDateMonth = urlencode(str_pad($expDateMonth, 2, '0', STR_PAD_LEFT)); $expDateYear = urlencode('cc_expiration_year'), $cvv2Number = urlencode('cc_cvv2_number'), $address1 = urlencode('customer_address1'), $address2 = urlencode('customer_address2'), $city = urlencode('customer_city'), $state = urlencode('customer_state'), $zip = urlencode('customer_zip'), $country = urlencode('customer_country'), // US or other valid country code $amount = urlencode('example_payment_amuont'), $currencyID = urlencode('USD'), // or other currency ('GBP', 'EUR', 'JPY', 'CAD', 'AUD') // Add request-specific fields to the request string. $nvpStr ="&PAYMENTACTION=$paymentType&AMT=$amount&CREDITCARDTYPE=$creditCardType". "&ACCT=$creditCardNumber&EXPDATE=$padDateMonth$expDateYear&CVV2=$cvv2Number". "&FIRSTNAME=$firstName&LASTNAME=$lastName&STREET=$address1&CITY=$city". "&STATE=$state&ZIP=$zip&COUNTRYCODE=$country&CURRENCYCODE=$currencyID"; // Execute the API operation; see the PPHttpPost function above. $httpParsedResponseAr = PPHttpPost('DoDirectPayment', $nvpStr); if("SUCCESS" == strtoupper($httpParsedResponseAr["ACK"])||"SUCCESSWITHWARNING"== strtoupper($httpParsedResponseAr["ACK"])) { exit('Direct Payment Completed Successfully: '.print_r($httpParsedResponseAr, true)); } else { exit('DoDirectPayment failed: ' . print_r($httpParsedResponseAr, true)); } ?>
3.137.200.7