Predictive Payments Routing
Predictive Payment Routing (PPR) enables merchants to optimize their payment processing by dynamically selecting the best Payment Service Provider (PSP) for each transaction based on real-time performance signals.
Target Integration Workflow
Predictive Routing operates across three stages:
- Pre-Authorization - Initial routing recommendation
- Post-Authorization - Retry routing on decline
- Order Status - Final transaction reporting
Endpoints:
- /v3/adaptive-auth/orders/[orderId]
- /v3/orders/[orderId]
Recommended Integration - V3
Migrating from V2 to V3 provides merchants with a streamlined process by combining pre-auth, post-auth, and order status updates in a single integration. V3 offers improved routing recommendations, enhancing transaction approval rates and minimizing false declines. Leveraging advanced payment insights and fraud detection, V3 supports faster, more reliable processing and is prepared for future 3DS execution.
If a merchant requires V2, it remains fully functional, though additional internal testing will be necessary.
Predictive Payment Routing Flow
The routing flow supports:
- 3DS recommendation - 3DS with the PSP
- 3DS recommendation + execution by Forter
Feature Access and Configurations
Customer and Site Structure
Merchant: Represents the merchant, who may operate multiple sites.
Example:
- Customer: My Streaming Platform
- Sites: US Streaming, EU Streaming, Mobile App
Site: Each site under a Merchant may have its own payment configuration, including Payment Service Providers (PSPs), commitment levels, and routing preferences.
Predictive Payment Routing Feature
- Only customers with Predictive Payment Routing enabled will receive the paymentRecommendations field in the API response
- For customers without this feature enabled, paymentRecommendations will be absent from the response
- If Predictive Payment Routing is enabled for a customer:
- All of the customer's sites will include the paymentRecommendations field in the response
- However, only sites with the correct payment configurations will receive populated data within paymentRecommendations
Multiple Responses
Handling the Order Response
The paymentRecommendations field is an object in the response containing payment-related recommendations, including potential 3DS requirements. Merchants should use this object if it is present in the response.
Sample Response Structure
{
"forterDecision": "APPROVE",
"recommendation": "",
"verificationMethod": {},
"processor_routing_reason": "",
"orderId": "tr_zooIDSH7t2yX7Ha1qlioyZwlI7ngiHjl",
"linkToEventInDashboard": "https://portal.forter.com/dashboard/tr_zooIDSH7t2yX7Ha1qlioyZwlI7ngiHjl",
"paymentRecommendations": {
"processors": [
{
"processorName": "checkout.com",
"processorMid": "",
"priority": 1,
"recommendationId": "8b4a2159-9ab3-4e8f-9c83-0b12e7606458",
"recommend3DS": false,
"regulationRecommendation": ""
}
],
"processor_routing_reason": "model_recommendation",
"action": "process_payment"
}
}Key Fields in paymentRecommendations
processors: An array of recommended payment processors, each with:
Field | Description |
|---|---|
processorName | Name or identifier of the recommended processor |
processorMid | Merchant ID as identified by the processor |
priority | Priority ranking of the processor recommendation (e.g., 1 for highest priority) |
recommendationId | Unique identifier for the recommendation |
recommend3DS | Boolean indicating if 3DS verification is recommended |
regulationRecommendation | Text providing regulatory recommendations or compliance directives |
processor_routing_reason: Why Forter provided the recommendation. Possible values:
Value | Description |
|---|---|
model_recommendation | Standard model-based recommendation |
no_optional_processor | No optional processor available according to onboarding documentation |
ineffective | The model decided it will not be beneficial to retry |
out_of_scope | Traffic not part of the routing solution |
exceeded_processing_attempts | Merchant should send 2 iterations only |
completed_payment | Merchant sent request for routing recommendation for an authorized transaction |
regulationRecommendation possible values:
- VERIFICATION_REQUIRED_3DS_CHALLENGE
- REQUEST_SCA_EXEMPTION_TRA
- REQUEST_SCA_EXEMPTION_LOW_VALUE
- REQUEST_SCA_EXEMPTION_CORP
- REQUEST_SCA_EXEMPTION_TRUSTED_BENEFICIARY
- REQUEST_SCA_EXCLUSION_ANONYMOUS
- REQUEST_SCA_EXCLUSION_ONE_LEG_OUT
- REQUEST_SCA_EXCLUSION_MIT
- REQUEST_SCA_EXCLUSION_MOTO
action: Recommended action for the transaction. Possible values:
- process_payment
- do_not_process
- no_processor_preference
- Null
Currently, the processors array always includes one item only. In the future, it might be extended to support multiple items, thus it is an array.
Order Requests and Status Calls
Order Request
Used for the initial pre-auth request ("authorizationStep": "PRE_AUTHORIZATION") to retrieve the Predictive Routing decision.
If a processing attempt fails, submit a second Post auth Order request ("authorizationStep": "POST_AUTHORIZATION") with processing details:
- Processor name
- Processor response
- Authorization result (text and code)
- 3DS result, if applicable
Status Call
- If the first processing attempt is successful, send a Status Call with the authorization result
- If the second processing attempt fails, send a Status Call to report the failed authorization
In the Status Call merchant needs to send:
- Processor name
- Processor response
- Authorization result (text and code)
- 3DS result, if applicable
Summary: When to Use Order Calls and Status Calls
Use Case | Call Needed |
|---|---|
1st Pre Auth request | Order Pre auth call (to get Predictive Routing decision) |
1st Successful Processing attempt | Status Call (send Authorization result) |
1st Failed processing attempt | Post auth Call (Get 2nd Routing decision) |
2nd Failed Processing attempt | Status Call (Send Authorization result) |
2nd Successful Processing attempt | Status Call (Send Authorization result) |
Payment Processor Routing Recommendation Response Matrix
Use Case | Action | processor_routing_reason | Billable | Notes |
|---|---|---|---|---|
Processor recommendation | process_payment | model_recommendation | True | |
No optional processor | no_processor_preference | no_optional_processor | True | Edge case - monitor merchant to configure fallback |
Analytics decided not to retry | do_not_process | ineffective | True | Common |
Transaction not under solution | no_processor_preference | out_of_scope | False | Merchant to configure fallback |
Exceeded processing attempts | do_not_process | exceeded_processing_attempts | True | Only 2 iterations supported |
Technical Failure in analytics | N/A | N/A | False | Merchant to configure fallback |
Order call after successful payment | do_not_process | authorized_payment | True | |
Second iteration for 3DS policy | do_not_process | technical_3ds_limitation | True | Merchant does not allow multiple 3DS attempts |
Hard Fraud decline | do_not_process | hard_fraud_decline | False | |
Control group processing | process_payment | Control | True | |
Control group Do not process | do_not_process | Control | True | |
Single Response
Handling the Order Response
The paymentRecommendations field is an object in the response containing payment-related recommendations, including potential 3DS requirements. Merchants should use this object if it is present in the response.
For a full description of all fields, see Key Fields in paymentRecommendationsKey Fields in paymentRecommendations in the Multiple Responses section above.
Sample Response Structure - 2 Routing Recommendations
{
"paymentRecommendations": {
"processors": [
{
"processorMid": "",
"processorName": "nuvei",
"priority": 1,
"recommendationId": "28725caa-25a9-48f9-b1f6-cf3c0f40e143",
"recommend3DS": false,
"regulationRecommendation": ""
},
{
"processorMid": "",
"processorName": "worldpay",
"priority": 2,
"recommendationId": "c482f4c4-6b36-4ae9-a483-16014649112a",
"recommend3DS": true,
"regulationRecommendation": ""
}
],
"processor_routing_reason": "model_recommendation",
"action": "process_payment"
}
}Sample Response Structure - Do Not Retry (Single Recommendation)
When the Predictive Routing model doesn't recommend retrying after a failed authorization, Forter will return a single recommendation.
{
"paymentRecommendations": {
"processors": [
{
"processorMid": "",
"processorName": "nuvei",
"priority": 1,
"recommendationId": "28725caa-25a9-48f9-b1f6-cf3c0f40e143",
"recommend3DS": false,
"regulationRecommendation": ""
}
],
"processor_routing_reason": "model_recommendation",
"action": "process_payment"
}
}Sample Response Structure - Hard Decline
{
"paymentRecommendations": {
"processors": [],
"processor_routing_reason": "hard_fraud_decline",
"action": "do_not_process"
}
}Order Requests and Status Calls
In the single response format, the merchant sends a Status Call after every attempt, regardless of the outcome.
- If the first processing attempt is successful, send a Status Call with the authorization result
- If the second processing attempt fails, send a Status Call to report the failed authorization
Summary: When to Use Order Calls and Status Calls
Use Case | Call Needed |
|---|---|
1st Pre Auth request | Order call (to get Predictive Routing decision) |
1st Successful Processing attempt | Status Call (send Authorization result) |
1st Failed processing attempt | Status Call (send Authorization result) |
2nd Failed Processing attempt | Status Call (Send Authorization result) |
2nd Successful Processing attempt | Status Call (Send Authorization result) |
Retry Policy and Edge Cases
- No Retry Recommended: When the Predictive Routing model doesn't recommend retrying after a failed authorization, Forter will return a single recommendation. See Sample Response Structure - Do Not RetrySample Response Structure - Do Not Retry above.
- System Timeout: If the system experiences a timeout, the paymentRecommendations object may be absent from the response. Merchants should configure a default or fallback processor to handle these cases.
- No Available Processor: When no suitable processor is available for the transaction, an empty paymentRecommendations object will be returned.
- Non-Applicable Transactions: For transactions that do not qualify for predictive routing (e.g., sub-brands or transactions outside the configured sites), an empty paymentRecommendations object will be returned.
Important Disclaimer: The optimal performance of Predictive Payments Routing is subject to merchant following Forter's routing recommendation and the respective PSPs not applying their own rules after Forter's recommendation.
This API documentation may be subject to change as we make improvements or add features. Any updates will maintain backward compatibility, ensuring no breaking changes for existing integrations.