Make your first evaluation

You need an environment base URL, API key, and HMAC secret supplied by Vantrace. The examples below send the same minimal outbound-transfer payload; account_snapshot and context are optional and are covered in the request schema.

1. Set your credentials

export VANTRACE_BASE_URL="https://your-authorised-base-url"
export VANTRACE_API_KEY="your-api-key"
export VANTRACE_HMAC_SECRET="your-hmac-secret"

Keep these values in a server-side secret manager. Do not put them in browser code or source control.

2. Copy and run one complete example

Every example serializes the payload once, signs those exact UTF-8 bytes, and sends the same bytes as the request body.

cURL

Requires Bash, cURL, OpenSSL, and uuidgen.

body='{"transaction":{"reference_id":"BANK-TXN-0001","amount":25000.0,"currency":"NGN","trx_type":"transfer","channel":"mobile_app","txn_direction":"outbound","is_cash":false,"source_account_id":41001,"evaluated_account_id":41001,"beneficiary_account_id":91001},"customer":{"customer_id":"CUST-1001","entity_type":"individual","kyc_tier":2,"is_pep":false,"sanctions_flag":false,"adverse_media_flag":false,"is_shell_company":false,"has_complete_cdd":true},"context":{"current_balance":480000.0}}'
timestamp="$(date -u +"%Y-%m-%dT%H:%M:%SZ")"
request_id="$(uuidgen)"
signature="$(printf '%s' "$body" | openssl dgst -sha256 -hmac "$VANTRACE_HMAC_SECRET" -hex | sed 's/^.* //')"

curl --fail-with-body --request POST \
  "$VANTRACE_BASE_URL/v1/engine/evaluate" \
  --header 'Content-Type: application/json' \
  --header "X-API-Key: $VANTRACE_API_KEY" \
  --header 'X-Signature-Version: v2' \
  --header "X-Timestamp: $timestamp" \
  --header "X-Request-ID: $request_id" \
  --header "X-Signature: $signature" \
  --data-binary "$body"

Node.js

Requires Node.js 18 or later.

import crypto from 'node:crypto';

const payload = {
  transaction: {
    reference_id: 'BANK-TXN-0001',
    amount: 25000.0,
    currency: 'NGN',
    trx_type: 'transfer',
    channel: 'mobile_app',
    txn_direction: 'outbound',
    is_cash: false,
    source_account_id: 41001,
    evaluated_account_id: 41001,
    beneficiary_account_id: 91001,
  },
  customer: {
    customer_id: 'CUST-1001',
    entity_type: 'individual',
    kyc_tier: 2,
    is_pep: false,
    sanctions_flag: false,
    adverse_media_flag: false,
    is_shell_company: false,
    has_complete_cdd: true,
  },
  context: {
    current_balance: 480000.0,
  },
};

const body = JSON.stringify(payload);
const signature = crypto
  .createHmac('sha256', process.env.VANTRACE_HMAC_SECRET)
  .update(Buffer.from(body, 'utf8'))
  .digest('hex');

const response = await fetch(`${process.env.VANTRACE_BASE_URL}/v1/engine/evaluate`, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-Key': process.env.VANTRACE_API_KEY,
    'X-Signature-Version': 'v2',
    'X-Timestamp': new Date().toISOString(),
    'X-Request-ID': crypto.randomUUID(),
    'X-Signature': signature,
  },
  body,
});

const responseText = await response.text();
if (!response.ok) throw new Error(`Vantrace ${response.status}: ${responseText}`);
console.log(JSON.parse(responseText));

Run with node evaluate.mjs.

Python

Install the HTTP client with python -m pip install requests.

import hashlib
import hmac
import json
import os
import uuid
from datetime import datetime, timezone

import requests

payload = {
    "transaction": {
        "reference_id": "BANK-TXN-0001",
        "amount": 25000.0,
        "currency": "NGN",
        "trx_type": "transfer",
        "channel": "mobile_app",
        "txn_direction": "outbound",
        "is_cash": False,
        "source_account_id": 41001,
        "evaluated_account_id": 41001,
        "beneficiary_account_id": 91001,
    },
    "customer": {
        "customer_id": "CUST-1001",
        "entity_type": "individual",
        "kyc_tier": 2,
        "is_pep": False,
        "sanctions_flag": False,
        "adverse_media_flag": False,
        "is_shell_company": False,
        "has_complete_cdd": True,
    },
    "context": {
        "current_balance": 480000.0,
    },
}

body = json.dumps(payload, separators=(",", ":")).encode("utf-8")
signature = hmac.new(
    os.environ["VANTRACE_HMAC_SECRET"].encode("utf-8"),
    body,
    hashlib.sha256,
).hexdigest()

response = requests.post(
    f'{os.environ["VANTRACE_BASE_URL"]}/v1/engine/evaluate',
    data=body,
    headers={
        "Content-Type": "application/json",
        "X-API-Key": os.environ["VANTRACE_API_KEY"],
        "X-Signature-Version": "v2",
        "X-Timestamp": datetime.now(timezone.utc).isoformat(),
        "X-Request-ID": str(uuid.uuid4()),
        "X-Signature": signature,
    },
)

response.raise_for_status()
print(response.json())

Run with python evaluate.py.

Java

Requires Java 17 or later and no third-party dependencies.

import java.net.URI;
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.nio.charset.StandardCharsets;
import java.time.Instant;
import java.util.HexFormat;
import java.util.UUID;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;

public class Evaluate {
  public static void main(String[] args) throws Exception {
    String body = """
      {"transaction":{"reference_id":"BANK-TXN-0001","amount":25000.0,"currency":"NGN","trx_type":"transfer","channel":"mobile_app","txn_direction":"outbound","is_cash":false,"source_account_id":41001,"evaluated_account_id":41001,"beneficiary_account_id":91001},"customer":{"customer_id":"CUST-1001","entity_type":"individual","kyc_tier":2,"is_pep":false,"sanctions_flag":false,"adverse_media_flag":false,"is_shell_company":false,"has_complete_cdd":true},"context":{"current_balance":480000.0}}""".strip();

    Mac mac = Mac.getInstance("HmacSHA256");
    mac.init(new SecretKeySpec(
        System.getenv("VANTRACE_HMAC_SECRET").getBytes(StandardCharsets.UTF_8),
        "HmacSHA256"));
    String signature = HexFormat.of().formatHex(
        mac.doFinal(body.getBytes(StandardCharsets.UTF_8)));

    HttpRequest request = HttpRequest.newBuilder()
        .uri(URI.create(System.getenv("VANTRACE_BASE_URL") + "/v1/engine/evaluate"))
        .header("Content-Type", "application/json")
        .header("X-API-Key", System.getenv("VANTRACE_API_KEY"))
        .header("X-Signature-Version", "v2")
        .header("X-Timestamp", Instant.now().toString())
        .header("X-Request-ID", UUID.randomUUID().toString())
        .header("X-Signature", signature)
        .POST(HttpRequest.BodyPublishers.ofString(body, StandardCharsets.UTF_8))
        .build();

    HttpResponse<String> response = HttpClient.newHttpClient()
        .send(request, HttpResponse.BodyHandlers.ofString());
    if (response.statusCode() / 100 != 2) {
      throw new RuntimeException("Vantrace " + response.statusCode() + ": " + response.body());
    }
    System.out.println(response.body());
  }
}

Run with java Evaluate.java.

Go

Uses only the Go standard library.

package main

import (
  "crypto/hmac"
  "crypto/rand"
  "crypto/sha256"
  "encoding/hex"
  "fmt"
  "io"
  "net/http"
  "os"
  "strings"
  "time"
)

func main() {
  body := `{"transaction":{"reference_id":"BANK-TXN-0001","amount":25000.0,"currency":"NGN","trx_type":"transfer","channel":"mobile_app","txn_direction":"outbound","is_cash":false,"source_account_id":41001,"evaluated_account_id":41001,"beneficiary_account_id":91001},"customer":{"customer_id":"CUST-1001","entity_type":"individual","kyc_tier":2,"is_pep":false,"sanctions_flag":false,"adverse_media_flag":false,"is_shell_company":false,"has_complete_cdd":true},"context":{"current_balance":480000.0}}`

  mac := hmac.New(sha256.New, []byte(os.Getenv("VANTRACE_HMAC_SECRET")))
  mac.Write([]byte(body))
  signature := hex.EncodeToString(mac.Sum(nil))
  requestIDBytes := make([]byte, 16)
  if _, err := rand.Read(requestIDBytes); err != nil { panic(err) }
  requestIDBytes[6] = (requestIDBytes[6] & 0x0f) | 0x40
  requestIDBytes[8] = (requestIDBytes[8] & 0x3f) | 0x80
  requestID := fmt.Sprintf("%x-%x-%x-%x-%x",
    requestIDBytes[0:4], requestIDBytes[4:6], requestIDBytes[6:8],
    requestIDBytes[8:10], requestIDBytes[10:16])

  request, err := http.NewRequest(
    http.MethodPost,
    os.Getenv("VANTRACE_BASE_URL")+"/v1/engine/evaluate",
    strings.NewReader(body),
  )
  if err != nil { panic(err) }
  request.Header.Set("Content-Type", "application/json")
  request.Header.Set("X-API-Key", os.Getenv("VANTRACE_API_KEY"))
  request.Header.Set("X-Signature-Version", "v2")
  request.Header.Set("X-Timestamp", time.Now().UTC().Format(time.RFC3339))
  request.Header.Set("X-Request-ID", requestID)
  request.Header.Set("X-Signature", signature)

  response, err := http.DefaultClient.Do(request)
  if err != nil { panic(err) }
  defer response.Body.Close()
  responseBody, err := io.ReadAll(response.Body)
  if err != nil { panic(err) }
  if response.StatusCode/100 != 2 {
    panic(fmt.Sprintf("Vantrace %d: %s", response.StatusCode, responseBody))
  }
  fmt.Println(string(responseBody))
}

Run with go run evaluate.go.

These first-call examples do not prescribe production timeout values. Before launch, configure explicit connect and read timeouts confirmed for your network path and integration agreement; see Reliability and retries.

Do not serialize twice

Do not sign one JSON string and then let an HTTP library serialize the object again. Whitespace, property order, and numeric formatting all change the signed bytes.

3. Read the response

A successful non-blocking response includes at least these decision fields:

{
  "evaluation_status": "complete",
  "should_block": false,
  "final_action": "none"
}

Settlement rule

Branch only on should_block

should_block = true  → do not settle
should_block = false → continue settlement

Do not use alert_ids, triggered-rule count, highest severity, Mule results, or asynchronous case status as the synchronous settlement gate.

Store your reference_id, the returned trx_id, and the X-Request-ID you generated for reconciliation.

Production retry warning

Do not blindly retry a request that times out. A timeout means the outcome may be unknown, and reference_id is not a server-side idempotency key. Follow Reliability and retries before another submission.

Next steps

• Review authentication and exact-byte signing.
• Confirm account mapping for each transaction direction.
• Read the complete request schema and response schema.
• Download the OpenAPI specification.
• Run the integration test cases.