Smart Routing

Smart Routing is a beta feature that is open to Spreedly customers who want to improve their success rates.

Smart Routing enables merchants and payment managers to increase payment success rates, promoting a better experience for their customers and increasing top line revenue. Additionally, it will reduce costs and complexity for engineers who have limited capacity to build and support complicated routing rules.

To see a video about Smart Routing beta, and to sign up for more information, please visit our Smart Routing page and fill out the form.

What is Smart Routing?

Smart Routing is a beta feature that improves success rates for authorize and purchase transactions.

It currently optimizes for success rates by looking at three factors of the transaction: Issuing Country, Card Type, and Card Brand. Issuing Country is derived from the BIN (Bank Identification Number) tied to a card. Smart Routing then calculates which gateways connected to your environment have the highest recent success rate for those factors based on aggregated merchant data.

Smart Routing uses that criteria to determine an ordered list of gateways to run the transaction against. If a Gateway is marked as unavailable (by Spreedly’s internal systems), Smart Routing will automatically failover to the next gateway to process the transaction.

Diagram of how Smart Routing works

Smart Routing Preparation

Your account must have Smart Routing enabled in order to use this beta feature. If you’re interested in the Smart Routing beta trial, please contact Spreedly.

All gateways that you would like Smart Routing to consider must be in a single Spreedly environment, as Smart Routing operates on the environment level. Smart Routing will work if your environment has one gateway; however, there is no benefit in using Smart Routing until you have multiple gateways. At this time, you cannot use Smart Routing against any gateways that have multiple merchant accounts.

Once Spreedly has enabled Smart Routing beta for your account, you must enable “Smart Routing (Beta)” on your Environment Settings UI (shown below) and enter in a valid default gateway token.

Image showing the checkbox to enable Smart Routing for your Environment

How to Use Smart Routing

Once your account and environment are set up for Smart Routing, you may begin using it for authorize and purchase transactions.

You can ease into Smart Routing by sending a portion of your Spreedly traffic through the transactions endpoints. Please see the API documentation for more details on:

How to Send Gateway Specific Fields

Gateway specific fields are contained within a top-level gateway_specific_fields attribute, and can be sent for transactions against certain gateways.

When using Smart Routing, you should send gateway specific fields for all gateways in your environment.

Here is an example of how to send gateway specific fields for multiple gateways:

  "transaction": {
    "gateway_specific_fields": {
      "gateway1_name": {
        "car_color": "yellow",
        "frequent_flyer_id": "123"
      "gateway2_name": {
        "shirt_size": "large"

Smart Routing Response

A Smart Routing response is much like a traditional purchase or authorize response, with a few additions:

  • smart_routed - This attribute will be true when your request is to one of our transactions API endpoints.
  • routes - An ordered list of possible gateways, determined by Smart Routing, to try the request against.
    • rule - Each route has a rule attribute. This is the rule that was used to select that gateway for this transaction. The more criteria in the rule, the more granular the Smart Routing for the given transaction. If the default gateway is chosen due to other rules not fitting, this will be “default_gateway”.
    • result - Each route has a result attribute. This is the result from the gateway. If it is null, that means Smart Routing did not run a request against that gateway.

You can notice these fields in the sample response below:

  "transaction": {
    "on_test_gateway": true,
    "created_at": "2020-09-16T15:43:53Z",
    "updated_at": "2020-09-16T15:43:53Z",
    "succeeded": true,
    "state": "succeeded",
    "token": "MxG98de5rrU4jObeLkW8EsuTims",
    "transaction_type": "Purchase",
    "order_id": null,
    "ip": null,
    "description": null,
    "email": null,
    "merchant_name_descriptor": null,
    "merchant_location_descriptor": null,
    "gateway_specific_fields": null,
    "gateway_specific_response_fields": {
    "gateway_transaction_id": "57",
    "gateway_latency_ms": 0,
    "stored_credential_initiator": null,
    "stored_credential_reason_type": null,
    "warning": null,
    "amount": 100,
    "currency_code": "USD",
    "retain_on_success": false,
    "payment_method_added": true,
    "smart_routed": true,
    "message_key": "messages.transaction_succeeded",
    "message": "Succeeded!",
    "gateway_token": "MHwwW5zPbprxEKE4Qf342j64pFn",
    "gateway_type": "test",
    "response": {
      "success": true,
      "message": "Successful purchase",
      "avs_code": null,
      "avs_message": null,
      "cvv_code": null,
      "cvv_message": null,
      "pending": false,
      "result_unknown": false,
      "error_code": null,
      "error_detail": null,
      "cancelled": false,
      "fraud_review": null,
      "created_at": "2020-09-16T15:43:53Z",
      "updated_at": "2020-09-16T15:43:53Z"
    "shipping_address": {
      "name": "Joe Smith",
      "address1": null,
      "address2": null,
      "city": null,
      "state": null,
      "zip": null,
      "country": null,
      "phone_number": null
    "api_urls": [
        "referencing_transaction": [

        "failover_transaction": [

    "attempt_3dsecure": false,
    "payment_method": {
      "token": "WlQynb4WROt4mQBbYEH78sos0Jw",
      "created_at": "2020-09-16T15:43:52Z",
      "updated_at": "2020-09-16T15:43:53Z",
      "email": null,
      "data": null,
      "storage_state": "cached",
      "test": true,
      "metadata": null,
      "callback_url": null,
      "last_four_digits": "1111",
      "first_six_digits": "411111",
      "card_type": "visa",
      "first_name": "Joe",
      "last_name": "Smith",
      "month": 12,
      "year": 2025,
      "address1": null,
      "address2": null,
      "city": null,
      "state": null,
      "zip": null,
      "country": null,
      "phone_number": null,
      "company": null,
      "full_name": "Joe Smith",
      "eligible_for_card_updater": true,
      "shipping_address1": null,
      "shipping_address2": null,
      "shipping_city": null,
      "shipping_state": null,
      "shipping_zip": null,
      "shipping_country": null,
      "shipping_phone_number": null,
      "payment_method_type": "credit_card",
      "errors": [

      "fingerprint": "e3cef43464fc832f6e04f187df25af497994",
      "verification_value": "XXX",
      "number": "XXXX-XXXX-XXXX-1111"
    "routing": {
      "routes": [
          "gateway_token": "MHwwW5zPbprxEKE4Qf342j64pFn",
          "gateway_type": "test",
          "rule": "default_gateway",
          "result": "succeeded"
  <on_test_gateway type="boolean">true</on_test_gateway>
  <created_at type="dateTime">2020-09-16T15:43:52Z</created_at>
  <updated_at type="dateTime">2020-09-16T15:43:52Z</updated_at>
  <succeeded type="boolean">true</succeeded>
  <order_id nil="true"></order_id>
  <ip nil="true"></ip>
  <description nil="true"></description>
  <email nil="true"></email>
  <merchant_name_descriptor nil="true"></merchant_name_descriptor>
  <merchant_location_descriptor nil="true"></merchant_location_descriptor>
  <gateway_specific_fields nil="true"></gateway_specific_fields>
  <gateway_latency_ms type="integer">0</gateway_latency_ms>
  <stored_credential_initiator nil="true"></stored_credential_initiator>
  <stored_credential_reason_type nil="true"></stored_credential_reason_type>
  <warning nil="true"></warning>
  <amount type="integer">100</amount>
  <retain_on_success type="boolean">false</retain_on_success>
  <payment_method_added type="boolean">true</payment_method_added>
  <smart_routed type="boolean">true</smart_routed>
  <message key="messages.transaction_succeeded">Succeeded!</message>
    <name>Joe Smith</name>
    <address1 nil="true"></address1>
    <address2 nil="true"></address2>
    <city nil="true"></city>
    <state nil="true"></state>
    <zip nil="true"></zip>
    <country nil="true"></country>
    <phone_number nil="true"></phone_number>
    <success type="boolean">true</success>
    <message>Successful purchase</message>
    <avs_code nil="true"></avs_code>
    <avs_message nil="true"></avs_message>
    <cvv_code nil="true"></cvv_code>
    <cvv_message nil="true"></cvv_message>
    <pending type="boolean">false</pending>
    <result_unknown type="boolean">false</result_unknown>
    <error_code nil="true"></error_code>
    <error_detail nil="true"></error_detail>
    <cancelled type="boolean">false</cancelled>
    <fraud_review nil="true"></fraud_review>
    <created_at type="dateTime">2020-09-16T15:43:52Z</created_at>
    <updated_at type="dateTime">2020-09-16T15:43:52Z</updated_at>
    <created_at type="dateTime">2020-09-16T15:43:52Z</created_at>
    <updated_at type="dateTime">2020-09-16T15:43:52Z</updated_at>
    <email nil="true"></email>
    <data nil="true"></data>
    <test type="boolean">true</test>
    <metadata nil="true"></metadata>
    <callback_url nil="true"></callback_url>
    <month type="integer">12</month>
    <year type="integer">2025</year>
    <address1 nil="true"></address1>
    <address2 nil="true"></address2>
    <city nil="true"></city>
    <state nil="true"></state>
    <zip nil="true"></zip>
    <country nil="true"></country>
    <phone_number nil="true"></phone_number>
    <company nil="true"></company>
    <full_name>Joe Smith</full_name>
    <eligible_for_card_updater type="boolean">true</eligible_for_card_updater>
    <shipping_address1 nil="true"></shipping_address1>
    <shipping_address2 nil="true"></shipping_address2>
    <shipping_city nil="true"></shipping_city>
    <shipping_state nil="true"></shipping_state>
    <shipping_zip nil="true"></shipping_zip>
    <shipping_country nil="true"></shipping_country>
    <shipping_phone_number nil="true"></shipping_phone_number>
    <routes type="array">
  <attempt_3dsecure type="boolean">false</attempt_3dsecure>

Smart Routing Frequently Asked Questions

Q: How much does Smart Routing Cost?

Customers may use Smart Routing at no additional cost during the beta period.

Q: Do I have to use Smart Routing for all my transactions?

No. You may use Smart Routing for a portion of your transactions if you choose. You can determine which transactions to send to the Smart Routing gateway, and which transactions to send to a specific gateway.

Q: How often is the gateway success rate updated?

This is based on near real-time performance, and is refreshed every four hours.

Q: What is the minimum criteria for transaction data to be included in the success rate database?

There must be at least 200 transactions in a four-hour period for the given gateway.

Q: How do I change my default gateway?

You can change the default gateway by going to environment settings and replacing the existing default gateway with a new default gateway token. To view all gateway tokens on your account, go to the Spreedly Dashboard and click on “Gateways”.

Q: Which gateway should I use as the default gateway?

Your default gateway should be the gateway you find most reliable in case Smart Routing cannot find an available gateway using the logic described in What is Smart Routing?. Your default gateway must be a Supported Gateway and be linked to your Smart Routing environment.

Q: What happens when a non-card payment method is sent to the transactions endpoint?

Smart Routing will send a non-card payment method to your default gateway.

Q: What Card Brands are supported?

All Spreedly cards are supported, but those not meeting minimum volume criteria will be routed to the default gateway.

Q: What criteria does Spreedly use to build this list?

authorize and purchase transaction success rates

Q: What is Spreedly’s definition of Gateway Success Rates?

(Number of successful transactions) / (Number of attempted transactions)

Q: How do I know if a transaction was routed via Smart Routing?

The response code will now include the field smart_routed with the value true.

Q: What happens if the gateway Spreedly tries to use is down?

The next best gateway, as determined by Smart Routing, is selected. The configured default gateway is used in the case that no gateway meets the criteria.

Q: What if I have multiple gateway tokens for the same gateway created in one environment?

This is currently not supported in Smart Routing. There must be only one of any gateway type per environment.

Q: How do I send gateway specific fields if I don’t know which gateway the routing engine will select?

All gateway specific fields for every gateway should be sent in a single transaction. Spreedly will only send those relevant to the selected gateway.

Q: Can I exclude gateways from the routing selection process?

No, every gateway created in an environment is included.

Q: Aside from gateway-specific fields and the transactions endpoint, are there any other integration changes I must make to use Smart Routing?


Q: Are retried transactions counted in success rate calculations, or are they idempotent?

Customer-retried transaction attempts are considered individual transactions and do affect success rate metrics.

Q: Is there an override for Smart Routing transactions API to explicitly select a gateway?

Not today. To explicitly choose a gateway you may use the traditional gateways API.

Q: Which gateways are eligible to be selected for Smart Routing?

Smart Routing will choose among all gateways configured for your environment. Customers must have an existing gateway relationship configured in Spreedly for the gateway to be selected.

Q: Does Smart Routing directly support 3DS2 transactions?

Smart Routing will not support 3DS2 during the beta period. You may send transactions that don’t require Secure Customer Authentication (SCA) to the Smart Routing endpoint.