Finix Payments Identities API
{'$ref': 'api-descriptions/tags/identities.md'}
OpenAPI Specification
openapi: 3.0.2
info:
title: Finix Authorizations Identities API
description:
$ref: api-descriptions/main.md
contact:
name: Finix
url: https://finix.com
email: support@finixpayments.com
version: '2022-02-01'
servers:
- description: Sandbox server to be used for testing and development
url: https://finix.sandbox-payments-api.com
security:
- BasicAuth: []
tags:
- name: Identities
description:
$ref: api-descriptions/tags/identities.md
paths:
/identities:
post:
tags:
- Identities
description: "Create an `Identity` for your seller or buyer.\n\nAll fields for a buyer's `Identity` are optional. \n\nProviding `business_type` indicates that the `Identity` is being created for a Merchant.\n\nRelated Guides: [Getting Started](/guides/getting-started/), [Onboarding](/guides/onboarding/)"
summary: Create an Identity
operationId: createIdentity
requestBody:
$ref: '#/components/requestBodies/CreateIdentityRequest'
responses:
'201':
$ref: '#/components/responses/Identity'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: create
parameters:
- schema:
type: string
default: '2018-01-01'
example: '2022-02-01'
in: header
name: Finix-Version
description: Specify the API version of your request. For more details, see [Versioning.](/guides/developers/versioning/)
x-python-method-name: create
get:
tags:
- Identities
description: Retrieve a list of `Identities`.
summary: List Identities
operationId: listIdentities
parameters:
- $ref: '#/components/parameters/QueryAfterCursor'
- $ref: '#/components/parameters/QueryLimit'
- $ref: '#/components/parameters/QueryIdFilter'
- $ref: '#/components/parameters/QueryCreatedAtGteFilter'
- $ref: '#/components/parameters/QueryCreatedAtLteFilter'
- $ref: '#/components/parameters/QueryDefaultStatementDescriptorFilter'
- $ref: '#/components/parameters/QueryBusinessName'
- $ref: '#/components/parameters/QueryBusinessType'
- $ref: '#/components/parameters/QueryEmail'
- $ref: '#/components/parameters/QueryFirstName'
- $ref: '#/components/parameters/QueryLastName'
- $ref: '#/components/parameters/QueryTitle'
- $ref: '#/components/parameters/QueryBeforeCursor'
- $ref: '#/components/parameters/TagsKey'
- $ref: '#/components/parameters/TagsValue'
responses:
'200':
$ref: '#/components/responses/IdentitiesList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: list
x-group-parameters: true
x-codeSamples:
- lang: cURL
label: curl
source: "curl \"https://finix.sandbox-payments-api.com/identities\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Finix-Version: 2022-02-01\" \\\n -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e\n"
x-python-method-name: list
x-returns-list: true
/identities/{identity_id}:
parameters:
- description: ID of the `Identity` to fetch.
required: true
in: path
name: identity_id
schema:
type: string
get:
tags:
- Identities
description: Retrieve the details of a previously created `Identity`.
summary: Fetch an Identity
operationId: getIdentity
responses:
'200':
$ref: '#/components/responses/Identity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: get
x-codeSamples:
- lang: cURL
label: curl
source: "curl \"https://finix.sandbox-payments-api.com/identities/IDgWxBhfGYLLdkhxx2ddYf9K\" \\\n -H \"Finix-Version: 2022-02-01\" \\\n -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e\n"
x-python-method-name: get
put:
tags:
- Identities
description: '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](/api/tag/Merchants/#tag/Merchants/operation/createMerchantVerification).'
summary: Update an Identity
operationId: updateIdentity
requestBody:
$ref: '#/components/requestBodies/UpdateIdentityRequest'
responses:
'200':
$ref: '#/components/responses/Identity'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: update
x-codeSamples:
- lang: cURL
label: curl
source:
$ref: xcode/curl/identities/updateidentity.md
x-python-method-name: update
/identities/{identity_id}/associated_identities:
parameters:
- description: ID of `Identity` to associate object with.
required: true
in: path
name: identity_id
schema:
type: string
post:
tags:
- Identities
description: Create an associated `Identity` for [every owner with 25% or more ownership](/guides/onboarding/onboarding-with-api#step-3-add-associated-identities) over the merchant.
summary: Create an Associated Identity
operationId: createAssociatedIdentity
requestBody:
$ref: '#/components/requestBodies/CreateAssociatedIdentityRequest'
responses:
'201':
$ref: '#/components/responses/Identity'
'400':
$ref: '#/components/responses/ErrorUnprocessableEntity'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: createAssociatedIdentity
x-codeSamples:
- lang: cURL
label: curl
source: "curl \"https://finix.sandbox-payments-api.com/identities/IDgXNAaoy5d4TLkp5ze6gScA/associated_identities\" \\\n -H \"Content-Type: application/json\" \\\n -H \"Finix-Version: 2022-02-01\" \\\n -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e\n -d '\n{\n \"entity\": {\n \"first_name\": \"John\", \n \"last_name\": \"Smith\", \n \"title\": \"Founder\", \n \"dob\": {\n \"month\": 1, \n \"day\": 1, \n \"year\": 2013\n }, \n \"principal_percentage_ownership\": 25, \n \"phone\": \"14158885080\", \n \"personal_address\": {\n \"city\": \"San Francisco\", \n \"region\": \"CA\", \n \"postal_code\": \"90650\", \n \"line1\": \"123 Main Street\", \n \"country\": \"USA\"\n }, \n \"email\": \"john.smith@company1.com\", \n \"tax_id\": \"123456789\"\n }\n}'\n"
x-python-method-name: create_associated_identity
get:
tags:
- Identities
description: Retrieve a list of `Associated Identities` for an `Identity`.
summary: List Associated Identities
operationId: listIdentityAssociatedIdentities
parameters:
- required: false
in: query
name: limit
schema:
type: integer
format: int64
description: The number of entries to return.
- $ref: '#/components/parameters/QueryAfterCursor'
- $ref: '#/components/parameters/QueryBeforeCursor'
responses:
'200':
$ref: '#/components/responses/IdentitiesList'
'401':
$ref: '#/components/responses/ErrorUnauthorized'
'403':
$ref: '#/components/responses/ErrorForbidden403'
'404':
$ref: '#/components/responses/ErrorNotFound'
'406':
$ref: '#/components/responses/Error406NotAcceptable'
x-java-method-name: listAssociatedIdentities
x-group-parameters: true
x-codeSamples:
- lang: cURL
label: curl
source: "curl \"https://finix.sandbox-payments-api.com/identities/IDf33pdVaTZGXVFNccdKvaPu/associated_identities\" \\\n -H \"Finix-Version: 2022-02-01\" \\\n -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e\n"
x-python-method-name: list_associated_identities
x-returns-list: true
components:
schemas:
Error406NotAcceptable:
type: object
properties:
total:
type: integer
_embedded:
type: object
properties:
errors:
type: array
items:
type: object
additionalProperties: true
properties:
code:
type: string
enum:
- NOT_FOUND
logref:
$ref: '#/components/schemas/LogRef'
message:
type: string
_links:
type: object
properties:
source:
type: object
properties:
href:
type: string
title: ''
IdentitiesList:
type: object
properties:
page:
$ref: '#/components/schemas/PageCursor'
_embedded:
type: object
description: List of `Identity` resources.
properties:
identities:
type: array
uniqueItems: true
description: An `Identity` resource represents either a person or business in Finix.
items:
$ref: '#/components/schemas/Identity'
_links:
$ref: '#/components/schemas/ListLinks'
CreateIdentityRequest:
type: object
properties:
additional_underwriting_data:
type: object
description: "- Additional underwriting details required to verify `Identities`. \n- Required for any `Merchants` onboarded by Finix Flex customers. If you have any questions, please contact [Finix Support](/guides/business/support-at-finix/)."
nullable: true
properties:
annual_ach_volume:
type: integer
description: The approximate annual ACH sales expected to be processed (in cents) by this merchant (max 10 characters).
average_ach_transfer_amount:
type: integer
description: The approximate average ACH sale amount (in cents) for this merchant.
average_card_transfer_amount:
type: integer
description: The average credit card sale amount (in cents) for this merchant.
business_description:
type: string
description: Description of this merchant's business (max 200 characters).
card_volume_distribution:
type: object
description: The distribution of the merchant's credit card volume The sum of `card_volume_distribution` must be 100.
properties:
card_present_percentage:
type: integer
description: The percentage of the merchant's volume that's card present (between 0 and 100).
mail_order_telephone_order_percentage:
type: integer
description: The percentage of the merchant's business that is a mail order or telephone order (between 0 and 100).
ecommerce_percentage:
type: integer
description: The percentage of the merchant's business that is eCommerce (between 0 and 100).
credit_check_allowed:
type: boolean
description: Sets if this merchant has consented and accepted to a credit check.
credit_check_ip_address:
type: string
description: The IP address of the merchant when they consented to a credit check (e.g., 42.1.1.113 ).
minLength: 1
credit_check_timestamp:
type: string
minLength: 1
description: A timestamp of when this merchant consented to a credit check (e.g., 2021-04-28T16:42:55Z).
credit_check_user_agent:
type: string
minLength: 1
description: The details of the browser that was used when this merchant consented to a credit check (e.g., Mozilla 5.0 (Macintosh; Intel Mac OS X 10 _14_6)).
merchant_agreement_accepted:
type: boolean
description: Sets whether this merchant has accepted the terms and conditions of the merchant agreement.
merchant_agreement_ip_address:
type: string
description: IP address of the merchant when this merchant accepted the merchant agreement (e.g., 42.1.1.113).
minLength: 1
merchant_agreement_timestamp:
type: string
minLength: 1
description: Sets if this merchant has consented and accepted to a credit check.
merchant_agreement_user_agent:
type: string
description: The details of the browser that was used when this merchant accepted Finix's Terms of Service (e.g., Mozilla 5.0 (Macintosh; Intel Mac OS X 10 _14_6)).
minLength: 1
refund_policy:
type: string
description: The details of the browser that was used when this merchant consented to a credit check (e.g., Mozilla 5.0 (Macintosh; Intel Mac OS X 10 _14_6)).
enum:
- NO_REFUNDS
- MERCHANDISE_EXCHANGE_ONLY
- 30_DAYS
- OTHER
volume_distribution_by_business_type:
type: object
description: IP address of the merchant when this merchant accepted the merchant agreement (e.g., 42.1.1.113).
properties:
other_volume_percentage:
type: integer
description: The percentage of the merchant's volume that isn't represented by the previous fields (between 0 and 100).
consumer_to_consumer_volume_percentage:
type: integer
description: Merchant's percentage of volume that is consumer to consumer (between 0 and 100).
business_to_consumer_volume_percentage:
type: integer
description: The percentage of the merchant's volume that's business to consumer (between 0 and 100).
business_to_business_volume_percentage:
type: integer
description: The percentage of the merchant's volume that's business to business (between 0 and 100).
person_to_person_volume_percentage:
type: integer
description: The percentage of the merchant's volume that's person to person (between 0 and 100).
entity:
type: object
description: The underwriting details required to verify `Identities`.
properties:
annual_card_volume:
type: integer
description: The annual credit card sales (in cents) expected to be processed (max 19 characters).
business_address:
type: object
description: The primary address for the legal entity.
required:
- city
- country
- region
- line1
- postal_code
nullable: true
properties:
city:
type: string
minLength: 1
description: City (max 20 characters).
country:
type: string
minLength: 1
description: 3-Letter Country code (e.g. USA).
region:
type: string
minLength: 1
description: 2-letter state code.
line2:
type: string
minLength: 1
description: Second line of the address (max 35 characters).
line1:
type: string
minLength: 1
description: First line of the address (max 35 characters).
postal_code:
type: string
minLength: 1
description: Zip or Postal code (max 7 characters).
business_name:
type: string
description: The merchant's legal business name (max 120 characters).<ul><li>If **INDIVIDUAL_SOLE_PROPRIETORSHIP**, pass the owner's legal first name, last name and middle initial.</li><li>Special characters (e.g., <code>.</code><code>,</code><code>_</code><code>-</code><code>?</code><code>+</code><code>*</code> or <code>/</code>.) are not allowed.</li></ul>
nullable: true
business_phone:
type: string
description: Customer service phone number where the merchant can be reached (max 10 characters).
business_tax_id:
type: string
description: Nine digit Tax Identification Number (TIN), Employer Identification Number (EIN). If the `business_type` is **INDIVIDUAL\_SOLE\_PROPRIETORSHIP** and they do not have an EIN, use the sole proprietor's Social Security Number (SSN).
business_type:
type: string
description: The business entity type of the Merchant.
enum:
- INDIVIDUAL_SOLE_PROPRIETORSHIP
- CORPORATION
- LIMITED_LIABILITY_COMPANY
- PARTNERSHIP
- ASSOCIATION_ESTATE_TRUST
- TAX_EXEMPT_ORGANIZATION
- INTERNATIONAL_ORGANIZATION
- GOVERNMENT_AGENCY
default_statement_descriptor:
type: string
description: The description of the merchant that appears on the buyer's bank or card statement.
dob:
type: object
description: The control owner's date of birth.
required:
- day
- month
- year
properties:
day:
type: integer
description: Day of birth (between 1 and 31).
month:
type: integer
description: Month of birth (between 1 and 12).
year:
type: integer
description: Year of birth (4-digit). Year must be greater than 1900
doing_business_as:
type: string
description: Alternate names of the business. If there are no other names, pass the same value used for `business_name` (max 60 characters).
email:
type: string
description: The email address of the buyer where they can be reached (max 100 characters).
first_name:
type: string
description: The legal first name of the buyer (max 20 characters).
has_accepted_credit_cards_previously:
type: boolean
description: Defaults to **false** if not passed.
incorporation_date:
type: object
description: The date the company was founded and registered.
required:
- day
- month
- year
nullable: true
properties:
day:
type: integer
description: Day business was incorporated (between 1 and 31).
month:
type: integer
description: Month business was incorporated (between 1 and 12).
year:
type: integer
description: Year business was incorporated (4-digit).
last_name:
type: string
description: The legal last name of the buyer (max 20 characters).
max_transaction_amount:
type: integer
description: The maximum amount (in cents) that can be charged for a single transaction (max 12 characters).
ach_max_transaction_amount:
type: integer
description: The maximum amount (in cents) that can be charged for a single ACH transaction (max 12 characters).
mcc:
type: string
description: The Merchant Category Code ([MCC](http://www.dm.usda.gov/procurement/card/card\_x/mcc.pdf)) that this merchant will be classified under. For a list of approved MCCs, see [Approved Merchant Category Codes.](/docs/guides/business/security-and-compliance/approved-merchants/)
ownership_type:
type: string
description: "Avalible values include: <ul><li><strong>PUBLIC</strong> to indicate a publicly-traded company.<li><strong>PRIVATE</strong> for privately-held businesses.\n\nFor `business_type` of **GOVERNMENT_AGENCY** and **TAX_EXEMPT_ORGANIZATION** the `ownership_type` should be set to **PUBLIC**. \nFor `business_type` **INDIVIDUAL_SOLE_PROPRIETORSHIP**, the `ownership_type` should be set to **PRIVATE**."
enum:
- PUBLIC
- PRIVATE
nullable: true
personal_address:
type: object
description: The billing address of the buyer. This field is used for identity verification purposes.
required:
- city
- country
- line1
- postal_code
- region
properties:
city:
type: string
description: City (max 20 characters).
country:
type: string
description: 3-Letter country code (e.g. USA).
line1:
type: string
description: First line of the address (max 35 characters).
line2:
type: string
description: Second line of the address (max 35 characters).
postal_code:
type: string
description: Zip or Postal code (max 7 characters).
region:
type: string
description: 2-letter State code.
phone:
type: string
description: Phone number where the buyer can be reached.
principal_percentage_ownership:
type: integer
description: Percentage of the company owned by the principal control owner (min 0; max 100).
tax_id:
type: string
description: Pass one of the following values (nine digits):<ul><li>Social Security Number (SSN)<li>Tax Identification Number (TIN)<li>Individual Taxpayer Identification Number (ITIN)</ul>
title:
type: string
description: The corporate title of the control owner (e.g. Chief Executive Officer, CFO, etc. Max 60 characters).
url:
type: string
description: The URL of the merchant's public website.
required:
- annual_card_volume
- business_address
- business_name
- business_phone
- business_tax_id
- business_type
- default_statement_descriptor
- dob
- doing_business_as
- email
- first_name
- has_accepted_credit_cards_previously
- incorporation_date
- last_name
- max_transaction_amount
- ach_max_transaction_amount
- mcc
- ownership_type
- personal_address
- phone
- principal_percentage_ownership
- tax_id
- title
- url
tags:
$ref: '#/components/schemas/Tags'
Error401Unauthorized:
type: object
properties:
total:
type: integer
_embedded:
type: object
properties:
errors:
type: array
items:
type: object
additionalProperties: true
properties:
code:
type: string
enum:
- UNKNOWN
logref:
$ref: '#/components/schemas/LogRef'
message:
type: string
_links:
type: object
additionalProperties: true
properties:
self:
type: object
properties:
href:
type: string
source:
type: object
properties:
href:
type: string
ErrorGeneric:
type: object
properties:
total:
type: integer
_embedded:
type: object
properties:
errors:
type: array
items:
type: object
additionalProperties: true
properties:
code:
type: string
enum:
- FORBIDDEN
logref:
$ref: '#/components/schemas/LogRef'
message:
type: string
_links:
type: object
properties:
source:
type: object
properties:
href:
type: string
Tags:
type: object
title: tags
additionalProperties:
type: string
description: 'Include up to 50 `key`: **value** pairs to annotate requests with custom metadata.
- Maximum character length for individual `keys` is 40.
- Maximum character length for individual **values** is 500.
(e.g., `order number`: **25**, `item_type`: **produce**, `department`: **sales**, etc.)'
nullable: true
Identity:
description: ''
x-examples:
example-1:
id: IDpYDM7J9n57q849o9E9yNrG
application: APgPDQrLD52TYvqazjHJJchM
entity:
title: CEO
first_name: dwayne
last_name: Sunkhronos
email: user@example.org
business_name: Petes Coffee
business_type: INDIVIDUAL_SOLE_PROPRIETORSHIP
doing_business_as: Petes Coffee
phone: '14158885080'
business_phone: +1 (408) 756-4497
personal_address:
line1: 741 Douglass St
line2: Apartment 7
city: San Mateo
region: CA
postal_code: '94114'
country: USA
business_address:
line1: 741 Douglass St
line2: Apartment 8
city: San Mateo
region: CA
postal_code: '94114'
country: USA
mcc: '4900'
dob:
day: 27
month: 6
year: 1978
max_transaction_amount: 12000000
amex_mid: null
discover_mid: null
url: www.PetesCoffee.com
annual_card_volume: 12000000
has_accepted_credit_cards_previously: true
incorporation_date:
day: 27
month: 6
year: 1978
principal_percentage_ownership: 50
short_business_name: null
ownership_type: PRIVATE
tax_authority: null
tax_id_provided: true
business_tax_id_provided: true
default_statement_descriptor: Petes Coffee
tags:
Studio Rating: '4.7'
created_at: '2022-01-27T07:36:52.11Z'
updated_at: '2022-01-27T07:36:52.00Z'
additional_underwriting_data:
annual_ach_volume: 200000
average_ach_transfer_amount: 200000
average_card_transfer_amount: 200000
business_description: SB3 vegan cafe
card_volume_distribution:
card_present_percentage: 30
ecommerce_percentage: 60
mail_order_telephone_order_percentage: 10
credit_check_allowed: true
credit_check_ip_address: 42.1.1.113
credit_check_timestamp: '2021-04-28T16:42:55Z'
credit_check_user_agent: Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)
merchant_agreement_accepted: true
merchant_agreement_ip_address: 42.1.1.113
merchant_agreement_timestamp: '2021-04-28T16:42:55Z'
merchant_agreement_user_agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)
refund_policy: MERCHANDISE_EXCHANGE_ONLY
volume_distribution_by_business_type:
business_to_business_volume_percentage: 100
business_to_consumer_volume_percentage: 0
consumer_to_consumer_volume_percentage: 0
other_volume_percentage: 0
person_to_person_volume_percentage: 0
_links:
self:
href: https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG
verifications:
href: https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/verifications
merchants:
href: https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/merchants
settlements:
href: https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/settlements
authorizations:
href: https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/authorizations
transfers:
href: https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/transfers
payment_instruments:
href: https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/payment_instruments
associated_identities:
href: https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/associated_identities
disputes:
href: https://finix.sandbox-payments-api.com/identities/IDpYDM7J9n57q849o9E9yNrG/disputes
application:
href: https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM
title: ''
type: object
properties:
id:
type: string
minLength: 1
description: The ID of the `Identity` resource.
created_at:
$ref: '#/components/schemas/CreatedAt'
updated_at:
$ref: '#/components/schemas/UpdatedAt'
additional_underwriting_data:
type: object
description: Additional underwriting data that's required to verify the `Identity`.
nullable: true
properties:
annual_ach_volume:
type: integer
description: The approximate annual ACH sales expected to be processed (in cents) by this seller (max 10 characters).
average_ach_transfer_amount:
type: integer
descrip
# --- truncated at 32 KB (97 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/finix-payments/refs/heads/main/openapi/finix-payments-identities-api-openapi.yml