Quickstart

Score your first transaction in under 10 minutes. This guide walks through installation, initialization, your first scoring request, and reading the response.

1. Install the SDK

Choose your language. All three SDKs wrap the REST API with typed responses and automatic retry logic on transient errors.

Node.js

npm install @txnworks/node

Python

pip install txnworks

Go

go get github.com/txnworks/go-sdk

Prefer direct HTTP? All examples below also show the raw curl equivalent.

2. Initialize the client

Your API key is available in your dashboard after account provisioning. Keep it server-side only — never expose it in client-side code.

Node.js

const { Txnworks } = require('@txnworks/node');

const client = new Txnworks({
  apiKey: process.env.TXNWORKS_API_KEY
});

Python

import txnworks
import os

client = txnworks.Client(api_key=os.environ["TXNWORKS_API_KEY"])

Go

import (
    txnworks "github.com/txnworks/go-sdk"
    "os"
)

client := txnworks.NewClient(os.Getenv("TXNWORKS_API_KEY"))

3. POST your first score request

Required fields: transaction_id, amount, currency, merchant_id, card_fingerprint, device_id, ip_address.

Optional fields — user_agent, session_id, shipping_address, billing_address, email — extend signal depth. Include as many as your integration makes available.

Node.js

const result = await client.score({
  transaction_id: 'txn_' + Date.now(),
  amount: 215.00,
  currency: 'USD',
  merchant_id: 'mer_shopify_8821',
  card_fingerprint: 'fp_a3b9cc12',
  device_id: 'dev_cc41ee87',
  ip_address: '203.0.113.42',
  user_agent: req.headers['user-agent'],
  session_id: req.session.id
});

curl

curl -X POST https://api.txnworks.com/v1/score \
  -H "Authorization: Bearer $TXNWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_1750000001",
    "amount": 215.00,
    "currency": "USD",
    "merchant_id": "mer_shopify_8821",
    "card_fingerprint": "fp_a3b9cc12",
    "device_id": "dev_cc41ee87",
    "ip_address": "203.0.113.42"
  }'

4. Read the score response

The response arrives in under 50ms. The key fields to act on are label (ALLOW / REVIEW / BLOCK) and score (0–1000).

{
  "transaction_id": "txn_1750000001",
  "score": 312,
  "label": "ALLOW",
  "confidence": 0.87,
  "latency_ms": 41,
  "contributing_signals": [
    { "signal": "ip_reputation", "weight": 0.22, "value": "clean" },
    { "signal": "device_fingerprint", "weight": 0.18, "value": "known" },
    { "signal": "txn_count_1h", "weight": 0.15, "value": 1 }
  ],
  "thresholds_applied": { "block": 700, "review": 400 }
}

Act on label: ALLOW = proceed; REVIEW = queue for manual review; BLOCK = decline and return appropriate error to your user.

Log score + contributing_signals for your ops team's review queue. The contributing_signals explain exactly why the model assigned the score — your team can use this to understand and tune thresholds over time.

5. Submit outcome feedback

When a transaction you scored is confirmed as fraud (via chargeback), or confirmed as a false positive (customer dispute resolved in their favor), submit the outcome via POST /v1/feedback. This is how signal weights improve for your transaction mix.

curl -X POST https://api.txnworks.com/v1/feedback \
  -H "Authorization: Bearer $TXNWORKS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "txn_1750000001",
    "outcome": "confirmed_legitimate"
  }'

Valid outcome values: confirmed_fraud, false_positive, confirmed_legitimate.

Feedback is processed in daily batches. Signal weight updates deploy automatically — no version migration required.

Next: Full API Reference for complete parameter lists and response schemas.