Onboarding Business Customers

Onboard business customers to enable cross-border payments and payouts through Fin.com’s platform. This guide walks you through creating business customer profiles, uploading verification documents, and managing the compliance workflow.

Prerequisites

Before you begin, ensure you have:

API credentials: Client ID and secret from the API Keys section
Access token: Generated via POST /v1/oauth/token
Catalogue data: Familiarity with /v1/industries, /v1/purposes, and /v1/source-of-funds endpoints

Onboarding Steps

Step	Endpoint	Description
1. Fetch Catalogue Data	GET /v1/industries, GET /v1/purposes?type=BUSINESS, GET /v1/source-of-funds?type=BUSINESS	Retrieve valid IDs for industries, purposes, and fund sources
2. Create Customer	POST /v1/customers/business	Submit company details, addresses, financial profile, and associated parties (UBOs)
3. Upload Documents	POST /v1/customers/upload	Upload business and associated party documents
4. Attach Business Docs	POST /v1/customers/business/attach	Link ownership structure, company details, and legal presence documents with TOS acceptance
5. Attach Party Docs	POST /v1/customers/associated-parties/individual/attach	Link identity and address proofs for each associated party
6. Monitor Status	Webhooks: `customer.status`	Track verification progress (INCOMPLETE → REVIEWING → APPROVED)

Request Body Structure

Verification Type (Optional)

Verification type determines how customer identity is validated. STANDARD uses traditional document verification (default). RELIANCE leverages third-party KYC data when enabled for your client.

{
  "verification_type": "STANDARD"
}

The verification_type field is optional and defaults to STANDARD if omitted.

RELIANCE verification must be explicitly enabled for your client. If not available, you’ll receive a 423 error with message: "RELIANCE is not available for your client"

Basic Information (Required)

Company details exactly as shown on incorporation documents. All fields must use only English (Latin) characters.

Fields:

Field	Type	Description	Example
`business_name`	string	Full legal name from Certificate of Incorporation	`"Acme Corporation"`
`business_trade_name`	string	Brand or DBA (Doing Business As) name	`"Acme"`
`description`	string	Description of the company’s business activities	`"Software development"`
`entity_type`	enum	Legal entity structure (see table below)	`"LIMITED_LIABILITY_COMPANY"`
`website`	string (uri)	Company website URL	`"https://acmecorp.com"`
`email`	string (email)	Business email address — must be all lowercase	`"[email protected]"`
`incorporation_date`	string (date)	Date of incorporation in YYYY-MM-DD format	`"2020-01-15"`
`phone`	string	Business phone number in E.164 format — country/area code must match `country_of_incorporation`	`"+14155552671"`
`country_of_incorporation`	string	ISO Alpha-3 country code	`"USA"`
`registration_number`	string	Business registration number	`"87-1234567"`
`tax_id`	string	Tax identification number (EIN for USA businesses)	`"12-3456789"`

Email must be all lowercase or validation will fail. Convert to lowercase before sending: [email protected] ✓ not [email protected] ✗

Valid Entity Types:

Entity Type	Description
`LIMITED_LIABILITY_COMPANY`	Limited Liability Company (LLC)
`PRIVATE_LIMITED`	Private Limited Company (Pte Ltd)
`PUBLICLY_LISTED_COMPANY`	Publicly traded corporation
`CORPORATION`	Corporation (Inc, Corp)
`SOLE_PROPRIETOR`	Sole proprietorship
`PARTNERSHIP`	Partnership
`TRUST`	Trust
`PRIVATE_FOUNDATION`	Private foundation
`CHARITY`	Charitable organization
`NONPROFIT_ORGANIZATION`	Non-profit organization
`PUBLIC_AGENCY_OR_AUTHORITY`	Government agency or authority

Financial Profile (Required)

Describes business purpose, industry, transaction volume, and fund sources. Use catalogue endpoints to fetch valid IDs.

Fields:

Field	Type	Description	How to Get Value
`purpose_id`	integer	Account purpose	GET /v1/purposes?type=BUSINESS
`other_purpose`	string	Custom purpose (only when purpose_id = “Other”)	User input
`business_industry_id`	integer	Industry classification	GET /v1/industries
`monthly_volume`	integer	Expected monthly volume in USD (not cents)	User estimate: `50000`
`source_of_fund_id`	integer	Source of funds	GET /v1/source-of-funds?type=BUSINESS
`third_party_fund_usage`	boolean	Processing funds on behalf of others	User confirmation

Third-Party Fund Usage: Set to true only if this business will be processing, holding, or moving funds on behalf of other parties (e.g., payment processors, escrow services, money services). This triggers enhanced compliance review. See High-Risk Business Activities for details.

For most normal businesses (SaaS companies, import/export, consulting agencies), third_party_fund_usage should be false. Only MSBs, payment facilitators, and similar businesses should set this to true.

Example:

{
  "financial_profile": {
    "purpose_id": 10,
    "business_industry_id": 1,
    "monthly_volume": 50000,
    "source_of_fund_id": 13,
    "third_party_fund_usage": false
  }
}

In this example: purpose_id: 10 = Cross-border payouts, business_industry_id: 1 = Technology, monthly_volume: 50000 = $50,000 USD (integer, not cents), source_of_fund_id: 13 = Sales revenue.

Addresses (Required)

Registered and operational addresses for the business.

Fields:

Field	Required	Description
`is_incorporated_address_same`	Yes	`true` if physical and incorporated addresses are identical
`incorporated_address`	Yes	Registered address from incorporation papers
`physical_address`	Conditional	Operating address (required only if different from incorporated address)

Address Object:

Field	Type	Description	Example
`street`	string	Street address	`"123 Market Street Suite 400"`
`city`	string	City name	`"San Francisco"`
`state`	string	State/province code from /v1/countries//subdivisions	`"US-CA"`
`postal_code`	string	Postal or ZIP code	`"94103"`
`country`	string	ISO Alpha-3 country code	`"USA"`

Avoid P.O. Boxes — Use verifiable street addresses for both incorporated and physical addresses. P.O. Boxes may be rejected during verification.

Example:

{
  "addresses": {
    "is_incorporated_address_same": false,
    "incorporated_address": {
      "street": "10 Anson Road #26-04 International Plaza",
      "city": "Singapore",
      "state": "SG-01",
      "postal_code": "079903",
      "country": "SGP"
    },
    "physical_address": {
      "street": "456 Market Street Floor 3",
      "city": "San Francisco",
      "state": "US-CA",
      "postal_code": "94103",
      "country": "USA"
    }
  }
}

Associated Parties (Minimum 1 Required)

UBO (Ultimate Beneficial Owner): Individuals with ≥10% ownership OR significant control over the entity. All must be disclosed for regulatory compliance.

Each associated party must include: basic_info (all fields required):

Field	Description
`first_name`	First name
`last_name`	Last name
`dob`	Date of birth (YYYY-MM-DD)
`email`	Email address
`phone`	Phone number in E.164 format
`country_of_residence`	ISO Alpha-3 country code
`nationality`	ISO Alpha-3 country code
`tin`	Tax Identification Number

address (all fields required): Residential address with same structure as business address (street, city, state, postal_code, country). ownership_info (all fields required):

Field	Type	Description
`designation`	string	Role or position (e.g., CEO, Director, UBO)
`percentage_of_ownership`	number	Percentage of ownership in the business
`relationship_establishment_date`	string (date)	When relationship was established (YYYY-MM-DD)

Ownership Validation: Total ownership percentages across all associated parties must be > 0.01% and < 100%. The system validates this constraint.

Example:

{
  "associated_parties": [
    {
      "basic_info": {
        "first_name": "John",
        "last_name": "Smith",
        "dob": "1985-03-20",
        "email": "[email protected]",
        "phone": "+14155551234",
        "country_of_residence": "USA",
        "nationality": "USA",
        "tin": "123-45-6789"
      },
      "address": {
        "street": "456 Oak Avenue",
        "city": "San Francisco",
        "state": "US-CA",
        "postal_code": "94102",
        "country": "USA"
      },
      "ownership_info": {
        "designation": "CEO",
        "percentage_of_ownership": 75.00,
        "relationship_establishment_date": "2020-01-15"
      }
    },
    {
      "basic_info": {
        "first_name": "Jane",
        "last_name": "Doe",
        "dob": "1988-07-12",
        "email": "[email protected]",
        "phone": "+14155555678",
        "country_of_residence": "USA",
        "nationality": "USA",
        "tin": "987-65-4321"
      },
      "address": {
        "street": "789 Pine Street Apt 12",
        "city": "San Francisco",
        "state": "US-CA",
        "postal_code": "94109",
        "country": "USA"
      },
      "ownership_info": {
        "designation": "CFO",
        "percentage_of_ownership": 25.00,
        "relationship_establishment_date": "2020-01-15"
      }
    }
  ]
}

Metadata (Optional)

Custom key-value pairs for internal tracking:

{
  "meta_data": {
    "reference": "REF-20250123-ACME",
    "internal_notes": "Enterprise tier customer",
    "sales_rep": "[email protected]"
  }
}

Document Upload & Attachment

After creating the business customer, you must upload and attach verification documents.

Step 1: Upload Documents

Upload files using multipart/form-data:

curl --request POST \
  --url https://sandbox.api.fin.com/v1/customers/upload \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'customer_id=2d0a9df3-e1e5-4955-9759-ce0522e0ddc9' \
  --form 'file1=@/path/to/certificate_of_incorporation.pdf' \
  --form 'file2=@/path/to/shareholder_registry.pdf'

Allowed file types: PDF, JPG, JPEG, PNG Response:

{
  "data": {
    "files": [
      {"file1": "/AbAcQ4hn_0652746727637.pdf"},
      {"file2": "/XyZ123mn_0652746727638.pdf"}
    ]
  }
}

Save these URIs—you’ll use them in the attachment requests.

Step 2: Attach Business Documents

Link documents to the business customer:

curl --request POST \
  --url https://sandbox.api.fin.com/v1/customers/business/attach \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "customer_id": "2d0a9df3-e1e5-4955-9759-ce0522e0ddc9",
  "ownership_structure": [
    {
      "type": "SHAREHOLDER_REGISTRY",
      "files": [{"uri": "/XyZ123mn_0652746727638.pdf"}]
    }
  ],
  "company_details": [
    {
      "type": "CERT_OF_INCORPORATION",
      "files": [{"uri": "/AbAcQ4hn_0652746727637.pdf"}]
    }
  ],
  "legal_presence": [
    {
      "type": "PROOF_OF_ADDRESS",
      "files": [{"uri": "/PoAdef45_0652746727639.pdf"}]
    }
  ],
  "tos_policies_value": "f11e77c6-8dc0-4d4b-a3f2-ed84c8ccfc69"
}'

The tos_policies_value should be parsed from the tos_policies_url query parameter returned when creating the customer. Providing this value signifies that the customer was shown the terms and accepted them.

Document Types:

Category	Type	Description
`ownership_structure`	`SHAREHOLDER_REGISTRY`	Shareholder registry or cap table
`company_details`	`CERT_OF_INCORPORATION`	Certificate of incorporation
`company_details`	`MEMORANDUM_OF_ASSOCIATION`	Memorandum of association
`legal_presence`	`PROOF_OF_ADDRESS`	Utility bill, lease agreement, or bank statement

Step 3: Attach Associated Party Documents

Upload identity and address proofs for each UBO:

curl --request POST \
  --url https://sandbox.api.fin.com/v1/customers/associated-parties/individual/attach \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'Content-Type: application/json' \
  --data '{
  "customer_id": "2d0a9df3-e1e5-4955-9759-ce0522e0ddc9",
  "associated_party_attachments": [
    {
      "associated_party_id": "a7c3b4e2-d8f1-4a5c-9e7d-2f6b8c3a1e9f",
      "proof_of_identity": {
        "type": "NATIONAL_ID",
        "number": "A12345678",
        "country": "USA",
        "issue_date": "2020-01-15",
        "expiry_date": "2030-01-15",
        "files": [
          {"side": "FRONT", "uri": "/id_front_john_0652746727640.pdf"},
          {"side": "BACK", "uri": "/id_back_john_0652746727641.pdf"}
        ]
      },
      "proof_of_address": {
        "type": "UTILITY_BILL",
        "country": "USA",
        "files": [
          {"uri": "/utility_john_0652746727642.pdf"}
        ]
      }
    }
  ]
}'

The associated_party_id is returned in the GET /v1/customers/ response after creating the business customer.

For NATIONAL_ID and DRIVERS_LICENSE, you must provide both FRONT and BACK images using the side field. For PASSPORT, the side field is optional.

Identity Document Types:

Type	Description	Side Required
`PASSPORT`	Passport	No (optional)
`NATIONAL_ID`	National ID card	Yes (FRONT + BACK)
`DRIVERS_LICENSE`	Driver’s license	Yes (FRONT + BACK)

Address Proof Types:

Type	Description
`UTILITY_BILL`	Recent utility bill (gas, electric, water)
`BANK_STATEMENT`	Bank statement (within last 3 months)
`GOVERNMENT_LETTER`	Official government correspondence
`RESIDENCE_PERMIT`	Residence permit document
`PASSPORT`	Passport showing address
`NATIONAL_ID`	National ID showing address
`DRIVERS_LICENSE`	Driver’s license showing address
`COMPANY_DOC`	Company document showing address

Customer Status & Webhooks

After document submission, customers go through a verification workflow: Status Lifecycle:

INCOMPLETE → REVIEWING → APPROVED
                ↓
           ON_HOLD / REJECTED

Special Status:

ASSOCIATED_PARTIES_REMAINING — Some party documents still needed

Webhook Events:

customer.created — Fired when customer is created
customer.status — Fired when status changes

Subscribe to webhooks to automate your onboarding flow. See Verifying Webhooks for setup.

Error Response Examples

Email validation error (not lowercase):

{
  "message": "Validation failed",
  "errors": {
    "basic_info.email": ["Email must be all lowercase"]
  }
}

RELIANCE not enabled:

{
  "message": "RELIANCE is not available for your client"
}

Ownership percentage validation:

{
  "message": "Validation failed",
  "errors": {
    "associated_parties": ["Total ownership percentages must be > 0.01 and < 100"]
  }
}

What’s Next?

You’ve successfully created a business customer. Here’s what to do next:

1. Monitor Verification Status

Listen for webhook events to track verification progress:

Subscribe to customer.created and customer.status webhooks
Handle status transitions: INCOMPLETE → REVIEWING → APPROVED
For ON_HOLD statuses, respond to RFIs (Requests for Information) via email or Slack with additional documents
See Webhook Verification for implementation details

2. Test Edge Cases

Validate your integration handles common errors:

✓ Email with uppercase characters
✓ Ownership percentages totaling > 100%
✓ Non-Latin characters in text fields
✓ Missing required fields
✓ RELIANCE verification when not enabled
✓ P.O. Box addresses

3. Production Checklist

Before going live, ensure you have:

Implemented webhook handling for status updates
Added proper error handling for all failure scenarios
Client-side validation for email lowercase
Fetched and cached catalogue data (industries, purposes, source-of-funds)
Implemented document upload UI/flow
Reviewed High-Risk Business Activities
Set up monitoring for failed verifications
Tested the complete workflow end-to-end

4. Create Beneficiaries

Once your business customer is approved, you can create beneficiaries for payouts:

See Beneficiary Account Validation
Review Beneficiary Relationships

Common Pitfalls & Solutions

Pitfall	Solution
Email validation fails	Ensure email is all lowercase before sending: `[email protected]` ✓ not `[email protected]` ✗
RELIANCE 423 error	RELIANCE verification must be enabled for your client. Contact support or use `STANDARD` verification type.
Ownership percentage error	Total ownership across all parties must be > 0.01% and < 100%. Check calculations before submitting.
Non-Latin character rejection	All text fields accept only English (Latin) characters. Transliterate or romanize names (e.g., `José` → `Jose`).
P.O. Box address rejected	Use verifiable street addresses for both incorporated and physical addresses. Avoid P.O. Boxes.
State code validation fails	Use state codes from /v1/countries//subdivisions. Format: `US-CA`, not `CA`.
Phone format rejected	Use E.164 format with country code: `+14155552671`, not `(415) 555-2671`.
Phone country mismatch	Phone number country/area code must match `country_of_incorporation`.
Monthly volume rejected	Provide amount in USD as integer (not cents): `50000` for $50,000, not `5000000`.

Customers

Funding & Balances

Compliance & Regulatory

Additional Information

Webhooks

Prerequisites

Onboarding Steps

Request Body Structure

Verification Type (Optional)

Basic Information (Required)

Financial Profile (Required)

Addresses (Required)

Associated Parties (Minimum 1 Required)

Metadata (Optional)

Document Upload & Attachment

Step 1: Upload Documents

Step 2: Attach Business Documents

Step 3: Attach Associated Party Documents

Customer Status & Webhooks

Error Response Examples

What’s Next?

1. Monitor Verification Status

2. Test Edge Cases

3. Production Checklist

4. Create Beneficiaries

Common Pitfalls & Solutions

Customers

Funding & Balances

Compliance & Regulatory

Additional Information

Webhooks

​Prerequisites

​Onboarding Steps

​Request Body Structure

​Verification Type (Optional)

​Basic Information (Required)

​Financial Profile (Required)

​Addresses (Required)

​Associated Parties (Minimum 1 Required)

​Metadata (Optional)

​Document Upload & Attachment

​Step 1: Upload Documents

​Step 2: Attach Business Documents

​Step 3: Attach Associated Party Documents

​Customer Status & Webhooks

​Error Response Examples

​What’s Next?

​1. Monitor Verification Status

​2. Test Edge Cases

​3. Production Checklist

​4. Create Beneficiaries

​Common Pitfalls & Solutions

Prerequisites

Onboarding Steps

Request Body Structure

Verification Type (Optional)

Basic Information (Required)

Financial Profile (Required)

Addresses (Required)

Associated Parties (Minimum 1 Required)

Metadata (Optional)

Document Upload & Attachment

Step 1: Upload Documents

Step 2: Attach Business Documents

Step 3: Attach Associated Party Documents

Customer Status & Webhooks

Error Response Examples

What’s Next?

1. Monitor Verification Status

2. Test Edge Cases

3. Production Checklist

4. Create Beneficiaries

Common Pitfalls & Solutions