Verifications

Verifications are used to verify Identities and Payment Instruments.

For Identities, a verification represents an attempt to onboard and underwrite an identity.

For Payment Instruments, a verification represents getting additional information from the card brands to verify a card is eligible for push to card.

Related Guides: Onboarding with the API, Push to Card

List Merchant Verifications

Get a list of all the Verifications for a Merchant resource.

Request
path Parameters
merchant_id
required
string

ID of Merchant object.

query Parameters
after_cursor
string

Return every resource created after the cursor value.

before_cursor
string

Return every resource created before the cursor value.

limit
integer <int64>

The number of entries to return.

Responses
200

List of Verification objects

Response Schema: application/hal+json
object

List of Verifications.

object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

object

Details the page that's returned.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/merchants/{merchant_id}/verifications
Request samples 
curl https://finix.sandbox-payments-api.com/merchants/MUpaGK5dUb2Sb7aGuXhFRNbj/verifications \
  -H "Content-Type: application/vnd.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/hal+json
{}

List Payment Instrument Verifications

List all the Verifications created for a Payment Instrument.

Request
path Parameters
payment_instrument_id
required
string

ID of Payment Instrument object.

query Parameters
limit
integer <int64>

The number of entries to return.

offset
integer <int64>

The number of items to skip before starting to collect the result set.

pageNumber
integer <int64>

The page number to list.

pageSize
integer <int64>

The size of the page.

Responses
200

List of Verification objects

Response Schema: application/hal+json
object

List of Verifications.

object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

object

Details the page that's returned.

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

get/payment_instruments/{payment_instrument_id}/verifications
Request samples 
curl https://finix.sandbox-payments-api.com/payment_instruments/PImc5nvdnp15atLxEBAGtxJs/verifications/ \
  -H "Content-Type: application/vnd.json+api" \
  -u USpEbizhxFRAFT7oYgWjX87B:6d3ace2c-23f9-4e59-8b75-a1a5b8a53055
Response samples
application/hal+json
{}

Create a Merchant Verification

Create a Verification to verify a merchant's Identity.

Verifications can also be created directly on the resources you want to verify. For example:

  • POST /merchants/{merchant_id}/verifications
  • POST /payment_instruments/{payment_instrument_id}/verifications
Request
Request Body schema: application/hal+json
identity
string

ID of the Identity resource associated with the Merchant.

merchant
string

The ID of the Merchant.

processor
string or null

Set the acquiring processor. Avalible values include:

  • DUMMY_V1
  • LITLE_V1
  • MASTERCARD_V1
  • VISA_V1
  • NMI_V1
  • VANTIV_V1
Use DUMMY_V1 or null to use your sandbox. For more details on which processor to use, reach out to your Finix point of contact or email Finix Support.

object

Key value pair for annotating custom meta data (e.g. order numbers).

Responses
201

Single Verification object

Response Schema: application/hal+json
object

For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.

application
string

ID of the Application the Merchant was created under.

created_at
string <date-time>

Timestamp of when the object was created.

id
string

The ID of the Verification attempt (begins with VIXXX).

identity
string or null

ID of the Identity that created the Merchant.

merchant
string or null

ID of the Merchant resource.

merchant_identity
string or null

ID of the Identity associated with the Merchant.

messages
Array of objects

Provides additional details about the verification (e.g why it failed). This field is usually null.

payment_instrument
string or null

The Payment Instrument that'll be used to settle the Merchant's processed funds.

processor
string

Name of the verification processor.

(Raw (object or null)) or (Raw (string or null))

Raw response from the processor.

state
string

The status of the Verification request.

Enum: "PENDING" "SUCCEEDED" "FAILED"
object

Key value pair for annotating custom meta data (e.g. order numbers).

trace_id
string

Trace ID of the Verification. The processor sends back the trace_id so you can track the verification end-to-end.

updated_at
string <date-time>

Timestamp of when the object was last updated.

400

Error

401

Authentication information is missing or invalid

403

Forbidden

406

Not Acceptable

422

Invalid field

post/verifications
Request samples 
Response samples 
application/hal+json
{}
List Verifications
Retrieve a list of Verifications.


Request 
query Parameters
after_cursor
string
Return every resource created after the cursor value.


 
before_cursor
string
Return every resource created before the cursor value.


 
limit
integer
The numbers of items to return.


 
 Example:  limit=10
Responses 
200
List of Verification objects


Response Schema: application/hal+json
object
List of Verifications.


 
object
For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.


 
object
Details the page that's returned.


 
401
Authentication information is missing or invalid


403
Forbidden


406
Not Acceptable


get/verifications
Request samples 
curl https://finix.sandbox-payments-api.com/verifications \
  -H "Content-Type: application/vnd.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/hal+json
{}
Fetch a Verification
Retrieve the details of a Verification.


Request 
path Parameters
verification_id
required
string
ID of Verification object.


 
Responses 
200
Single Verification object


Response Schema: application/hal+json
object
For your convenience, every response includes several URLs which link to resources relevant to the request. You can use these _links to make your follow-up requests and quickly access relevant IDs.


 
application
string
ID of the Application the Merchant was created under.


 
created_at
string <date-time> 
Timestamp of when the object was created.


 
id
string
The ID of the Verification attempt (begins with VIXXX).


 
identity
string or null
ID of the Identity that created the Merchant.


 
merchant
string or null
ID of the Merchant resource.


 
merchant_identity
string or null
ID of the Identity associated with the Merchant.


 
messages
Array of objects
Provides additional details about the verification (e.g why it failed). This field is usually null.


 
payment_instrument
string or null
The Payment Instrument that'll be used to settle the Merchant's processed funds.


 
processor
string
Name of the verification processor.


 
(Raw (object or null)) or (Raw (string or null))
Raw response from the processor.


 
state
string
The status of the Verification request.


 Enum: "PENDING" "SUCCEEDED" "FAILED"  
object
Key value pair for annotating custom meta data (e.g. order numbers).


 
trace_id
string
Trace ID of the Verification. The processor sends back the trace_id so you can track the verification end-to-end.


 
updated_at
string <date-time> 
Timestamp of when the object was last updated.


 
401
Authentication information is missing or invalid


403
Forbidden


404
Object does not exist


406
Not Acceptable


get/verifications/{verification_id}
Request samples 
curl https://finix.sandbox-payments-api.com/verifications/VIbXwBuccEcqw7rfZneELCv4 \
  -H "Content-Type: application/vnd.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e

Response samples 
application/hal+json
{}