Credit & Passport

Financial Passport

Create holder-consent verification requests and verify signed threshold-based Financial Passport presentations.

POST/api/credit-api/v1/passport/request

Create a verifier request and receive token, holder share URL, status URL and expiry.

GET/api/credit-api/v1/passport/requests/{token}/status

Poll pending, consented, fulfilled, rejected, expired or revoked state.

POST/api/credit-api/v1/passport/verify

Verify a VP JWT directly or resolve a fulfilled request token.

POST/api/credit-api/v1/passport/batch

Verify up to 50 VP JWTs or request tokens with per-item results.

Request criteria

A request must contain at least one supported criterion. The holder sees the verifier name, human-readable purpose and requested thresholds before deciding whether to fulfil it.

JSON

{
  "purpose": "affordability_assessment",
  "purpose_description": "Confirm rental affordability",
  "verifier_name": "Example Property",
  "criteria": {
    "income": {
      "currency_code": "KES",
      "monthly_amount": 50000,
      "months_required": 12,
      "source_rail": "mpesa",
      "source_country": "KE"
    },
    "score": { "min": 65 },
    "dti": { "max": 0.4 },
    "savings_rate": { "min": 0.1 }
  },
  "ttl_seconds": 86400
}

End-to-end flow

Create the request.
Send share_url to the holder; do not imitate the consent screen.
Poll status_url with bounded backoff.
When presentation_available is true, call verify with request_token.
Require valid === true before trusting any returned claim.
Evaluate overall_holds separately as the business outcome.

Current SDK path

Version 0.1.0 of @fullness/credit-api-sdk does not yet expose Passport-specific convenience methods. Its public low-level request method still applies the API key, exact-body HMAC and purpose header, so approved integrators can call the implemented routes now.

TypeScript

const request = await credit.request<{
  token: string;
  share_url: string | null;
}>(
  'POST',
  '/api/credit-api/v1/passport/request',
  {
    purpose: 'affordability_assessment',
    purpose_description: 'Confirm rental affordability',
    criteria: {
      income: { currency_code: 'KES', monthly_amount: 50000, months_required: 12 },
    },
  },
  { purpose: 'affordability_assessment' },
);

// Give request.share_url to the holder, then poll request.status_url.
const verified = await credit.request<{
  valid: boolean;
  overall_holds: boolean;
}>(
  'POST',
  '/api/credit-api/v1/passport/verify',
  { purpose: 'affordability_assessment', request_token: request.token },
  { purpose: 'affordability_assessment' },
);