Card Program Connect associates cards from an existing card program with a Facto user. The cardholder signs in, selects cards, and approves the change on a page provided by the Card Program or its authorized platform. The backend then submits the final card list to the Engine. Facto stores an independent binding for each card and checks the binding, consent, PaymentRoute, and limits before payment authorization.

Integration model

Card Program Connect has three parts:

  • Connect intent. Facto creates a 15-minute connect intent and sends connect_hint and connect_intent_id to the registered connect_page_url.
  • Card list. The backend reads the current bindings and submits the complete desired_cards set approved by the cardholder. The update is transactional, and Idempotency-Key makes retries safe.
  • Per-card payment configuration. Each active binding has its own consent and may reference zero or one PaymentRoute. The cardholder manages that route in Facto.

Facto enables this capability per environment and Card Program. Development and Production are configured separately; access in one environment does not grant access in another.

Responsibilities

OwnerResponsibilities
Card Program or authorized platformCardholder sign-in, card display, consent text, and approval page; connect-hint verification, current-list reads, final-list submission, idempotency keys, and audit references on the backend.
CardholderSelect cards, approve the disclosed data, and attach or remove a PaymentRoute for each card in Facto.
FactoCreate and track connect intents; store per-card bindings and consent; provide card-portfolio and PaymentRoute management; run payment-authorization checks.

The Card Program cannot read the cardholder's PaymentRoute or payment_readiness. The cardholder manages both through their Facto session.

Prerequisites

Complete the following configuration before integration:

  • The Card Program is active in the target environment, with the required connection capability enabled.
  • An active Program Connection grants the operation being called.
  • Facto has issued Provider Connection server credentials for the same environment.
  • The connect_page_url is registered and reachable by Facto.

Security requirements

Keep server credentials on the backend. After reading connect_hint and connect_intent_id from the URL fragment, remove the fragment immediately. Submit only an opaque card_ref and display metadata in the card list. Never submit a PAN, CVV, or another payment credential.

Connection and payment states

LayerState or objectMeaning
AccessActive Program ConnectionThe backend may call approved operations for the Card Program; this state alone does not indicate whether a user card binding exists.
Connect intentapplied or no_changeThe Engine processed the final card list; no PaymentRoute is implied.
Card bindingbinding_status: activeThe card is associated with the Facto user; payment still depends on route, limit, and authorization checks.
Route associationstatus: associatedThe card has a PaymentRoute; every payment still rechecks the route and runtime conditions.
Payment authorizationstatus: processingThe request passed authorization checks and entered asynchronous processing; settlement and reconciliation are separate.