AVS and IDV

Run an address verification or identity verification check.

Run an AVS check

To run an address verification check, add the following snippet to the body of your transaction request.

{
  "addressVerification": {
    "houseNumberOrName": "10 Downing Street",
    "postalCode": "SW1A 2AA",
    "countryCode": "GB"
  }
}

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": {},
  "approvalCode": "124488",
  "merchantTransactionDate": "2025-04-03T10:15:41",
  "merchantTransactionId": "b5495b17-347a-4067-93ea-cae9fb767251",
  "systemTransactionId": "75620b31-295f-4361-a26f-4cbd568aad2f",
  "fundingData": {
    "cardScheme": "MasterCard",
    "expiryMonth" :null,
    "expiryYear": null,
    "gatewayTokenId": "5fbd77ce-02c1-40ed-94bc-1016660b7512",
    "addressVerificationServiceResult": "NoInformationAvailable", // AVS check result from the PXP Unity Gateway 
    "providerResponse": {
      "provider": "pxpfinancial",
      "code": "00",
      "merchantId" : "77772182",
      "addressVerificationServiceResult": "X", // AVS check result from the provider
      "emvDataResponse": {},
      "paymentAccountReference": "637607302178175469",
      "electronicCommerceIndicatorAdjustment": "07",
      "merchantAdvice": {},
      "authorisedAmount": 20,
      "settlementDate": "2025-04-04T00:00:00"
    },
    "processorTransactionId": "1a1c6969-dce6-463a-82e2-aa1d4f1b7af7"
  }
}

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

To run an identity verification check, add the following snippet to the body of your request and set the transactionMethod.intent to Verification.

{
  "identityVerification": {
    "nameVerification": true
  }
}

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?