Smart Routing

Spreedly Smart Routing is a beta feature that leverages Spreedly’s data to improve authorization rates by reducing false declines for participating merchants. This provides a better experience for buyers and increases top line revenue. Additionally, it reduces costs and time to market by freeing up engineering resources, making it easier to support a custom payment orchestration layer.

Get started with Smart Routing by following our Quick Start Guide.

How Smart Routing Works

Smart Routing leverages Spreedly’s data to optimize payment success rates for customers using multiple payment providers.

Success rate is calculated by considering three factors of the transaction:

  1. Issuing Country
  2. Card Type
  3. Card Brand

Issuing Country is derived from the credit card BIN (Bank Identification Number), the first six digits of a card number. Smart Routing then predicts a success rate for each gateway under consideration based on recent aggregated merchant data.

How to Use Smart Routing

You can access Smart Routing in two ways:

  1. Recommend + Transact API
  2. Recommendation API

The Recommend + Transact API is a full service option for customers that want Spreedly to handle the routing decision and route the transaction in tandem. Spreedly will make a recommendation and transact against the gateway in your environment with the highest chance of success.

The Recommendation API is a standalone recommendation-only service that is decoupled from Spreedly’s core Payments Orchestration Platform. Unlike the Recommend + Transact API, this service enables customers and partners who don’t tokenize or vault with Spreedly to leverage the Smart Routing decision engine. This is a lightweight API that can be plugged into a wide variety of payment stacks. You can request an API key for this service by contacting us.

Recommend + Transact API

Account Preparation

All gateways that you would like the Recommend + Transact API to consider must be in a single Spreedly environment, as the API operates on the environment level. The Recommend + Transact API will work if your environment has one gateway; however, you will start to see the impact of Smart Routing using multiple gateways. At this time, you cannot use the Recommend + Transact API if you have multiple gateway tokens of the same gateway type in an environment.

Recommend + Transact Quick Start

Get started with the Smart Routing Recommend + Transact API in three steps:

  1. Login using your user credentials through id.spreedly.com 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, enter in the default gateway token for your environment and hit save.

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

curl https://core.spreedly.com/v1/transactions/purchase.json \
-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"
  }
}'

How to Send a Transaction

Once your environment has Smart Routing enabled, you may begin to use it for authorize and purchase transactions.

You can begin by sending a portion of your Spreedly traffic through the transactions endpoints. For example, one approach is to use a 50/50 random split that sends half of transactions to the Smart Routing endpoint and the other half to the default gateway. This enables you to A/B test success rates using a control and challenge group and monitor for success rate improvements. You can monitor your success rate by checking your Spreedly Dashboard.

The following calls are supported, please see the API Reference for more details:

  • purchase with Smart Routing Recommend + Transact
    • Pass-in Credit Card: Pass a credit card directly to the purchase request without specifying a gateway. Smart routing will determine which gateway connected with your account has the highest success rate based on aggregated merchant data and the information sent in your purchase call. If the card number is valid, it will automatically be tokenized at Spreedly before sending to the gateway chosen by Smart Routing.
    • Tokenized Payment Method: Charge a tokenized payment method (already stored in the Spreedly environment) the specified amount. The payment method can be of any type (credit card, bank account, Apple Pay, etc…), as long as it exists in the specified environment. Smart routing will determine which gateway to send this purchase request to. For payment methods that are not credit cards, Smart Routing will route to the default gateway.
  • authorize with Smart Routing Recommend + Transact
    • Pass-in Credit Card: Pass a credit card directly into the authorize request. If the card number is valid, it will automatically be tokenized at Spreedly before sending to the gateway selected by Smart Routing.
    • Tokenized Payment Method: Authorize a tokenized payment method (already stored in the Spreedly environment) to be charged a specific amount. Smart routing determines the gateway to use for this request.

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": {
        "application_fee": "103",
        "receipt_email": "email@example.com"
      },
      "gateway2_name": {
        "merchant_reference": "cb76a9ffcb",
        "transfer_group": "ORDER10"
      }
    }
  }
}
<transaction>
  <gateway_specific_fields>
    <gateway1_name>
      <application_fee>103</application_fee>
      <receipt_email>email@example.com</receipt_email>
    </gateway1_name>
    <gateway2_name>
      <merchant_reference>cb76a9ffcb</merchant_reference>
      <transfer_group>ORDER10</transfer_group>
    </gateway2_name>
  </gateway_specific_fields>
</transaction>

Response Structure

The Recommend + Transact API 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"
        }
      ]
    }
  }
}
<transaction>
  <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>
  <state>succeeded</state>
  <token>MO7N9TAqVaQSOBgpEf77PaQN1DE</token>
  <transaction_type>Purchase</transaction_type>
  <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_specific_response_fields>
  </gateway_specific_response_fields>
  <gateway_transaction_id>48</gateway_transaction_id>
  <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>
  <currency_code>USD</currency_code>
  <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>
  <gateway_token>MHwwW5zPbprxEKE4Qf342j64pFn</gateway_token>
  <gateway_type>test</gateway_type>
  <shipping_address>
    <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>
  </shipping_address>
  <response>
    <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>
  </response>
  <api_urls>
  </api_urls>
  <payment_method>
    <token>3HrITgcUtha9zIFwgnw2mtB522f</token>
    <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>
    <storage_state>cached</storage_state>
    <test type="boolean">true</test>
    <metadata nil="true"></metadata>
    <callback_url nil="true"></callback_url>
    <last_four_digits>1111</last_four_digits>
    <first_six_digits>411111</first_six_digits>
    <card_type>visa</card_type>
    <first_name>Joe</first_name>
    <last_name>Smith</last_name>
    <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>
    <payment_method_type>credit_card</payment_method_type>
    <errors>
    </errors>
    <verification_value>XXX</verification_value>
    <number>XXXX-XXXX-XXXX-1111</number>
    <fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
  </payment_method>
  <routing>
    <routes type="array">
      <route>
        <rule>default_gateway</rule>
        <result>succeeded</result>
        <gateway_token>MHwwW5zPbprxEKE4Qf342j64pFn</gateway_token>
        <gateway_type>test</gateway_type>
      </route>
    </routes>
  </routing>
  <attempt_3dsecure type="boolean">false</attempt_3dsecure>
</transaction>

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.

Recommendation API

The Recommendation API is a standalone recommendation-only service that is decoupled from Spreedly’s core Payment Orchestration platform. There’s no need to transact with Spreedly or have relationships with payment gateways to use the service.

Recommendation Quick Start

Get started with the Recommendation API in three steps:

  1. Request an API Key by completing the contact us form on the Smart Routing Landing Page.
  2. Consider what “gateway_types” and “bin” you would like the Recommendation API to consider.
  3. Send a request to the Revenue Optimization endpoint using your API key:
curl -X POST https://ro.spreedly.com/api/v1/transaction-routing/recommendations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <your-api-key>" \
  -d '{
    "gateway_types": ["stripe", "braintree", "authorize_net"],
    "bin": "411111",
    "amount" : "300",
    "currency" : "USD"
  }'

When to Use

The Recommendation API can be plugged into a wide range of payment stacks to serve as the routing decision engine layer. Users that transact using direct gateway integrations or a Payment Orchestration Platform outside of Spreedly can use the Recommendation API as their core or supplementary routing decision engine.

Users can also use the Recommendation API to explore different gateway combinations before pursuing a business relationship with a new set of gateways.

Partners can leverage the Recommendation API on their platform for their customers instead of building their own.

How to Request a Recommendation

The customer can send API calls with their API key to ro.spreedly.com/api/v1. To request an API key, please contact product@spreedly.com. Requests should be structured to match the request format defined in the Recommendation API documentation.

We recommend reading the Smart Routing Frequently Asked Questions to learn more.