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:
- Log in to your Finix Dashboard and click Merchants > Merchant Accounts .
-
Select the
Merchant
. Click the FILES tab on the top navigation bar. - Click Upload File and enter the name you want to give the file. Select the Document Type .
- 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:
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/vnd.api+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/vnd.api+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/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>