Address verification

The Address Verification Service (AVS) compares the billing address and cardholder name of a card payment with what the card issuer has on file. AVS doesn't block a payment: it gives you a result, and you decide whether to keep the payment.

When AVS appliesCopy Anchor Link

AVS runs when all of these apply:

• The payment is a card payment.
• Your business is based in the United Kingdom, the United States or Canada.
• The payment is domestic: your customer is in the same country as your business.
• The order has a billing address.

Request AVSCopy Anchor Link

Set request_avs to true in the payment_method_details of a credit-card transaction, and send the billing address in the customer object:

curl https://api.prod.smartpay.gingerpayments.com/v1/orders/ \
  --user "$API_KEY:" \
  --header "Content-Type: application/json" \
  --data '{
    "currency": "GBP",
    "amount": 995,
    "merchant_order_id": "EXAMPLE001",
    "description": "Example card order",
    "return_url": "https://www.example.com/order/EXAMPLE001",
    "transactions": [
      {
        "payment_method": "credit-card",
        "payment_method_details": {
          "request_avs": true
        }
      }
    ],
    "customer": {
      "first_name": "John",
      "last_name": "Smith",
      "address_type": "billing",
      "address": "10 Downing Street",
      "postal_code": "SW1A 2AA",
      "city": "London",
      "country": "GB"
    }
  }'

From here, the payment continues like any other card payment, with the hosted payment page or in your own checkout.

When AVS is on by default for your account, set request_avs to false to skip it for a payment.

Billing addressCopy Anchor Link

Send at least address, postal_code, city and country, with address_type set to billing. Instead of address, you can send street and housenumber. When you request AVS without a complete billing address, the transaction gets the status error.

Cardholder nameCopy Anchor Link

AVS also checks the cardholder name. On the hosted payment page, your customer enters it. In your own checkout, send it as name when you store the card in the vault. Apple Pay and Google Pay payments don't have a cardholder name.

Check the resultCopy Anchor Link

When the payment has been processed, retrieve the order. The result is in the payment_method_details of the transaction. The response is shortened:

{
  "transactions": [
    {
      "payment_method": "credit-card",
      "payment_method_details": {
        "avs_applicable": true,
        "avs_result": "match",
        "cardholder_name": "John Smith",
        "request_avs": true
      },
      "status": "accepted"
    }
  ]
}

The result doesn't change the status of the payment. If you don't want to keep the payment, refund it, or void it if you pre-authorized it.

AVS didn't runCopy Anchor Link

When avs_applicable is false, AVS didn't run for this payment. The avs_usage_determined event of the transaction tells why, in avs_supported:

See Get an order in the API reference for all fields.