Quickstart

Make your first AltFiScore decision in 15 minutes. By the end of this guide you'll have a working sandbox key and an approved BNPL transaction in your terminal.

Before you start

You'll need a way to make HTTP requests (cURL, Postman, or your editor of choice). All the examples on this page work in any language that can call a REST endpoint.

1. Sign up for a sandbox tenant

Every AltFiScore customer gets a free sandbox tenant provisioned within seconds of signup. The sandbox is fully isolated from production, comes pre-seeded with test consumers, and never bills.

Go to lenders.altfiscore.com/signup to create your sandbox tenant. After verifying your email, you'll land in the lender portal with full access to your sandbox.

2. Generate an API key

From the lender portal, navigate to Settings → API Keys and click Generate new key. Choose the sandbox environment for testing.

Your key will look something like:

altfi_test_DemoKey1234567890abcdefghijklmn

Treat keys like passwords

The full key is shown only once at creation. AltFiScore stores only a hash — if you lose it, you'll need to generate a new one. Never commit keys to version control or log them.

3. Set your environment variable

Store your API key as an environment variable so it never gets hardcoded into your application:

bash

export ALTFISCORE_API_KEY='altfi_test_DemoKey1234567890abcdefghijklmn'

4. Make your first decision

AltFiScore's sandbox includes three pre-seeded consumers ready for testing. We'll use Sarah Park (consumer_id 11111111-1111-1111-1111-111111111001) — a returning customer with verified identity and a good credit profile.

Call the BNPL decisioning endpoint with a $25 transaction:

cURL

curl -X POST 'https://api.altfiscore.com/v1/decisions/bnpl' \
  -H 'Authorization: Bearer altfi_test_YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: $(uuidgen)' \
  -d '{
    "consumer": {
      "consumer_id": "11111111-1111-1111-1111-111111111001"
    },
    "transaction": {
      "amount": 25.00,
      "currency": "USD",
      "merchant_name": "Bluebird Cafe",
      "merchant_category": "food_beverage",
      "product_description": "Coffee subscription"
    },
    "plan_preference": "pay_in_4"
  }'

Or in Node.js:

Node.js

const response = await fetch('https://api.altfiscore.com/v1/decisions/bnpl', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ALTFISCORE_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(),
  },
  body: JSON.stringify({
    consumer: {
      consumer_id: '11111111-1111-1111-1111-111111111001',
    },
    transaction: {
      amount: 25.00,
      currency: 'USD',
      merchant_name: 'Bluebird Cafe',
      merchant_category: 'food_beverage',
      product_description: 'Coffee subscription',
    },
    plan_preference: 'pay_in_4',
  }),
})

const decision = await response.json()
console.log(decision.outcome) // 'approved'

Or in Python:

Python

import requests, uuid, os

response = requests.post(
    'https://api.altfiscore.com/v1/decisions/bnpl',
    headers={
        'Authorization': f"Bearer {os.environ['ALTFISCORE_API_KEY']}",
        'Content-Type': 'application/json',
        'Idempotency-Key': str(uuid.uuid4()),
    },
    json={
        'consumer': {
            'consumer_id': '11111111-1111-1111-1111-111111111001',
        },
        'transaction': {
            'amount': 25.00,
            'currency': 'USD',
            'merchant_name': 'Bluebird Cafe',
            'merchant_category': 'food_beverage',
            'product_description': 'Coffee subscription',
        },
        'plan_preference': 'pay_in_4',
    },
)
decision = response.json()
print(decision['outcome'])  # 'approved'

5. Inspect the response

A successful BNPL decision returns the full approved schedule plus a TILA-compliant disclosure block, ready to display to your consumer:

200 OK

{
  "decision_id": "8496f4b6-5514-4e0b-a6bf-6da6fb987448",
  "application_id": "8496f4b6-5514-4e0b-a6bf-6da6fb987448",
  "status": "complete",
  "kyc_tier": "soft",
  "kyc_status": "matched",
  "outcome": "approved",
  "approved_amount": "25.00",
  "currency": "USD",
  "apr": "0.0",
  "term_months": 2,
  "payment_schedule": [
    { "num": 1, "due_date": "2026-05-15", "amount": "6.25" },
    { "num": 2, "due_date": "2026-05-29", "amount": "6.25" },
    { "num": 3, "due_date": "2026-06-12", "amount": "6.25" },
    { "num": 4, "due_date": "2026-06-26", "amount": "6.25" }
  ],
  "tila_disclosure": {
    "amount_financed": "25.00",
    "finance_charge": "0.00",
    "total_of_payments": "25.00",
    "apr": "0.0",
    "payment_frequency": "biweekly"
  }
}

The fields you'll use most:

outcome — one of approved, declined, referred
approved_amount — the amount AltFiScore approved (may be less than requested for risk-based offers)
payment_schedule — array of installments with due dates and amounts
tila_disclosure — Truth in Lending disclosures required to show consumers before checkout completion
decision_id — store this for your reconciliation and if you need to look up the decision later via GET /v1/decisions/bnpl/{id}

Next steps

Read about authentication — sandbox vs live keys, key rotation, retiring compromised keys
Explore the sandbox tenant — three pre-seeded consumers covering all KYC tiers
Set up idempotency keys to make your integration retry-safe
Handle errors gracefully — see the full error code reference
Try the live demo to see different KYC tiers trigger across transaction sizes