Processor Tags

Processor tags let you mark a processor as a backup or specialist that automatically takes over when your primary processor can't handle a specific kind of transaction. Instead of the payment failing, the gateway retries or splits it onto the tagged processor.

You typically set a tag when a merchant needs a fallback for surcharged cards, debit cards, keyed-in charges, or split-funding flows. Tags are set per processor when you create or edit the processor.

---

When to Use Each Tag

Scenario	Tag
A surcharge was applied but the card can't accept surcharges	surchargefallback
A keyed-in charge needs a different processor than swiped/chip transactions	itfallback
A debit card was declined on the primary processor	debitfallback
A single payment needs to be split across two processors	splittransaction
The surcharge or cash-discount portion of a payment needs a second processor	splitpaymentadjustment

---

Setting a Processor Tag

Control Panel

1. Log in as a partner user with processor-management permissions.
2. Go to Merchants → [merchant] → Processors.
3. Click Edit on the processor you want to tag, or Add Processor to create a new one.
4. Enter the exact tag value from the reference below in the Tag field.
5. Save.

The tagged processor is not used for ordinary transactions — only as a fallback or split leg in its designated scenario.

WARNING

Tag values must be typed exactly as shown. Any other value is accepted but has no effect — only the recognized values trigger the fallback behavior.

For your developer

Set or change a tag by including the tag field when creating or updating a processor via the API:

curl -X POST "https://sandbox.fluidpay.com/api/merchant/{merchantid}/processor" \
  -H "Authorization: APIKEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Backup Processor",
    "description": "Surcharge fallback",
    "tag": "surchargefallback",
    "status": "active",
    "timezone": "US/Central",
    "settle_at": "23:00:00",
    "settings": { ... }
  }'

See Merchant Boarding API → Create new Processor for the full request body and field list.

---

Tag Reference

surchargefallback

Used when a merchant runs a surcharge program but some cards can't accept surcharges.

If a card is declined on the primary processor because the surcharge can't be applied, the transaction is retried on a processor tagged surchargefallback, this time without the surcharge.

Requires: a primary processor configured for surcharge, a second processor tagged surchargefallback, and surcharge fallback enabled on the merchant account.

itfallback

Used when a merchant mostly takes card-present transactions but occasionally needs to run a keyed-in charge.

Keyed-in charges are routed to a processor tagged itfallback instead of the primary card-present processor. This lets you use separate processor accounts for card-present and card-not-present traffic.

Requires: a primary card-present processor, a second processor tagged itfallback, and card-not-present fallback enabled on the merchant account.

debitfallback

Used when some debit cards can't be processed on the primary processor but can be processed on a secondary one.

If a debit card is declined on the primary processor, the transaction is automatically retried on a processor tagged debitfallback.

Requires: a primary processor, a second processor tagged debitfallback, and debit fallback enabled on the merchant account.

splittransaction

Used when a single payment needs to be split across two processors — for example, when different portions of a charge fund to different merchant IDs for accounting or chargeback isolation.

When a split transaction is triggered, part of the payment runs on the primary processor and the remainder on the processor tagged splittransaction.

Requires: a primary processor, a second processor tagged splittransaction, and split-transaction enabled on the merchant account.

splitpaymentadjustment

Used when a merchant runs a surcharge or cash-discount program and the adjustment portion needs to fund separately from the base amount.

The base amount goes to the primary processor; the surcharge or cash-discount portion goes to the processor tagged splitpaymentadjustment.

Requires: a primary processor set up for surcharge or cash discount, a second processor tagged splitpaymentadjustment, and split payment adjustment enabled on the merchant account.

---

Notes

• Each tag requires a separate physical processor — you can't use the same processor as both primary and fallback.
• A merchant can have multiple tagged processors at the same time (for example, both surchargefallback and debitfallback).
• Merchants cannot set or change processor tags themselves. All tag changes must be made by a partner.
• If a tagged processor is missing or disabled when a fallback is needed, the original transaction outcome (decline or failure) stands.