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. This is honored on single-merchant campaigns and when merchant_id is passed. On a payment-router campaign the router's configured currency governs, and a passed currency_id is ignored.

Usage:

{
  "currency_id": 2
}

Behavior:

Overrides the merchant's default currency on single-merchant campaigns and when merchant_id is passed
Does not override a payment router's currency — if the transaction is routed (campaign router or API route_id) and that router has a currency configured, the router's currency is used and the passed currency_id is ignored
Merchant selection still follows campaign configuration (unless merchant_id also passed)

Validation:

The currency is validated only when a merchant is resolved — i.e. when merchant_id is passed, or the campaign is a single-merchant campaign
In those cases the merchant must support the requested currency (configured under the merchant's currencies), or the transaction declines with merchant_currency_invalid
On a payment-router campaign the passed currency_id is not validated against merchants and does not override the router's currency

Combining Parameters

You can combine parameters for different levels of control:

route_id + currency_id:

Uses the specified router
The router's configured currency governs — the passed currency_id is ignored (to process in a different currency, route to a currency-specific router via route_id, or pass merchant_id to bypass routing)

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:

Router currency - if the transaction is processed through a payment router (campaign router or API route_id) and that router has a currency configured, it governs and overrides a passed currency_id
API currency_id parameter - applies on single-merchant campaigns and merchant_id flows (and on routed transactions only if the router has no currency configured); validated against the merchant
Merchant default currency (from API merchant_id or campaign merchant) when no currency_id is passed
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: A single-merchant campaign uses USD by default, but you need to process an order in EUR. (On a payment-router campaign a passed currency_id is ignored — see the note in the result below.)

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:

The campaign's merchant is used
Transaction processes in EUR instead of USD
The merchant must support EUR, or the transaction declines with merchant_currency_invalid
Note: if the campaign uses a payment router instead of a single merchant, the router's currency governs and this currency_id is ignored — route to a currency-specific router via route_id, or pass merchant_id to bypass routing

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 the router's currency (USD) — the passed currency_id is ignored on payment-router campaigns
To process in another currency, route to a currency-specific router via route_id, or pass merchant_id to bypass routing

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

Currency is validated only when a merchant is resolved — i.e. when merchant_id is passed, or the campaign is a single-merchant campaign. When currency_id is passed in those cases:

The merchant must support the requested currency (configured under the merchant's currencies)
The currency must be configured on the merchant

If validation fails:

Transaction will decline
Error code: merchant_currency_invalid ("Invalid currency for merchant")

On payment-router campaigns the passed currency_id is not validated against merchants and does not override the router's currency.

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 (merchant_currency_invalid)

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

Note: This validation applies to single-merchant and merchant_id flows. On a payment-router campaign a passed currency_id is ignored (the router's currency governs), so it neither validates nor declines on currency.

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`