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	✅
Capture	✅
Refund	✅
Card Tokenization	✅
3D Secure	✅
ACH	❌
Digital Wallet	❌
$0 Transactions	❌

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	✅
Use Sandbox Environment	Check to use the Finix sandbox environment for testing	Checkbox	❌
Bypass $0 Transaction Authorizations	Check this box to bypass card validation with Finix for $0 transactions. When unchecked, a $1 authorization (voided immediately) will be used to validate the card — the result of this authorization will determine if the transaction is successful. This setting only applies to initial transactions — $0 renewals will always bypass the gateway. Learn more about $0.00 transaction handling.	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

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

Buyer Identity & Payment Instrument Creation

Finix requires each cardholder to have a buyer identity linked to their payment instrument. VRIO automatically handles this during the first transaction:

Create Buyer Identity — A BUYER identity is created via POST /identities with the customer's name, email, phone, and customer ID tag.
Create Payment Instrument — The card is tokenized via POST /payment_instruments linked to the buyer identity, with billing address for AVS.
Store Token — VRIO stores a concatenated token (buyerIdentityId_paymentInstrumentId) and extracts the payment instrument ID as the source parameter for subsequent transactions.

VRIO Field	Finix Parameter	Description
`customer_card_merchant_token`	`source`	Payment instrument ID extracted from stored token
N/A	`type`	Always set to `PAYMENT_CARD`
Auto-created	`identity`	Per-buyer identity created automatically

📘
Automatic Token Management
Both the buyer identity and payment instrument are created automatically during the first transaction. The token is stored and used for all subsequent recurring payments. No merchant-level identity configuration is needed.

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

Learn more about $0.00 transaction handling.

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
`network_details.authorization_code`	`gateway_auth_code`	Authorization code from the network
`state`	`gateway_response_code`	Transaction state/status
`security_code_verification`	`gateway_response_cvv`	CVV verification result
`address_verification`	`gateway_response_avs`	AVS verification result
`processor_response`	`processor_response_text`	Raw processor response details

Transaction States

State	Success	Description	When This Occurs
`SUCCEEDED`	✅ Yes	Transaction completed successfully	Sale/transfer completed, or authorization approved
`PENDING`	❌ No	Transaction is still processing	Hasn't resolved yet; could become SUCCEEDED or FAILED
`FAILED`	❌ No	Transaction failed	Technical error or validation failure occurred
`CANCELED`	❌ No	Transaction was canceled	Transaction was voided or reversed
`UNKNOWN`	❌ No	Unknown state	Unable to determine transaction outcome

🚧
PENDING is not treated as success
Per Finix documentation, PENDING means the transaction is still processing and could resolve to FAILED. VRIO only treats SUCCEEDED as a successful transaction.

Common Errors

Configuration Errors

Error Message	Solution
"Invalid API credentials"	Verify API username and password
"Merchant not found"	Check Merchant ID spelling

Validation Errors

Error Code	Description	Solution
`INVALID_FIELD`	A field value failed validation	Check the `field` property in the error response for details
`INVALID_NUMBER`	Card number failed validation	Verify card number before submitting

Payment Failures

Common failure codes returned by Finix:

Failure Code	Description
`INSUFFICIENT_FUNDS`	Not enough balance on the card
`EXPIRED_CARD`	Card has expired
`INVALID_CARD_NUMBER_OR_EXPIRED_CARD`	Card number is invalid or card has expired
`INVALID_ACCOUNT_NUMBER`	Account number is invalid
`FRAUD_DETECTED_BY_ISSUER`	Card issuer flagged transaction as fraud
`FRAUD_DETECTED_BY_FINIX`	Finix risk rules flagged transaction as fraud
`ISSUER_POLICY_VIOLATION`	Transaction violates issuer policy
`CARD_NOT_ACTIVATED_OR_BLOCKED`	Card is not activated or has been blocked
`CARD_ACCOUNT_CLOSED`	Card account has been closed
`GENERIC_DECLINE`	General decline with no specific reason
`PICK_UP_CARD`	Issuer requests the card be picked up
`INVALID_CVV`	CVV verification failed
`ADDRESS_VERIFICATION_FAILED_RISK_RULES`	AVS check failed Finix risk rules
`CVV_FAILED_RISK_RULES`	CVV check failed Finix risk rules

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