AI Payout & B2B Wallet API

Multi-Ledger Wallet Smart Settlement Routing Risk-Aware Payout Timing FX Netting Reconciliation Artifacts Idempotency + Webhooks
Operated by Spyface Tech Company, LLC • 30 N Gould St Ste N, Sheridan, WY 82801 USA • Support: hello@spyface.com

1) Core Capabilities

2) Wallet & Ledger Model

Each counterparty (supplier, clinic, partner, agency) is represented as a wallet account with distinct ledgers. The system uses double-entry principles to preserve invariants and make reconciliation deterministic.

// Ledger invariants (conceptual)
available + reserved + pending == balance_total
journal_entry: { debit_account, credit_account, amount, currency, reference }

3) Smart Settlement Routing (AI)

Routing selects the best payout rail/corridor for a given beneficiary, currency, and urgency. The objective is not “fastest” or “cheapest” alone; it optimizes expected total cost including failure overhead and operational rework.

expected_total_cost =
  base_fee(route)
+ fx_cost(route)
+ p_fail(route) * failure_overhead
+ ops_cost(route, beneficiary_risk)

4) Risk-Aware Payout Timing (AI)

Timing decisions schedule payouts based on dispute windows, refund likelihood, consumption status, and counterparty reliability. This prevents “pay too early, claw back later” failure modes.

holdback = f(p_refund, p_chargeback, amount, partner_dispute_rate, policy_rules)
schedule = argmin_time( expected_total_cost(time) ) subject to liquidity_constraints

5) Netting, Splits, and FX

// Example: netting
net_payable = sum(payables) - sum(reversals) - sum(setoffs)

// Example: split instruction
splits: [
  { beneficiary_id:"supplier_01", amount: 540 },
  { beneficiary_id:"agency_19",  amount: 80  },
  { beneficiary_id:"affiliate_7",amount: 20  }
]

6) Controls: Limits, Reserves, and Compliance

7) Endpoints

8) Schemas

Plan a payout (AI)

{
  "request_id":"req_plan_1001",
  "payout":{
    "wallet_id":"w_9012",
    "beneficiary_id":"b_771",
    "amount":6400,
    "currency":"USD",
    "urgency":"STANDARD",
    "purpose":"SUPPLIER_SETTLEMENT"
  },
  "context":{
    "product":"FLIGHT_BOOKING",
    "market":"US",
    "consumption_status":"TICKETED",
    "refund_window_days":7
  }
}

Plan response

{
  "request_id":"req_plan_1001",
  "route":{
    "rail":"BANK_TRANSFER",
    "corridor":"US->US",
    "provider_hint":"ROUTE_A"
  },
  "eta_bucket":"T+1",
  "p_fail":0.03,
  "expected_total_cost_usd":9.84,
  "holdback":{
    "amount":192,
    "currency":"USD",
    "policy":"RESERVE_3PCT_7D"
  },
  "recommended_actions":[
    {"type":"SCHEDULE", "execute_at":"2026-01-26T18:30:00Z"},
    {"type":"RESERVE", "ledger":"reserved", "amount":192}
  ],
  "reason_codes":[
    "LOW_FAILURE_CORRIDOR",
    "REFUND_WINDOW_ACTIVE",
    "PARTNER_STABLE"
  ]
}

Create payout

{
  "idempotency_key":"idem_payout_7f2c",
  "payout":{
    "wallet_id":"w_9012",
    "beneficiary_id":"b_771",
    "amount":6208,
    "currency":"USD",
    "reference":"INV-2026-00191",
    "metadata":{
      "booking_id":"bk_88219",
      "supplier_id":"sup_88"
    }
  },
  "execution":{
    "mode":"SCHEDULED",
    "execute_at":"2026-01-26T18:30:00Z"
  }
}

9) Idempotency, Webhooks, and Retries

// Retry guidance (conceptual)
if (http_status in [429, 503]) retry_with_exponential_backoff()
if (payout_failed && reason == "ROUTING_TEMPORARY") request_new_plan_and_reroute()

10) Code Examples

Node.js — Plan + Execute payout

const base = "https://api.spyface.com";
const headers = {
  "Authorization": `Bearer ${process.env.SPYFACE_API_KEY}`,
  "Content-Type": "application/json"
};

const planRes = await fetch(`${base}/v1/payouts/plan`, {
  method: "POST", headers, body: JSON.stringify(planPayload)
});
const plan = await planRes.json();

// Apply recommended actions (reserve/schedule) in your orchestration layer.
// Then create payout with idempotency key.
const payoutRes = await fetch(`${base}/v1/payouts`, {
  method: "POST",
  headers: { ...headers, "Idempotency-Key": "idem_payout_7f2c" },
  body: JSON.stringify(createPayoutPayload)
});
const payout = await payoutRes.json();
console.log(payout.status, payout.payout_id);

Python — Verify webhook signature (HMAC)

import hmac, hashlib

def verify(sig, ts, body, secret: bytes) -> bool:
  msg = (ts + "." + body).encode("utf-8")
  expected = hmac.new(secret, msg, hashlib.sha256).hexdigest()
  return hmac.compare_digest(sig, expected)

11) Reconciliation Artifacts

Reconciliation is deterministic when every payout and ledger movement shares stable references: reference, booking_id, journal_entry_id, and provider_trace_id.

{
  "payout_id":"po_55119",
  "status":"SETTLED",
  "provider_trace_id":"prov_9c21",
  "ledger_map":[
    {"journal_entry_id":"je_7711","ledger":"available","delta":-6208},
    {"journal_entry_id":"je_7712","ledger":"reserved","delta":-192}
  ],
  "export":{
    "type":"FINANCE_CSV",
    "hash":"sha256:..."
  }
}

12) Operational Playbooks