Finix Integration

Overview

Finix is the payment processor used for brand partner subscriptions (US). It handles payment instrument creation, card validation, and recurring subscriptions.

Files

File	Purpose
`api/external/utils/finixUtils.php`	Core Finix API utilities
`api/external/saveFinixIdentityDetails.php`	Create/update Finix identity
`api/external/saveFinixPaymentDetails.php`	Payment instrument + subscription creation

Configuration

Finix credentials are stored in environment variables (AWS Secrets Manager):


function getFinixCredentials()
{
    return [
        'username' => $_ENV['FINIX_USERNAME'],
        'password' => $_ENV['FINIX_PASSWORD'],
        'merchantId' => $_ENV['FINIX_MERCHANT_ID'],
        'apiUrl' => $_ENV['FINIX_API_URL']
    ];
}

Sandbox credentials are used for all non-production environments. Production uses live credentials.

API Utilities

HTTP Methods


finixPost($data, $endpoint)   // POST request
finixGet($endpoint)            // GET request
finixPut($data, $endpoint)     // PUT request

All requests use cURL with basic auth and Finix-Version: 2022-02-01 header.

Origin Validation

External Finix endpoints validate the request origin:


$allowedOrigins = [
    "https://myhousr.webflow.io",
    "https://myhousr.com",
    "https://www.myhousr.com",
    "https://housr.com",
    "https://www.housr.com",
    // staging URLs...
];

Payment Flow

1. Create Identity

api/external/saveFinixIdentityDetails.php creates a Finix identity for the brand partner with:

Personal details (name, email, phone, address)
Business details (business name, address)
Postal code validation (must be valid 5-digit US zip code)

2. Create Payment Instrument


createPaymentInstrument($tokenId, $identityId)

Creates a payment instrument from a tokenized card. Posts to payment_instruments endpoint with the token and identity.

3. Card Validation


cardValidationCheck($paymentInstrumentId)

Performs a $0 authorization to verify the card is valid:


$data = [
    "amount" => 0,
    "currency" => "USD",
    "merchant" => $_ENV['FINIX_MERCHANT_ID'],
    "source" => $paymentInstrumentId,
];

4. Create Subscription

For paid plans, creates a recurring subscription:


$data = [
    "amount" => $subscriptionDetails['amount'],
    "currency" => "USD",
    "plan_name" => $planName . " Subscription",
    "linked_to" => $merchantId,
    "linked_type" => "MERCHANT",
    "billing_interval" => "MONTHLY",
    "subscription_details" => [
        "collection_method" => "BILL_AUTOMATICALLY",
        "trial_details" => [...]  // if trial period > 0
    ],
    "buyer_details" => [
        "identity_id" => $identityId,
        "instrument_id" => $paymentInstrumentId
    ]
];

After payment is set up:

Calls brandPartnerSignUpComplete() to create the brand partner account
Calls handleHubSpotBrandPartner() to update CRM
Returns a magic link for portal access (if brand portal is enabled)

Basic Plan (Free)

Basic plan signup skips payment processing entirely — just calls brandPartnerSignUpComplete().

Error Handling

Finix errors are mapped to user-friendly messages:


function finixErrorHandler($errors = null)
{
    switch ($error->message) {
        case "USA Personal Address Postal Codes should be...":
        case "USA Business Address Postal Codes should be...":
        case "Email should use valid email format...":
            $errorMessage = $error->message;
            break;
        default:
            $errorMessage = genericErrorMessage();
    }
}

Generic fallback: “Oops! Something went wrong while submitting the form. Please contact support@myhousr.com for assistance.”