Website Payments Pro Security Features

Fraud filters

If you have signed-up for the Fraud Management Filters feature, refer to the Fraud Management Filters integration guide.

3-D Secure (UK only)

3-D Secure enables you to authenticate cardholders through the card issuers. Its goals are to reduce the likelihood of fraud when using supported cards and to improve transaction performance. Visa offers 3-D Secure under the name Verified by Visa and MasterCard offers it as MasterCard SecureCode. Use of 3-D Secure authentication is optional for Visa and MasterCard transactions, but Merchants who do not use 3-D Secure may be liable for fraudulent transactions even if the transaction was authorized by other means.

Integration steps

PayPal enables you to pass 3-D Secure data to PayPal for Payments Pro transactions, but you must obtain the 3-D Secure authentication data from the card's issuer.

To integrate 3-D Secure with PayPal:

1. Required Review 3-D Secure support and limitations.
2. Required Meet the prerequisites.
3. Required Update your app debit or credit card flow for 3-D Secure immediately before the Direct Payment API request, and add additional fields to the Direct Payment API request.
4. Required Set up your website with required 3-D Secure logos, status windows, and other information for your customers.
5. Required Test your integration using Cardinal's testing facilities. PayPal's Sandbox cannot be used for testing 3-D Secure functionality.
6. Optional Refer to the 3-D Secure API reference.

3-D Secure support and limitations

Website Payments Pro allows UK merchants to pass 3-D Secure™ authentication data to PayPal for debit and credit cards processed with the DoDirectPayment API request. Updating your site with 3-D Secure enables your participation in the Verified by Visa and MasterCard SecureCode programs.

Note: A US or Canadian merchant can implement 3-D Secure; however, the authentication data is ignored by PayPal. This information only applies to 3-D Secure for UK merchants implementing Direct Payment.

3-D Secure is not supported for direct recurring billing and reference transactions. Cards that require 3-D Secure authentication cannot use these operations; however, cards where 3-D Secure is optional can continue to process transactions without authentication. If you use either of these operations in your current integration, you must exclude the Maestro card type from the available options.

Prerequisites

PayPal has an agreement with Cardinal Commerce that allows Payments Pro merchants free access to Cardinal's 3-D Secure technology, Cardinal Centinel™. The Cardinal Centinel® Thin Client interface provides access to payer authentication for transactions using Visa, MasterCard, and Maestro branded cards.

Register with Cardinal Commerce and install software

Before you can use Cardinal Centinel to obtain cardholder authentication:

  1. Register with Cardinal by filling in a simple form. After you have registered, Cardinal Commerce acknowledges your 3-D Secure registration by sending you an email and welcome pack, which includes information about next steps and links for downloading their documentation and software.
  2. Download and install the Cardinal Centinel Thin Client software. Refer to the Cardinal documentation for installation instructions.

Note: Cardinal Commerce will be available to schedule an integration meeting with you and will support you with your Cardinal Centinel Integration requirements.

Update your app debit or credit card flow

Integrating Cardinal Centinel and 3-D Secure with your PayPal transaction processing is fairly straightforward. You must make the following integration updates:

  1. Set up a web page that can handle a response from the card issuer.
  2. Insert three additional 3-D Secure requests into your application before the direct payment request.
  3. Add 3-D Secure fields to the DoDirectPayment request.

Note: Refer to the Cardinal documentation for the most recent Cardinal Centinel information. Cardinal requests, responses, and processes are provided for you in this document as a convenience but might not reflect the most current Cardinal information.

Web page to handle response from card issuer

You must establish a page on your site whose URL can receive a form POST from the card's issuer that contains two fields, PaRes and MD. The page must then request cmpi_authenticate as described in the next section. Your page's URL is referred to as TermURL.

Insert additional 3-D secure requests

Note: The steps in this section are explained in the Cardinal Thin Client Integration Guide Payer Authentication document; refer there for the most current information. This summary is provided for you as a convenience.

Transaction flow with numbered steps

To create a 3-D Secure transaction using Website Payments Pro and Cardinal Centinel, do the following before executing the direct payment request:

  1. Call Cardinal Centinel with the cmpi_lookup request, passing your merchant and transaction information. See cmpi_lookup API for the complete list of required fields.

  2. The cmpi_lookup request responds with several fields; see cmpi_lookup API for details about these fields:

    • Error information: Evaluate and take appropriate action if nonzero. Refer to the Thin Client Integration Guide for error codes, descriptions, explanations, and recommended actions.
    • Cardinal transaction information that you will pass to other requests: TransactionId, Enrolled, Payload, and EciFlag.
    • ACSUrl: If Enrolled=Y, this contains the URL for the card issuer's (bank's) authentication site.

    Evaluate Enrolled and ACSUrl:

    • If cardholder is not enrolled (Enrolled=N) or if the Authentication service is unavailable (ACSUrl is U or N), continue with Step 5 below.
    • If cardholder is enrolled, continue with the next step.
  3. Using an HTTP form POST, pass the cardholder to the URL (ACSUrl) returned by cmpi_lookup, which is the card issuer's authentication URL. Pass several fields to this request:

    • Transaction information from cmpi_lookup.
    • MD field optionally containing arbitrary merchant data; set to blank if not used.
    • TermUrl: The URL of the page you set up to handle the issuer's return call. See Issuer Authentication Request for the complete list of required fields. Cardholders attempt to authenticate themselves at the issuer's URL. The completion of the attempt returns a response to your application by using HTTP Form POST to call the URL you specified in TermUrl. The response contains the PaRes.
  4. Call cmpi_authenticate, passing PaRes as PAResPayLoad. This interprets the payload to determine whether the cardholder passed the authentication process with the card's issuer. See cmpi_authenticate API for the complete list of required fields.

  5. The cmpi_authenticate request returns several fields:

    • Error information: Evaluate and take appropriate action if nonzero. Refer to the Thin Client Integration Guide for error codes, descriptions, explanations, and recommended actions.
    • Authentication information in PAResStatus, SignatureVerification, Cavv, EciFlag, and Xid. See cmpi_authenticate response for details about the returned fields.

    Evaluate SignatureVerification:

    • If the signature is not verified, return an authentication-failed message to the cardholder and stop processing the transaction.
    • If the signature is verified, continue with the next section.

3-D Secure fields for Direct Payment transaction requests

If the cardholder is authenticated, or if not authenticated for valid reasons such as the authentication service being unavailable or the cardholder not being enrolled, execute the direct payment transaction request with the following additional fields:

NVP/SOAP Field SOAP Field Description
VERSION Version Set to 59.0. or higher.
AUTHSTATUS3DS AuthStatus3ds Set this to the returned PAResStatus value.
MPIVENDOR3DS MpiVendor3ds Set to the Enrolled value from Step 2.
CAVV Cavv Set to the returned Cavv value.
ECI3DS Eci3ds Set to the returned EciFlag value.
XID Xid Set to the returned Xid value.

Flow of field values among requests and responses. Not all fields are shown.

DoDirectPayment request examples

The following example shows the additional fields required for 3-D Secure transactions; refer to the DoDirectPayment documentation for all required fields.

NVP example
METHOD=DoDirectPayment&...&ECI3DS=5&CAVV=OTJlMzViODhiOTllMjBhYmVkMGU=&AUTHSTATUS3DS=Y&MPIVENDOR3DS=Cardinal&VERSION=59.0
SOAP example
<?xml version="1.0" encoding="UTF-8"?>
<env:Envelope xmlns:xsd="http://www.w3.org/2001/XMLSchema"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:env="http://schemas.xmlsoap.org/soap/envelope/">
<env:Header>
<RequesterCredentials env:mustUnderstand="0" xmlns:n1="urn:ebay:apis:eBLBaseComponents" xmlns="urn:ebay:api:PayPalAPI">
 <n1:Credentials>
  <Username>{Username}</Username>
  <Password>{Passsword}</Password>
  <Subject></Subject>
  <Signature>{Signature}</Signature>
 </n1:Credentials>
</RequesterCredentials></env:Header>
<env:Body>
 <DoDirectPaymentReq xmlns="urn:ebay:api:PayPalAPI">
  <DoDirectPaymentRequest xmlns:n2="urn:ebay:apis:eBLBaseComponents">
   <Version>89.0</Version>
   <DoDirectPaymentRequestDetails>
     <PaymentAction>Authorization</PaymentAction>
      <PaymentDetails>
        <OrderTotal currencyID="GBP">44.00</OrderTotal>
        <NotifyURL></NotifyURL>
        <OrderDescription></OrderDescription>
        <InvoiceID></InvoiceID>
        <ButtonSource>ActiveMerchant</ButtonSource>
      </PaymentDetails>
      <CreditCard>
        <CreditCardType>Switch</CreditCardType>
        <CreditCardNumber>** REMOVED **</CreditCardNumber>
        <ExpMonth>03</ExpMonth>
        <ExpYear>2011</ExpYear>
        <CVV2>598</CVV2>
        <StartMonth>02</StartMonth>
        <StartYear>2009</StartYear>
        <ThreeDSecureRequest>
          <MpiVendor3ds>Y</MpiVendor3ds>
          <AuthStatus3ds>Y</AuthStatus3ds>
          <Cavv>jMKEKlqlJGiJARAbxMDZ5+fnFeg=</Cavv>
          <Eci3ds>02</Eci3ds>
          <Xid>TTVmdlFxbERYVXo5R1hrVUY5bjY=</Xid>
        </ThreeDSecureRequest>
        <CardOwner>
          <PayerName>
            <FirstName>Miss Kate L Jones</FirstName>
            <LastName></LastName>
          </PayerName>
          <Payer>michael@iamhuman.co.uk</Payer>
          <Address>
            <Name></Name>
            <Street1>21 Wishbone Road</Street1>
            <Street2></Street2>
            <CityName>Hove</CityName>
            <StateOrProvince>East Sussex</StateOrProvince>
            <Country>GB</Country>
            <PostalCode>BN3 4LL</PostalCode>
            <Phone></Phone>
          </Address>
        </CardOwner>
      </CreditCard>
      <IPAddress>93.39.132.123</IPAddress>
    </DoDirectPaymentRequestDetails>
  </DoDirectPaymentRequest>
</DoDirectPaymentReq>
</env:Body>
</env:Envelope>

Set up your website

Cardinal and/or 3-D Secure require that you add specific elements to your web pages. These include:

  • Integrate the authentication window to allow for consistent site branding during the authentication process.
  • Display the Verified by Visa and MasterCard SecureCode "Learn More" logos on your home and check-out pages.
  • Provide text and logo on the check-out page in which you collect payment information. Notify the cardholder that they may be required to provide their authentication password.
  • Notify the cardholder of authentication results.

Refer to the Cardinal Thin Client Integration Guide for details.

Test your integration

For 3-D Secure, you cannot use PayPal's sandbox for testing. You must use Cardinal's test procedures. Refer to the Cardinal documentation for information.

The following examples outline the transaction process for three basic situations.

Example 1: Successful 3-D Secure authentication

In this example, the cardholder's issuer uses 3-D Secure and the authentication is successful:

  1. Construct your message for cmpi_lookup.
  2. Review the response from cmpi_lookup. Ensure that all of the following are true:
    • ErrorNo=0
    • Enrolled=Y
    • ACSUrl has content; for example: https://www.somewebsite.com/acs
  3. Using HTTP Form POST, redirect the cardholder to the issuer's URL that was provided in ACSUrl. Ensure that the PaReq has the data from the field PayLoad, from the cmpi_lookup response.
  4. Send the response (redirect) from the issuer's HTTP Form POST to Cardinal using the cmpi_authenticate message to determine how to proceed with the transaction.
  5. The cmpi_authenticate response will specify how to proceed. To continue with authorization, the following must be true:
    • SignatureVerification=Y
    • PAResStatus=Y, U, or A
  6. Authorize as you would normally, with the additional fields described in 3-D Secure Fields for Direct Payment Transaction Requests.

Example 2: 3-D Secure with unsuccessful authentication

In this example, the cardholder's issuer uses 3-D Secure and the authentication is not successful:

  1. Construct your message for cmpi_lookup.
  2. Review the response from cmpi_lookup. Ensure that all of the following are true:
    • ErrorNo=0
    • Enrolled=Y
    • ACSUrl has content; for example: https://www.somewebsite.com/acs
  3. Using HTTP Form POST, redirect the cardholder to the issuer's URL that was provided in ACSUrl. Ensure that the PaReq has the data from the field PayLoad, from the cmpi_lookup response.
  4. Send the response (redirect) from the issuer's HTTP Form POST to Cardinal using the cmpi_authenticate message to determine how to proceed with the transaction.
  5. The cmpi_authenticate response determines how to proceed. In this example, when authentication fails, the following are true:
    • SignatureVerification=Y
    • PAResStatus=N
  6. Notify the cardholder that the transaction is declined.

Example 3: Card issuer not using 3-D Secure

In this example, the card's issuer does not use 3-D Secure:

  1. Construct message for cmpi_lookup.
  2. Review the response from cmpi_lookup. Ensure that:
    • ErrorNo=0
    • Enrolled=N or U
  3. Authorize as you would normally, with the additional fields described in 3-D Secure Fields for Direct Payment Transaction Requests.

Example 4: Merchant not using 3-D Secure

In this example, the merchant does not authenticate a Maestro transaction using 3-D Secure before executing a direct-payment transaction request:

  • Through 31 December, 2009, a DoDirectPayment request returns ACK=SuccessWithWarning with error code 12001; PayPal still accepts the transaction.
  • Beginning on 1 January, 2010, a DoDirectPayment request will return ACK=Failure with error code 12000 and PayPal will not accept the transaction.

3-D Secure Reference

See the Cardinal documentation for up-to-date and complete reference information.

cmpi_lookup API

The cmpi_lookup request is a Cardinal Centinel request. This section lists required fields and responses as a convenience for you. Refer to the Cardinal Thin Client Integration Guide Payer Authentication document for details and the most current information.

cmpi_lookup Request

cmpi_lookup Request Fields
Field Description
MsgType (Required) Must be cmpi_lookup.
Version (Required) Must be 1.7.
ProcessorId (Required) Your processor identification code, assigned by Cardinal when you register.
MerchantId (Required) Your merchant identification code as assigned by Cardinal.
TransactionPwd (Required) Your Cardinal password as you configured it at the Cardinal site.
TransactionType (Required) Must be C.
Amount (Required) The value of the transaction in cents or pence with no decimal point. For example, £100 is specified as 10000.
CurrencyCode (Required) The [3-digit numeric ISO 4217 currency code](https://en.wikipedia.org/wiki/ISO_4217#Active_codes) for the sale amount. For example, GBP is 826 and EUR is 978.
CardNumber (Required) The debit or credit card number, up to 19 digits, numeric characters only.
CardExpMonth (Required) The card's expiration month, formatted as MM.
CardExpYear (Required) The card's expiration year, formatted as YYYY.
OrderNumber (Required) Your order number or transaction identifier. Limited to 50 characters.
various additional fields (Optional) Cardinal allows several additional optional fields, which you can choose to use. Refer to the Cardinal documentation for details.

cmpi_lookup Response

cmpi_lookup Response Fields
Field Description
ErrorNo Error number. 0 indicates no error.
ErrDesc Empty if there is no error, otherwise, describes the error.
TransactionId Centinel transaction identifier. Identifies the transaction within Centinel.
Enrolled Status of authentication eligibility. If not Y, then the cardholder is not eligible for authentication. Value is:
  • Y — Enrolled
  • N — Not enrolled
  • U — Cardholder authentication unavailable.
ACSUrl If Enrolled=Y, this contains the URL to which your application must next send the cardholder to complete authentication.
Payload If Enrolled=Y, this contains the encoded transaction details; otherwise, this field is empty.
EciFlag The Electronic Commerce Indicator (ECI). MasterCard:
  • 01 — Merchant Liability
  • 02 — Issuer Liability
Visa:
  • 05 — Issuer Liability
  • 06 — Issuer Liability
  • 07 — Merchant Liability

Issuer Authentication Fields

The call to the card issuer's site is explained in the Cardinal Thin Client Integration Guide Payer Authentication document. This section lists required fields and responses as a convenience.

Issuer Authentication Request

Specify the following fields when you call the card issuer's URL that you received from cmpi_lookup in ACSUrl.

Issuer Authentication Request Fields
Field Description
PaReq (Required) Content of the Payload field from cmpi_lookup.
TermUrl (Required) Your URL for handling and processing the response from the ACSUrl.
MD (Required) Merchant's session tracker. Set to blank if not used.

Issuer Authentication Response

When the issuer has completed its authentication processing, it calls the URL that you provided to it in TermURL. The issuer returns the following fields.

Issuer Authentication Response Fields
Field Description
PaRes Authentication information to pass to cmpi_authenticate.
MD Copy of MD sent by merchant.

cmpi_authenticate API

The cmpi_authenticate request is a Cardinal Centinel request. This section lists required fields as a convenience for you. Refer to the Cardinal Thin Client Integration Guide Payer Authentication document for details and the most current information.

cmpi_authenticate Request

cmpi_authenticate Request Fields
Field Description
MsgType (Required) Must be cmpi_authenticate.
Version (Required) Must be 1.7.
ProcessorId (Required) Your Processor identification code as assigned by Cardinal.
MerchantId (Required) Your merchant identification code as assigned by Cardinal.
TransactionPwd (Required) Your Cardinal password as you configured it at the Cardinal site.
TransactionType (Required) Must be C.
TransactionId (Required) The transaction identifier returned from cmpi_lookup.
PAResPayload (Required) PaRes provided in the package returned after the call to the card's issuer.

cmpi_authenticate Response

cmpi_authenticate Response Fields
Field Description
ErrorNo Error number. For example, 0 indicates no error; 1140 indicates that the cardholder pressed the back button on the browser.
ErrDesc Empty if there is no error, otherwise, describes the error.
PAResStatus The outcome of the issuer's authentication. Value is:
  • Y — Successful; merchant is protected.
  • N — Failed; no protection.
  • U — Unable to complete; no protection.
  • A — Successful; merchant is protected.
Cavv A random sequence of characters; this is the encoded authentication.
SignatureVerification Status of authentication eligibility. If not Y, then the cardholder is not eligible for authentication. Value is:
  • Y — Good
  • N — Failed
EciFlag The Electronic Commerce Indicator (ECI).
MasterCard:
  • 01 — Merchant Liability
  • 02 — Issuer Liability
Visa:
  • 05 — Issuer Liability
  • 06 — Issuer Liability
  • 07 — Merchant Liability
Xid Transaction identifier from authentication.