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:

Business Verification

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

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.

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, 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

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

Business Verification

Bank Verification and Other Documents

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 to your Finix Dashboard and click Merchants > Merchant Accounts.
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.

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.

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

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 directly if you're collecting files and want to upload them on behalf of your users.
• Allow your users to upload a file directly from their browser
  • Create an external link to share with users so they can upload files directly from their browsers.
  • Create an external link when you don't have the files and don't plan on requesting them from users.

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.

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.

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

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

{
    "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 following example 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.

// 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/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>