Chapter 3. PayPal Website Payments Pro

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.

Overview of Direct Payment

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.

Direct Payment Workflow

Figure 3-1 shows the checkout workflow a user experiences with Direct Payment:

  1. The buyer clicks the Checkout button on your website, provides shipping and billing information, and clicks Continue.

  2. The buyer reviews the order for accuracy and clicks Pay.

  3. Information is handed off to PayPal via the DoDirectPayment API operation, and the buyer’s card is charged.

  4. The customer receives the Order Complete summary page.

PayPal Direct Payment workflow
Figure 3-1. PayPal Direct Payment workflow

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 3-1 outlines the DoDirectPayment request fields, and Table 3-2 outlines the method’s response fields.

Table 3-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 U.S. 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_NAMEnThe item name. Limited to 127 single-byte characters.
L_DESCnThe item description. Limited to 127 single-byte characters.
L_AMTnThe 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_NUMBERnThe item number. Limited to 127 single-byte characters.
L_QTYnThe item quantity. Can be any positive integer.
L_TAXAMTnThe 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 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.
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 3-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_FMFfilterIDnThe 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:
  • 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_FMFfilterNAMEnThe filter name, including the filter type, (PENDING, REPORT, or DENY), the filterNAME, and the entry number, n, starting from 0.

Simple Direct Payment Integration

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:

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

  2. Specify the payment action. It is best practice to explicitly specify the payment action as one of the following values:

    PAYMENTACTION=Sale

    PAYMENTACTION=Authorization

  3. Specify the IP address of the buyer’s computer:

    IPADDRESS=xxx.xxx.xxx.xxx

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

  5. 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 Integrations

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

Example 3-1. dodirectpayment.php

<?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));
}

?>
..................Content has been hidden....................

You can't read the all page of ebook, please click here login for view all page.
Reset
3.144.227.231