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.
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 | 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 | 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:
| |
| cvv | string | 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. | |
| string length<=255 | No | This is the customer's email address. | ||
| billingDetails | street | string | No | This is the first line of the street address in the billing address. |
| city | string | 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 | No | This is the customer's IP address. | |
| description | string | No | This is a description of the transaction, provided by the merchant. |
{
"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 | 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:
| |
| 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:
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:
| |
| status | enum | This is the status of the verification. Possible values are:
|