VRIO supports Finix as a payment gateway for processing credit card transactions. Finix provides payment processing with direct merchant onboarding, transparent pricing, and comprehensive payment management capabilities. The integration supports tokenization for recurring payments, 3D Secure authentication, and zero-dollar authorization handling.

Supported Functionality

Feature	Supported
Authorization	✅
Sale	✅
Capture	✅
Void	✅
Refund	✅
Tokenization	✅
3D Secure	✅
AVS Verification	✅
CVV Verification	✅
Recurring Payments	✅
Multi-currency	✅
Zero-amount Auth	✅

Adding a Finix Merchant

To configure a Finix merchant in VRIO:

Navigate to Merchants → Add Merchant
Select Finix as the gateway type
Configure the following gateway details:

Required Gateway Details

Field Name	Description	Type	Required
API Key Username	Your Finix API key username (from Developers > API Keys in dashboard)	Text	✅
API Key Password	Your Finix API key password (from Developers > API Keys in dashboard)	Password	✅
Merchant ID	Your Finix Merchant ID (from Finix Processing Details in dashboard)	Text	✅
Merchant Identity ID	Your Finix Merchant Identity ID (required for payment instruments)	Text	✅
Use Sandbox Environment	Check to use the Finix sandbox environment for testing	Checkbox	❌
Bypass $0 Auth	Bypass zero-amount transactions without gateway processing	Checkbox	❌

Environment Configuration

Sandbox Environment: Use finix.sandbox-payments-api.com endpoints (Use Sandbox Environment = checked)
Live Environment: Use finix.live-payments-api.com endpoints (Use Sandbox Environment = unchecked)

Request Data Mapping

VRIO maps transaction data to Finix's API format as follows:

Basic Transaction Fields

VRIO Field	Finix Parameter	Description
`transaction_id`	`idempotency_id`	Unique transaction reference to prevent duplicates
`transaction_total`	`amount`	Amount in cents (multiplied by 100)
`currency_value`	`currency`	ISO 4217 currency code
Merchant ID	`merchant`	Merchant ID from settings
Merchant Identity ID	`identity`	Merchant Identity ID for payment instruments

Payment Method Fields

VRIO Field	Finix Parameter	Description
`card_number`	`number`	Credit card number
`card_exp_month`	`expiration_month`	Card expiration month (integer)
`card_exp_year`	`expiration_year`	Card expiration year (4 digits)
`card_cvv`	`security_code`	Card verification code
`cardholder_name`	`name`	Name on card

Billing Address Fields

VRIO Field	Finix Parameter	Description
`billing_address1`	`address.line1`	Billing street address
`billing_address2`	`address.line2`	Billing address line 2
`billing_zip`	`address.postal_code`	Billing postal code
`billing_city`	`address.city`	Billing city
`billing_state`	`address.region`	Billing state/province
`billing_country`	`address.country`	Billing country (default: US)

Tokenization

Payment Instrument Creation

Finix uses payment instruments for tokenization. VRIO automatically creates payment instruments during the first transaction:

VRIO Field	Finix Parameter	Description
`customer_card_merchant_token`	`source`	Payment instrument ID for recurring payments
N/A	`type`	Always set to `PAYMENT_CARD`
Merchant Identity ID	`identity`	Merchant Identity ID required for creation

Token Storage

VRIO stores the Finix payment instrument ID directly as the token, which can be used as the source parameter in subsequent transactions.

📘
Payment Instrument Process
Payment instruments are created automatically during the first transaction. The returned payment instrument ID is stored and used for all subsequent recurring payments.

3D Secure Authentication

VRIO supports 3D Secure authentication by passing MPI data to Finix:

3DS Fields Mapping

VRIO Field	Finix Parameter	Description
`order_cavv`	`3d_secure_authentication.cardholder_authentication`	CAVV authentication verification value
`order_eci`	`3d_secure_authentication.electronic_commerce_indicator`	ECI value (passed directly)
`order_3ds_ds_transaction_id` or `order_xid`	`3d_secure_authentication.transaction_id`	3DS transaction identifier

🚧
Important
All three 3DS fields (CAVV, ECI, and Transaction ID) must be present for Finix to accept the 3D Secure authentication data. If any field is missing, the 3DS data will not be sent.

Transaction Types

Authorization vs Sale

Transaction Type	Finix Endpoint	Description
Authorization	`/authorizations`	Holds funds without capturing
Sale	`/transfers`	Immediate capture of funds
Capture	`/authorizations/{id}`	Captures a previous authorization

Zero Dollar Transactions

For $0.00 transactions, Finix requires special handling:

With Bypass Setting: Returns success without gateway call
Without Bypass: Creates a $1.00 authorization and immediately voids it to validate the card

Response Data Mapping

VRIO processes Finix responses and maps them to standardized response fields:

Response Fields

Finix Response	VRIO Field	Description
`id`	`gateway_response_id`	Finix's unique transaction reference
`approval_code`	`gateway_auth_code`	Authorization code (when available)
`state`	`gateway_response_code`	Transaction state/status
`security_code_verification`	`gateway_response_cvv`	CVV verification result
`address_verification`	`gateway_response_avs`	AVS verification result

Transaction States

State	Success	Description	When This Occurs
`SUCCEEDED`	✅ Yes	Transaction completed successfully	Sale/transfer completed, or authorization approved
`PENDING`	✅ Yes	Transaction is processing	Transaction submitted and awaiting processor response
`READY_TO_SETTLE`	✅ Yes	Authorization ready for settlement	Authorization approved and ready to be settled
`REQUIRES_CAPTURE`	✅ Yes	Authorization awaiting capture	Authorization successful, waiting for capture call
`CAPTURED`	✅ Yes	Authorization has been captured	Capture completed on a previous authorization
`DECLINED`	❌ No	Transaction was declined	Card issuer or processor declined the transaction
`FAILED`	❌ No	Transaction failed	Technical error or validation failure occurred

Common Errors

Configuration Errors

Error Message	Solution
"Invalid API credentials"	Verify API username and password
"Merchant not found"	Check Merchant ID spelling
"Identity required"	Ensure Merchant Identity ID is configured

Validation Errors

Error Code	Description	Solution
`INVALID_AMOUNT`	Invalid transaction amount	Ensure amount is greater than zero
`INVALID_CARD`	Card validation failed	Check card number and expiration
`MISSING_REQUIRED_FIELD`	Required field missing	Verify all required fields are provided

Payment Failures

Common failure reasons include:

Failure Code	Description
`INSUFFICIENT_FUNDS`	Not enough balance
`EXPIRED_CARD`	Card has expired
`INVALID_CARD_NUMBER`	Card number is invalid
`FRAUD_SUSPECTED`	Transaction flagged for fraud
`DO_NOT_HONOR`	Issuer declined transaction

Testing

Note : Placing test orders with a Finix sandbox account or using Finix test cards will not automatically set the order as a test in Vrio. Be sure to flag the order as a test using the is_test flag after the order is processed. For more details on placing test orders, see Placing a Test Order.

For Finix test cards, check here