Integrating Fraud Scoring Into Your Payment Flow Without Adding Latency

The most common integration mistake we see when fraud teams add a third-party scoring API is placing the API call after the payment gateway call. The checkout flow calls the gateway, gets an authorization response, then fires the fraud scoring call -- and uses the result to decide whether to capture or void the authorized transaction. This pattern has the fraud score, but the fraud score arrives too late to change the authorization outcome.

Where the API call needs to go

The Riskgrove API call needs to be placed before the payment gateway authorization request. In a standard payment flow, that means:

1. Customer submits payment form
2. Server collects card token + transaction fields
3. POST /v1/score to Riskgrove (async, ~40ms response)
4. Evaluate risk_score + recommendation
5. If recommendation == "decline": reject without calling gateway
6. If recommendation == "review": flag for manual review, call gateway
7. If recommendation == "approve": call gateway to authorize

In this pattern, the Riskgrove API call is synchronous from the perspective of your checkout flow -- you wait for the response before proceeding. The 40ms latency is within the tolerance budget of most payment UIs; users don't notice an additional 40ms on a checkout form submission that already involves a network round trip to your server.

The key requirement is that this happens on the server side, not in the browser. Do not make fraud API calls from client-side JavaScript -- the API key would be exposed, and the fraud signal context (IP address, device fingerprint) is more reliable when gathered server-side.

What fields to send

The Riskgrove scoring endpoint accepts the following fields, with the ones marked required being the minimum for a useful score:

• card_token (required): The tokenized card identifier from your PSP. We never receive raw card numbers.
• user_id: Your internal user identifier, if the buyer is authenticated. Passing this allows cross-session behavioral scoring for that account.
• amount_cents (required): Transaction amount in the smallest currency unit.
• currency: ISO 4217 code. Defaults to USD if omitted.
• device_id: Your device fingerprint identifier for the session. This is the primary signal for card testing and velocity pattern detection. Required for accurate scoring on guest checkout.
• merchant_category: The MCC code for this transaction. Used to evaluate whether the card's history is consistent with this merchant type.
• ip_address: The customer's IP address at checkout time. Pass the originating IP, not your server's IP.
• session_id: An identifier for this checkout session. Allows us to correlate multiple transaction attempts within a single checkout flow.

If you pass only card_token and amount_cents, you will get a score -- but it will have lower signal quality than a full request. The device_id field in particular has a large impact on card testing detection accuracy. If you do not already have a device fingerprinting solution, consider implementing one before integrating Riskgrove; the incremental fraud coverage from device signals is significant.

Handling timeouts

Any external API call in your checkout critical path needs a timeout and a fallback strategy. For Riskgrove, we recommend a 150ms timeout on the scoring call. If the call times out:

• Option 1 (conservative): Default to "review" -- proceed with the transaction but flag it for manual review. This minimizes false declines from API latency while maintaining a review queue for edge cases.
• Option 2 (permissive): Default to "approve" -- proceed with the transaction without a fraud score. Appropriate if your platform has low fraud exposure and checkout conversion is critical.
• Option 3 (strict): Default to "decline" -- reject transactions when the fraud score is unavailable. Appropriate for high-risk transaction categories (large amounts, digital goods, gift cards).

We observe a p99 latency under 90ms in production. Timeouts at 150ms should be rare. If you are seeing frequent timeouts, the issue is usually network routing between your servers and our API endpoint; contact us to configure a regional endpoint closer to your infrastructure.

Interpreting the response

The response includes three fields you need to evaluate:

• risk_score (0-100): Higher is riskier. Above 70 typically warrants a "review" action. Above 85 typically warrants a "decline." Thresholds should be calibrated to your platform's fraud tolerance and false-positive appetite.
• recommendation ("approve" / "review" / "decline"): Our default thresholds applied to the risk_score. Use this as a starting point and adjust based on your chargeback rate and customer support volume.
• top_signals: An array of string codes indicating the top contributing signals to the score. These are useful for your manual review queue -- a reviewer can see immediately whether the flag is from a device velocity issue vs. an account takeover indicator.

Do not treat the recommendation field as determinative without calibration. Our default thresholds are set for a mid-market platform with average fraud exposure. A BNPL platform with high-value average order values should use a lower risk_score threshold for declines than a low-AOV subscription platform. We provide threshold calibration guidance in our documentation based on your historical chargeback rate.

Testing before you go live

We provide a sandbox environment that accepts any card_token string and returns deterministic scores based on the token value. Use token strings beginning with "tok_test_decline_" to get a decline recommendation, "tok_test_review_" for a review recommendation, and "tok_test_approve_" for an approve. This lets you test your timeout handling, your review queue flow, and your decline path without touching production data.

Once you have validated the integration in sandbox, run a 7-day parallel evaluation in production: log the Riskgrove recommendation alongside your current fraud decision for each transaction, but do not act on it. Compare the Riskgrove recommendations to your post-authorization chargeback outcomes. This tells you what threshold calibration is appropriate for your transaction mix before you switch to acting on the recommendations.