API Overrides

Regardless of how your campaign is configured (single merchant or payment router), you can override the payment processing behavior for any transaction by passing API parameters when processing an order. This gives you complete control over which merchant processes the transaction and what currency is used.

These override parameters (route_id, merchant_id, currency_id) are only accepted when processing orders through the API - either when creating a new order with the process or authorize action, or when processing or authorizing an existing order. Pass these parameters in your API request body to override the campaign's default payment configuration for that specific transaction.

When to Use API Overrides

Common use cases:

Testing specific merchant configurations without changing campaign settings
Handling special customer scenarios (VIP customers, specific regions, etc.)
Processing transactions in non-default currencies
Implementing custom routing logic in your application
Retry logic with specific merchants after declines
A/B testing different merchants or processors

Available Parameters

`route_id`

What it does: Forces a specific payment router for the transaction, overriding the campaign's configured router.

Usage:

{
  "route_id": 789
}

Behavior:

Overrides campaign's router setting
Uses specified router's logic and currency
All routing rules apply normally (exclusions, inclusions, routing method)

Validation:

Router must exist and be active
Merchants in router must support payment method and card type

Use cases:

Testing different routers without changing campaign
A/B testing routing strategies
Custom routing logic per traffic source or customer segment

`merchant_id`

What it does: Forces a specific merchant to process the transaction, completely bypassing campaign configuration.

Usage:

{
  "merchant_id": 123
}

Behavior:

Bypasses single merchant campaign setting
Bypasses payment router completely (no routing logic applied)
Uses the specified merchant's default currency
Transaction processes as if merchant was configured on campaign

Validation:

Merchant must exist and be active
Merchant must support the payment method
Merchant must support the card type
BIN blocks still apply
Processing limits still apply

`currency_id`

What it does: Forces a specific currency for the transaction, overriding merchant or router defaults.

Usage:

{
  "currency_id": 2
}

Behavior:

Overrides merchant default currency
Overrides router default currency
Merchant selection still follows campaign configuration (unless merchant_id also passed)

Validation:

Merchant must support the requested currency
Transaction will decline if currency not supported

Combining Parameters

You can combine parameters for different levels of control:

route_id + currency_id:

Uses specified router
Overrides router's default currency

merchant_id + currency_id:

Complete override of both merchant and currency
Bypasses all campaign and router configuration

Both Merchant and Currency

Usage:

{
  "merchant_id": 123,
  "currency_id": 2
}

Behavior:

Uses specified merchant
Uses specified currency
Bypasses all campaign configuration
Bypasses all router logic

Priority Order

When multiple sources can determine routing and currency, the system uses this priority:

Merchant Selection:

API merchant_id parameter (if passed) - Bypasses all routing
API route_id parameter (if passed) - Overrides campaign router
Campaign router (if configured)
Campaign single merchant (if configured)

Currency Selection:

API currency_id parameter (if passed) - Highest priority
Router currency (from API route_id or campaign router)
Merchant default currency (from API merchant_id or campaign merchant)
USD fallback (currency_id = 1)

Examples

Example 1: Test Different Router

Scenario: You want to test Router 50 without changing campaign configuration.

API Call:

curl -X POST "https://api.vrio.app/orders" \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_API_KEY" \
-d '{
  "connection_id": 1,
  "campaign_id": 18,
  "route_id": 50,
  "offers": "[{\"offer_id\": 89, \"order_offer_quantity\": 1}]",
  "email": "[email protected]",
  "bill_fname": "John",
  "bill_lname": "Doe",
  "card_number": "4111111111111111",
  "card_cvv": "123",
  "card_exp_month": "12",
  "card_exp_year": "2025"
}'

Result:

Transaction uses Router 50's logic and currency
Campaign remains configured with original router
All Router 50's routing rules apply

Example 2: Force Specific Merchant

Scenario: You want to test Merchant 456 without changing campaign configuration.

API Call:

curl -X POST "https://api.vrio.app/orders" \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_API_KEY" \
-d '{
  "connection_id": 1,
  "campaign_id": 18,
  "merchant_id": 456,
  "offers": "[{\"offer_id\": 89, \"order_offer_quantity\": 1}]",
  "email": "[email protected]",
  "bill_fname": "John",
  "bill_lname": "Doe",
  "card_number": "4111111111111111",
  "card_cvv": "123",
  "card_exp_month": "12",
  "card_exp_year": "2025"
}'

Result:

Transaction processes through Merchant 456
Bypasses campaign router completely
Uses Merchant 456's default currency

Example 3: Process in Different Currency

Scenario: Campaign uses USD by default, but you need to process an order in EUR.

API Call:

curl -X POST "https://api.vrio.app/orders" \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_API_KEY" \
-d '{
  "connection_id": 1,
  "campaign_id": 18,
  "currency_id": 2,
  "offers": "[{\"offer_id\": 89, \"order_offer_quantity\": 1}]",
  "email": "[email protected]",
  "bill_fname": "John",
  "bill_lname": "Doe",
  "card_number": "4111111111111111",
  "card_cvv": "123",
  "card_exp_month": "12",
  "card_exp_year": "2025"
}'

Result:

Campaign's merchant selection logic applies (single merchant or router)
Transaction processes in EUR instead of USD
Merchant must support EUR or transaction will decline

Example 4: Complete Override

Scenario: VIP customer needs to process through specific merchant in specific currency.

API Call:

curl -X POST "https://api.vrio.app/orders" \
-H "Content-Type: application/json" \
-H "X-API-KEY: YOUR_API_KEY" \
-d '{
  "connection_id": 1,
  "campaign_id": 18,
  "merchant_id": 456,
  "currency_id": 3,
  "offers": "[{\"offer_id\": 89, \"order_offer_quantity\": 1}]",
  "email": "[email protected]",
  "bill_fname": "John",
  "bill_lname": "Doe",
  "card_number": "4111111111111111",
  "card_cvv": "123",
  "card_exp_month": "12",
  "card_exp_year": "2025"
}'

Result:

Transaction processes through Merchant 456
Transaction processes in GBP (currency_id 3)
All campaign configuration bypassed

How Overrides Work with Campaign Types

Single Merchant Campaign

Learn more: Single Merchant Setup

Campaign configured with Merchant 100, USD

No override:

Uses Merchant 100
Uses USD

Pass merchant_id: 200:

Uses Merchant 200
Uses Merchant 200's default currency

Pass currency_id: 2:

Uses Merchant 100 (campaign setting)
Uses EUR

Pass both:

Uses Merchant 200
Uses EUR

Payment Router Campaign

Learn more: Payment Router Setup

Campaign configured with Router 50 (USD, 3 merchants)

No override:

Router selects merchant based on routing logic
Uses USD

Pass merchant_id: 200:

Uses Merchant 200 (bypasses router completely)
Uses Merchant 200's default currency
No routing logic applied

Pass currency_id: 2:

Router selects merchant based on routing logic
Uses EUR

Pass both:

Uses Merchant 200 (bypasses router completely)
Uses EUR
No routing logic applied

Validation Rules

All API overrides are validated before processing:

Merchant Validation

When merchant_id is passed:

Merchant must exist in system
Merchant must be active (merchant_active = 1)
Merchant must support the payment method
Merchant must support the card type (for credit cards)
BIN blocks are still enforced
Processing limits are still enforced

If validation fails:

Transaction will decline
Error code returned indicating the issue

Currency Validation

When currency_id is passed:

Merchant must support the requested currency
Currency must be configured on merchant

If validation fails:

Transaction will decline
Error: Currency not supported by merchant

Important Notes

Router Bypass

When you pass merchant_id, the payment router is completely bypassed:

No routing logic runs
No exclusion rules apply (merchant groups, reattempt restrictions, etc.)
No inclusion rules apply (priorities, BIN routing, etc.)
No routing method used (round robin, weighted, volume)
Direct processing on specified merchant

This means:

You take full responsibility for merchant selection
Consider validation that router would normally do
Useful for custom logic but requires careful implementation

Logging

All API overrides are logged in the route log:

Which parameters were passed
Why merchant was selected
"Merchant ID passed from API" or similar reason

Check route log to debug:

Which merchant processed transaction
Whether override was used
Why specific merchant was selected

Troubleshooting

Override Not Working

Issue: Passed merchant_id but transaction used different merchant

Possible causes:

Parameter name misspelled
Parameter not properly formatted in API call
Middleware stripping parameter before reaching Vrio

Solution:

Check API call logs
Verify parameter name matches exactly
Check route log to see what Vrio received

Currency Declined

Issue: Passed currency_id but transaction declined with currency error

Possible causes:

Merchant doesn't support requested currency
Currency ID incorrect

Solution:

Verify merchant supports the currency in merchant configuration
Check currency ID is correct (1=USD, 2=EUR, etc.)
Add currency support to merchant if needed

Merchant Not Found

Issue: Transaction declined with "Merchant not found" or similar error

Possible causes:

Merchant ID doesn't exist
Merchant is inactive
Merchant was deleted

Solution:

Verify merchant ID is correct
Check merchant is active in Merchants section
Use different merchant ID

Payment Method Not Supported

Issue: Transaction declined even though override merchant was specified

Possible causes:

Merchant doesn't support payment method (e.g., PayPal)
Merchant doesn't support card type (e.g., Amex)

Solution:

Check merchant configuration for supported payment methods
Check merchant configuration for supported card types
Enable support or use different merchant

When to Use API Overrides

Available Parameters

route_id

merchant_id

currency_id

Combining Parameters

Both Merchant and Currency

Priority Order

Examples

Example 1: Test Different Router

Example 2: Force Specific Merchant

Example 3: Process in Different Currency

Example 4: Complete Override

How Overrides Work with Campaign Types

Single Merchant Campaign

Payment Router Campaign

Validation Rules

Merchant Validation

Currency Validation

Important Notes

Router Bypass

Logging

Troubleshooting

Override Not Working

Currency Declined

Merchant Not Found

Payment Method Not Supported

Related Documentation

`route_id`

`merchant_id`

`currency_id`