Assess Payment Risk for an Agreement

Before a buyer funds an escrow agreement, you should run a payment risk assessment. This endpoint analyses the buyer’s transaction context — including device fingerprint and network signals — and returns a risk score alongside a colour-coded flag: GREEN, AMBER, or RED. When the flag is GREEN or AMBER, Vouch also returns the virtual bank account details the buyer should transfer funds to. If the flag is RED, the transaction should be blocked and no virtual account is provided.

Endpoint

POST /v1/escrow/agreements/:id/assess

Request

Headers

string

required

Your Vouch API key.

Path Parameters

string

required

The unique ID of the escrow agreement to assess. This is the id returned when you created the agreement (e.g. agr_clx8f7k2z000108l4).

Body Parameters

string

required

The buyer’s external ID as stored in your platform. Must match the buyerExternalId used when creating the agreement.

number

required

The amount the buyer intends to transfer, in the smallest currency unit (kobo for NGN). Should match the agreement’s totalAmount or a partial funding amount.

string

An opaque string uniquely identifying the buyer’s device. Providing this improves the accuracy of the risk score. Can be generated client-side using a fingerprinting library.

boolean

default:"false"

When set to true, the assessment engine treats the request as if it originated from a VPN. Useful for testing your integration’s RED-flag handling in non-production environments.

boolean

default:"false"

When set to true, the assessment engine simulates an impossible-travel signal. Useful for testing your integration in non-production environments.

Examples

curl --request POST \
  --url https://vouch-fmql.onrender.com/v1/escrow/agreements/agr_clx8f7k2z000108l4/assess \
  --header "Content-Type: application/json" \
  --header "x-api-key: <YOUR_API_KEY>" \
  --data '{
    "external_user_id": "client_buyer_123",
    "transaction_amount": 500000,
    "device_fingerprint": "abc123xyz",
    "simulate_vpn": false,
    "simulate_impossible_travel": false
  }'

import Vouch from "@vouch/sdk";

const vouch = new Vouch({ apiKey: process.env.VOUCH_API_KEY });

const assessment = await vouch.escrow.assess("agr_clx8f7k2z000108l4", {
  external_user_id: "client_buyer_123",
  transaction_amount: 500000,
  device_fingerprint: "abc123xyz",
});

if (assessment.flag === "RED") {
  // Block the transaction on your frontend
  throw new Error(assessment.recommendation);
}

// Present virtual account details to the buyer
console.log(assessment.virtualAccount?.accountNumber);

Response

number

A numeric risk score from 0 (lowest risk) to 100 (highest risk). Scores below roughly 30 yield GREEN, above 70 yield RED, and values in between yield AMBER.

string

The overall risk verdict. One of:

GREEN — transaction is low-risk; virtual account is provided.
AMBER — elevated risk; virtual account is provided but you may want to apply additional checks.
RED — high risk; no virtual account is returned and the transaction should be blocked.

object

The virtual bank account the buyer should transfer funds to. Only present when flag is GREEN or AMBER.

Show virtualAccount fields

string

The 10-digit virtual account number generated for this agreement.

string

The bank routing code for the virtual account provider.

string

The display name on the account, typically "Vouch Escrow — <buyerName>".

array

A list of signal identifiers that contributed to a high risk score. Only present on AMBER and RED responses. Example values: "vpn_detected", "impossible_travel", "device_mismatch".

string

A human-readable action recommendation. Only present on RED responses, e.g. "Block this transaction.".

The virtualAccount object is only returned when the flag is GREEN or AMBER. If the flag is RED, no virtual account is included in the response and you must not proceed with the payment. Always check the flag field before presenting account details to the buyer.

Example Response — GREEN

{
  "score": 15,
  "flag": "GREEN",
  "virtualAccount": {
    "accountNumber": "9988771122",
    "bankCode": "000017",
    "accountName": "Vouch Escrow — Acme Holdings"
  }
}

Example Response — RED

{
  "score": 87,
  "flag": "RED",
  "triggeredSignals": ["vpn_detected"],
  "recommendation": "Block this transaction."
}

Identity

Fraud

Escrow

Developer

Assess Payment Risk for an Agreement — Vouch API

Endpoint

Request

Headers

Path Parameters

Body Parameters

Examples

Response

Example Response — GREEN

Example Response — RED

​Endpoint

​Request

​Headers

​Path Parameters

​Body Parameters

​Examples

​Response

​Example Response — GREEN

​Example Response — RED

Endpoint

Request

Headers

Path Parameters

Body Parameters

Examples

Response

Example Response — GREEN

Example Response — RED