Uploading Files to Finix

During the onboarding process. Sometimes Finix may reject an onboarding attempt and require additional information. Depending on the rejection reason, you'll be prompted to upload files to Finix to clear those exceptions.

The files you'll need to upload contain personal information and can only be submitted through Finix. Request these files from users via a secure link or a secure upload. Don't request users submit files via email or other unsecured methods.

Finix's underwriting team reviews the uploaded files and verifies them with the information that was first submitted when creating an identity. Reasons you may be prompted to upload files can be to complete:

  • Identity verification
  • Business verification
  • Bank verification
  • PCI Compliance

This guide details how to upload documents using Finix. You can upload documents using the Finix Dashboard or Finix's API:

  • If you have the necessary documents in hand, you can upload files for sellers using the Finix Dashboard. For more information, see Finix Dashboard .
  • You can use Finix's API to request files from sub-merchants who need to complete verification with Finix's underwriting team. Once approved by our underwriting team, you can make another provisioning request .

When to Upload files to Finix

When you initially create an identity, Finix reviews the information submitted to confirm the identity complies with Finix's terms of service.

If a review is rejected, Finix alerts you by sending a reject code via our webhooks. The reject code that you receive indicates why the review was rejected and what files need to be uploaded and reviewed by Finix's underwriting team.

Reject codes that require a file to be uploaded include:

Identity Verification

These rejection codes are returned while verifying the owners of the merchant or platform:

Reject Code Description Steps needed for approval
ID_VERIFICATION_NEEDED ID Verification of owner(s) needed. Submit a valid Driver's License, Government issued ID, or Passport.
ID_VERIFICATION_FAILED ID Verification was unsuccessful. Verify the ID used for verification matches the owner's full name, is readable, and is not expired. Upload the document again to Finix.

Business Verification

These rejection codes are returned when verifying information about the business.

Reject Code Description Steps needed for approval
TAX_ID_VERIFICATION_NEEDED EIN or Tax ID verification needed. Upload a copy of your EIN Issuance Letter or Tax ID document.
TAX_ID_VERIFICATION_FAILED EIN or Tax ID documentation could not be verified. Verify the EIN Issuance Letter or Tax ID document is clearly visible. Upload the document again to Finix.

Bank Account Verification

These rejection codes are returned when verifying the owners of the merchant or platform and the bank account information submitted with the merchant application.

Reject Code Description Steps needed for approval
BANK_VERIFICATION_NEEDED Bank account requires verification. Upload 3 months of bank statements showing bank account number, account holder name, and bank logo. The statement must confirm the details of the bank account belongs to the business or control owner.
BANK_VERIFICATION_FAILED Bank statement could not be verified. Verify the account number, account holder name, and bank logo are clearly visible in the statement. Upload the document again to Finix.

For information on the other kinds of reject codes, see Reject codes.

If you receive a reject code from Finix, before you can process any payments, you'll need to upload the required files to Finix to clear any exceptions and complete underwriting.

Requirements for file Uploads

Before you upload any file or document to Finix, it must meet the following requirements:

  • Allowed formats: JPEG, JPG, PNG, TIFF, or PDF
  • Allowed size:
    • For PDFs: minimum 1 KB, maximum 10 MB
    • All other formats: minimum 100 KB, maximum 10 MB

Additionally, some document types need to be uploaded in a specific orientation so Finix's underwriting team can capture the data accurately for review. The different types of documents you may be asked to provide and how you should upload them are:

Identity Verification

Document type type value
Government issued ID Card: Upload the front and back with separate File IDs IDENTIFICATION_CARD_FRONT, IDENTIFICATION_CARD_BACK
Passport: Upload the front/data page PASSPORT
Driver’s License: Upload the front and back with separate File IDs DRIVERS_LICENSE_FRONT, DRIVERS_LICENSE_BACK

Note: ID cards and Driver’s Licenses must be uploaded horizontally.

Business Verification

Document type type value
Tax Document: 3 months of bank statements TAX_DOCUMENT
Business Registration: EIN issuance letters and other documents used to register the business. BUSINESS_REGISTRATION
Business Address Verification: A utility bill BUSINESS_ADDRESS_VERIFICATION

Bank Verification and Other Documents

Document type type value
Bank document: 3 months of bank statements BANK_STATEMENT
Other: For all other file uploads, please use other. OTHER

How to Upload a file to Finix

You have two options to upload files to Finix:

  • Finix Dashboard : Use the Finix Dashboard when you already have the files you need to upload.
  • Finix's API : Use Finix's API to request and upload files from merchants.

Finix Dashboard

To upload files using the Finix Dashboard:

  1. Log in and navigate to the PEOPLE header—click Merchants .
  2. Select the merchant . Click the FILES tab on the top navigation bar.
  3. Click Upload File and enter the name you want to give the file. Select the Document Type .
  4. Drag and drop the file you want to upload and click Upload File .

Uploading files on the Finix Dashboard

If the upload is successful a green banner will appear. You can view the file in your browser by clicking the File ID.

Finix's API

Uploading a file using Finix's API is a two step process:

  1. Create a File resource
  2. Upload a file to the File resource

With this two step process:

  • Merchants can upload files directly from their preferred browser without needing to authenticate with Finix credentials.
  • Uploaded files are scanned for viruses before landing anywhere critical like a server or personal computer.

Step 1: Create a File

Create a File resource with the type of document and the merchant the file should be linked to.

Copy
Copied
curl -X POST \
  https://finix.sandbox-payments-api.com/files \
  -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -H 'Content-Type: application/vnd.api+json' \
  -H 'Finix-Version:2022-02-01' \
  -d '{
    "display_name": "My Drivers License",
    "linked_to": "MU2n7BSovtwYsWYZF6rBnnzk",
    "type": "DRIVERS_LICENSE_FRONT",
	"tags": {
        "key_1": "value_1"
     }
}'

A successful creation returns the File object with a status of REQUIRES_UPLOAD. Next, you need to upload a file.

Step 2: Upload the file

You have two choices on how to upload a file when using Finix's API:

Upload Directly to Finix

Upload the file to the File resource you created in Step 1. This is a multi part post that includes the file.

Copy
Copied
curl 'https://finix.sandbox-payments-api.com/files/FILE_bJecqoRPasStEPVpvKHtgA/upload' \
    -H 'Content-Type: multipart/form-data' \
    -H 'Finix-Version:2022-02-01' \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -F "file"="@/Users/Desktop/finix_file.png"

A successful upload returns the File object with a status of PENDING.

Create an External Link

An external_link is a temporary link that end users use to directly upload files from their browsers. This allows your users to upload documents without the files ever touching your own servers.

Create an external_link with the type UPLOAD.

Copy
Copied
curl https://finix.sandbox-payments-api.com/files/FILE_bJecqoRPasStEPVpvKHtgA/external_links \
    -H "Content-Type: application/vnd.api+json" \
    -H 'Finix-Version:2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{
        "type": "UPLOAD",
        "duration": 15
    }'

A successful creation returns the external_link object with url populated with the link your user can use to upload the file.

Copy
Copied
{
    "id": "EL_n4baDHgeidWcst61qzf1Aq",
    "created_at": "2022-02-25T16:18:47.641122-08:00",
    "url": "http://finix-file-quarantine-sb.s3.us-east-2.amazonaws.com/.../upload/FILE_bJecqoRPasStEPVpvKHtgA/...",
    "type": "UPLOAD",
    "expires_at": "2022-02-25T16:28:47.631612-08:00",
    "user_id": "USsRhsHYZGBPnQw8CByJyEQW",
    "file_id": "FILE_bJecqoRPasStEPVpvKHtgA",
    "tags": {
        "key": "value"
    },
    "expired": false
}

Use this URL to help your user upload the file. The example below shows how the above URL could be used in a simple JavaScript upload form. The users file needs to be uploaded to Finix via a PUT request:

When users return the needed files, upload them to Finix via a PUT request.

Copy
Copied
// Step 1: Create an HTML form 
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <title>File Upload</title>
  </head>

  <body>
    <form id="upload">
      <input type="file" id="file" name="filename" />
      <input type="submit" />
    </form>
  </body>
   <script>  
    const postFile = async function (e) { // Step 2: Include a script so the HTML form can accept file uploads
      e.preventDefault()
// Step 3: Include the domain of Finix's API and your username and credentials
      const file = document.getElementById('file').files[0];
      const api = 'https://finix.sandbox-payments-api.com/';
      
      const username = 'USsRhsHYZGBPnQw8CByJyEQW';             // replace with your username
      const password = '8a14c2f9-d94b-4c72-8f5c-a62908e5b30e'; // replace with your password

      const request_headers = {
        Authorization: 'Basic ' + window.btoa(username + ':' + password),
        'Content-Type': 'application/vnd.api+json',
      };

      // Step 4: Create the File resource
      const file_response = await fetch(`${api}/files`, {
        method: 'POST',
        headers: request_headers,
        body: JSON.stringify({
          display_name: file.name, // Set a display name for the file
          linked_to: 'MU2n7BSovtwYsWYZF6rBnnzk', // Include the merchant ID the file is being uploaded for
          type: 'DRIVERS_LICENSE_FRONT', // The type of file being uploaded
        }),
      });

      const file_data = await file_response.json();
      const file_id = file_data.id;

      // Step 5: Create an external link to upload the file to
      const external_link_response = await fetch(`${api}/files/${file_id}/external_links`, {
        method: 'POST',
        headers: request_headers,
        body: JSON.stringify({ type: 'UPLOAD' }),
      });

      const external_link_data = await external_link_response.json();
      const upload_url = external_link_data.url;

      // Step 6: Prompt your user to upload the file directly
      const upload_response = await fetch(upload_url, {
        method: 'PUT',
        headers: {
          'Content-Type': 'multipart/form-data',
        },
        body: file,
      });

      if (upload_response.status === 200) {
        alert('file successfully uploaded');
      } else {
        alert('there was an error uploading the file');
      }
    }

    document.getElementById('upload').addEventListener('submit', postFile);
  </script>
</html>