Validate a Credit Card

POST /cardpayments/v1/accounts/account_id/verifications

This request verifies that the customer's card is valid, but without actually charging an amount on the card. For example, you may want to verify a credit card before adding it to a customer profile for future billing transactions.

You can also use the request to verify that a payment token, which represents a credit card, is valid – a check you should perform before attempting to convert a temporary, single-use token into a permanent payment token. Single-use tokens are valid for only 15 minutes and are not consumed by verification. See the API Reference section for further information.

To process a verification, you must initiate a POST request to the verifications endpoint with a card object containing the card details you wish to check.

See our full API documentation for a complete description of the parameters required for the Verification request.
Request Example
curl -X POST https://api.test.paysafe.com/cardpayments/v1/accounts/89987201/verifications \
  -u devcentre322:B-qa2-0-53625f86-302c021476f52bdc9deab7aea876bb28762e62f92fc6712d0214736abf501e9675e55940e83ef77f5c304edc7968 \
  -H 'Content-Type: application/json' \
  -d ' {
	"merchantRefNum": "merchant ABC-444",
	"card": {
		"cardNum": "4111111111111111",
		"cardExpiry": {
			"month": 2,
			"year": 2027
		},
		"cvv": "123"
	},
	"profile": {
		"firstName": "Joe",
		"lastName": "Smith",
		"email": "Joe.Smith@canada.com"
	},
	"billingDetails": {
		"street": "100 Queen Street West",
		"city": "Toronto",
		"state": "ON",
		"country": "CA",
		"zip": "M5H2N2"
	},
	"customerIp": "204.91.0.12",
	"description": "This is a test transaction"
}'

By default, the card processing system will check for duplicate transactions.

Prior to trying the example, you should:

  • Replace the account number (89987201) in the URL with the test account number you have received.
  • Replace the API key (after the -u) with the API key you have received.
  • Provide a unique merchant reference number for each transaction.

The request contains the following parameters:

Element Child Element Type Required? Description
merchantRefNum

string
length<=255

Yes This is the merchant reference number created by the merchant and submitted as part of the request. A unique merchant reference number must be provided for each transaction.
card cardNum

string
length=8-20

Yes This is the card number used for the request.
cardExpiry object Yes

This is the card's expiry date. The following parameters are required:

  • month – number, length=2
  • year – number, length=4
cvv

string
length=3-4

No This is the 3- or 4-digit security code that appears on the card following the card number.
profile firstName string
length<=80

No

This is the customer's first name.

lastName string
length<=80
No This is the customer's last name.
email string
length<=255
No This is the customer's email address.
billingDetails street

string
length<=50

No This is the first line of the street address in the billing address.
city

string
length<=40

No This is the city in the billing address.
state string
length<=40
No This is the state/province in the billing address.
country string
length=2
No This is the country in the billing address.
zip string
length<=10
No This is the zip/postal code in the billing address.
customerIp

string
length<=39

No This is the customer's IP address.
description

string
length<=255

No This is a description of the transaction, provided by the merchant.
Response Example
{
  "links":[
    {
      "rel":"self",
      "href":"https://api.test.paysafe.com/cardpayments/v1/accounts/99000/verifications/e50e19a6-8edd-44ec-abc4-18d0a97d51d8"
    }
  ],
  "id":"e50e19a6-8edd-44ec-abc4-18d0a97d51d8",
  "merchantRefNum":"merchant ABC-444",
  "card":{
    "type":"VI",
    "lastDigits":"1111",
    "cardExpiry":{
      "month":2,
      "year":2027
    }
  },
  "authCode":"026189",
  "profile":{
    "firstName":"Joe",
    "lastName":"Smith",
    "email":"Joe.Smith@canada.com"
  },
  "billingDetails":{
    "street":"100 Queen Street West",
    "city":"Toronto",
    "state":"ON",
    "country":"CA",
    "zip":"M5H 2N2"
  },
  "customerIp":"204.91.0.12",
  "description":"This is a test transaction",
  "txnTime":"2017-12-14T15:12:18Z",
  "currencyCode":"USD",
  "avsResponse":"MATCH",
  "cvvVerification":"MATCH",
  "status":"COMPLETED"
}

The response parameters not included in the initial request are described below:

Element Child Element Type Description
links array of link objects This parameter contains a single self link which can be used to fetch details about this verification at any time.
id string
length<=36
This is the unique ID for this verification operation. This ID can be used to look up the result of the verification at a later date by appending the ID to the verifications URL as shown in the self link.
card lastDigits

string
length=4

This is the last four digits of the card used for the request.
type enum

The type of card used in the request. Possible values are:

  • AM – American Express
  • DC – Discover
  • JC – JCB
  • MC – Mastercard
  • MD – Maestro
  • SO – Solo
  • VI – Visa
  • VD – Visa Debit
  • VE – Visa Electron
authCode string
length<=50
This is the authorization code returned by the issuing bank.
txnTime string This is the transaction time and date in UTC format.
currencyCode string
length=3

This is the three-digit currency code. This is the currency of the merchant account specified in the account_id request URL parameter account_id.

avsResponse enum

This is the Address Verification Service (AVS) response from the card issuer:

  • MATCH
  • MATCH_ADDRESS_ONLY
  • MATCH_ZIP_ONLY
  • NO_MATCH
  • NOT_PROCESSED
  • UNKNOWN

The address in the billingDetails object in the request is verified against the address the issuer has on file for the card.

cvvVerification enum

This is the response to the CVV submitted with the transaction request. Possible values are:

  • MATCH
  • NO_MATCH
  • NOT_PROCESSED
  • UNKNOWN
status enum

This is the status of the verification. Possible values are:

  • RECEIVED – Our system has received the request and is waiting for the downstream processor’s response.
  • COMPLETED – The transaction has been completed.
  • FAILED – The transaction failed, due to an error or by being declined.

Did you find this page useful?