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 Quick Start

It’s easy to get started with Smart Routing. Follow this quick start guide to get started in 3 steps.

  1. Login using your user credentials through and ensure you’re on the Environments tab.

  2. Select your chosen environment and click “Configure” to open Environment Settings. In Environment Settings, click “Edit Settings” to proceed. At the bottom of this page, press the Smart Routing toggle switch and enter in your default environment gateway token.

Image showing the checkbox to enable Smart Routing for your Environment 3. Send a test transaction to your Smart Routing endpoint, you can use this code snippet to test a transaction yourself:

curl \
-u 'environment-key:access-secret' \
-H 'Content-Type: application/json' \
-d '{
  "transaction": {
    "credit_card": {
      "first_name": "Joe",
      "last_name": "Smith",
      "number": "4111111111111111",
      "verification_value": "123",
      "month": "12",
      "year": "2025"
    "amount": 100,
    "currency_code": "USD"

Smart Routing Preparation

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.

If you’re interested in the Smart Routing beta trial, you must enable “Smart Routing (Beta)” on your Environment Settings UI (shown below) and enter in a valid default gateway token.

How to Use Smart Routing

Once your environment is 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>

How to set up Volume Commitments

The Smart Routing endpoint now supports the ability to prioritize volume based commitments before activating success based routing. This will allow you to fulfill contractual obligations or reach a discount tier with a PSP while also maximizing your success rates.

Volume Commitment allows you to define a minimum threshold, let’s call this $X, in USD for a specific gateway. Volume Commitment works by sending the first $X in transactions for the month to said gateway. Once this minimum threshold is reached, Smart Routing will shift to success based routing and consider all gateways tied to your environment for the remainder of the month. At the start of the next month, this process will reset. Volume Commitments are calculated using Net Processing Amount (monthly processing volume minus refunds and disputes) in USD.

To set up a volume commitment through Smart Routing, send us a request using this form, or otherwise contact your account manager and we can set up volume commitments on your behalf.

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: Can I control how much volume one payment provider receives over another?

Yes, you can now fulfill volume commitments using the Smart Routing endpoint. To enable volume commitment, refer to our volume commitment guide. This will allow you to meet your volume based commitments before activating success based routing.

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.