You can limit the routing by specifying processingOptions.paymentOptionTag in the transaction request (such as Run card transaction).

The paymentOptionTag parameter is a custom value used to route transactions to a specific gateway or merchant account. In order to use the paymentOptionTag for routing, contact Integrations Support to designate one or more tags for your merchant account.

Before you begin setting up a paymentOptionTag, Nexio recommends that you understand the following notes.

🚧

Important

• If the value provided for paymentOptionTag in the transaction request is invalid for the account, Nexio sends an error rather than attempt the transaction
• If the transaction would be disqualified because of the specified parameter, Nexio responds with an error message and does not attempt to process the transaction further
• If you specify a value for the paymentOptionTag in the request and that tag has been assigned to multiple merchant IDs (MIDs) for your API user account, Nexio checks for target allocation or item routing rules as well. If there are not any rules, the system uses the MID with the current lowest monthly gross of authorized transactions (also known as transaction volume)
• In addition, if you want to use target allocation or routing based on item with the paymentOptionTag, see the Important Notes in the appropriate topics:
  - How do I keep a relationship active at a specific transaction percentage?
  - How do I route all transactions with a specific item to a relationship?

Along with the paymentOptionTag, you can also make the payment routing flow more complex with either or both target allocation and item routing.

To set up paymentOptionTags

1. Contact Integrations Support to designate one or more tags for your merchant account (MID).

   Example 1: paymentOptionTags for USD as official currency in different countries

   MID #1
   - USD currency for United States: usa
   - USD currency for Puerto Rico: pri
   - USD currency for Ecuador: ecu
   

   
   Example 2: paymentOptionTags for CBD

   MID #1
   - Gateway that allows transactions with CBD: CBD
   - Gateway to use for all other transactions: NoCBD 
   

2. Make note of the tags that are created for your MIDs. These are not visible in the Dashboard.

   📘

   Note

   If you later need to find out what paymentOptionTags have been enabled, contact Integrations Support.

3. If necessary, complete the steps in Setting up payment routing by target allocation

4. If necessary, complete the steps in Setting up payment routing by item

5. For the transaction request, configure the API as follows:

   Each payment request must include the following parameters for payment routing with the paymentOptionTag:

   • data.amount
   • data.currency
   • processingOptions.paymentOptionTag

   To customize payment routing with the paymentOptionTag and item routing, also include the following parameter:

   • data.cart.items[n]

What happens after you set up paymentOptionTags?

After you complete the steps for setting up one or more paymentOptionTags (and potentially also either or both target allocation and item routing), the following process happens for each transaction:

1. A consumer adds an item to the shopping cart and submits payment with a specific transaction currency.

   For example, The consumer adds a CBD item and uses a card to pay in USD.

   The data.cart.items[1].type parameter is set to 'CBD' and the transaction currency is 'USD'.

   Also, the processingOptions.paymentOptionTag parameter is set to 'CBD'.

   If the consumer instead had a cart of one or more items and none are CBD, then the paymentOptionTag would be 'NoCBD'.

2. The Nexio system determines the merchant account (MID) with the lowest monthly gross of authorized transactions (also known as transaction volume).

   Example 1: Suppose MID #1, MID #2, and MID #3 can support the currency and paymentOptionTag of CBD and NoCBD and MID #4 does not have any paymentOptionTags. Only the first 3 MIDs are considered.

   Then, if MID #1 has a current volume of $4,500, MID #2 is $10,300, and MID #3 is $8,000, the system prioritizes them as follows:
   - MID #1
   - MID #3
   - MID #2
   
   In this case, MID #1 has the lowest transaction volume.
   

   
   Example 2: Suppose only MID #1 and MID #3 can support the currency and paymentOptionTag and MID #2 only supports the currency and MID #4 does not have any paymentOptionTags. Only MIDs #1 and #3 are considered.

   Then, if MID #1 has a current volume of $10,300, and MID #3 is $8,000, the system prioritizes them as follows:
   - MID #3
   - MID #1
   
   In this case, MID #3 has the lowest transaction volume.
   

3. The system checks to see if any routing rules have been configured and that apply.

   For example, all three MIDs have item routing and target allocation rules.

4. The system checks whether there are any item routing rules with any of the applicable MIDs.

   For example, MID #1 has a rule about the type being 'CBD', MID #2 has a rule about the description containing 'CBD', and MID #3 has a rule about the type and item containing 'CBD'.

   If there are not any item routing rules, the system skips to step 6 in this sequence.

5. Based on the items in the cart and the item routing rules, the system identifies which of the MIDs can process the transaction.

   For the following examples, MID #1 has a rule about the type being 'CBD', MID #2 has a rule about the description containing 'CBD', and MID #3 has a rule about the type and item containing 'CBD'.

   Example 1:

   Filtering when only type is 'CBD'
   
   The MIDs would be prioritized as follows:
   - MID #1
   

   Example 2:

   Filtering when both type and item are 'CBD'
   
   The MIDs would be prioritized as follows:
   - MID #1
   - MID #3
   

   Example 3:

   Filtering when type is 'CBD' and description and item both contain 'CBD'
   
   The MIDs would be prioritized as follows:
   - MID #1
   - MID #3
   - MID #2
   

   Example 4:

   If applying the item routing rules results in no possible MIDs to process the transaction, the system ignores the rules.
   

   	Filtering when description is exactly 'CBD'
   
   	The list is empty, therefore the system removes the rule filtering, resulting in the following priorities for the MIDs:
   	- MID #1
   	- MID #3
   	- MID #2
   

6. The system checks to see if there are target allocation rules that match for this transaction.

   If there are not any target allocation rules, the system skips to step 8 in this sequence.

7. The system takes the target allocations and re-sorts the list so that the MID that is farthest away from its target allocation is at the top.

   For the following examples, the target allocation is 10% for MID #1, 90% for MID #2, and 0% for MID #3.

   Example 1: Current total transaction volume of $5,600.

   MID #1 has a current volume of $300 and 10% allocation, so it is at 5.4% and thus 4.6% away from the target for the month.
   
   MID #2 has a current volume of $4,800 and 90% allocation, so it is at 85.7% and thus 4.3% away from the target for the month.
   
   MID #3 has a current volume of $500 but 0% target allocation, so it is at 8.9%. However, the target is 0%, so no transactions will go to this MID.
   
   The MIDs would be prioritized as follows:
   - MID #1
   - MID #2
   - (MID #3)
   

   
   Example 2: Current total transaction volume of $22,800

   MID #1 has a current volume of $4,500 and 10% allocation, so it is at 19.7% currently and thus 9.7% over the target for the month.
   
   MID #2 has a current volume of $10,300 and 90% allocation, so it is at 45.2% and thus 44.8% away from the target for the month.
   
   MID #3 has a current volume of $8,000 but 0% target allocation, so it is at 35.1%. However, the target is 0%, so no transactions will go to this MID.
   
   The MIDs would be prioritized as follows:
   - MID #2
   - MID #1
   - (MID #3)
   

8. The system routes the payment to the MID at the top of the list.
   
   

The following image shows a high-level view of the payment flow from the above process when you are using paymentOptionTags along with the potential for target allocation and item routing with multiple MIDs.