Verify a customer's account

API v5

Last updated March 2023

Change log

To verify your customer's account, you must send a verifications request to one of our supported resources.

Intelligent verification

With an Intelligent verification, Worldpay chooses the amount to use in the verification.

Intelligent verification request

You can POST your intelligent verification request to one of these resources:

`oneTime` intelligent verification

For a oneTime verification, POST your request to the verifications:oneTime action link received in yourquery the verifications root resourcerequest.

POST https://try.access.worldpay.com/verifications/accounts/intelligent/oneTime

`cardOnFile` intelligent verification

cardOnFile payments are initiated by the customer using the payment instrument details that have already been stored.

For a cardOnFile verification, POST your request to the verifications:cardOnFile action link received in yourquery the verifications root resourcerequest to become Cardholder Initiated Transaction (CIT) compliant.

POST https://try.access.worldpay.com/verifications/accounts/intelligent/cardOnFile

Example request body

Intelligent verification for cardOnFile and oneTime requests with mandatory fields only:

Copied!

{
    "currency": "GBP",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "paymentInstrument": {
        "type": "card/plain",
        "cardNumber": "4444333322221111",
        "cardExpiryDate": {
            "month": 1,
            "year": 2035
        },
        "cardHolderName": "Sherlock Holmes"
    },
    "transactionReference": "Memory265-13/08/1876"
}

{
    "currency": "GBP",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "paymentInstrument": {
        "type": "card/tokenized",
        "href": "https://try.access.worldpay.com/tokens/{}"
    },
    "transactionReference": "Memory265-13/08/1876"
}

Descriptions of your mandatory intelligent verification request parameters:

Parameter	Required	Description
`currency`		The 3-digit currency code. See list ofsupported currencies.
`transactionReference`		A unique reference generated by you that is used to identify a payment throughout its lifecycle. Seetransaction reference format, for more details and the best practices.
`paymentInstrument`		An object that contains your customer's payment details.
`paymentInstrument.type`		An object that contains your customer's payment type. Possible values: `card/plain` `card/tokenized`
`paymentInstrument.cardNumber`		An object that contains your customer's payment card number. Required for `paymentInstrument` `card/plain`.
`paymentInstrument.cardExpiryDate`		An object that contains your customer's payment card expiry date.
`paymentInstrument.href`		An object that contains your token. Required for `paymentInstrument` `"card/tokenized"`.
`merchant`		An object that contains information about the merchant.
`merchant.entity`		Direct your verification to assist with billing, reporting and reconciliation. For more information contact your Relationship Manager or Implementation Manager.

Optional fields in a verification request

Intelligent verification for cardOnFile and oneTime requests with optional and mandatory fields:

Copied!

{
    "transactionReference": "Memory265-13/08/1876",
    "currency": "GBP",
    "merchant": {
        "entity": "MindPalaceLtd",
        "mcc": "6012",
        "paymentFacilitator": {
            "pfId": "12345678901",
            "isoId": "4101",
            "subMerchant": {
                "merchantId": "1234567",
                "name": "Example Shop",
                "street": "123 Street",
                "state": "CA",
                "city": "San Francisco",
                "countryCode": "840",
                "postalCode": "94101",
                "taxId": "987-65-4321"
            }
        }
    },
    "narrative": {
        "line1": "The Mind Palace Ltd",
        "line2": "Memory265-13/08/1876"
    },
    "paymentInstrument": {
        "type": "card/plain",
        "cardHolderName": "Sherlock Holmes",
        "cardNumber": "4444333322221111",
        "cardExpiryDate": {
            "month": 5,
            "year": 2035
        },
        "verificationAddress": {
            "address1": "221B Baker Street",
            "countryCode": "GB",
            "postalCode": "NW1 6XE",
            "city": "London"
        },
        "cvc": "321"
    },
    "storedCredentials": {
        "reason": "recurring"
    }
}

{
    "transactionReference": "Memory265-13/08/1876",
    "currency": "GBP",
    "merchant": {
        "entity": "MindPalaceLtd",
        "mcc": "6012",
        "paymentFacilitator": {
            "pfId": "12345678901",
            "isoId": "4101",
            "subMerchant": {
                "merchantId": "1234567",
                "name": "Example Shop",
                "street": "123 Street",
                "state": "CA",
                "city": "San Francisco",
                "countryCode": "840",
                "postalCode": "94101",
                "taxId": "987-65-4321"
            }
        }
    },
    "narrative": {
        "line1": "The Mind Palace Ltd",
        "line2": "Memory265-13/08/1876"
    },
    "paymentInstrument": {
        "type": "card/tokenized",
        "href": "https://try.access.worldpay.com/tokens/{}",
        "cvc": "123"
    }
}

Descriptions of your optional intelligent verification request parameters:

Parameter	Required	Description
`paymentInstrument.verificationAddress`		An object containing the verification address information. Applicable for `paymentInstrument` "card/plain" only. If included you must send at least: `city` `countryCode` `postalCode`
`narrative`		The text that appears on your customer's statement. Used to identify the merchant. Seenarrative formatfor more details and best practices. If not supplied, the default is "Active Card Check".
`narrative.line1`		The first line of the narrative which appears on your customer's statement (24 characters max.) Seenarrative `line1` formatfor more details. You must send this if you provide `narrative`.
`narrative.line2`		Additional details about the payment e.g. order number, telephone number.
`paymentInstrument.cardHolderName`		An object that contains your customer's name. This is not a mandatory field however it is recommended you supply this to improve authorization rates. If not sent, the default is "Not Supplied".
`cvc`		CVC is a unique set of 3 or 4 numbers on the back of your customer's card. Including the CVC in your request increases the chances of the verification request `outcome` being `verified`. Our API checks to see if the CVC supplied matches the CVC held by the issuing bank.
`merchant.mcc`		A Merchant Category Code (`mcc`) can be applied to an individual request. An `mcc` can only be provided if the dynamic `mcc` feature has been enabled during boarding. If enabled but not provided, `merchant.mcc` defaults to a configured value. For more information contact your Relationship Manager or Implementation Manager.
`merchant.paymentFacilitator`		An object containing your payment facilitator information. If required you must send: pfId subMerchant.merchantId subMerchant.postalcode subMerchant.street subMerchant.city subMerchant.countryCode See ourformatting pagefor further details. This parameter is only required for verification if you are a payment facilitator.
`storedCredentials`		A stored credential is Visa, Mastercard, or AMEX information (such as a card number) that a customer has opted for you, as the merchant, to store and use to process future transactions. Note: This field is only applicable for `cardOnFile` endpoint.
`storedCredentials.reason`		Gives the reason for a merchant initiated transaction using stored credentials. Possible values: `unscheduled`: A transaction using a stored credential for a fixed or variable amount that does not occur on a scheduled or regularly occurring transaction date. This includes account top-ups triggered by balance thresholds. `instalment`: A single purchase of goods or services billed to a cardholder in multiple transactions, over a period of time agreed by the cardholder and you. `recurring`: Transactions processed at fixed, regular intervals not to exceed one year between transactions, representing an agreement between a cardholder and you to purchase goods or services provided over a period of time. `reauth`: Reauthorization - a purchase made after the original purchase. A common scenario is delayed/split shipments. `delayed`: A delayed charge is typically used in hotel, cruise lines and vehicle rental environments to perform a supplemental account charge after original services are rendered. `incremental`: An incremental authorization is typically found in hotel and car rental environments, where the cardholder has agreed to pay for any service incurred during the duration of the contract. An incremental authorization is where you need to seek authorization of further funds in addition to what you have originally requested. A common scenario is additional services charged to the contract, such as extending a stay in a hotel. `resubmission`: When the original purchase occurred, but you were not able to get authorization at the time the goods or services were provided. It should only be used where the goods or services have already been provided, but the post-event authorization request is declined for insufficient funds. `noshow`: A no-show is a transaction where you are enabled to charge for services which the cardholder entered into an agreement to purchase, but the cardholder did not meet the terms of the agreement.

Dynamic verification

Our Dynamic verifications service gives you granular control over the amount that is used for verification.

Dynamic verification request

You can POST your verification request to one of these resources :

`dynamicOneTime` verification

For a dynamicOneTime verification, POST your request to the verifications:dynamicOneTime action link received in yourquery the verifications root resourcerequest.

POST https://try.access.worldpay.com/verifications/accounts/dynamic/oneTime

`dynamicCardOnFile` verification

cardOnFile payments are initiated by the customer using the payment instrument details that have already been stored.

For a dynamicCardOnFile verification, POST your request to the verifications:dynamicCardOnFile action link received in yourquery the verifications root resourcerequest to become Cardholder Initiated Transaction (CIT) compliant.

POST https://try.access.worldpay.com/verifications/accounts/dynamic/cardOnFile

Example request body

Dynamic verification for cardOnFile and oneTime requests with mandatory fields only:

Copied!

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardNumber": "4444333322221111",
            "cardHolderName": "Sherlock Holmes",
            "cardExpiryDate": {
                "month": 12,
                "year": 2023
            }
        }
    }
}

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "paymentInstrument": {
            "type": "card/tokenized",
            "href": "https://try.access.worldpay.com/tokens/{}"
        }
    }
}

Descriptions of your mandatory dynamic verification request parameters:

Parameter	Required	Description
`instruction`		An object that contains all the information related to the payment.
`value.currency`		The 3-digit currency code. See list ofsupported currencies.
`value.amount`		The payment amount. This is a whole number with an exponent e.g. if exponent is two, 250 is 2.50. You can find the relevant exponent in ourcurrency table.
`transactionReference`		A unique reference generated by you that is used to identify a payment throughout its lifecycle. Seetransaction reference format, for more details and the best practices.
`instruction.paymentInstrument`		An object that contains your customer's payment details.
`paymentInstrument.type`		An object that contains your customer's payment type. Possible values: `card/plain` `card/tokenized`
`paymentInstrument.cardNumber`		An object that contains your customer's payment card number.
`paymentInstrument.cardExpiryDate`		An object that contains your customer's payment card expiry date.
`merchant`		An object that contains information about the merchant.
`merchant.entity`		Direct your verification to assist with billing, reporting and reconciliation. For more information contact yourRelationship Manager.

Optional fields in a verification request

Dynamic verification for cardOnFile and oneTime requests with optional and mandatory fields:

Copied!

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd",
        "mcc": "6012",
        "paymentFacilitator": {
            "pfId": "12345678901",
            "isoId": "4101",
            "subMerchant": {
                "merchantId": "1234567",
                "name": "Example Shop",
                "street": "123 Street",
                "state": "CA",
                "city": "San Francisco",
                "countryCode": "840",
                "postalCode": "94101",
                "taxId": "987-65-4321"
            }
        }
    },
    "instruction": {
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "narrative": {
            "line1": "The Mind Palace Ltd",
            "line2": "Memory265-13/08/1876"
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cardHolderName": "Sherlock Holmes",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 5,
                "year": 2035
            },
            "verificationAddress": {
                "address1": "221B Baker Street",
                "countryCode": "GB",
                "postalCode": "NW1 6XE",
                "city": "London"
            },
            "cvc": "321"
        },
        "storedCredentials": {
            "reason": "instalment"
        }
    }
}

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd",
        "mcc": "6012",
        "paymentFacilitator": {
            "pfId": "12345678901",
            "isoId": "4101",
            "subMerchant": {
                "merchantId": "1234567",
                "name": "Example Shop",
                "street": "123 Street",
                "state": "CA",
                "city": "San Francisco",
                "countryCode": "840",
                "postalCode": "94101",
                "taxId": "987-65-4321"
            }
        }
    },
    "instruction": {
        "value": {
            "currency": "GBP",
            "amount": 250
        },
        "narrative": {
            "line1": "The Mind Palace Ltd",
            "line2": "Memory265-13/08/1876"
        },
        "paymentInstrument": {
            "type": "card/tokenized",
            "href": "https://try.access.worldpay.com/tokens/{}",
            "cvc": "123"
        }
    }
}

Descriptions of your optional dynamic verification request parameters:

Parameter	Required	Description
`paymentInstrument.cardHolderName`		An object that contains your customer's name. This is not a mandatory field however it is recommended you supply this to improve authorization rates. If not sent, the default is "Not Supplied".
`paymentInstrument.verificationAddress`		An object containing the verification address information. Applicable for `paymentInstrument` "card/plain" only. If included you must send at least: `city` `countryCode` `postalCode`
`narrative`		The text that appears on your customer's statement. Used to identify the merchant. Seenarrative formatfor more details and best practices. If not supplied, the default is "Active Card Check".
`narrative.line1`		The first line of the narrative which appears on your customer's statement (24 characters max.) Seenarrative `line1` formatfor more details. You must send this if you provide `narrative`.
`narrative.line2`		Additional details about the payment e.g. order number, telephone number.
`paymentInstrument.cvc`		CVC is a unique set of 3 or 4 numbers on the back of your customer's card. Including the CVC in your request increases the chances of the verification request `outcome` being `verified`. Our API checks to see if the CVC supplied matches the CVC held by the issuing bank.
`merchant.paymentFacilitator`		An object containing your payment facilitator information. If required you must send: pfId subMerchant.merchantId subMerchant.postalcode subMerchant.street subMerchant.city subMerchant.countryCode See ourformatting pagefor further details. This parameter is only required for verification if you are a payment facilitator.
`storedCredentials`		A stored credential is Visa, Mastercard, or AMEX information (such as a card number) that a customer has opted for you, as the merchant, to store and use to process future transactions. Note: This field is only applicable for `cardOnFile` endpoint.
`storedCredentials.reason`		Gives the reason for a merchant initiated transaction using stored credentials. Possible values: `unscheduled`: A transaction using a stored credential for a fixed or variable amount that does not occur on a scheduled or regularly occurring transaction date. This includes account top-ups triggered by balance thresholds. `instalment`: A single purchase of goods or services billed to a cardholder in multiple transactions, over a period of time agreed by the cardholder and you. `recurring`: Transactions processed at fixed, regular intervals not to exceed one year between transactions, representing an agreement between a cardholder and you to purchase goods or services provided over a period of time. `reauth`: Reauthorization - a purchase made after the original purchase. A common scenario is delayed/split shipments. `delayed`: A delayed charge is typically used in hotel, cruise lines and vehicle rental environments to perform a supplemental account charge after original services are rendered. `incremental`: An incremental authorization is typically found in hotel and car rental environments, where the cardholder has agreed to pay for any service incurred during the duration of the contract. An incremental authorization is where you need to seek authorization of further funds in addition to what you have originally requested. A common scenario is additional services charged to the contract, such as extending a stay in a hotel. `resubmission`: When the original purchase occurred, but you were not able to get authorization at the time the goods or services were provided. It should only be used where the goods or services have already been provided, but the post-event authorization request is declined for insufficient funds. `noshow`: A no-show is a transaction where you are enabled to charge for services which the cardholder entered into an agreement to purchase, but the cardholder did not meet the terms of the agreement.

3DS

You can optionally submit 3DS parameters for intelligent and dynamic verification requests.

To get the customer authentication object you must complete anauthentication requestusing our3DS API.

Copied!

{
    "transactionReference": "Memory265-13/08/1876",
    "currency": "GBP",
    "merchant": {
        "entity": "MindPalaceLtd",
        "mcc": "6012",
        "paymentFacilitator": {
            "pfId": "12345678901",
            "isoId": "4101",
            "subMerchant": {
                "merchantId": "1234567",
                "name": "Example Shop",
                "street": "123 Street",
                "state": "CA",
                "city": "San Francisco",
                "countryCode": "840",
                "postalCode": "94101",
                "taxId": "987-65-4321"
            }
        }
    },
    "narrative": {
        "line1": "The Mind Palace Ltd"
    },
    "paymentInstrument": {
        "type": "card/plain",
        "cvc": "321",
        "cardHolderName": "Sherlock Holmes",
        "cardNumber": "4444333322221111",
        "cardExpiryDate": {
            "month": 5,
            "year": 2035
        },
        "verificationAddress": {
            "address1": "221B Baker Street",
            "countryCode": "GB",
            "postalCode": "NW1 6XE",
            "city": "London"
        }
    },
    "customer": {
        "authentication": {
            "version": "1.0.2",
            "type": "3DS",
            "eci": "05",
            "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
            "transactionId": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA="
        }
    }
}

{
    "transactionReference": "Memory265-13/08/1876",
    "currency": "GBP",
    "merchant": {
        "entity": "MindPalaceLtd",
        "mcc": "6012",
        "paymentFacilitator": {
            "pfId": "12345678901",
            "isoId": "4101",
            "subMerchant": {
                "merchantId": "1234567",
                "name": "Example Shop",
                "street": "123 Street",
                "state": "CA",
                "city": "San Francisco",
                "countryCode": "840",
                "postalCode": "94101",
                "taxId": "987-65-4321"
            }
        }
    },
    "narrative": {
        "line1": "The Mind Palace Ltd"
    },
    "paymentInstrument": {
        "type": "card/plain",
        "cvc": "321",
        "cardHolderName": "Sherlock Holmes",
        "cardNumber": "4444333322221111",
        "cardExpiryDate": {
            "month": 5,
            "year": 2035
        },
        "verificationAddress": {
            "address1": "221B Baker Street",
            "countryCode": "GB",
            "postalCode": "NW1 6XE",
            "city": "London"
        }
    },
    "customer": {
        "authentication": {
            "version": "2.1.0",
            "type": "3DS",
            "eci": "05",
            "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
            "transactionId": "683001f5-3805-423a-b580-638e4b2093b3"
        }
    }
}

{
    "transactionReference": "Memory265-13/08/1876",
    "currency": "GBP",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "narrative": {
        "line1": "abc"
    },
    "paymentInstrument": {
        "type": "card/tokenized",
        "href": "https://try.access.worldpay.com/tokens/{}"
    },
    "customer": {
        "authentication": {
            "version": "1.0.2",
            "type": "3DS",
            "eci": "05",
            "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
            "transactionId": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA="
        }
    }
}

{
    "transactionReference": "Memory265-13/08/1876",
    "currency": "GBP",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "narrative": {
        "line1": "The Mind Palace Ltd"
    },
    "paymentInstrument": {
        "type": "card/tokenized",
        "href": "https://try.access.worldpay.com/tokens/{}"
    },
    "customer": {
        "authentication": {
            "version": "2.1.0",
            "type": "3DS",
            "eci": "05",
            "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
            "transactionId": "683001f5-3805-423a-b580-638e4b2093b3"
        }
    }
}

Copied!

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd",
        "mcc": "6012",
        "paymentFacilitator": {
            "pfId": "12345678901",
            "isoId": "4101",
            "subMerchant": {
                "merchantId": "1234567",
                "name": "Example Shop",
                "street": "123 Street",
                "state": "CA",
                "city": "San Francisco",
                "countryCode": "840",
                "postalCode": "94101",
                "taxId": "987-65-4321"
            }
        }
    },
    "instruction": {
        "narrative": {
            "line1": "The Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 20
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cvc": "321",
            "cardHolderName": "Sherlock Holmes",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 5,
                "year": 2035
            },
            "verificationAddress": {
                "address1": "221B Baker Street",
                "countryCode": "GB",
                "postalCode": "NW1 6XE",
                "city": "London"
            }
        }
    },
    "customer": {
        "authentication": {
            "version": "1.0.2",
            "type": "3DS",
            "eci": "05",
            "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
            "transactionId": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA="
        }
    }
}

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd",
        "mcc": "6012",
        "paymentFacilitator": {
            "pfId": "12345678901",
            "isoId": "4101",
            "subMerchant": {
                "merchantId": "1234567",
                "name": "Example Shop",
                "street": "123 Street",
                "state": "CA",
                "city": "San Francisco",
                "countryCode": "840",
                "postalCode": "94101",
                "taxId": "987-65-4321"
            }
        }
    },
    "instruction": {
        "narrative": {
            "line1": "The Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 20
        },
        "paymentInstrument": {
            "type": "card/plain",
            "cvc": "321",
            "cardHolderName": "Sherlock Holmes",
            "cardNumber": "4444333322221111",
            "cardExpiryDate": {
                "month": 5,
                "year": 2035
            },
            "verificationAddress": {
                "address1": "221B Baker Street",
                "countryCode": "GB",
                "postalCode": "NW1 6XE",
                "city": "London"
            }
        }
    },
    "customer": {
        "authentication": {
            "version": "2.1.0",
            "type": "3DS",
            "eci": "05",
            "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
            "transactionId": "683001f5-3805-423a-b580-638e4b2093b3"
        }
    }
}

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "The Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 20
        },
        "paymentInstrument": {
            "type": "card/tokenized",
            "href": "https://try.access.worldpay.com/tokens/{}}"
        }
    },
    "customer": {
        "authentication": {
            "version": "1.0.2",
            "type": "3DS",
            "eci": "05",
            "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
            "transactionId": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA="
        }
    }
}

{
    "transactionReference": "Memory265-13/08/1876",
    "merchant": {
        "entity": "MindPalaceLtd"
    },
    "instruction": {
        "narrative": {
            "line1": "The Mind Palace Ltd"
        },
        "value": {
            "currency": "GBP",
            "amount": 20
        },
        "paymentInstrument": {
            "type": "card/tokenized",
            "href": "https://try.access.worldpay.com/tokens/{}}"
        }
    },
    "customer": {
        "authentication": {
            "version": "2.1.0",
            "type": "3DS",
            "eci": "05",
            "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
            "transactionId": "683001f5-3805-423a-b580-638e4b2093b3"
        }
    }
}

The descriptions of parameters from your 3DS authorization request

Parameter	Required	Description
`customer`		An object containing the result of your customer's verification. For more details see3DS verification.
`authentication.type`		3DS
`authentication.version`		The version of 3DS used to process the transaction. For 3DS1 - `1.0.2` For 3DS2 - `2.1.0` or `2.2.0` Note: Required for Mastercard's Identity Check transactions in Authorization.
`authentication.eci`		Electronic Commerce Indicator (ECI). Indicates the outcome of the3DS verification. 02 or 05 - Fully Authenticated Transaction 01 or 06 - Attempted Authentication Transaction 00 or 07 - Non 3-D Secure Transaction Mastercard - 02, 01, 00 Visa - 05, 06, 07 Amex - 05, 06, 07 JCB - 05, 06, 07 Diners - 05, 06, 07
`authentication.authenticationValue`		A cryptographic value that provides evidence of the outcome of a 3DS verification. Visa - Cardholder Authentication Verification Value (CAVV) Mastercard - Universal Cardholder Authentication Field (UCAF) For version 3DS1: `authentication.authenticationValue` is required if `authentication.eci` value is 01, 02 or 05. For version 3DS2: `authentication.authenticationValue` is required if `authentication.eci` value is 01, 02, 05 or 06. `authentication.authenticationValue` must be 28 digits max and must be base64-encoded.
`authentication.transactionId`		Required, if `authentication.eci` value is 01, 02, 05 or 06. A unique authentication transaction identifier, generated by the issuer. For version 3DS1: `transactionId` must be base64-encoded and 28 digits in length. For version 3DS2: `transactionId` must be a UUID and 36 characters in length.

Apple Pay decrypted

You can optionally submit Apple Pay decrypted parameters for intelligent and dynamic cardOnFile requests.

Verification request example:

Copied!

{
   "currency":"EUR",
   "paymentInstrument":{
      "type":"card/networkToken+applepay",
      "cardHolderName":"Sherlock Holmes",
      "cardExpiryDate":{
         "month":1,
         "year":2019
      },
      "dpan":"4444333322221111"
   },
   "narrative":{
      "line1":"The Mind Palace Ltd",
      "line2":"Memory265-13/08/1876"
   },
   "merchant":{
      "entity":"MindPalaceLtd"
   },
   "transactionReference":"Memory265-13/08/1876",
   "customer":{
      "authentication":{
         "type":"card/networkToken",
         "eci":"05",
         "authenticationValue":"MTIzNDU2Nzg5MDEyMzQ1Njc4OTA="
      }
   }
}

{
   "merchant":{
      "entity":"MindPalaceLtd"
   },
   "transactionReference":"Memory265-13/08/1876",
   "instruction":{
      "value":{
         "amount":100,
         "currency":"GBP"
      },
      "paymentInstrument":{
         "type":"card/networkToken+applepay",
         "cardHolderName":"Sherlock Holmes",
         "cardExpiryDate":{
            "month":1,
            "year":2019
         },
         "dpan":"4444333322221111"
      },
      "narrative":{
         "line1":"The Mind Palace Ltd",
         "line2":"Memory265-13/08/1876"
      }
   },
   "customer":{
      "authentication":{
         "type":"card/networkToken",
         "eci":"05",
         "authenticationValue":"MTIzNDU2Nzg5MDEyMzQ1Njc4OTA="
      }
   }
}

The descriptions of parameters from your Apple Pay decrypted authorization request

Parameter	Required	Description
`paymentInstrument.type`		An object that contains your customer's payment type; `card/networkToken+applepay`.
`paymentInstrument.dpan`		An object that contains the device primary account number.
`customer`		An object containing the authentication information required for Apple Pay decrypted.
`authentication.type`		`card/networkToken`
`authentication.eci`		Electronic Commerce Indicator (ECI). Indicates the value contained in the Apple Pay decrypted response.
`authentication.authenticationValue`		A cryptographic value that provides evidence of the outcome of a Apple Pay decrypted verification.

Important: We currently don't return action links in our response for this paymentInstrument. This is still under development. You can use our payments:migrateCardOnFileAuthorize action link totake a paymentin the meantime.

Verifications response

The response is the same for both anIntelligentorDynamicverification.

You receive:

Best Practice: Access Worldpay returns a WP-CorrelationId in the headers of service responses. We highly recommend you log this. The WP-CorrelationId is used by us to examine individual service requests.

a 201 HTTP response code
a verification outcome (either verified or not verified)
anissuer response code and description(not verified result only)
a schemeTransactionReference for card on file only (not all issuers return this)
riskFactors
a paymentInstrument

Note: The paymentInstrument contains the paymentInstrument.type sent in the request at minimum. If you wish to receive more card metadata this must be enabled. For more information contact your Implementation Manager.

Copied!

{
    "outcome": "verified",
    "checkedAt": "2018-09-01T10:37:36.923Z",
    "riskFactors": [{
            "risk": "matched",
            "type": "cvc"
        },
        {
            "risk": "matched",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "matched",
            "detail": "address",
            "type": "avs"
        }
    ],
    "_links": {
        "verifications:verification": {
            "href": "https://try.access.worldpay.com/verifications/accounts/{resource}"
        },
        "curies": [{
            "name": "verifications",
            "href": "https://try.access.worldpay.com/rels/verifications/accounts/{rel}",
            "templated": true
        }]
    }
}

{
    "outcome": "verified",
    "checkedAt": "2019-11-01T10:37:36.923Z",
    "schemeTransactionReference": "000000000000020005060720116005060",
    "riskFactors": [{
            "risk": "matched",
            "type": "cvc"
        },
        {
            "risk": "matched",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "matched",
            "detail": "address",
            "type": "avs"
        }
    ],
    "_links": {
        "verifications:verification": {
            "href": "https://try.access.worldpay.com/verifications/accounts/{resource}"
        },
        "payments:cardonFileAuthorize": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cardonFile/{resource}"
        },
        "payments:recurringAuthorize": {
            "href": "http://try.access.worldpay.com/payments/authorizations/recurring/{resource}"
        },
        "payments:recurringSale": {
            "href": "https://try.access.worldpay.com/payments/sales/recurring/{resource}"
        },
        "curies": [{
            "name": "verifications:verification",
            "href": "https://try.access.worldpay.com/rels/verifications/accounts/{rel}",
            "templated": true
        }]
    }
}

{
    "outcome": "verified",
    "checkedAt": "2018-09-01T10:37:36.923Z",
    "riskFactors": [{
            "risk": "matched",
            "type": "cvc"
        },
        {
            "risk": "matched",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "matched",
            "detail": "address",
            "type": "avs"
        }
    ],
    "paymentInstrument": {
        "type": "card/plain",
        "card": {
            "number": {
                "bin": "444433",
                "last4Digits": "1111"
            },
            "countryCode": "GB",
            "expiryDate": {
                "month": 12,
                "year": 2029
            },
            "brand": "visa",
            "fundingType": "debit",
            "issuer": {
                "name": "cardIssuer"
            },
            "category": "consumer",
            "paymentAccountReference": "reference"
        }
    },
    "_links": {
        "verifications:verification": {
            "href": "https://try.access.worldpay.com/verifications/accounts/{resource}"
        },
        "curies": [{
            "name": "verifications",
            "href": "https://try.access.worldpay.com/rels/verifications/accounts/{rel}",
            "templated": true
        }]
    }
}

{
    "outcome": "not verified",
    "code": "106",
    "description": "INVALID ACCOUNT",
    "checkedAt": "2019-11-01T10:37:36.923Z",
    "riskFactors": [{
            "risk": "matched",
            "type": "cvc"
        },
        {
            "risk": "matched",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "matched",
            "detail": "address",
            "type": "avs"
        }
    ],
    "_links": {
        "verifications:verification": {
            "href": "https://try.access.worldpay.com/verifications/accounts/{resource}"
        },
        "curies": [{
            "name": "verifications:verification",
            "href": "https://try.access.worldpay.com/rels/verifications/accounts/{rel}",
            "templated": true
        }]
    }
}

The parameter checkedAt contains a timestamp showing when the verification was performed, and the location of the verification for future access.

Best practice: If you receive an outcome of not verified it means that your customer has failed the verification. We strongly recommend that you refuse the payment made with that payment instrument.

Action Link (resources)	Description
`verifications:verification`	The link to the outcome of your verification request.
`payments:recurringAuthorize`	A subsequent payment in a recurring agreement. This resource is returned as a result of a successful`verifications:cardOnFile`,`verifications:dynamicCardOnFile`or`payments:migrateRecurringAuthorize`request.
`payments:CardOnFileAuthorize`	A subsequent payment in a card on file agreement. This resource is only returned as a result of a successful`verifications:cardOnFile`,`verifications:dynamicCardOnFile`or`payments:migrateCardOnFileAuthorize`request.
`payments:recurringSale`	A subsequent payment in a recurring agreement. This resource is only returned as a result of a successful`verifications:cardOnFile`or`verifications:dynamicCardOnFile`request.

Note: In case of any errors, you can get further information in ourerror reference.

Risk Factors

We recommend you supply cvc and verificationAddress to increase probability of a successful verification.

The table below describes the response parameters:

Parameter	Description
`riskFactors.type`	Returns `avs` or `cvc`
`riskFactors.detail`	For `avs` only. Returns `postcode` or `address`
`riskFactors.risk`	Returns `not_checked`, `not_matched`, `not_supplied` or `matched`

Payment Instrument

We only return the paymentInstrument card metadata if you are enabled for this feature.

The table below describes the response parameters:

Parameter	Description
`paymentInstrument.type`	Returns the `paymentInstrument.type` provided in your request. Can be either `card/plain` or `card/tokenized`.
`paymentInstrument.card`	An object containing all the additional metadata for the card/token provided in the request.
`paymentInstrument.card.number`	An object containing the `bin` and `last4Digits` of the card.
`paymentInstrument.card.countryCode`	The country code of the card issuer.
`paymentInstrument.card.expiryDate`	An object that contains your customer's payment card expiry date.
`paymentInstrument.card.brand`	The card scheme, e.g. `visa` or `mastercard`.
`paymentInstrument.card.fundingType`	Can be either `debit`, `credit`, `chargeCard`, `prepaid`, or `deferredDebit`.
`paymentInstrument.card.issuer.name`	The name of the card issuer.
`paymentInstrument.card.category`	Can be either `consumer` or `commercial`.
`paymentInstrument.card.paymentAccountReference`	The unique reference associated with the card PAN.

Location storing

You must store the returned location information. Failing to store the location information means the outcome of the verification is lost. You are not able to query a historic verification.

The location is stored in the href of the verifications:verification action link received on yourverifications response.

Best practice: We recommend you store all responses.

Query a historic verification

To query a historic verification, submit a query to the location returned in yourinitial response.

Query verifications request

GET https://try.access.worldpay.com/verifications/accounts/{resource}

You can query thelocationthat was returned in theinitial responseto retrieve the outcome of the initial verification. You can only get the location from theinitial response.

Query verifications response

In your response is a 200 HTTP response code and the historic outcome of the verification.

outcome:

verified
not verified

Copied!

{
    "outcome": "verified",
    "checkedAt": "2018-09-01T10:37:36.923Z",
    "riskFactors": [{
            "risk": "matched",
            "type": "cvc"
        },
        {
            "risk": "matched",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "matched",
            "detail": "address",
            "type": "avs"
        }
    ],
    "_links": {
        "verifications:verification": {
            "href": "https://try.access.worldpay.com/verifications/accounts/{resource}"
        },
        "curies": [{
            "name": "verifications",
            "href": "https://try.access.worldpay.com/rels/verifications/accounts/{rel}",
            "templated": true
        }]
    }
}

{
    "outcome": "verified",
    "checkedAt": "2019-11-01T10:37:36.923Z",
    "schemeTransactionReference": "000000000000020005060720116005060",
    "riskFactors": [{
            "risk": "matched",
            "type": "cvc"
        },
        {
            "risk": "matched",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "matched",
            "detail": "address",
            "type": "avs"
        }
    ],
    "_links": {
        "verifications:verification": {
            "href": "https://try.access.worldpay.com/verifications/accounts/{resource}"
        },
        "payments:cardonFileAuthorize": {
            "href": "https://try.access.worldpay.com/payments/authorizations/cardonFile/{resource}"
        },
        "payments:recurringAuthorize": {
            "href": "http://try.access.worldpay.com/payments/authorizations/recurring/{resource}"
        },
        "payments:recurringSale": {
            "href": "https://try.access.worldpay.com/payments/sales/recurring/{resource}"
        },
        "curies": [{
            "name": "verifications:verification",
            "href": "https://try.access.worldpay.com/rels/verifications/accounts/{rel}",
            "templated": true
        }]
    }
}

{
    "outcome": "not verified",
    "code": "106",
    "description": "INVALID ACCOUNT",
    "checkedAt": "2019-11-01T10:37:36.923Z",
    "riskFactors": [{
            "risk": "matched",
            "type": "cvc"
        },
        {
            "risk": "matched",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "matched",
            "detail": "address",
            "type": "avs"
        }
    ],
    "_links": {
        "verifications:verification": {
            "href": "https://try.access.worldpay.com/verifications/accounts/{resource}"
        },
        "curies": [{
            "name": "verifications:verification",
            "href": "https://try.access.worldpay.com/rels/verifications/accounts/{rel}",
            "templated": true
        }]
    }
}

Note: Verifications are accurate at the time of the initial request. Sending anotherintelligentordynamicverification request may return different results.

ACH verification

ACH verification gives you the ability to perform an account verification against a US bank account.

ACH verification request

For a ACH verification, POST your request to the verifications:ach action link received in yourquery the verifications root resourcerequest.

POST https://try.access.worldpay.com/verifications/accounts/ach

Example request body

ACH verification requests with mandatory fields only:

Copied!

{
  "merchant": {
    "entity": "default"
  },
  "transactionReference": "1234567",
  "paymentInstrument": {
    "type": "bankAccountUS",
    "accountType": "checking",
    "accountNumber": "1234567890",
    "routingNumber": "011400495",
    "billToAddress": {
      "firstName": "John",
      "lastName": "Smith",
      "address1": "address1",
      "city": "city",
      "region": "state",
      "postalCode": "postalCode",
      "countryCode": "US",
      "telephoneNumber": "4085551212"
    }
  }
}

{
  "merchant": {
    "entity": "default"
  },
  "transactionReference": "1234567",
  "paymentInstrument": {
    "type": "bankAccountUS",
    "accountType": "corporateSavings",
    "accountNumber": "1234567890",
    "routingNumber": "011400495",
    "companyName": "companyName",
    "billToAddress": {
      "address1": "address1",
      "city": "city",
      "region": "state",
      "postalCode": "postalCode",
      "countryCode": "US",
      "telephoneNumber": "4085551212"
    }
  }
}

Descriptions of your mandatory ACH verification request parameters:

Parameter	Required	Description
`merchant.entity`		Direct your verification to assist with billing, reporting and reconciliation. For more information contact yourRelationship Manager.
`transactionReference`		A unique reference generated by you that is used to identify a payment throughout its lifecycle. It can be up to 25 characters. Spaces, code brackets (< and >), quotation marks and pipes (\|) are not allowed. Please note that the format is different than the one used for card verifications.
`paymentInstrument`		An object that contains your customer's payment details.
`paymentInstrument.type`		An object that contains your customer's payment type. The only allowed value is: `bankAccountUS`
`paymentInstrument.accountType`		An object that contains your customer's payment account type. For Personal Account possible values: `checking` `savings` For Corporate Account possible values: `corporate` `corporateSavings`
`paymentInstrument.accountNumber`		An object that contains your customer's bank account number.
`paymentInstrument.routingNumber`		An object that contains your customer's bank routing number
`paymentInstrument.companyName`		An object that contains your customer's company name. This is a mandatory field for Corporate Account and must not be supplied for Personal Account.
`paymentInstrument.billToAddress`		An object containing the bill to address information. Mandatory fields include: `address1` `city` `region` `postalCode` `countryCode` `telephoneNumber`
`billToAddress.firstName`		An object that contains your customer's first name. This is a mandatory field for Personal Account.
`billToAddress.lastName`		An object that contains your customer's last name. This is a mandatory field for Personal Account.

Optional fields in an ACH verification request

ACH verification requests with optional and mandatory fields:

Copied!

{
  "merchant": {
    "entity": "default"
  },
  "transactionReference": "1234567",
  "paymentInstrument": {
    "type": "bankAccountUS",
    "accountType": "checking",
    "accountNumber": "1234567890",
    "routingNumber": "011400495",
    "billToAddress": {
      "firstName": "John",
      "lastName": "Smith",
      "address1": "address1",
      "address2": "address2",
      "address3": "address3",
      "city": "city",
      "region": "state",
      "postalCode": "postalCode",
      "countryCode": "US",
      "telephoneNumber": "4085551212"
    }
  }
}

{
  "merchant": {
    "entity": "default"
  },
  "transactionReference": "1234567",
  "paymentInstrument": {
    "type": "bankAccountUS",
    "accountType": "corporateSavings",
    "accountNumber": "1234567890",
    "routingNumber": "011400495",
    "companyName": "companyName",
    "billToAddress": {
      "firstName": "John",
      "lastName": "Smith",
      "address1": "address1",
      "address2": "address2",
      "address3": "address3",
      "city": "city",
      "region": "state",
      "postalCode": "postalCode",
      "countryCode": "US",
      "telephoneNumber": "4085551212"
    }
  }
}

Descriptions of your optional ACH verification request parameters:

Parameter	Required	Description
`paymentInstrument.billToAddress`		An object containing the bill to address information. Optional fields includes: `address2` `address3`
`billToAddress.firstName`		An object that contains your customer's first name. This is an optional field for Corporate Account.
`billToAddress.lastName`		An object that contains your customer's last name. This is an optional field for Corporate Account.

ACH verification response

In your response is a 201 HTTP response code and the historic outcome of the verification.

outcome:

verified
not verified

Copied!

{
  "outcome": "verified",
  "checkedAt": "2021-09-27T18:02:16.475Z",
  "_links": {
    "curies": [
      {
        "name": "verifications",
        "href": "https://try.access.worldpay.com/rels/verifications/accounts/{rel}",
        "templated": true
      }
    ]
  }
}

{
  "outcome": "not verified",
  "description": "Invalid account number",
  "checkedAt": "2021-09-27T18:02:16.475Z",
  "_links": {
    "curies": [
      {
        "name": "verifications",
        "href": "https://try.access.worldpay.com/rels/verifications/accounts/{rel}",
        "templated": true
      }
    ]
  }
}

Searching accross the entire site

Filter by product

Filter by product Searching across the entire site

Verify a customer's account

Intelligent verification

Intelligent verification request

oneTime intelligent verification

cardOnFile intelligent verification

Example request body

Optional fields in a verification request

Dynamic verification

Dynamic verification request

dynamicOneTime verification

dynamicCardOnFile verification

Example request body

Optional fields in a verification request

3DS

The descriptions of parameters from your 3DS authorization request

Apple Pay decrypted

Verification request example:

The descriptions of parameters from your Apple Pay decrypted authorization request

Verifications response

Risk Factors

Payment Instrument

Location storing

Query a historic verification

Query verifications request

Query verifications response

ACH verification

ACH verification request

Example request body

Optional fields in an ACH verification request

ACH verification response

Searching accross the entire site

Filter by product

Filter by product Searching across the entire site

​

`oneTime` intelligent verification

`cardOnFile` intelligent verification

`dynamicOneTime` verification

`dynamicCardOnFile` verification