Smart Routing

Introduction

Smart Routing is an advanced feature of the Token platform that optimizes payment processing by dynamically selecting the most suitable payment rail for each transaction. By leveraging real-time bank metadata and intelligent routing logic, Smart Routing ensures payments are processed efficiently, minimizing delays and costs while maximizing success rates.

This guide explains the business context, technical implementation, and integration steps for Smart Routing, making it accessible to both Product Managers and Developers.

Feature Overview

Smart Routing intelligently evaluates the capabilities and limits of connected banks to determine the optimal payment rail for a transaction. It ensures that payments are routed through the fastest, most cost-effective, and reliable rail available.

Key Benefits

• Optimize Payment Success Rates: Proactively select the appropriate rail to reduce failures due to limits or unsupported rails.

• Enhance User Experience: Seamless fallback to secondary rails, reducing disruptions and drop-offs.

• Improve Operational Efficiency: Automate rail selection, reducing manual intervention and error handling.

• Support Regional Variability: Accommodate unique payment infrastructures in different regions.

• Enable Scalability: Integrate with existing platform, supporting new banks and rails as needed.

Supported Countries

The Payment v2 API is progressively being rolled out across different European markets.
Availability is grouped into three categories:

• ✅ Fully Available – Production-ready, suitable for live payments.
• 🧪 Beta – Live and processing transactions but still under validation.
• 🛠️ Test Only – Available in sandbox/test environments only.

We aim to increase coverage across the rest of the eurozone.

To determine if a bank supports smart routing, filtering is enabled on GET /banks/v2. If a query parameter supportSmartRouting = true is provided, it will show only banks for which smart routing is possible.

How Smart Routing Works

Smart Routing uses real-time metadata about banks and their supported payment rails. When a payment is initiated, the system:

1. Checks the bank’s metadata for supported payment rails and their respective limits.

2. Selects the best rail (e.g., SEPA Instant if the amount is within the limit, or SEPA Credit Transfer if not).

3. If the primary rail is not suitable, the system seamlessly falls back to a secondary rail.

4. Token informs the TPP of the selected rail and this can be used to inform the PSU of the expected processing time.

This approach removes the need for manual rail selection, reducing complexity and the risk of failed transactions.

Using the Payment v2 API with Smart Routing

To enable Smart Routing, specify the "localInstrument": "AUTO_SELECT" in your payment initiation request. The platform will then dynamically select the most appropriate payment rail based on the bank’s capabilities, transaction amount, and current routing logic.

Example Payment Initiation

POST /v2/payments

{
    "initiation": {
        "bankId": "mock-redirect",
        "refId": "7156806",
        "remittanceInformationPrimary": "SteakNight",
        "remittanceInformationSecondary": "DemoSession",
        "amount": {
            "value": "1000.00",
            "currency": "GBP"
        },
        "localInstrument": "AUTO_SELECT",
        "creditor": {
            "name": "Dom Peter",
            "iban": "FR7630004005040001013515521"
        },
        "returnRefundAccount": true,
        "callbackUrl": "https://www.google.co.uk/",
        "flowType": "FULL_HOSTED_PAGES"
    }
}

Example Payment status

GET /v2/payments/{{paymentId}}

{
    "payment": {
        "id": "pm2:3QoreDUNFiFqFk3htM6W1fjMbXSN:2gFUX1NE25L",
        "initiation": {
            "bankId": "mock-redirect",
            "refId": "7156806",
            "amount": {
                "currency": "GBP",
                "value": "1000.00"
            },
            "localInstrument": "SEPA_INSTANT",
            "creditor": {
                "name": "Dom Peter",
                "iban": "FR7630004005040001013515521"
            },
            "callbackUrl": "https://www.google.co.uk/",
            "returnRefundAccount": true,
            "flowType": "FULL_HOSTED_PAGES"
        },
        "status": "INITIATION_COMPLETED",
        "bankPaymentStatus": "success",
        "statusReasonInformation": "success"
    },
    "message": "Payment will be processed via SEPA Credit Transfer. Estimated arrival: 1 business day."
}

Key Points

• Setting "localInstrument": "AUTO_SELECT" is the only way to leverage Smart Routing.

• No additional configuration is required; the platform handles all routing decisions.

• The system automatically falls back to a secondary rail if the primary rail is not suitable.

Regional Considerations

User Experience

• Proactive Rail Selection: The system evaluates transaction parameters before initiation, ensuring seamless fallback and reducing failures.

• Clear Messaging: TPP are informed of the selected rail and can inform the PSU of the expected processing time.

• Reduced Failures: Validation before authentication prevents post-auth failures and drop-offs.

Conclusion

Smart Routing significantly enhances payment processing by dynamically selecting the optimal payment rail based on real-time bank metadata, transaction amounts, and regional constraints. This results in a seamless, efficient, and user-friendly payment experience.

For further integration details and advanced scenarios, consult the API documentation.

If you have any feedback about the developer documentation, please contact devdocs@token.io