Overview

Verifying credit card data can help stop fraudulent transactions and prevent rate downgrades from your authorizer. You can verify a card at any time before performing a transaction, such as when setting up a recurring or scheduled future payment or when creating a token. In the past, card-not-present merchants had to verify cards by sending $1.00 "ghost authorizations," which captured funds while the transaction remained in a pending state before eventually expiring. For merchants, these "ghost authorizations" created support problems, and for issuers, they negatively impacted cardholder spending. Hence, Visa and MasterCard began allowing zero-dollar transactions so that merchants could perform Address and CVV verifications.

Forte’s card verification service ensures that a card is linked to an open, valid account by matching up the following data on file with the customer’s issuing bank:

• Primary Account Number (PAN)
• CVV/CVV2
• Expiration Month and Year
• Cardholder’s Street Address and Zip Code

You can verify credit cards using Forte’s REST API or the Advanced Gateway Interface. NOTE: Only merchants who have Vantiv as their credit card authorizer can pass non-swiped, zero-dollar verify transactions. The process for other credit card authorizers will vary. Contact Forte Technical Support at 888-235-4635 option 3 for information on your authorizer.

The Verification Process

Forte reports and bills/commissions verify transactions normally and provides a postback to merchants indicating Address Verification Services (AVS) and Card Verification Value (CVV) results. No funds are captured and the transactions never go through settlement. Credit card verifications have no impact on SplitFund merchants.

The following diagram provides a high-level overview of this process:

Verifying Card Data in REST 

Credit cards can be verified by passing transaction parameters or passing swipe data in a POST request to the transactions URI. 

Crafting Requests

To create a verify transaction via parameters, use the following values in your request:

• authorization_amount=0
• action=sale or action=verify
• billing_address.first_name
• billing_address.last_name
• billing_address.physical_address.street_line1
• billing_address.physical_address.locality
• billing_address.physical_address.region
• billing_address.physical_address.postal_code
• card.card_type
• card.account_number
• card.expire_month
• card.expire_year
• card.card_verification_value

To create a verify transaction via swipe data, use the following values in your request. NOTE: Swiped transactions require an authorization_amount greater than zero. For verification purposes, Forte recommends the 0.01 value.

• authorization_amount=0.01
• action=sale or action=verify
• billing_address.first_name
• billing_address.last_name
• billing_address.physical_address.street_line1
• billing_address.physical_address.locality
• billing_address.physical_address.region
• billing_address.physical_address.postal_code
• card.card_reader
• card.card_data

NOTE: The verify action for a credit card transaction works differently than an ACH verify. ACH verify requests provide money amount verification (e.g., authorization_amount=10) with the transaction; whereas, in non-swiped credit card verify requests, the authorization_amount must be zero and in swiped credit card verify requests, the authorization_amount value must be 0.01. The transaction behaves the same as a zero-dollar sale transaction.  

Example - Verify Credit Card Data in REST with Parameters

Request

curl -X POST
    -H "Content-Type: application/json"
    -H "X-Forte-Auth-Organization-Id: org_300005" 
    -H "Authorization: Basic {encoded APIAccess<span class="fr-marker" data-id="0" data-type="false" style="display: none; line-height: 0;"></span><span class="fr-marker" data-id="0" data-type="true" style="display: none; line-height: 0;"></span>ID:APISecureKey string}"
    -H "Accept: application/json"
    -H "Cache-Control: no-cache" -d '{
       "action":"verify",
       "authorization_amount":0,
       "sales_tax_amount":0,
       "billing_address":{
          "first_name": "Emmett",
          "last_name": "Brown",
          "physical_address":{
             "street_line1":"2324 DeLorean Avenue",
             "locality":"Hill Valley",
             "region":"CA",
             "postal_code":"95420"
          }
       }, 
       "card":{
          "card_type": "visa",
          "account_number": "4003030000000006",
          "expire_month": 12,
          "expire_year": 2020,
          "card_verification_value": "123"
       }
} ' "/organizations/org_300005/locations/loc_115161/customers/?filter=last_name eq McFly"

Response

{                      
   "transaction_id": "trn_f1abb22c-be6f-489a-be21-ee35adc1680a",
   "location_id": "loc_115161",
   "action": "verify",
   "billing_address": {
      "first_name": "Emmett",
      "last_name": "Brown",
      "physical_address": {
         "street_line1": "2324 DeLorean Avenue",
         "locality": "Hill Valley",
         "region": "CA",
         "postal_code": "95420"
      },
   "card": {
      "last_4_account_number": "0006",
      "masked_account_number":"****0006",
      "expire_month": 12,
      "expire_year": 2020,
      "card_type": "visa"
   },
   "response": {
     "environment": "sandbox",
     "response_type": "A",
     "response_code": "A01",
     "response_desc": "TEST APPROVAL",
     "authorization_code":"123456",
     "avs_result":"Y",
     "cvv_result":"M"
   } 
}

Example - Verify Credit Card Data in REST with Swipe Data

Request

curl -X GET
    -H "Content-Type: application/json"
    -H "X-Forte-Auth-Organization-Id: org_300005"
    -H "Authorization: Basic {encoded APIAccessID:APISecureKey string}"
    -H "Accept: application/json"
    -H "Cache-Control: no-cache" -d '{
       "action":"verify",
       "authorization_amount":0.01,
       "billing_address": {
          "first_name":"Emmett",
          "last_name":"Brown",
          "physical_address": {
             "street_line1":"2123 Einstein Way",
             "street_line2":"Suite 200",
             "locality":"Hill Valley",
             "region":"CA",
             "postal_code":"90217"
          }
       },
       "card":{
          "card_reader": "30050202",
          "card_data":"0~IPAD100KB|24~98CE04601007130D|1~11|2~87687687687876876876|4~|5~516F2DCD1EB18A99E775E36457E3454AA4C1448635D9067F3151A112D49A6F02F9CAC15F2B608D2E915EBA99846E81AC763AE89D29437B31|6~%B4445220002000007^TESTCARD/TEST^17120000011111000?|7~;4445220002000007=17120000000000000000?|8~|9~00000000|10~000001|11~9500020000C8892001C7|12~00002200|"
       }
} ' "/organizations/org_300005/locations/loc_115161/customers/cst__hbpJNFPhUK8MGmTynKuAQ"

Response

{
    "transaction_id": "trn_594c5e56-cd05-4daf-ba44-2a5d5d034275",
    "location_id": "loc_192642",
    "action": "verify",
    "entered_by": "4fefaf5f77d944ce10bdd3d88f7a2da9",
    "billing_address": {
       "first_name": "Emmett",
       "last_name": "Brown",
       "physical_address": {
     "street_line1": "2123 Einstein Way",
     "street_line2": "Suite 200",
     "locality": "Hill Valley",
     "region": "CA",
     "postal_code": "90217"
  }
    },
    "response": {
       "environment": "sandbox",
  "response_type": "A",
  "response_code": "A01",
  "response_desc": "TEST APPROVAL",
  "avs_result": "Y",
  "cvv_result": "M"
    }
}

Understanding Responses

Forte verifies the data with the issuing bank and sends one of the following responses back in the cvv_result field of the response object. NOTE: CVV testing in the sandbox environment can only simulate the M (i.e., Match) or N (i.e., No Match) responses. 

• M = Match
• N = No Match
• E = Error (Unrecognized or Unknown Response)
• I = Invalid or Null
• P = Not Processed
• S = Service Not Supported
• U = Issuer Unable to Process
• X = No Response

Forte also verifies if the address data provided by the customer with the issuing bank and sends one of the following responses back in the avs_result field of the response object. NOTE: AVS testing in the sandbox environment can only simulate the Y (i.e., Match: Street Address and 5-digit ZIP Code both match) or N (i.e., No Match: Street Address, 5-digit ZIP Code, and 9-digit ZIP Code all do not match) responses.

• X = Match: Street Address and 9-digit ZIP Code both match
• Y = Match: Street Address and 5-digit ZIP Code both match
• A = Partial Match: Street Address matches, but both 5-digit and 9-digit ZIP Codes do not match
• W = Partial Match: Street Address does not match, but 9-digit ZIP Code matches
• Z = Partial Match: Street Address does not match, but 5-digit ZIP Code matches
• N = No Match: Street Address, 5-digit ZIP Code, and 9-digit ZIP Code all do not match
• U = System Unavailable: Address information unavailable. Forte returns this response if the Street Address is a non-US address, if the AVS service is unavailable, or if the AVS service for a particular US bank is not properly functioning.
• R = System Unavailable: Forte will retry the AVS check because the issuer's system is unavailable or the request times out.
• E = Invalid: AVS data is invalid
• S = Not Supported: The US issuing bank does not support AVS checks

Using Parameters to Test AVS in REST

Sandbox enables you to perform limited AVS and CVV testing using passed parameters. For the avs_result parameter, sandbox testing can only simulate the Y (i.e., Match: Street Address and 5-digit ZIP Code both match) or N (i.e., No Match: Street Address, 5-digit ZIP Code, and 9-digit ZIP Code all do not match) response values. For the cvv_result parameter, sandbox testing can only simulate the M (i.e., Match) or N (i.e., No Match) responses. Use the data values in the following chart when testing.

Account Number	Authorization Amount	Sales Tax Amount	AVS Result	CVV Result
4111111111111111	0	0	N	N
4111111111112101	0	0	N	N
4111111111111111	1	1	Y	M
4111111111112101	1	1	Y	M
4012888888881881	1	1	Y	M
4012888888881881	0	0	N	N
4003030000000006	1	1	Y	M
4003030000000006	0	0	Y	M

Verifying Card Data in AGI

Understanding AVS Checks

AGI enables merchants to specify what type of data they want to include in their AVS verification checks. Merchants can choose to verify the following data:

• Credit Card Account and ZIP Code
• Credit Card Account and Street Number
• State and ZIP Code
• State and Area Code
• Anonymous Email

These checks are captured in the pg_avs_method parameter via a 5-digit code that indicates what to verify and what action Forte should take upon verification. The pg_avs_result parameter also relies on this 5-digit code to indicate the result of the verification check. When creating your customized verification check, use the following model:

X₁X₂X₃X₄X₅

Where, 

Value	Type of Verification Check
X1	Credit Card Account and ZIP Code
X2	Credit Card Account and Street Number
X3	State and ZIP Code
X4	State and Area Code
X5	Anonymous Email

To define the value of the pg_avs_method parameter, use the following digits to determine what types of AVS checks you want Forte to perform:

Digit	Description
0	Do not perform check
1	Check only; do not decline on fail
2	Check and decline on fail

For example, let's assume you want to ensure your customer's credit card account number matches the ZIP code and street number on file with the issuer. If these values do not match, you want Forte to automatically decline the transaction. For this scenario, you will need a 2 in the X₁ and X₂ places of your pg_avs_method code and a 0 in the remaining places (X₃ - X₅). Hence, the request parameter and value for this transaction will be pg_avs_method=22000.

Similarly, you will use the following digits to decode the value of the pg_avs_result parameter to determine the result of the submitted verification check(s):

Digit	Description
0	Check not performed
3	Passed
4	Failed

Using the example above, on the X₁ and X₂ places will contain digits. Unless both of these digits are 3 (i.e., the data matched and the verification check passed), this transaction will automatically decline.

Understanding CVV/CVV2 Checks

AGI performs CVV/CVV2 checks for all credit card transactions and uses the same response codes as Forte's REST API to indicate the result of a CVV verification. Forte verifies the CVV data with the issuing bank and sends one of the following responses back in either the pg_cvv2_result or pg_cvv_code parameter in the response message template.

• M = Match
• N = No Match
• E = Error (Unrecognized or Unknown Response)
• I = Invalid or Null
• P = Not Processed
• S = Service Not Supported
• U = Issuer Unable to Process
• X = No Response

Crafting the Request Message Template

Like REST, you can verify credit cards with AGI via parameters or encrypted swipe data using a transaction request. To verify credit card data in AGI via parameters, include the following data in your request message template:

• pg_total_amount=0
• pg_transaction_type=10
• ecom_billto_postal_first_name
• ecom_billto_postal_last_name
• ecom_billto_postal_street_line1
• ecom_billto_postal_stateprov
• ecom_billto_postal_postalcode
• ecom_billto_postal_phone_number
• ecom_billto_online_email
• ecom_payment_card_type
• ecom_payment_card_number
• ecom_payment_card_expdate_month
• ecom_payment_card_expdate_year
• ecom_payment_card_verification
• pg_avs_method

To verify credit card data in AGI via swipe data, include the following data in your request message template:

• pg_total_amount=0.01
• pg_transaction_type=11
• ecom_billto_postal_first_name
• ecom_billto_postal_last_name
• ecom_billto_postal_street_line1
• ecom_billto_postal_stateprov
• ecom_billto_postal_postalcode
• ecom_billto_postal_phone_number
• ecom_billto_online_email
• pg_cc_enc_swipe_data
• pg_cc_enc_decryptor
• pg_avs_method

The following request message templates indicates the merchant wants to verify the credit card and if the AVS check fails, automatically decline the transaction. The responses indicate that the card passed verification. Note that pg_avs_result=33000 indicates that the ZIP code and Street Address on file for the customer matched his or her credit card account number and the pg_cvv_code=M indicates that the provided card verification value matches the provided credit card account number.

Example - Verify Credit Card Data in AGI with Parameters

Request

   pg_merchant_id=<Merchant ID>
   pg_password=<Merchant Password>
   pg_transaction_type=10
   pg_total_amount=0.00
   ecom_billto_postal_name_first=Emmett
   ecom_billto_postal_name_last=Brown
   ecom_billto_postal_street_line_1=2123 Einstein Way
   ecom_billto_postal_city=Hill Valley
   ecom_billto_postal_stateprov=CA
   ecom_billto_postal_postalcode=90217
   ecom_payment_card_name=Emmett H Brown
   ecom_payment_card_type=Visa
   ecom_payment_card_number=<Credit Card Account Number>
   ecom_payment_card_expdate_month=<Credit Card Expiration Month>
   ecom_payment_card_expdate_year=<Credit Card Expiration Year>
   pg_avs_method=22000
   endofdata

Response

   pg_response_type=A
   pg_response_code=A01
   pg_response_description=APPROVED
   pg_merchant_id=<Merchant ID>
   pg_authorization_code=420023
   pg_trace_number=f0b77189-4014-11d6-a7fd-0050da8def0f
   pg_avs_result=33000
   pg_transaction_type=10
   pg_total_amount=0.00
   ecom_billto_postal_name_first=Emmett
   ecom_billto_postal_name_last=Brown
   ecom_billto_postal_street_line_1=2123 Einstein Way
   ecom_billto_postal_city=Hill Valley
   ecom_billto_postal_stateprov=CA
   ecom_billto_postal_postalcode=90217
   ecom_payment_card_name=Emmett H Brown
   ecom_payment_card_type=Visa
   ecom_payment_card_number=<Masked Credit Card Account Number>
   ecom_payment_card_expdate_month=<Credit Card Expiration Month>
   ecom_payment_card_expdate_year=<Credit Card Expiration Year>
   pg_cvv_code=M
   pg_preauth_code=none
   pg_preauth_result=POS
   pg_preauth_description=P70: VALIDATED
   endofdata

Example - Verify Credit Card Data in AGI with Swipe Data

Request

   pg_merchant_id=<Merchant ID>
   pg_password=<Merchant Password>
   pg_transaction_type=11
   pg_total_amount=0.01
   ecom_billto_postal_name_first=Emmett
   ecom_billto_postal_name_last=Brown
   ecom_billto_postal_street_line_1=2123 Einstein Way
   ecom_billto_postal_city=Hill Valley
   ecom_billto_postal_stateprov=CA
   ecom_billto_postal_postalcode=90217
   pg_cc_enc_swipe_data=0~IPAD100KB|24~98CE04601007130D|1~11|2~87687687687876876876|4~|5~516F2DCD1EB18A99E775E36457E3454AA4C1448635D9067F3151A112D49A6F02F9CAC15F2B608D2E915EBA99846E81AC763AE89D29437B31|6~%B4445220002000007^TESTCARD/TEST^17120000011111000?|7~;4445220002000007=17120000000000000000?|8~|9~00000000|10~000001|11~9500020000C8892001C7|12~00002200|
   pg_cc_enc_decryptor=30050203
   pg_avs_method=22000
   endofdata

Response

   pg_response_type=A
   pg_response_code=A01
   pg_response_description=APPROVED
   pg_merchant_id=<Merchant ID>
   pg_authorization_code=420023
   pg_trace_number=f0b77189-4014-11d6-a7fd-0050da8def0f
   pg_avs_result=33000
   pg_transaction_type=11
   pg_total_amount=0.01
   ecom_billto_postal_name_first=Emmett
   ecom_billto_postal_name_last=Brown
   ecom_billto_postal_street_line_1=2123 Einstein Way
   ecom_billto_postal_city=Hill Valley
   ecom_billto_postal_stateprov=CA
   ecom_billto_postal_postalcode=90217
   pg_preauth_code=none
   pg_preauth_result=POS
   pg_preauth_description=P70: VALIDATED
   endofdata