Create an Identity

Create an Identity for your merchant or buyer.

All fields for a buyer's Identity are optional.

Providing business_type indicates that the Identity is being created for a Merchant.

Related Guides: Getting Started, Onboarding

Request
Request Body schema: application/hal+json
Any of:
object or null

Addition underwriting details required to verify Identities.

object

The underwriting details required to verify Identities.

object

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

Responses
201

Single Identity object

Response Schema: application/hal+json
Any of:
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 or null

Additional underwriting data that's required to verify the Identity.

application
string non-empty

ID of the Application associated with the Identity.

created_at
string <date-time>

Timestamp of when the object was created.

object

The underwriting details required to verify the Identity.

id
string non-empty

The ID of the Identity resource.

object

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

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

post/identities
Request samples
Response samples
application/hal+json
{}

List Identities

Retrieves a list of Identities.

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.

business_name
string

Filter by the full business name. Partial business names are not supported.

business_type
string

Filter by the business type. Partial business types are not supported.

created_at.gte
string

Filter where created_at is after the given date.

Example: created_at.gte=created_at.gte=2019-06-15
created_at.lte
string

Filter where created_at is before the given date.

Example: created_at.lte=created_at.lte=2019-06-15
default_statement_descriptor
string

Filter by the default_statement_descriptor.

email
string

Filter by the email address or email domain. Partial emails are not supported.

Example: email=user@example.org
first_name
string

Filter by the first name of the person associated to the Identity.

Example: first_name=first_name=Daphne
id
string

Filter by id.

last_name
string

Filter by the last name of the person associated to the Identity.

Example: last_name=kline
limit
integer

The numbers of items to return.

Example: limit=10
sort
string

Specify key to be used for sorting the collection.

title
string

Filter by the title if available.

Example: title=ceo
Responses
200

List of Identity objects

Response Schema: application/hal+json
object

List of Identity resources.

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/identities
Request samples
curl https://finix.sandbox-payments-api.com/identities \
  -H "Content-Type: application/vnd.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/hal+json
{}

Fetch an Identity

Retrieve the details of a previously created Identity.

Request
path Parameters
identity_id
required
string

ID of the Identity to fetch.

Responses
200

Single Identity object

Response Schema: application/hal+json
Any of:
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 or null

Additional underwriting data that's required to verify the Identity.

application
string non-empty

ID of the Application associated with the Identity.

created_at
string <date-time>

Timestamp of when the object was created.

object

The underwriting details required to verify the Identity.

id
string non-empty

The ID of the Identity resource.

object

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

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/identities/{identity_id}
Request samples
curl https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K \
  -H "Content-Type: application/vnd.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/hal+json
{}

Update an Identity

Update an existing Identity.

If you are updating the Identity of a Merchant that’s already been onboarded, you need to verify the merchant again.

Request
path Parameters
identity_id
required
string

ID of the Identity to fetch.

Request Body schema: application/hal+json
Any of:
object

Additional underwriting data that's required to verify the Identity of merchants.

object

Underwriting data that's required to verify the Identity.

object

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

Responses
200

Single Identity object

Response Schema: application/hal+json
Any of:
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 or null

Additional underwriting data that's required to verify the Identity.

application
string non-empty

ID of the Application associated with the Identity.

created_at
string <date-time>

Timestamp of when the object was created.

object

The underwriting details required to verify the Identity.

id
string non-empty

The ID of the Identity resource.

object

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

updated_at
string <date-time>

Timestamp of when the object was last updated.

400

Error

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

put/identities/{identity_id}
Request samples
Response samples
application/hal+json
{}

Create an Associated Identity

Create an associated Identity for every owner with 25% or more ownership over the merchant.

Request
path Parameters
identity_id
required
string

ID of Identity to associate object with.

Request Body schema: application/hal+json
object

Underwriting data that's required to verify the Identity.

object

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

Responses
201

Single Identity object

Response Schema: application/hal+json
Any of:
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 or null

Additional underwriting data that's required to verify the Identity.

application
string non-empty

ID of the Application associated with the Identity.

created_at
string <date-time>

Timestamp of when the object was created.

object

The underwriting details required to verify the Identity.

id
string non-empty

The ID of the Identity resource.

object

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

updated_at
string <date-time>

Timestamp of when the object was last updated.

400

Error

401

Authentication information is missing or invalid

403

Forbidden

404

Object does not exist

406

Not Acceptable

post/identities/{identity_id}/associated_identities
Request samples
curl https://finix.sandbox-payments-api.com/identities/IDgXNAaoy5d4TLkp5ze6gScA/associated_identities \
  -H "Content-Type: application/vnd.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
  -d '
{
    "entity": {
        "first_name": "John", 
        "last_name": "Smith", 
        "title": "Founder", 
        "dob": {
            "month": 1, 
            "day": 1, 
            "year": 2013
        }, 
        "principal_percentage_ownership": 25, 
        "phone": "1234567890", 
        "personal_address": {
            "city": "San Francisco", 
            "region": "CA", 
            "postal_code": "90650", 
            "line1": "123 Main Street", 
            "country": "USA"
        }, 
        "email": "john.smith@company1.com", 
        "tax_id": "123456789"
    }
}'
Response samples
application/hal+json
{}

List Associated Identities

Retrieve a list of Associated Identities for an Identity.

Request
path Parameters
identity_id
required
string

ID of Identity to associate object with.

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 Identity objects

Response Schema: application/hal+json
object

List of Identity resources.

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/identities/{identity_id}/associated_identities
Request samples
curl https://finix.sandbox-payments-api.com/identities/IDf33pdVaTZGXVFNccdKvaPu/associated_identities \
  -H "Content-Type: application/vnd.json+api" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
Response samples
application/hal+json
{}

Verify an Identity

Verify an Identity.

Request
path Parameters
identity_id
required
string

ID of Identity to verify.

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

404

Object does not exist

406

Not Acceptable

post/identities/{identity_id}/verifications
Request samples
Response samples
application/hal+json
{}