PayinferencePayinferenceDocs
payinference.com
Documentation / Start here

Getting started

From zero to your first decision, executed instruction, and reported outcome, against the hosted sandbox. Nothing to install and nothing to run.

1. Get a sandbox key#

Create a workspace at https://dashboard.payinference.com, then go to Developers → API keys and create a key in test mode. The raw secret is shown once, at creation.

Item Value
Base URL https://api.payinference.com
Auth x-api-key: <your test key>
Mode test — every decision is recorded "mode": "test"

Keep the key in an environment variable; the examples below read it from there.

bash 
export PAYINFERENCE_API_KEY=pi_test_your_key_here

Your workspace starts with one merchant. Use its merchant id (shown on Workspace → Settings) wherever the examples say m_123.

2. Create your first decision#

Every request needs an x-api-key header and safe payment context only — card numbers, CVVs, and emails are rejected by the schema, not ignored.

bash 
curl -s https://api.payinference.com/v1/decision \
  -H "content-type: application/json" \
  -H "x-api-key: $PAYINFERENCE_API_KEY" \
  -d '{
    "merchant_id": "m_123",
    "order_id": "order_456",
    "transaction": {
      "amount": 14900,
      "currency": "USD",
      "country": "US",
      "payment_method": "card",
      "card_network": "visa",
      "customer_type": "returning"
    },
    "available_providers": ["stripe", "adyen", "paypal"]
  }'

The response contains exactly one instruction in action, plus the evidence behind it:

json 
{
  "decision_id": "dec_9f3a1c0b22d14e55",
  "merchant_id": "m_123",
  "mode": "test",
  "action": "route",
  "route": { "primary_provider": "adyen", "fallback_provider": "stripe" },
  "risk": {
    "score": 0,
    "band": "low",
    "recommended_action": "route",
    "reason_codes": ["NORMAL_AMOUNT_FOR_MERCHANT", "RETURNING_CUSTOMER"]
  },
  "provider_health": {
    "adyen": { "score": 94, "state": "healthy", "confidence": 91, "source": "probe" },
    "stripe": { "score": 68, "state": "degraded", "confidence": 88, "source": "probe" }
  },
  "policy": {
    "policy_id": "policy_m_123_v1",
    "policy_version": "1.0.0",
    "matched_rules": ["avoid_degraded_providers"]
  },
  "model": {
    "model_version": "deterministic-v1",
    "route_scores": { "adyen": 0.91, "stripe": 0.64 }
  },
  "reason_codes": ["ADYEN_HEALTHY_FOR_SEGMENT", "HIGHER_EXPECTED_APPROVAL_RATE", "RISK_ACCEPTABLE"],
  "decision_latency_ms": 11.4,
  "ttl_ms": 3000
}

3. Handle the instruction#

Switch on action and execute through your own payment stack. There are seven instructions — see Decision instructions for what each obliges you to do.

ts 
switch (decision.action) {
  case 'route':
  case 'failover':
    return chargeWithProvider(decision.route!.primary_provider, order);

  case 'use_default_route':
    return chargeWithDefaultProvider(order);

  case 'step_up':
    return requireThreeDS(order, decision.decision_id);

  case 'hold':
    return parkForReview(order, decision.decision_id);

  case 'retry':
    return retryWithPolicy(order, decision.route);

  case 'block':
    return rejectPayment(order, decision.decision_id, decision.reason_codes);
}

4. Report the outcome#

After your PSP call finishes, tell PayInference what happened. This feeds provider health, analytics, and policy evaluation. It is safe to fire and forget.

bash 
curl -s https://api.payinference.com/v1/outcomes \
  -H "content-type: application/json" \
  -H "x-api-key: $PAYINFERENCE_API_KEY" \
  -d '{
    "decision_id": "dec_9f3a1c0b22d14e55",
    "order_id": "order_456",
    "provider_used": "adyen",
    "outcome": "approved",
    "provider_latency_ms": 842,
    "amount": 14900,
    "currency": "USD"
  }'

5. Use the SDK instead#

The Node.js SDK wraps the same two calls with validation, timeouts, retries, and a local fallback for when PayInference is unreachable:

ts 
import { PayInferenceClient } from '@payinference/sdk';

const payinference = new PayInferenceClient({
  apiKey: process.env.PAYINFERENCE_API_KEY!,
  baseUrl: process.env.PAYINFERENCE_BASE_URL ?? 'https://api.payinference.com',
  merchantId: 'm_123',
  timeoutMs: 50,
  fallback: { provider: 'stripe' },
});

const decision = await payinference.decide({
  order_id: 'order_456',
  transaction: { amount: 14900, currency: 'USD', country: 'US', payment_method: 'card' },
  available_providers: ['stripe', 'adyen', 'paypal'],
});

See the SDK guide for the full option set.

Next steps#

Payinference documentation