PreCheck Guide

What PreCheck Does

The PreCheck service performs early validation of card details before a payment authorization is attempted. It helps determine the likelihood that a charge against a card would succeed and provides verification signals that can assist with fraud and risk evaluation.

PreCheck is most commonly used prior to submitting a transaction to a payment gateway, allowing merchants to filter out invalid or undesirable transactions and avoid unnecessary gateway authorization fees.

The service evaluates card information and returns:

• An overall advisory decision

• Address Verification Service (AVS) results

• CVV verification results

These signals can be used independently or combined with additional fraud-detection systems.

Required vs Optional Fields

A minimal PreCheck request requires only the core card information.

Required fields

• cardNumber

• cardExpiryDate

Optional fields

• cardCvv2Value

• cardAddress

  • postalCode

  • street

• clientReferenceId

If the cardAddress object is provided, it must include at least postalCode. Postal code alone is sufficient for AVS processing.

Providing additional data such as CVV and address information improves the quality of verification signals returned by the service.

Address Verification (AVS)

When address information is included in the request, PreCheck returns an AVS verification result indicating how well the supplied address information matches the card issuer’s records.

Possible AVS result values include:

• FULL_MATCH

• STREET_MATCH

• POSTCODE_MATCH

• NO_MATCH

• UNVERIFIABLE

• RETRY

• NOT_PROVIDED

• UNKNOWN

AVS results should be evaluated by the merchant as part of their own risk decisioning process.

CVV Handling

If the request includes

cardCvv2Value

, PreCheck attempts to verify the value against the issuer.

Possible CVV result values include:

• MATCH

• NO_MATCH

• NOT_PROCESSED

• NOT_PROVIDED

• UNVERIFIABLE

• UNKNOWN

If the CVV value is not included in the request, the result will return NOT_PROVIDED.

Merchants should incorporate the CVV result into their own fraud and risk policies.

Understanding the advice Field

The advice field represents the system’s overall assessment of the likelihood that a charge against the card would succeed.

Typical responses include:

The advice value represents a prediction of authorization success, but it does not incorporate AVS or CVV results. These values should be evaluated separately when making a final risk decision.

Retry Behavior

If a response returns RETRY or TEMP_ERROR, the request may be attempted again.

When retrying requests, it is recommended to use an exponential backoff strategy to prevent excessive retry traffic.

Example Request

{
  "clientReferenceId": "order-12345",
  "cardNumber": "4111111111111111",
  "cardExpiryDate": "2040-10",
  "cardCvv2Value": "123",
  "cardAddress": {
    "postalCode": "94404",
    "street": "801 Metro Center Blvd"
  }
}

Example Response

{
  "isSuccess": true,
  "preCheckResponse": {
    "avsResult": "POSTCODE_MATCH",
    "cvv2Result": "MATCH",
    "advice": "ACCEPT"
  },
  "billing": {
    "items": [
      {
        "feeType": "PRECHECK",
        "fee": {
          "currency": "USD",
          "amount": 0.0400
        },
        "completed": true
      }
    ],
    "remainingBalance": {
      "currency": "USD",
      "amount": 99.9200
    },
    "amountAuthorized": {
      "currency": "USD",
      "amount": 0.0400
    },
    "amountClosed": {
      "currency": "USD",
      "amount": 0.0400
    }
  },
  "errors": null
}

Common Response Scenarios

Card likely valid

advice: ACCEPT
avsResult: FULL_MATCH
cvv2Result: MATCH

This combination indicates a high likelihood of successful authorization.

Address mismatch

advice: ACCEPT
avsResult: NO_MATCH
cvv2Result: MATCH

The card may still authorize successfully, but the address mismatch may indicate increased risk.

Invalid or unusable card

advice: BAD_CARD

Card information appears invalid and should generally not be submitted to a payment gateway.

Temporary processing issue

advice: RETRY

The request should be retried using exponential backoff.

Example Use Cases

Pre-authorization card screening

Run PreCheck before submitting a transaction to a payment gateway. Transactions predicted to decline can be rejected early, saving gateway fees.

Fraud signal enrichment

Combine PreCheck results with other risk signals such as device fingerprinting or rules-based fraud detection to strengthen checkout decisioning.

Checkout optimization

Filter out invalid cards early in the checkout flow, improving payment success rates and reducing unnecessary authorization attempts.