Finix MCP Server

Instructions

Implementation Reference

• src/tools/identities/createSeller.ts:132-222 (handler)

  The handler function for the 'create_seller' tool. It constructs a payload from the input parameters, including entity details and optional underwriting data, then posts to the Finix /identities endpoint to create a new seller identity.

  const createSeller = async (client: FinixClient, _context: FinixContext, params: any): Promise<any> => {
    try {
      if (!client.hasCredentials()) {
        throw new Error('Finix username and password are required for this operation. Please configure FINIX_USERNAME and FINIX_PASSWORD in your environment.');
      }
  
      const {
        email, first_name, last_name, business_name, business_type, business_description,
        phone, business_phone, business_tax_id, tax_id, url,
        personal_address, business_address,
        doing_business_as, default_statement_descriptor, title, principal_percentage_ownership,
        mcc, ownership_type, dob, incorporation_date,
        annual_card_volume, max_transaction_amount, ach_max_transaction_amount,
        has_accepted_credit_cards_previously,
        annual_ach_volume, average_ach_transfer_amount, average_card_transfer_amount,
        card_volume_distribution, volume_distribution_by_business_type, refund_policy,
        merchant_agreement_accepted, merchant_agreement_timestamp, merchant_agreement_ip_address, merchant_agreement_user_agent,
        credit_check_allowed, credit_check_timestamp, credit_check_ip_address, credit_check_user_agent,
        tags
      } = params;
  
      const payload: any = {
        type: 'BUSINESS',
        identity_roles: ['SELLER'],
        entity: {
          email,
          first_name,
          last_name,
          business_name,
          business_type,
          ...(phone && { phone }),
          ...(business_phone && { business_phone }),
          ...(business_tax_id && { business_tax_id }),
          ...(tax_id && { tax_id }),
          ...(url && { url }),
          ...(personal_address && { personal_address }),
          ...(business_address && { business_address }),
          ...(doing_business_as && { doing_business_as }),
          ...(default_statement_descriptor && { default_statement_descriptor }),
          ...(title && { title }),
          ...(principal_percentage_ownership !== undefined && { principal_percentage_ownership }),
          ...(mcc && { mcc }),
          ...(ownership_type && { ownership_type }),
          ...(dob && { dob }),
          ...(incorporation_date && { incorporation_date }),
          ...(annual_card_volume !== undefined && { annual_card_volume }),
          ...(max_transaction_amount !== undefined && { max_transaction_amount }),
          ...(ach_max_transaction_amount !== undefined && { ach_max_transaction_amount }),
          ...(has_accepted_credit_cards_previously !== undefined && { has_accepted_credit_cards_previously })
        },
        ...(tags && { tags })
      };
  
      // Build additional underwriting data if any fields are provided
      const underwritingData: any = {};
      if (business_description) underwritingData.business_description = business_description;
      if (annual_ach_volume !== undefined) underwritingData.annual_ach_volume = annual_ach_volume;
      if (average_ach_transfer_amount !== undefined) underwritingData.average_ach_transfer_amount = average_ach_transfer_amount;
      if (average_card_transfer_amount !== undefined) underwritingData.average_card_transfer_amount = average_card_transfer_amount;
      if (card_volume_distribution) underwritingData.card_volume_distribution = card_volume_distribution;
      if (volume_distribution_by_business_type) underwritingData.volume_distribution_by_business_type = volume_distribution_by_business_type;
      if (refund_policy) underwritingData.refund_policy = refund_policy;
      if (merchant_agreement_accepted !== undefined) underwritingData.merchant_agreement_accepted = merchant_agreement_accepted;
      if (merchant_agreement_timestamp) underwritingData.merchant_agreement_timestamp = merchant_agreement_timestamp;
      if (merchant_agreement_ip_address) underwritingData.merchant_agreement_ip_address = merchant_agreement_ip_address;
      if (merchant_agreement_user_agent) underwritingData.merchant_agreement_user_agent = merchant_agreement_user_agent;
      if (credit_check_allowed !== undefined) underwritingData.credit_check_allowed = credit_check_allowed;
      if (credit_check_timestamp) underwritingData.credit_check_timestamp = credit_check_timestamp;
      if (credit_check_ip_address) underwritingData.credit_check_ip_address = credit_check_ip_address;
      if (credit_check_user_agent) underwritingData.credit_check_user_agent = credit_check_user_agent;
  
      if (Object.keys(underwritingData).length > 0) {
        payload.additional_underwriting_data = underwritingData;
      }
  
      const response = await client.post('/identities', payload);
      
      if (response.error) {
        throw new Error(`Error creating seller identity: ${response.error.message}`);
      }
      
      const identity = response.data;
      
      // Return clean data without _links
      const { _links, ...cleanIdentity } = identity;
      return cleanIdentity;
  
    } catch (error) {
      throw error;
    }
  };

• src/tools/identities/createSeller.ts:20-122 (schema)

  Zod schema defining all input parameters for the create_seller tool, including required fields like email, names, business details, and extensive optional underwriting and address fields.

  const createSellerParameters = () => z.object({
    // Required basic info
    email: z.string().email().describe('The email address of the seller'),
    first_name: z.string().describe('The first name of the primary contact'),
    last_name: z.string().describe('The last name of the primary contact'),
    business_name: z.string().describe('The legal business name'),
    business_type: z.enum([
      'INDIVIDUAL_SOLE_PROPRIETORSHIP', 'CORPORATION', 'LIMITED_LIABILITY_COMPANY',
      'PARTNERSHIP', 'ASSOCIATION', 'GOVERNMENT_AGENCY', 'OTHER'
    ]).describe('The business type'),
    business_description: z.string().describe('Description of the business for underwriting'),
  
    // Business contact info
    phone: z.string().optional().describe('Personal phone number'),
    business_phone: z.string().optional().describe('Business phone number'),
    business_tax_id: z.string().optional().describe('Business tax ID (EIN)'),
    tax_id: z.string().optional().describe('Personal tax ID (SSN)'),
    url: z.string().optional().describe('Business website URL'),
  
    // Addresses
    personal_address: z.object({
      line1: z.string().describe('Address line 1'),
      line2: z.string().optional().describe('Address line 2'),
      city: z.string().describe('City'),
      region: z.string().describe('State/Region (e.g., CA)'),
      postal_code: z.string().describe('Postal/ZIP code'),
      country: z.string().default('USA').describe('Country code')
    }).optional().describe('Personal address of the primary contact'),
  
    business_address: z.object({
      line1: z.string().describe('Address line 1'),
      line2: z.string().optional().describe('Address line 2'),
      city: z.string().describe('City'),
      region: z.string().describe('State/Region (e.g., CA)'),
      postal_code: z.string().describe('Postal/ZIP code'),
      country: z.string().default('USA').describe('Country code')
    }).optional().describe('Business address'),
  
    // Business details
    doing_business_as: z.string().optional().describe('DBA name'),
    default_statement_descriptor: z.string().optional().describe('Statement descriptor for transactions'),
    title: z.string().optional().describe('Title of the primary contact (e.g., CEO)'),
    principal_percentage_ownership: z.number().min(0).max(100).optional().describe('Ownership percentage'),
    mcc: z.string().optional().describe('Merchant Category Code'),
    ownership_type: z.enum(['PRIVATE', 'PUBLIC']).optional().describe('Ownership type'),
  
    // Dates
    dob: z.object({
      year: z.number().int().describe('Birth year'),
      month: z.number().int().min(1).max(12).describe('Birth month (1-12)'),
      day: z.number().int().min(1).max(31).describe('Birth day (1-31)')
    }).optional().describe('Date of birth of primary contact'),
  
    incorporation_date: z.object({
      year: z.number().int().describe('Incorporation year'),
      month: z.number().int().min(1).max(12).describe('Incorporation month (1-12)'),
      day: z.number().int().min(1).max(31).describe('Incorporation day (1-31)')
    }).optional().describe('Date of business incorporation'),
  
    // Financial info
    annual_card_volume: z.number().optional().describe('Annual card processing volume in cents'),
    max_transaction_amount: z.number().optional().describe('Maximum single transaction amount in cents'),
    ach_max_transaction_amount: z.number().optional().describe('Maximum ACH transaction amount in cents'),
    has_accepted_credit_cards_previously: z.boolean().optional().describe('Has accepted credit cards before'),
  
    // Underwriting data
    annual_ach_volume: z.number().optional().describe('Annual ACH volume in cents'),
    average_ach_transfer_amount: z.number().optional().describe('Average ACH transfer amount in cents'),
    average_card_transfer_amount: z.number().optional().describe('Average card transfer amount in cents'),
    
    card_volume_distribution: z.object({
      card_present_percentage: z.number().min(0).max(100).describe('Card present percentage'),
      mail_order_telephone_order_percentage: z.number().min(0).max(100).describe('MOTO percentage'),
      ecommerce_percentage: z.number().min(0).max(100).describe('Ecommerce percentage')
    }).optional().describe('Card volume distribution'),
  
    volume_distribution_by_business_type: z.object({
      business_to_business_volume_percentage: z.number().min(0).max(100).describe('B2B percentage'),
      business_to_consumer_volume_percentage: z.number().min(0).max(100).describe('B2C percentage'),
      consumer_to_consumer_volume_percentage: z.number().min(0).max(100).describe('C2C percentage'),
      person_to_person_volume_percentage: z.number().min(0).max(100).describe('P2P percentage'),
      other_volume_percentage: z.number().min(0).max(100).describe('Other percentage')
    }).optional().describe('Volume distribution by business type'),
  
    refund_policy: z.enum([
      'NO_REFUNDS', 'REFUNDS_WITH_RESTOCKING_FEE', 'MERCHANDISE_EXCHANGE_ONLY', 
      'FULL_REFUNDS', 'OTHER'
    ]).optional().describe('Refund policy'),
  
    // Agreement and credit check info
    merchant_agreement_accepted: z.boolean().optional().describe('Merchant agreement accepted'),
    merchant_agreement_timestamp: z.string().optional().describe('When agreement was accepted (ISO 8601)'),
    merchant_agreement_ip_address: z.string().optional().describe('IP address when agreement was accepted'),
    merchant_agreement_user_agent: z.string().optional().describe('User agent when agreement was accepted'),
  
    credit_check_allowed: z.boolean().optional().describe('Credit check allowed'),
    credit_check_timestamp: z.string().optional().describe('When credit check was authorized (ISO 8601)'),
    credit_check_ip_address: z.string().optional().describe('IP address for credit check'),
    credit_check_user_agent: z.string().optional().describe('User agent for credit check'),
  
    // Tags
    tags: z.record(z.string()).optional().describe('Key-value pairs for tagging')
  });

• src/tools/identities/createSeller.ts:224-236 (registration)

  Tool factory definition registering the 'create_seller' tool, specifying method name, description, parameters, annotations, and linking to the execute handler.

  const tool: ToolFactory = () => ({
    method: 'create_seller',
    name: 'Create Seller Identity',
    description: createSellerPrompt(),
    parameters: createSellerParameters(),
    annotations: createSellerAnnotations(),
    actions: {
      identities: {
        create: true
      }
    },
    execute: createSeller
  });

• src/tools/index.ts:15-27 (registration)

  Central registration of all tools, including createSeller, in the allTools array for export and use in MCP.

  export const allTools: ToolFactory[] = [
    // Search & Documentation
    searchDocs,
    
    // Identities (Buyers/Sellers)
    createBuyer,
    createSeller,
    listBuyers,
    listSellers,
    
    // Payment Links
    createPaymentLink,
  ];

• src/tools/index.ts:8-8 (registration)

  Import of the createSeller tool module.

  import createSeller from './identities/createSeller.js';