GuidesAPI ReferenceDiscussions
Guides
Start typing to search…

Card Deposits with AVS

More information about the Address Verification Service

AVS is a service used to verify the identity of the person claiming to own the credit card in order to detect suspicious transactions and prevent fraud. The service works by comparing the billing address of the credit card provided by the user with the address on file at the card issuer company.

📘

Geographical Scope

AVS is applicable only for cards issued in the US, Canada and UK.

If the AVS Check should be executed (for a particular payment), the following conditions have to be met:

  • The AVS Service must be activated for the merchant. This has to be requested via PXP Financial Support.
  • The user's card must be issued by a US, Canada or UK issuer.
  • For Backend2Backend Integration: The user's address data needs to be provided in the initiatePaymentRequest.
  • For Redirect Integration: At least the user's address country needs to be provided in the getRedirectDataRequest.

Backend2Backend Integration

To provide the address to be used for the AVS check the merchant has two options:

  1. Use AVS specific elements
    The following mandatory fields should be sent to PXP Financial in the initiatePaymentRequest.specificPaymentData request:
  • AVSCountry
  • AVSStreetAddress
  • AVSPostCode
  • PerformAVS (should be set to "true")
📘

PerformAVS = false

In case the merchant system sends PerformAVS as false the PXP Financial Payment Service will not send the AVS data for check to the issuer.

📘

PerformAVS = true

In case PerformAVS is true, the merchant needs to provide a value for all the three mandatory fields (AVSCountry, AVSStreet, AVSPostCode). If only one or two of the fields is missing, the PXP Financial Payment Service will reject the payment and respond with a validation error. If PerformAVS field is not provided, case 2 as described below will be applied.

  1. Use the user's billing address
    In case the user's billing address is provided in the request (user.address element in initiatePaymentRequest) and is not different from the AVS address, the merchant need not provide the AVS data at all. By default the PXP Financial Payment Service will use the user address and send it as AVS data to the issuer.
📘

Partial Address Data will be sent

In this case, the data will be sent even if not all address data is provided (e.g. if the AVSPostCode is missing, PXP Financial Payment Service will still send the payment to the issuer). This is done in order to increase the chance of issuer approvals.

📘

PerformAVS parameter optional

PerformAVS parameter need not be sent at all. If it is sent, it should be set to true. If PerformAVS is sent as false, no AVS check will be done.

The following table gives an overview about the possible combinations and default settings:

AVS Service activated in PXP Financial Payment Service and Card issued in US, Canada or UK?

PerformAVS value

AVS Check performed?

Notes

No

true/false or not provided at all

No

Yes

false

No

Yes

true

Yes

  • If merchant provides address data in the respective AVS fields, all three mandatory fields have to contain data, otherwise validation error.
  • If no data provided in AVS fields, then by default the user's billing address is used (if provided), even if not all fields are provided.

Yes

parameter not provided

Yes

By default the user's billing address is used (if provided), even if not all fields are provided.

📘

Response fields

The AVSResponseCode and AVSResponseMessage fields will be sent in the initiatePaymentResponse following the AVS Check. See the code sample below.

Example Card DepositinitiatePaymentRequest with AVS fields supplied:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentRequest xmlns="http://www.cqrpayments.com/PaymentProcessing" 
                        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
                        xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <merchantID>KalixaAcceptDEMO</merchantID>
  <shopID>KalixaAcceptDEMO</shopID>
	<merchantTransactionID>Order999992</merchantTransactionID>
	<paymentMethodID>2</paymentMethodID>
	<amount currencyCode="EUR">100</amount>
	<userID>u12312312</userID>
	<userData>
		<username>johndoe</username>
		<firstname>John</firstname>
		<lastname>Doe</lastname>
		<currencyCode>EUR</currencyCode>
		<languageCode>EN</languageCode>
		<email>[email protected]</email>
		<address>
			<street>Marxergasse</street>
			<houseNumber>1b</houseNumber>
			<postalCode>1030</postalCode>
			<city>Vienna</city>
			<countryCode2>AT</countryCode2>
			<telephoneNumber>00437778889999</telephoneNumber>
		</address>
		<dateOfBirth>1980-10-10T00:00:00</dateOfBirth>
		<gender>Male</gender>
	</userData>

	<userIP>127.0.0.1</userIP>
	<userSessionID>123</userSessionID>
	<creationTypeID>1</creationTypeID>

	<specificPaymentData>
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescription</key>
			<value>some description</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>PaymentDescriptionLanguageCode</key>
			<value>en</value>
		</data>
		
		<data xsi:type="keyStringValuePair">
			<key>AVSCountry</key>
			<value>GB</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>AVSStreetAddress</key>
			<value>3 Roydon Rd</value>
		</data>
		<data xsi:type="keyStringValuePair">
			<key>AVSPostCode</key>
			<value>SG128XL</value>
		</data>
		<data xsi:type="keyBooleanValuePair">
			<key>PerformAVS</key>
			<value>true</value>
		</data>			
		<data xsi:type="keyStringValuePair">
			<key>AVSPolicy</key>
			<value>1</value>
		</data>				
	</specificPaymentData>

	<paymentAccount>
		<specificPaymentAccountData>
			<data xsi:type="keyStringValuePair">
				<key>CardNumber</key>
				<value>4111111111111111</value>
			</data>
			<data xsi:type="keyStringValuePair">
				<key>CardVerificationCode</key>
				<value>111</value>
			</data>
			<data xsi:type="keyStringValuePair">
				<key>HolderName</key>
				<value>John Doe</value>
			</data>
			<data xsi:type="keyIntValuePair">
				<key>ExpiryMonth</key>
				<value>1</value>
			</data>
			<data xsi:type="keyIntValuePair">
				<key>ExpiryYear</key>
				<value>2099</value>
			</data>
		</specificPaymentAccountData>
	</paymentAccount>

</initiatePaymentRequest>

ExampleinitiatePaymentResponse:

<?xml version="1.0" encoding="utf-8"?>
<initiatePaymentResponse xmlns="http://www.cqrpayments.com/PaymentProcessing"
                         xmlns:xsd="http://www.w3.org/2001/XMLSchema"
                         xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
    <payment xsi:type="paymentWithPaymentAccount">
        <merchantID>KalixaAcceptDEMO</merchantID>
        <shopID>KalixaAcceptDEMO</shopID>
        <paymentMethod>
            <key>2</key>
            <value>VISA Deposit</value>
        </paymentMethod>
        <merchantTransactionID>Order999992</merchantTransactionID>
        <paymentID>78f28538-540c-434a-b477-856f54a93d32</paymentID>
        <userID>u12312312</userID>
        <paymentProvider>
            <key>92</key>
            <value>CQRUK</value>
        </paymentProvider>
        <amount currencyCode="EUR">100</amount>
        <creationType>
            <key>1</key>
            <value>User</value>
        </creationType>
        <userIP>127.0.0.1</userIP>
        <state>
            <id>46ea9c31-326f-424f-a56f-3fe9623c9c2d</id>
            <definition>
                <key>13</key>
                <value>AuthorisedByProvider</value>
            </definition>
            <createdOn>2017-04-06T08:48:31.276414Z</createdOn>
            <description>Approved or completed successfully</description>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseCode</key>
                    <value>0</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>AVSResponseCode</key>
                    <value>N</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>AVSResponseMessage</key>
                    <value>No data matches</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>ApprovalCode</key>
                    <value>188582</value>
                </detail>
            </paymentStateDetails>
        </state>
        <isExecuted>true</isExecuted>
        <baseAmount currencyCode="EUR">100</baseAmount>
        <paymentDetails>
            <detail xsi:type="keyStringValuePair">
                <key>ProviderExternalID</key>
                <value>472736</value>
            </detail>
        </paymentDetails>
        <paymentAccount>
            <paymentAccountID>7d3d1fce-3b15-438f-a63d-db92ce576f57</paymentAccountID>
        </paymentAccount>
    </payment>
</initiatePaymentResponse>

Redirect Integration

The same pre-conditions as for the Backend2Backend integration apply also for the Redirect Integration:

  • The AVS Service must be activated for the merchant. This has to be requested via PXP Financial Support.
  • The user's card must be issued by a US, Canada or UK issuer.

The following (usually optional) parameters are mandatory and must provided in the getRedirectDataRequest (see getRedirectData):

ParameterValueNote
AVSCountryCountry of the AVS addressIf no value is provided, the payment initiation will fail after the user has confirmed the payment.

The following parameters are still optional. The below table explains their usage in the Redirect Integration:

Parameter

Value

Note

AVSStreetAddress and AVSPostCode

Street/Postal or Zip Code of the AVS address

If values for both fields are provided, no AVS input fields will be displayed to the customer in the PXP Financial Checkout Cards payment page. The values will be used for the AVS check in the backend.

If values for only one field or no values provided at all, AVS input fields will be displayed to the customer in the PXP Financial Checkout Cards payment page (field "Address" and "Postal/Zip Code").

PerformAVS

true or false

If false, then no AVS fields will be displayed to the customer and no AVS check will be performed.
If true or PerformAVS not provided, the AVS fields will be displayed or not according to the description above and AVS check will be performed.

📘

Display the AVS fields to the customer

The functionality to display the AVS fields to the customer in the PXP Financial Checkout is supported on the "Cards" payment method group page only and not on the single card payment method detail pages.

Flow if: the customer uses a new card

  1. The Merchant requests the redirection URL using getRedirectData and transmits a value for AVSCountry. Optionally the merchant can also provide values for AVSStreetAddress, AVSPostCode, PerformAVS and AVSPolicy (see next chapter for more information).
  2. The Merchant redirects the customer to the PXP Financial Checkout.
  3. The customer selects the "Cards" payment method group.
  4. The customer starts entering his card number.
  5. After entering the first 8 digits of his card number, the card BIN data is retrieved. In case the Issuer Country of the Card is UK, US or Canada and only one or no values were transmitted for AVSStreetAddress, AVSPostCode two additional (mandatory) input fields are displayed to the customer: "Address" and "Postal/ZIP Code". Note: if only one field was transmitted, both fields are displayed, one pre-filled.
  6. The customer fills out the form with his address data and confirms the payment

Flow if: the customer uses a saved card
In case the customer has already used his card before in the PXP Financial Checkout, the flow will be different from point 4. onwards:

  1. The customer selects his saved card and enters the CVC code. In case the Issuer Country of the Card is UK, US or Canada and only one or no values were transmitted for AVSStreetAddress, AVSPostCode two additional (mandatory) input fields are displayed to the customer: Address/Street and Postal/ZIP Code. Note: if only one field was transmitted, both fields are displayed, one pre-filled.
    5. The customer fills out the form with his address data and confirms the payment

Example: Customer uses a new card
In the below example, the merchant has not transmitted AVS data in the getRedirectData request. As a result both input fields "Address" and "Postal/ZIP Code" are displayed without any prefilled value/data.

Example: Customer uses a saved card
In the below example, the merchant has transmitted a value for AVSStreetAddress, but no value for AVSPostCode in the getRedirectData request. As a result both input fields "Address" and "Postal/ZIP Code" are displayed and the provided value for AVSStreetAddress is prefilled in the "Address" field.

Example for providing AVS fields in thegetRedirectDataRequest:

<additionalDetails>
              <detail xsi:type="keyStringValuePair">
                             <key>AVSCountry</key>
                             <value>GB</value>
              </detail>
              <detail xsi:type="keyStringValuePair">
                             <key>AVSStreetAddress</key>
                             <value>10 Downing Street</value>
              </detail>
              <detail xsi:type="keyStringValuePair">
                             <key>AVSPostCode</key>
                             <value>SW1A 2AA</value>
              </detail>
              <detail xsi:type="keyStringValuePair">
                             <key>AVSPolicy</key>
                             <value>2</value>
              </detail>
              <detail xsi:type="keyBooleanValuePair">
                             <key>PerformAVS</key>
                             <value>true</value>
              </detail>
</additionalDetails>

AVS Response and Policy

As mentioned earlier, the AVSResponseCode and AVSResponseMessage fields will be sent in the initiatePaymentResponse following the AVS Check.

In addition to the other AVS parameters in the initiatePayment request, AVSPolicy can be specified (in Backend2Backend as well as Redirect Integration). If not provided, the default policy 1 will be applied.
Based on the defined policy and the returned AVS response (code) the PXP Financial system will approve or decline the transaction.

The below table shows a list of applicable AVS policies and the resulting approval behavior (approve/decline):

AVS ResponseCodePolicy 1Policy 2Policy 3Policy 4Policy 5
EXACT MATCHFApproveApproveApproveApproveApprove
POST CODE MATCH ONLYPApproveApproveApproveApproveApprove
ADDR MATCH ONLYBApproveApproveApproveDeclineDecline
DATA NOT CHECKEDUApproveApproveDeclineApproveDecline
NO DATA MATCHESNApproveDeclineDeclineDeclineDecline
📘

AVS Response Code "X" - AVS check was not performed

In case the PXP Financial system could not send the AVS data to the issuer although AVS Check was requested to be done, the AVS response code will be set to "X", which means "No AVS check was done".
This is not an expected case. In case it happens, please contact the PXP Support team to solve the problem.

Test scenarios

To test the above described scenarios against the PXP Financial test system, a specific value has to be used for payment amount.

  • For Backend2Backend Integration: initiatePaymentRequest - field: amount
  • For Redirect Integration: getRedirectDataRequest - field: redirectParameters.grossAmount

Test Case Description

Value for Amount

Expected Outcome

EXACT MATCH

10.56

F

POST CODE MATCH ONLY

10.55

P

ADDR MATCH ONLY

10.54

B

DATA NOT CHECKED

10.37

U

NO DATA MATCHES

10.52

N

Example for aninitiatePaymentResponse where AVS check was done
The AVS information can be found in the paymentStateDetails section with keys: AVSResponseCode and AVSResponseMessage

...     
       <state>
            <id>79235d59-af94-4099-89bd-fccf9bc7a718</id>
            <definition>
                <key>13</key>
                <value>AuthorisedByProvider</value>
            </definition>
            <createdOn>2019-11-25T09:01:59.7345504Z</createdOn>
            <description>Approved or completed successfully</description>
            <paymentStateDetails>
                <detail xsi:type="keyStringValuePair">
                    <key>ProviderResponseCode</key>
                    <value>0</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>AVSResponseCode</key>
                    <value>N</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>AVSResponseMessage</key>
                    <value>No data matches</value>
                </detail>
                <detail xsi:type="keyStringValuePair">
                    <key>ApprovalCode</key>
                    <value>976156</value>
                </detail>
            </paymentStateDetails>
        </state>
...

Notifications

If the transaction is processed successfully, Payment Service will send a standard PaymentStateChangeNotificationRequest to the merchant's listener endpoint. For more information see PaymentStateChangedNotification.

Updated 5 months ago