Dynamic Routing

Optimize your payments performance.

Get a better understanding of our Channels feature.

The combination of a payment method and a provider represents a channel in the Switch Platform. Understand how you can make the most of Switch channels.

Dynamic Routing provides real-time switching capabilities that allow you to select the best provider for a given transaction.

Through our Dynamic Routing components, you can add routing rules which guide transactions around a wide network of payment channels in real-time to maximize payment performance.

Routing Rules

Learn how to create and manage the routing rules that feed Dynamic Routing.

Conditions and Priority

Set your conditions for Dynamic Routing. Work around the amount and processing currency towards the optimization of your transactions.

Strategy

Choose the course of your transactions towards a more effective and cost-efficient payment operation.

Channels

The combination of a payment method and a provider, including the integration of choice, representes a channel in the Switch Platform.

Routing Rules

Want to know more about the Switch Dashboard?

By enabling the Switch Dashboard you get access to a user-friendly management tool to oversee your transactions. Head over to Dashboard and learn more about it.

In case you are using the Switch Dashboard , you can set up routing rules by accessing the specific channel on which you want to implement Dynamic Routing.

On the main navigation menu, select channels.
From your list of available channels, select the payment method you would like to apply Dynamic Routing to.
Add routing rules or edit the existing ones according to your strategy.
Drag and drop routing rules in the list to make changes to their priority levels.

Dynamic Routing is established when an instrument is created.

If you are looking to understand when Dynamic Routing enters the lifecycle of your transaction, know that routing rules are triggered upon the creation of an instrument, after a charge has already been created and before it evolves into a payment.

POST `/v1/router/rules`

Method	Path	Description
POST	Sandbox `https://merchant-api-test.switchpayments.com/v1/router/rules` Production `https://merchant-api.switchpayments.com/v1/router/rules`	Create a new Dynamic Routing rule.

Request Parameters

charge_typeString

Identifier of the charge type (e.g. card_onetime, card_recurring, paypal).

conditionsJSON Object

The routing conditions.

created_atString

The date when the rule was created.

updated_atString

The date when the rule was last updated.

enabledBoolean

Whether the rule is currently enabled or not.

priorityInteger

The rule's priority. 0 being the top priority.

paramsArray

Required configurations to calculate the rule's output.

typeString

Type of algorithm that will be used to select the provider.

idString

The rule's ID.

REQUEST
  $ curl -vX POST https://merchant-api.switchpayments.com/v1/router/rules?merchant_id={accountId} -u accountId:merchantApiKey -d '{
    "charge_type": "card_onetime",
    "conditions": {
      "amount__gt": 50,
      "processing_currency__in": [
        "DOP"
      ]
    },
    "created_at": "2019-09-10T12:09:47.583718+00:00",
    "enabled": true,
    "priority": 2,
    "params": [
      {
        "channel": {
          "label": "card_onetime_cardnet",
          "processor": "cardnet",
          "id": "7581c500240442c1ec8b2f755583cdd4d488708f5ccb1ba5"
        },
        "value": 1
      }
    ],
    "type": "percentage",
    "id": "7d50afab5076d99ffcf84ce3abe7b056ab8844c45cd0190b"
  }

Result Parameters

charge_typeString

Identifier of the charge type (e.g. card_onetime, card_recurring, paypal).

conditionsJSON Object

The routing conditions.

created_atString

The date when the rule was created.

updated_atString

The date when the rule was last updated.

enabledBoolean

Whether the rule is currently enabled or not.

priorityInteger

The rule's priority. 0 being the top priority.

paramsArray

Required configurations to calculate the rule's output.

typeString

Type of algorithm that will be used to select the provider.

idString

The rule's ID.

RESULT: HTTP 201
  {
    "charge_type": "card_onetime",
    "conditions": {
      "amount__gt": 50,
      "processing_currency__in": [
        "DOP"
      ]
    },s
    "created_at": "2019-09-10T12:09:47.583718+00:00",
    "enabled": true,
    "priority": 2,
    "params": [
      {
        "channel": {
          "label": "card_onetime_cardnet",
          "processor": "cardnet",
          "id": "7581c500240442c1ec8b2f755583cdd4d488708f5ccb1ba5"
        },
        "value": 1
      }
    ],
    "type": "percentage",
    "id": "7d50afab5076d99ffcf84ce3abe7b056ab8844c45cd0190b"
  }

GET `/v1/router/rules`

Method	Path	Description
GET	Sandbox `https://merchant-api-test.switchpayments.com/v1/router/rules` Production `https://merchant-api.switchpayments.com/v1/router/rules`	List the available Dynamic Routing rules.

Result Parameters

charge_typeString

Identifier of the charge type (e.g. card_onetime, card_recurring, paypal). If the request does not include charge_type, all charge types will be returned.

conditionsJSON Object

The routing conditions.

created_atString

The date when the rule was created.

updated_atString

The date when the rule was last updated.

enabledBoolean

Whether the rule is enabled or not.

priorityInteger

The rule's priority. 0 being the top priority.

paramsArray

Necessary configurations to calculate the rule's output.

typeString

Type of algorithm that will be used to select the processor.

idString

The rule's ID.

REQUEST
  $ curl GET https://merchant-api.switchpayments.com/v1/router/rules?charge_type={chargeType}&merchant_id={accountId} -u accountId:merchantApiKey

RESULT: HTTP 200
  {
    "card_onetime": [
      {
        "charge_type": "card_onetime",
        "conditions": {
          "amount__gt": 50,
          "processing_currency__in": [
            "DOP"
          ]
        },
        "created_at": "2019-09-10T12:09:47.583718+00:00",
        "enabled": true,
        "priority": 2,
        "params": [
          {
            "channel": {
              "label": "card_onetime_cardnet",
              "processor": "cardnet",
              "id": "7581c500240442c1ec8b2f755583cdd4d488708f5ccb1ba5"
            },
            "value": 1
          }
        ],
        "type": "percentage",
        "id": "7d50afab5076d99ffcf84ce3abe7b056ab8844c45cd0190b"
      },
      {
        "charge_type": "card_onetime",
        "conditions": null,
        "created_at": null,
        "enabled": true,
        "updated_at": null,
        "priority": null,
        "params": [
          {
            "channel": {
              "label": "card_onetime_acapture",
              "processor": "acapture",
              "id": "9c62fb17a095f6dc32f3f36ea289f8a9473afcb95b1ead14"
            },
            "value": 1
          }
        ],
        "type": "percentage",
        "id": null
      }
    ]
  }

It is not possible to create a routing rule without registering all the required fields. Tending to this error case, a list with all the invalid fields and the respective errors is returned.

REQUEST
  $ curl -vX POST https://merchant-api.switchpayments.com/v1/router/rules?merchant_id={accountId} -u accountId:merchantApiKey -d '{
    "charge_type": "card_onetime",
    "type": "percentage"
  }'

Result Parameters

messageString

String with the error details, in this case: "Invalid parameters".

parametersJSON Object

A list with all the invalid fields and the respective errors.

RESULT: HTTP 400
  {
    "message": "Invalid parameters",
    "parameters": {
      "params": [
          "This field is required."
      ]
    }
  }

GET `/v1/router/rules/{id}`

Method	Path	Description
GET	Sandbox `https://merchant-api-test.switchpayments.com/v1/router/rules/{id}` Production `https://merchant-api.switchpayments.com/v1/router/rules/{id}`	Search a specific routing rules using its ID.

Result Parameter

charge_typeString

Identifier of the charge type (e.g. card_onetime, card_recurring, paypal).

conditionsJSON Object

The routing conditions.

created_atString

The date when the rule was created.

updated_atString

The date when the rule was last updated.

enabledBoolean

Whether the rule is currently enabled or not.

priorityInteger

The rule's priority. 0 being the top priority.

paramsArray

Required configurations to calculate the rule's output.

typeString

Type of algorithm that will be used to select the provider.

idString

The rule's ID.

REQUEST
  $ curl -vX GET https://merchant-api.switchpayments.com/v1/router/rules/{id}?merchant_id={accountId} -u accountId:merchantApiKey

RESULT: HTTP 200
  {
    "charge_type": "card_onetime",
    "conditions": {
      "amount__gt": 50,
      "processing_currency__in": [
        "DOP"
      ]
    },
    "created_at": "2019-09-10T12:09:47.583718+00:00",
    "enabled": true,
    "priority": 2,
    "params": [
      {
        "channel": {
          "label": "card_onetime_cardnet",
          "processor": "cardnet",
          "id": "7581c500240442c1ec8b2f755583cdd4d488708f5ccb1ba5"
        },
        "value": 1
      }
    ],
    "type": "percentage",
    "id": "7d50afab5076d99ffcf84ce3abe7b056ab8844c45cd0190b"
  }

PUT `/v1/router/rules/{id}`

Method	Path	Description
PUT	Sandbox `https://merchant-api-test.switchpayments.com/v1/router/rules/{id}` Production `https://merchant-api.switchpayments.com/v1/router/rules/{id}`	Substitute routing rule through its ID.

Request Parameters

charge_typeString

Identifier of the charge type (e.g. card_onetime, card_recurring, paypal).

conditionsJSON Object

The routing conditions.

created_atString

The date when the rule was created.

updated_atString

The date when the rule was last updated.

enabledBoolean

Whether the rule is currently enabled or not.

priorityInteger

The rule's priority. 0 being the top priority.

paramsArray

Necessary configurations to calculate the rule's output.

typeString

Type of algorithm that will be used to select the provider.

idString

The rule's ID.

REQUEST
  $ curl -vX PUT https://merchant-api.switchpayments.com/v1/router/rules/{id}?merchant_id={accountId} -u accountId:merchantApiKey -d '{
    "charge_type": "card_onetime",
    "conditions": {
      "amount__gt": 50,
      "processing_currency__in": [
        "DOP"
      ]
    },
    "created_at": "2019-09-10T12:09:47.583718+00:00",
    "enabled": true,
    "priority": 2,
    "params": [
      {
        "channel": {
          "label": "card_onetime_cardnet",
          "processor": "cardnet",
          "id": "7581c500240442c1ec8b2f755583cdd4d488708f5ccb1ba5"
        },
        "value": 1
      }
    ],
    "type": "percentage",
    "id": "7d50afab5076d99ffcf84ce3abe7b056ab8844c45cd0190b"
  }

Result Parameter

charge_typeString

Identifier of the charge type (e.g. card_onetime, card_recurring, paypal).

conditionsJSON Object

The routing conditions.

created_atString

The date when the rule was created.

updated_atString

The date when the rule was last updated.

enabledBoolean

Whether the rule is currently enabled or not.

priorityInteger

The rule's priority. 0 being the top priority.

paramsArray

Required configurations to calculate the rule's output.

typeString

Type of algorithm that will be used to select the provider.

idString

The rule's ID.

RESULT: HTTP 200
  {
    "charge_type": "card_onetime",
    "conditions": {
        "amount__gt": 50,
        "processing_currency__in": [
            "DOP"
        ]
    },
    "created_at": "2019-09-10T12:09:47.583718+00:00",
    "enabled": true,
    "priority": 2,
    "params": [
      {
        "channel": {
          "label": "card_onetime_cardnet",
          "processor": "cardnet",
          "id": "7581c500240442c1ec8b2f755583cdd4d488708f5ccb1ba5"
        },
        "value": 1
      }
    ],
    "type": "percentage",
    "id": "7d50afab5076d99ffcf84ce3abe7b056ab8844c45cd0190b"
  }

DELETE `/v1/router/rules/{id}`

REQUEST
  $ curl -vX DELETE https://merchant-api.switchpayments.com/v1/router/rules/{id}?merchant_id={accountId} -u accountId:apiKey

RESULT: HTTP 204 NO CONTENT

Conditions and Priority

Conditions set in routing rules can be related to five different variables: amount, processing currency, card BIN, card brand, and issuer country.

Condition Type	Condition	Example
Amount	greater than	`amount__gt: 100`
	greater than or equals	`{amount__gte: 101}`
	less than	`{amount__lt: 103}`
	less than or equals	`{amount__lte: 102}`
Processing Currency	in	`processing_currency__in: ["EUR"]`
	not in	`processing_currency__not_in: ["USD"]`
Card BIN	in	`{card_bin__in: ["377750", "377753"]}`
Card Brand	in	`{card_brand__in: ["AMERICAN EXPRESS"]}`
	not in	`{card_brand__not_in: ["AMERICAN EXPRESS"]}`
Issuer Country	in	`{issuer_country__in: ["US"]}`
	not in	`{issuer_country__not_in: ["US"]}`

POST `/v1/router/rules/priority`

Request Parameter

charge_typeString

Identifier of the charge type (card_onetime, card_recurring, paypal...)

priorityInteger

The rule's priority (the lower, the more priority it has)

REQUEST
  $ curl -vX POST https://merchant-api.switchpayments.com/v1/router/rules/priority?merchant_id={accountId} -u accountId:merchantApiKey -d '{
    "charge_type": "card_onetime",
    "priority": 2
  }

Result Parameter

charge_typeString

Identifier of the charge type (card_onetime, card_recurring, paypal...). If the request does not include charge_type, all charge types will be returned.

charge_typeString

Identifier of the charge type (card_onetime, card_recurring, paypal...).

conditionsJSON Object

The routing conditions.

created_atString

The date when the rule was created.

updated_atString

The date when the rule was last updated.

enabledBoolean

Whether the rule is enabled or not.

priorityInteger

The rule's priority (the lower, the more priority it has).

paramsArray

Necessary configurations to calculate the rule's output.

typeString

Type of algorithm that will be used to select the processor.

idString

The rule's ID.

RESULT: HTTP 200
  {
    "card_onetime": [
      {
        "charge_type": "card_onetime",
        "conditions": {
          "amount__gt": 50,
          "processing_currency__in": [
            "DOP"
          ]
        },
        "created_at": "2019-09-10T12:09:47.583718+00:00",
        "enabled": true,
        "priority": 2,
        "params": [
          {
            "channel": {
              "label": "card_onetime_cardnet",
              "processor": "cardnet",
              "id": "7581c500240442c1ec8b2f755583cdd4d488708f5ccb1ba5"
            },
            "value": 1
          }
        ],
        "type": "percentage",
        "id": "7d50afab5076d99ffcf84ce3abe7b056ab8844c45cd0190b"
      },
      {
          "charge_type": "card_onetime",
          "conditions": null,
          "created_at": null,
          "enabled": true,
          "updated_at": null,
          "priority": null,
          "params": [
            {
              "channel": {
                "label": "card_onetime_acapture",
                "processor": "acapture",
                "id": "9c62fb17a095f6dc32f3f36ea289f8a9473afcb95b1ead14"
              },
              "value": 1
            }
          ],
          "type": "percentage",
          "id": null
      }
    ]
  }

Strategy

When considering the course of action to take with your Routing Rules there are two strategies to keep in mind: Percentage and Fallback.

Tackle acceptance rates and recover lost revenue.

Declined transactions cost you money and potential customers. When planning a future-proof payment structure, the acceptance rate is seen as the critical metric to account for. Switch Dynamic Routing can help with that. Learn more about acceptance rates.

`type: "percentage"`

With percentage, you can distribute your transactions across any number of channels available to you. Under params you should list the channel_id of the channels you want to pick and in value the respective percentages of transactions intended for routing.

The probability of a given transaction landing on a specific channel is defined by an algorithm. With this in mind, the resulting distribution will not match precisely the one configured, but the bigger the number of transactions, the closer it will get to the set percentage goals. In the following example, we select two channels for routing, each of them holding 50% of the transactions.

STRATEGY PERCENTAGE EXAMPLE
    {
       "charge_type": "card_onetime",
       "conditions": [
           { amount__gt: 10000},
       ],
       "params": [
           {"channel_id": "1a2b3c4d5e", "value": 0.5},
           {"channel_id": "2a3b4c5d6e", "value": 0.5}
       ],
       "type": "percentage"
    }

`type: "fallback"`

With the fallback strategy, you are able to define which channels become the default for handling your transactions when a certain condition is verified. As you can observe in the request example that follows, the structure of the request is similar, minus the value attributed to the different percentages and changing the type of strategy. You are free to select multiple channels for this routing strategy.

STRATEGY FALLBACK EXAMPLE
    {
       "charge_type": "card_onetime",
       "conditions": [
           { amount__gt: 10000},
       ],
       "params": [
           {"channel_id": "1a2b3c4d5e"},
       ],
       "type": "fallback"
    }

Next Steps

After setting up your routing rules, you might want to consider jumping to another set of rules and improve the safety of your transactions. Head over to Risk and learn more about risk rules.

Dynamic Routing

Optimize your payments performance.

Get a better understanding of our Channels feature.

Routing Rules

Conditions and Priority

Strategy

Channels

Routing Rules

Want to know more about the Switch Dashboard?

Dynamic Routing is established when an instrument is created.

POST /v1/router/rules

Request Parameters

Result Parameters

GET /v1/router/rules

Result Parameters

Check out the following use case

Result Parameters

GET /v1/router/rules/{id}

Result Parameter

PUT /v1/router/rules/{id}

Request Parameters

Result Parameter

DELETE /v1/router/rules/{id}

Conditions and Priority

POST /v1/router/rules/priority

Request Parameter

Result Parameter

Strategy

Tackle acceptance rates and recover lost revenue.

type: "percentage"

type: "fallback"

Next Steps

POST `/v1/router/rules`

GET `/v1/router/rules`

GET `/v1/router/rules/{id}`

PUT `/v1/router/rules/{id}`

DELETE `/v1/router/rules/{id}`

POST `/v1/router/rules/priority`

`type: "percentage"`

`type: "fallback"`