# Verifies a card

POST {{baseURL}}/pay-api/v1/transactions/card-verification
This endpoint verifies a card's details with the issuing bank without charging it.
This checks the card against AVS (address verification service) and the security code.
No funds are authorized, captured, or held against the card.
This is useful for validating a card, such as before saving it as a customer's payment method, without processing a payment.
See Also:
To authorize a transaction, see POST /pay-api/v1/transactions/auth.
To create a transaction, see POST /pay-api/v1/transactions/sale.
To retrieve a transaction by ID, see GET /pay-api/v1/transactions/{transactionId}.

Endpoint: POST /pay-api/v1/transactions/card-verification
Version: V1
Security: Bearer

## Security:

  - `Bearer` (unknown)
    http bearer JWT

## Request fields (application/json):

  - `accountNumber` (string)
    Specifies the card number to verify.
We recommend using `paymentMethodId` instead of `accountNumber`.
This field may contain a token issued against a card number.
This is de-tokenized by TransIT to process the verification.
Example: 4111111111111111
    Example: 4111111111111111

  - `paymentMethodId` (string)
    Specifies the customer payment method identifier.
We recommend using `paymentMethodId` instead of `accountNumber`.
Example: b4c48037-4c5d-4e6f-7a8b-9c0d1e2f3a69
    Example: b4c48037-4c5d-4e6f-7a8b-9c0d1e2f3a69

  - `expirationMonth` (integer, required)
    Specifies the expiration month of the card.

Example: 7
    Example: 7

  - `expirationYear` (integer, required)
    Specifies the expiration year of the card.

Example: 2032
    Example: 2032

  - `cardDataSource` (integer)
    Specifies the card data source.
Possible values:
| Value | Name | Description |
|  --- | --- | --- |
| 1 | Internet | Virtual Terminal, ISV API |
| 2 | Swipe | Track1, Track2 |
| 3 | NFC | EMV Tags, Track2 |
| 4 | EMV | EMV Tags |
| 5 | EMVContactless | EMV Tags |
| 6 | FallbackSwipe | Track 2 |
| 7 | Manual | Card present keyed transaction |

Example: 2
    Example: 2

  - `paymentProcessorId` (string)
    Specifies the payment processor identifier.
A list of available payment processers can be found with `GET {{baseURL}}/pay-api/v1/configurations/payments`.
See response `availablePaymentProcessors.id`.
If omitted, the merchant's default payment processor will be used.
Example: 37bd9ccb-2c9d-45cf-a65f-c9a224bdeaeb
    Example: 37bd9ccb-2c9d-45cf-a65f-c9a224bdeaeb

  - `customerId` (string)
    Specifies the customer identifier.
This is used when saving the payment method.
If this value is provided, the payment method is saved to the specified customer.
If this value is not provided, a new customer record is created.
Example: fd9198a4-eb6f-4620-9603-4f4638289de5
    Example: fd9198a4-eb6f-4620-9603-4f4638289de5

  - `deviceId` (string)
    Specifies the device when using the Flute mobile app.
If this value is included, the user is linked to that device.
This stores their name as the verification creator `createdBy`.
Example: a30f9b66-b2f0-4b18-a03a-b861b00afa8b
    Example: a30f9b66-b2f0-4b18-a03a-b861b00afa8b

  - `appVersion` (string)
    Specifies the version of the mobile app.
This value is stored on the verification record.
The `appVersion` value takes priority over the `sdkVersion` if both are present.
Example: 10.413.01
    Example: 10.413.01

  - `sdkVersion` (string)
    Specifies the version of the Flute SDK.
This value is stored on the verification record.
The `appVersion` value takes priority over the `sdkVersion` if both are present.
Example: 8.61.01
    Example: 8.61.01

  - `billingAddress` (object)
    Specifies an object defining the address.

  - `billingAddress.city` (string, required)
    Specifies the name of the city.

Example: Chicago
    Example: Chicago

  - `billingAddress.countryId` (integer, required)
    Specifies the Flute country identifier.
Example: 1
    Example: 1

  - `billingAddress.line1` (string)
    Specifies the street address.

Example: 322 Unicorn Boulevard
    Example: 322 Unicorn Boulevard

  - `billingAddress.line2` (string)
    Specifies additional street address information.

Example: Apt. Block 6
    Example: Apt. Block 6

  - `billingAddress.postalCode` (string)
    Specifies the postal or ZIP code.
Examples:
60601
60601-0001
    Example: 60601-0001

  - `billingAddress.stateName` (string)
    Indicates the full state name.
Examples:
Texas
Washington
Illinois
    Example: Illinois

  - `billingAddress.stateId` (integer)
    Specifies the Flute US state or territory identifier code.
Example: 1
    Example: 1

  - `securityCode` (string)
    Specifies the three or four digit security code on the credit card.

Example: 123
    Example: 123

  - `track1` (string)
    Specifies the card data from track 1 of the magnetic stripe.
Example: %B4111111111111111^Smith/John^12121010000000000000?
    Example: %B4111111111111111^Smith/John^12121010000000000000?

  - `track2` (string)
    Specifies the information stored on the magnetic stripe of a credit or debit card, including the card number, expiration date, and cardholder's name.
Example: 4111111111111111=200257999
    Example: 4111111111111111=200257999

  - `referenceId` (string)
    Specifies an external identifier for client-side tracking.

Also used in duplicate control validation.
A unique value allows similar verification requests to process as distinct, bypassing duplicate blocking when needed.

Example: REF-EXT-12345
    Example: REF-EXT-12345

## Response 200:

  - `200` (unknown)
    OK

## Response 200 fields (application/json):

  - `transactionId` (string)
    Indicates the verification record's identifier.

Example: c7c15dd0-03e7-4e55-917c-54bedafba5e7
    Example: c7c15dd0-03e7-4e55-917c-54bedafba5e7

  - `transactionDateTime` (string)
    Indicates the date and time (in an ISO 8601 date-time UTC format) of the verification.

Example: 2026-02-19T20:24:52.934Z
    Example: 2026-02-19T20:24:52.934Z

  - `typeId` (integer)
    Indicates the type identifier of the verification.
Valid values are:
| Value | Name | Description |
|  --- | --- | --- |
| 8 | CardVerification | Identifies the record as a card verification. |

Example: 8
    Example: 8

  - `type` (string)
    Indicates the type name of the verification.
Valid values are:
| Value | Description |
|  --- | --- |
| CardVerification | Identifies the record as a card verification. |

Example: CardVerification
    Example: CardVerification

  - `statusId` (integer)
    Indicates the status identifier of the verification.
Valid values are:
| Value | Name | Description |
|  --- | --- | --- |
| 1 | Verified | The card and billing details matched the issuing bank's records. |
| 2 | Declined | The card or billing details did not match, and verification was declined. |
| 3 | Failed | The verification could not be completed due to a processing error. |

Example: 1
    Example: 1

  - `status` (string)
    Indicates the status name of the verification.
Valid values are:
| Value | Description |
|  --- | --- |
| Verified | The card and billing details matched the issuing bank's records. |
| Declined | The card or billing details did not match, and verification was declined. |
| Failed | The verification could not be completed due to a processing error. |

Example: Verified
    Example: Verified

  - `details` (object)
    Indicates additional processor-level response details for the transaction.

  - `details.hostResponseCode` (string)
    Indicates a two-character response code for the status of the authorization request.

Example: 00
    Example: 00

  - `details.hostResponseMessage` (string)
    Indicates the response message from the authorization host.

Example: APPROVAL
    Example: APPROVAL

  - `details.hostResponseDefinition` (string)
    Indicates the definition of the host response code.

Example: Approved and completed
    Example: Approved and completed

  - `details.code` (string)
    Indicates the high-level operation response.
Valid values are:
| Value | Description |
|  --- | --- |
| Approve | The operation was approved. |
| Decline | The operation was declined. |
| Error | The operation encountered a processing error. |

Example: Approve
    Example: Approve

  - `details.message` (string)
    Indicates a free-form result description.

Example: Success
    Example: Success

  - `details.processorResponseCode` (string)
    Indicates the processor-specific response code that precisely describes the operation result.

Example: 1000
    Example: 1000

  - `details.authCode` (string)
    Indicates the authorization code received for the transaction.

Example: VTLMC1
    Example: VTLMC1

  - `details.maskedPan` (string)
    Indicates the customer’s PAN (primary account number).
This is the payment card number.
The value is partially masked, or blocked, for security.
Example: ********3743
    Example: ********3743

  - `avsResponse` (object)
    Indicates the Address Verification Service (AVS) response.

  - `avsResponse.actionId` (integer)
    Possible values:
| Value | Name |
|  --- | --- |
| 1 | Allow |
| 2 | Deny |

Example: 1
    Example: 1

  - `avsResponse.action` (string)
    Indicates the AVS action.
Valid values are:
| Value | Description |
|  --- | --- |
| Allow | The transaction is allowed to proceed. |
| Deny | The transaction is denied because of the AVS result. |

Example: Allow
    Example: Allow

  - `avsResponse.responseCode` (string)
    Indicates the AVS response code.

This is a processor-specific code describing the AVS match result.

Example: 0
    Example: 0

  - `avsResponse.groupId` (integer)
    Possible values:
| Value | Name |
|  --- | --- |
| 1 | NoMatch |
| 2 | PartialMatch |
| 3 | Incompatible |
| 4 | Unavailable |
| 5 | ValidGroup |

Example: 5
    Example: 5

  - `avsResponse.group` (string)
    Indicates the AVS code group.
Valid values are:
| Value | Description |
|  --- | --- |
| NoMatch | None of the address data matched. |
| PartialMatch | Some of the address data matched. |
| Incompatible | The address data could not be compared due to a format mismatch. |
| Unavailable | AVS is not available for this transaction or card type. |
| ValidGroup | All of the address data matched. |

Example: ValidGroup
    Example: ValidGroup

  - `avsResponse.resultId` (integer)
    Possible values:
| Value | Name |
|  --- | --- |
| 1 | Passed |
| 2 | Failed |

Example: 1
    Example: 1

  - `avsResponse.result` (string)
    Indicates the AVS response result.
Valid values are:
| Value | Description |
|  --- | --- |
| Passed | All address data is correct. |
| Failed | Some address data is incorrect. |

Example: Passed
    Example: Passed

  - `avsResponse.codeDescription` (string)
    Indicates the AVS response code description.

Example: Street Address and ZIP Code Match the information on file.
    Example: Street Address and ZIP Code Match the information on file.

## Response 400:

  - `400` (unknown)
    Bad Request

## Response 400 fields (application/json):

  - `details` (string)
    Indicates details about the error.

Example: Validation failed: -- Email: 'Email' is not a valid email address. Severity: Error
    Example: Validation failed: -- Email: 'Email' is not a valid email address. Severity: Error

  - `statusCode` (integer)
    Specifies the HTTP response status code.
This is the HTTP status code returned by the attempted delivery.
The following is a list of HTTP response status codes that include but are not limited to:
| HTTP Status | Meaning |
|  --- | --- |
| 200 | Delivery succeeded |
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Endpoint not found |
| 429 | Rate limited |

Example: 401
    Example: 401

  - `source` (string)
    Indicates the source of the error.

Example: FluteOpsDeveloper.MSG322
    Example: FluteOpsDeveloper.MSG322

  - `exceptionType` (string)
    Indicates the error's exception type.

Example: FluentValidation.ValidationException
    Example: FluentValidation.ValidationException

  - `correlationId` (string)
    Indicates the correlation identifier.

Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef
    Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef

  - `entityId` (string)
    Indicates the entity identifier.
Example:
null

  - `errorCode` (string)
    Indicates the error code.
Example:
null

  - `errors` (object)
    Indicates the collection of validation errors, keyed by field name.
Example:
{ "Email": ["'Email' is not a valid email address."] }

## Response 404:

  - `404` (unknown)
    Resource not found

## Response 404 fields (application/json):

  - `details` (string)
    Indicates details about the error.

Example: Entity with ID 'aa6cfcd0-0295-4a4c-b074-8c901f114fef' was not found.
    Example: Entity with ID 'aa6cfcd0-0295-4a4c-b074-8c901f114fef' was not found.

  - `statusCode` (integer)
    Specifies the HTTP response status code.
This is the HTTP status code returned by the attempted delivery.
The following is a list of HTTP response status codes that include but are not limited to:
| HTTP Status | Meaning |
|  --- | --- |
| 200 | Delivery succeeded |
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Endpoint not found |
| 429 | Rate limited |

Example: 401
    Example: 401

  - `source` (string)
    Indicates the source of the error.

Example: FluteOpsDeveloper.MSG322
    Example: FluteOpsDeveloper.MSG322

  - `exceptionType` (string)
    Indicates the error's exception type.

Example: System.Collections.Generic.KeyNotFoundException
    Example: System.Collections.Generic.KeyNotFoundException

  - `correlationId` (string)
    Indicates the correlation identifier.

Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef
    Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef

  - `entityId` (string)
    Indicates the entity identifier.
Example:
null

  - `errorCode` (string)
    Indicates the error code.
Example:
null

## Response 500:

  - `500` (unknown)
    Internal Error

## Response 500 fields (application/json):

  - `details` (string)
    Indicates details about the error.

Example: An unexpected error occurred while processing the request.
    Example: An unexpected error occurred while processing the request.

  - `statusCode` (integer)
    Specifies the HTTP response status code.
This is the HTTP status code returned by the attempted delivery.
The following is a list of HTTP response status codes that include but are not limited to:
| HTTP Status | Meaning |
|  --- | --- |
| 200 | Delivery succeeded |
| 400 | Bad request |
| 401 | Unauthorized |
| 404 | Endpoint not found |
| 429 | Rate limited |

Example: 401
    Example: 401

  - `source` (string)
    Indicates the source of the error.
Example: <Service>
    Example: (Service)

  - `exceptionType` (string)
    Indicates the error's exception type.

Example: System.Exception
    Example: System.Exception

  - `correlationId` (string)
    Indicates the correlation identifier.

Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef
    Example: aa6cfcd0-0295-4a4c-b074-8c901f114fef

  - `entityId` (string)
    Indicates the entity identifier.
Example:
null

  - `errorCode` (string)
    Indicates the error code.
Example:
null