New API Version | Last Updated: 25 July 2024 | Change Log

Verify a customer's card

Verify your customer's card or make a name inquiry.

Card Verification

• Card Verification
  Verify and validate your customer's card details to protect you against fraud.

• Name Inquiry
  Visa have mandated that acquirers offering OCTs and AFTs must offer a way for you to check the validity of a name on the card. This is important if you make payouts so you can check that the person receiving the payout is who they say they are.

Example request

POST https://try.access.worldpay.com/cardVerifications

{
  "type": "cardVerification",
  "merchant": {
    "entity": "default"
  },
  "transactionReference": "Memory265-13/08/1876",
  "instruction": {
    "nominalRetry": true,
    "value": {
      "currency": "GBP"
    },
    "narrative": {
      "line1": "MindPalace",
      "line2": "Memory"
    },
    "paymentInstrument": {
      "type": "card/plain",
      "cardHolderName": "Sherlock Holmes",
      "expiryDate": {
        "month": 5,
        "year": 2050
      },
      "cardNumber": "4444333322221111",
      "billingAddress": {
        "address1": "221B Baker Street",
        "address2": "Marylebone",
        "address3": "Westminster",
        "postalCode": "NW1 6XE",
        "city": "Cambridge",
        "countryCode": "GB"
      }
    }
  }
}

Parameter descriptions

Name Inquiry

• Name Inquiry
  Visa have mandated that acquirers offering OCTs and AFTs must offer a way for you to check the validity of a name on the card. This is important if you make payouts so you can check that the person receiving the payout is who they say they are.

Example request

POST https://try.access.worldpay.com/cardVerifications

{
  "type": "nameInquiry",
  "merchant": {
    "entity": "default"
  },
  "instruction": {
    "paymentInstrument": {
      "type": "card/plain",
      "cardNumber": "4444333322221111",
      "expiryDate": {
        "month": 5,
        "year": 2035
      },
      "cvc": "123"
    },
    "cardHolder": {
      "firstName": "William",
      "middleName": "Sherlock Scott",
      "lastName": "Holmes"
    }
  }
}

Parameter descriptions

Test Values

Test Cardholder Name Inquiry outcomes using the values below:

3DS

You can optionally submit 3DS parameters for card verification requests.

To get the customer authentication object you must complete an authentication request using our 3DS API.

Example Request

{
  "type": "cardVerification",
  "merchant": {
    "entity": "default"
  },
  "transactionReference": "Memory265-13/08/1876",
  "instruction": {
    "value": {
      "amount": 250,
      "currency": "GBP"
    },
    "narrative": {
      "line1": "MindPalace",
      "line2": "Memory"
    },
    "paymentInstrument": {
      "type": "card/plain",
      "cardHolderName": "Sherlock Holmes",
      "expiryDate": {
        "month": 5,
        "year": 2050
      },
      "cardNumber": "4444333322221111",
      "billingAddress": {
        "address1": "221B Baker Street",
        "address2": "Marylebone",
        "address3": "Westminster",
        "postalCode": "NW1 6XE",
        "city": "Cambridge",
        "countryCode": "GB"
      },
      "cvc": "101"
    }
  },
  "authentication": {
    "threeDS": {
      "eci": "05",
      "version": "2.1.0",
      "authenticationValue": "MAAAAAAAAAAAAAAAAAAAAAAAAAA=",
      "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645",
      "cryptogramAlgorithm": "2",
      "challengePreference": "challengeMandated",
      "authenticationFlow": "challenge",
      "statusReason": "11",
      "cancellationIndicator": "01",
      "networkScore": "00",
      "brand": "cartesBancaires"
    }
  }
}

3DS Paramaters

You can view the full details for our authentication object in our API Reference.

Apple Pay decrypted

You can optionally submit Apple Pay decrypted parameters for card verification requests.

Example request

{
  "type": "cardVerification",
  "merchant": {
    "entity": "default"
  },
  "transactionReference": "Memory265-13/08/1876",
  "instruction": {
    "value": {
      "amount": 250,
      "currency": "GBP"
    },
    "narrative": {
      "line1": "MindPalace",
      "line2": "Memory"
    },
    "paymentInstrument": {
      "type": "card/networkToken+applepay",
      "cardHolderName": "Sherlock Holmes",
      "expiryDate": {
        "month": 5,
        "year": 2050
      },
      "tokenNumber": "4444333322221111"
    }
  },
  "authentication": {
    "networkToken": {
      "eci": "05",
      "cryptogram": "2.1.0"
    },
    "threeDS": {
      "eci": "05",
      "authenticationValue": "MTIzNDU2Nzg5MDEyMzQ1Njc4OTA=",
      "version": "2.1.0",
      "transactionId": "c5b808e7-1de1-4069-a17b-f70d3b3b1645"
    }
  }
}

Apple Pay decrypted parameter descriptions

You can view the full details for the "card/networkToken+apple" paymentInstrumentin our API Reference.

Risk Factors

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

Funds Transfers

A funds transfer is a money movement for a reason other than for the purchase of goods or services. These are also referred to as Account Funding Transactions (AFTs).

Examples:

• Loading a wallet with funds using a card (including stored value digital wallets and crypto or trading wallets)
• Adding funds to a pre-paid card using another card
• Sending money to another person (for example as a gift)

    "instruction": {        
        "fundsTransfer": {
            "type": "transfer",
            "purpose": "crypto",
           }
      }

Response

You receive:

• a 200 (name inquiry) or 201 (card verification) HTTP response code
• a verification outcome (either verified or not verified)
• an issuer response code and description (not verified result only), and a refusalAdvice code (not verified result only and MasterCard is the only card that may return this)
• a schemeTransactionReference for card on file only (not all issuers return this)
• riskFactors
• a paymentInstrument

{
    "outcome": "verified",    
    "scheme": {
        "reference": "MCCYQ2PBT0626"
    },
    "checkedAt": "2024-06-26T14:33:22.780572Z",
    "riskFactors": [
        {
            "risk": "matched",
            "type": "cvc"
        },
        {
            "risk": "notSupplied",
            "detail": "postcode",
            "type": "avs"
        },
        {
            "risk": "notSupplied",
            "detail": "address",
            "type": "avs"
        }
    ],
    "paymentInstrument": {
        "type": "card/plain+masked",
        "countryCode": "GB",
        "brand": "mastercard",
        "fundingType": "credit",
        "issuerName": "BANK OF SCOTLAND PLC",
        "category": "consumer"
    },
    "_links": {
        "cardVerifications:verification": {
            "href": "https://access.worldpay.com/cardVerifications/MjpHbzRkTGNDVnh1alJzN3NFdG1LSGZnPT06QUVTL0NCQy9QS0NTNVBhZGRpbmc6SktwM2Q0MkFsM2RORlV2NnhkendYTlFZcHlPMmxUeUs0TVlpY0srUmtBcVY4Sk1tRGJaaGVMQ3ZDWjZ0M2dJdDE3Vi94VHhFZHdZR0NXbFlXL1gxSmFUaEZXaHhzbWtzT0xHdlpBc2pPUGZ3eVE3bVRpZVNncVN2NTJRQ3c5QVo="
        }
    }
}

Payment Instrument

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

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 your verifications response.