AVS and IDV

Run an address verification or identity verification check.

Run an AVS check

Use the following request to initiate a card authorisation with an address verification (AVS) check.

{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "merchantTransactionGroupId": "This_is_my_merchant_transaction_group_id",
  "merchantTransactionDate": "2024-01-27T08:51:02.826445+00:00",
  "transactionMethod": {
    "intent": "Authorisation",
    "entryType": "Ecom",
    "fundingType": "Card"
  },
  "fundingData": {
    "card": {
      "primaryAccountNumber": "4111111111111111",
      "expiryMonth": "03",
      "expiryYear": "2027",
      "holderName": "Mr John Doe"
    }
  },
  "amounts": {
    "transaction": 30.32,
    "currencyCode": "EUR"
  },
  "addressVerification": {
    "houseNumberOrName": "en",
    "postalCode": "",
    "countryCode": "GB"
  },
  "shopper": {
    "id": "Shopper_01",
    "firstName": "John",
    "lastName": "Doe",
    "dateOfBirth": "1980-03-01",
    "email": "shopper@example.com"
  }
}

Parameter	Description
`addressVerification` object	Details about the address verification details.
`addressVerification.houseNumberOrName` string (≤ 100 characters) required	The house number or name associated with the cardholder's address.
`addressVerification.postalCode` string (≤ 10 characters) required	The postal or ZIP code of the cardholder's address. This field accepts up to 5 digits for US addresses or up to 10 characters for addresses in other countries, accommodating global variations in postal code formats.	`addressVerification.countryCode` string (2 characters) required	The country code identifying the country associated with the cardholder's address, in ISO-3166-1 alpha-2 format.

If your request is successful, you'll receive a 200 response and a Transaction (Card Authorised) webhook notification.

The response includes the transaction's updated state, as well as two addressVerificationServiceResult fields indicating the result of the ADV check. The first one comes from the PXP Unity Gateway and describes the outcome of the check in a human-readable format, while the second one is the raw data received from the provider.

If the check failed, you can look at the merchantAdvice.message for advice on your next steps.

{
  "state": "Authorised",
  "stateData": {
    "code": "CRD000",
    "message": "Approved"
  },
  "approvalCode": "123456",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "systemTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "merchantTransactionDate": "2024-01-27T08:51:02.826Z",
  "providerTransactionId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
  "fundingData": {
    "cardScheme": "Visa",
    "primaryAccountNumber": "************1111",
    "expiryMonth": "12",
    "expiryYear": "2026",
    "gatewayTokenId": "1ed768bb-e88a-4636-91ae-67927ccbb02b",
    "schemeTokenNumber": "4837261112345678",
    "addressVerificationServiceResult": "NoInformationAvailable",
    "cardVerificationCodeResult": "NoInformationAvailable",
    "providerResponse": {
      "provider": "PXPFinancial",
      "code": "00",
      "message": "Approved",
      "merchantId": "77772182",
      "terminalId": "75836665",
      "cardVerificationCodeResult": "A",
      "addressVerificationServiceResult": "D",
      "schemeTransactionId": "TX1234567890123456",
      "schemeTransactionLinkId": "TX1234567890123456",
      "paymentAccountReference": "V001ABCDEFGHIJKLMNOPQRSTUVWXY",
      "retrievalReferenceNumber": "613808317649",
      "electronicCommerceIndicatorAdjustment": "01",
      "settlementDate": "2024-01-25T00:00:00.000Z"
    }
  }
}

Possible AVS check results

The following tables describe the possible AVS check results and their corresponding AVS response codes, depending on the acquirer.

AVS check result	AVS response code
`NoInformationAvailable`	`X`
`PostCodeMatchedAddressMatched`	`F`
`PostCodeMatchedAddressNotMatched`	`P`
`PostCodeNotMatchedAddressMatched`	`B`
`PostCodeNotMatchedAddressNotMatched`	`N`
`PostCodeNotCheckedAddressNotChecked`	`U`

Run an IDV check

Use the following request to run an identity verification (IDV) check. The example sets transactionMethod.intent to Verification and includes identityVerification.

{
  "merchant": "MERCHANT-1",
  "site": "SITE-1",
  "merchantTransactionId": "This_is_my_merchant_transaction_id",
  "merchantTransactionGroupId": "This_is_my_merchant_transaction_group_id",
  "merchantTransactionDate": "2024-01-27T08:51:02.826445+00:00",
  "transactionMethod": {
    "intent": "Verification",
    "entryType": "Ecom",
    "fundingType": "Card"
  },
  "fundingData": {
    "card": {
      "primaryAccountNumber": "4111111111111111",
      "expiryMonth": "03",
      "expiryYear": "2027",
      "holderName": "Mr John Doe",
      "cardVerificationCode": "123"
    }
  },
  "amounts": {
    "transaction": 0,
    "currencyCode": "EUR"
  },
  "identityVerification": {
    "nameVerification": true
  },
  "shopper": {
    "id": "Shopper_01",
    "firstName": "John",
    "lastName": "Doe",
    "email": "shopper@example.com"
  }
}

Parameter	Description
`identityVerification` object	Details about the identity verification.
`nameVerification` boolean Defaults to `false`	A boolean indicating whether the cardholder's name matches the name associated with the registered address on file. This is part of the validation process to ensure authenticity and reduce fraudulent activities.

If your request is successful, you'll receive a 200 response.

AVS and IDV

Run an AVS check

Possible AVS check results

Run an IDV check

Was this helpful?