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

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.

  1. On the main navigation menu, select channels.
  2. From your list of available Channels, select the payment method you would like to apply Dynamic Routing to.
  3. Add routing rules or edit the existing ones according to your strategy.
  4. 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 paymment.

POST /v1/router/rules

MethodPathDescription
POSTSandbox
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 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 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 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 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

MethodPathDescription
GETSandbox
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 Parameter

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}

MethodPathDescription
GETSandbox
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}

MethodPathDescription
PUTSandbox
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 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

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 TypeConditionExample
Amountgreater thanamount__gt: 100
greater than or equals{amount__gte: 101}
less than{amount__lt: 103}
less than or equals{amount__lte: 102}
Processing Currencyinprocessing_currency__in: ["EUR"]
not inprocessing_currency__not_in: ["USD"]
Card BINin{card_bin__in: ["377750", "377753"]}
Card Brandin{card_brand__in: ["AMERICAN EXPRESS"]}
not in{card_brand__not_in: ["AMERICAN EXPRESS"]}
Issuer Countryin{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.

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.