Uploading Files

Learn how to upload files to Finix.

Uploading Files with the Dashboard

To upload files from Finix's dashboard:

Inside your dashboard, navigate to your Seller's Identity page
On their Identity page, navigate to their Files tab
Use the Upload File button to upload their file

You will see a green banner after the file uploads successfully.

Uploading Files with the API

To upload files with Finix's File API:

Create a File resource
Upload your file to the File resource

Seller Onboarding File Upload Diagram

Step 1: Create a `File` resource

Create a File resource with the document's type, display name, and Merchant the file belongs to.

Request

curl "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 \
    -X POST \
    -d '{
        "display_name": "Bank Statement (January 2024)",
        "linked_to": "MU2n7BSovtwYsWYZF6rBnnzk",
        "type": "DRIVERS_LICENSE_FRONT"
    }'

Response

{
    "id": "FILE_fk2YvD9cpr6Xgq5WaCd1Aq",
    "status": "REQUIRES_UPLOAD",
    "created_at": "2024-12-25T01:56:27.601941Z",
    "updated_at": "2024-12-25T01:56:27.619529Z",
    "linked_type": "MERCHANT",
    "linked_to": "MU2n7BSovtwYsWYZF6rBnnzk",
    "extension": null,
    "display_name": "Bank Statement (January 2024)",
    "type": "DRIVERS_LICENSE_FRONT",
    "platform_id": "PLm5E6FbtCZ5vjpCaKhq5PwN",
    "application_id": "APgPDQrLD52TYvqazjHJJchM",
    "tags": {},
    "identity_id": "ID82tmeBrw6ithr8DjDnAdVb"
}

Step 2: Upload your file to the `File` resource

To upload your file to the File resource, you can either:

Upload the file directly (for example, if the file is stored on your own servers).
Use an external_link to let your seller upload the file directly from their browser.

Option 1: Upload the file directly

Use the /upload endpoint to upload the file directly to the File resource:

Request

curl "https://finix.sandbox-payments-api.com/files/FILE_3iNDtFwPaAE2iTTBzUiJK8/upload" \
    -H 'Content-Type: multipart/form-data' \
    -H 'Finix-Version: 2022-02-01' \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -F "file=@{{file_path}}"

This request is asynchronous. Finix will respond with a File object with status: PENDING, and afterward the status to UPLOADED after the file finishes uploading (typically, this takes about 60 seconds).

File Resource

{
    "id": "FILE_3iNDtFwPaAE2iTTBzUiJK8",
    "status": "PENDING",
    "created_at": "2024-08-27T22:02:38.170135Z",
    "updated_at": "2024-08-27T22:02:38.181962Z",
    "linked_type": "MERCHANT",
    "linked_to": "MU2n7BSovtwYsWYZF6rBnnzk",
    "extension": "png",
    "display_name": "Bank Statement (January 2024)",
    "type": "DRIVERS_LICENSE_FRONT",
    "platform_id": "PLm5E6FbtCZ5vjpCaKhq5PwN",
    "application_id": "APgPDQrLD52TYvqazjHJJchM",
    "tags": {},
    "identity_id": "ID82tmeBrw6ithr8DjDnAdVb"
}

Option 2: Upload the file with an `external_link`

Alternatively, you can create an external_link that your user can use to upload the file directly from their browser. This lets your users upload documents without the files ever touching your own servers. To do this, start by creating an external_link with type: UPLOAD.

External Link Request

curl "https://finix.sandbox-payments-api.com/files/FILE_jyLRzpcLcvUh8yCuTdRJE8/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"
    }'

External Link Response

{
    "id": "EL_3zJ3B4UYMWrLPyYSdL65hX",
    "created_at": "2024-08-27T22:09:51.396334Z",
    "url": "https://finix-file-quarantine-sb.s3.us-east-2.amazonaws.com/MERCHANT/MU2n7BSovtwYsWYZF6rBnnzk/DRIVERS_LICENSE_FRONT/FILE_vhbDpyGKGUAUtBZnBv67AQ/file?X-Amz-Security-Token=IQoJb3JpZ2luX2VjEAYaCXVzLWVhc3QtMiJHMEUCIQDqZMMyXnwQkuWLRrOOyLoQnqaOZKpz8UDTq07CDgdDrgIgL1XJpGqc9nJPAJ6vHOgxG%2F8XRsxD4idH7dQ%2BrdnKlG4q%2BQQIHxACGgwzNzU2MzU1NzAwNzAiDHZtIXMx1embf%2BSOMirWBB77UW%2FTQu19mMt7ERQjJ5IYVR%2BykbtVYVQXFYrVLg6Hla5Qv8ncxm3%2BiWnN9%2BcWlnz1d0g1lX7indpff8tjHbnZRrLVNbfJbKQISRgb5qIxcHKXfUuvZvBYKhlqZe%2BEJ3x%2BbD1A4EdLf35wRFq%2FZscST24XGIQkB99GaJeaEH0pL%2BrWdhgE%2FpJHxuTfCVVR6sia7tLltC3CSwd8DJZCrqIEZjaFa69I%2FXvcwnz3VRvofEcgUcbEGTrUCmWS3cK1IpcvBZg1dQj4KC6Ds8%2FSK7DaWDfEtYpwyKfRVGDE6PzbHsNHkn7GEtM7%2FQcZ18mReMOzb0kjd5apPvbrLJiduxOAJC3q7lRRn3NN24mhc844PLrZAKgD4XqDuRUzh1IQrCByWAE%2Boq8pnRwGMfMzVHkr%2FXCiJrQzt7rGh1okNxFx8WR5You4xN1uHLeZuN9AHa37wMB%2FMAIS12NwmHwSy9WO5c60rnS8sof0qCEiN4Qx3uLr8LLc%2F3JeEEni1Tb2Og3kcnY0qZmSXKHZe7r3dSvet6RVT33Cxt8YIzwKWdCMy%2FT7ACE%2Br5mJWMynmLXfs%2B2nceYYWoabSTAoMte%2BRz%2BgsCqmTRg9eXns8ITFH7nxakDhf3zLDqByWHIkBRlv0SVAKb%2F31tGzeAdGheAF1zaltbVEnAwz7U0zFPeDtKpRXxiBcXivUpHHHEkXHJeIHjdfM1r%2FH6E7ASY4CSvbw3eMEw9j1EB0eLxej8xquTRpW6%2F5adT0bcfM0ZGEt3EjD7YFKtGvs4wuzmhG4imJS7c%2BoAnFXIww1pm5tgY6mgFXwaweuRLsT4LlKvxRBw1Kj0%2BeyMjTwgWnINHAVGzrmt4XHfHrZxEyY0CCF%2Fw%2B1yjxxRFwMT83zzgI4YzLF%2FX6nK989O9Lv%2F6QrIO%2Fx5am9ksDCybEkth5u1hkSuaUV4pZP4fZjSqTzM1j%2B3JMVSPsVdnCVPW8UFTKuuFk1y62ImovKuAcET1Pq4JRUc2AZkjNPRUkC6HewLSk&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20240827T220951Z&X-Amz-SignedHeaders=host&X-Amz-Expires=899&X-Amz-Credential=ASIAVO5M75WLGULA5QPJ%2F20240827%2Fus-east-2%2Fs3%2Faws4_request&X-Amz-Signature=5e973b4aa7a7f6ac4026b88bf1470efa334bde06adb51837e559b74c7df06ae6",
    "type": "UPLOAD",
    "expires_at": "2024-08-27T22:24:51.380464Z",
    "user_id": "USsRhsHYZGBPnQw8CByJyEQW",
    "file_id": "FILE_vhbDpyGKGUAUtBZnBv67AQ",
    "duration": null,
    "tags": {},
    "expired": false
}

See below for an example of how to embed the external_link into an HTML form, including making a PUT request to the url to upload the file.

Embedded External Link Snippet

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

File Types

Bank statement (one month)

Type: BANK_STATEMENT_ONE_MONTH
Accepted documents: 1 month bank statements, signed bank verification letter
Expected format: Account number, routing number, and account owner name must be clearly visible

Bank statement (three months)

Type: BANK_STATEMENT_THREE_MONTHS
Accepted documents: 3 month bank statements
Expected format: Account number, routing number, and account owner name must be clearly visible

Business incorporation document

Type: BUSINESS_INCORPORATION_DOCUMENT
Accepted documents: Articles of Incorporation
Expected format: Must be original business registration document

Business registration document

Type: BUSINESS_REGISTRATION_DOCUMENT
Accepted documents: Secretary of State filing
Expected format: Must be active state filing

Business tax ID document

Type: BUSINESS_TAX_ID_DOCUMENT
Accepted documents: Form CP-575, Form 147C
Expected format: Must not be EIN Application form

Business tax exemption status document

Type: BUSINESS_TAX_EXEMPTION_STATUS_DOCUMENT
Accepted documents: Form 1023-EZ, Form T3010 (CAN)
Expected format: Must prove business tax exemption status

Business address document

Type: BUSINESS_ADDRESS_DOCUMENT
Accepted documents: Utility bill, lease
Expected format: Must display active business address

Business ownership structure

Type: BUSINESS_OWNERSHIP_STRUCTURE
Accepted documents: Diagram, cap table
Expected format: Must illustrate business ownership structure

Owner government-issued photo ID

Type: OWNER_GOVERNMENT_ISSUED_PHOTO_ID
Accepted documents: Driver's License, passport, residence card
Expected format: Must clearly show owner's name and face and not be expired

Owner tax ID document

Type: OWNER_TAX_ID_DOCUMENT
Accepted documents: SSN Card, TIN Card, SIN Card (CAN)
Expected format: Must clearly show owner's name and tax ID and not be expired