# 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](https://docs.forter.com/predictive-payments-routing#target-integration-workflow)
### 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](https://docs.forter.com/predictive-payments-routing#recommended-integration-v3)
### 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](https://docs.forter.com/predictive-payments-routing#predictive-payment-routing-flow)
### Predictive Payment Routing Flow

The routing flow supports:

- 3DS recommendation - 3DS with the PSP
- 3DS recommendation + execution by Forter

## [Feature Access and Configurations](https://docs.forter.com/predictive-payments-routing#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

## [Handling the Order Response](https://docs.forter.com/predictive-payments-routing#handling-the-order-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.

### [Sample Response Structure](https://docs.forter.com/predictive-payments-routing#sample-response-structure)

```json
{
  "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](https://docs.forter.com/predictive-payments-routing#key-fields-in-paymentrecommendations)
### 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

## [Order Requests and Status Calls](https://docs.forter.com/predictive-payments-routing#order-requests-and-status-calls)
### 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](https://docs.forter.com/predictive-payments-routing#payment-processor-routing-recommendation-response)

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

## [Retry Policy and Edge Cases](https://docs.forter.com/predictive-payments-routing#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. 
- **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.