Skip to main content

Payments & PSP Integration

Most Nexa tenants run in corporate-guarantee mode — the airline settles with the hotel at check-out and no card is charged at booking. Some airports (or chains) require a card-backed booking, which is where the PSP adapter comes in.

Guarantee vs card​

ModeWhen to usePCI surface
GUARANTEEAirline settles post-stayNone
CARDHotel requires card-on-fileTokenized only

The choice is per-policy (acceptedPayments). If a policy allows both, the allocator prefers GUARANTEE because it's cheaper operationally.

Tokenized card flow​

Nexa never stores a PAN. The PSP adapter tokenizes once — during onboarding — and Nexa carries only the token.

1. Ops user submits corporate card via PSP hosted form (Nexa never sees the PAN).
2. PSP returns a long-lived token (tok_xxxxxxxx…).
3. Operator pins the token to a policy or to a specific airport.
4. At booking time, Nexa forwards the token to the booking provider.

The token lives in policy.cardToken or in tenant.defaultCardToken as a fallback.

Supported PSPs​

The PSP contract is intentionally narrow — three operations: open a hosted token session, exchange a session for a token, and revoke a token. That's enough to cover every PSP we've encountered without leaking provider-specific quirks into the rest of Nexa.

Out of the box, Nexa ships:

  • A deterministic limited PSP for sandbox tenants (no real card movement, no live network calls).
  • Production adapters provisioned per tenant — most airlines reuse the PSP contract they already have.

Onboarding a new PSP is handled by Nexa's integration team; tell us which PSP you use during tenant setup.

Virtual cards​

For the "pay the hotel at check-in but make sure they get paid" problem, Nexa supports single-use virtual cards through the PSP. The flow:

  1. On booking confirmation, Nexa asks the PSP for a single-use virtual card scoped to (amount, currency, hotel, dates).
  2. The card details are added to the voucher.
  3. The hotel charges the card at check-out.
  4. Unused cards auto-expire.

This keeps the airline's real account numbers out of the hotel's systems entirely.

Failures​

  • Token rejection at the booking provider produces a PAYMENT_FAILED manual-review item with the provider's decline reason.
  • PSP downtime is treated as a transient error — Nexa retries with exponential backoff, then escalates to manual review.

Settlement​

Nexa is not a settlement system. It records the booked cost and the payment mode; reconciling invoices with hotel folios is handled by the airline's finance / AP platform. The audit log is the source of truth for what Nexa authorized.

A nightly export drops the day's bookings into a CSV (or Parquet, optionally) for the AP pipeline.

Security posture​

  • No PANs anywhere in Nexa.
  • Tokens treated as secrets — never logged, masked in audit, rotated via PSP's API.
  • Single-use cards scoped to (amount, hotel, date window) — a leak is bounded.
  • RBAC — only ADMIN can mint or revoke tokens; OPS_SUPERVISOR can attach existing tokens to policies.
Was this helpful?