About Flexible Credentials

What is Flexible Credential?

A credential is the pairing of a FinancialAccount and a PaymentCard. A flexible credential holds both a primary and secondary credential. And cardholders carry the payment card for the primary credential.

On your side of the API, each credential's PaymentCard, referred to as a member card, has its own Primary Account Number (PAN). Where the cardholder has one card, you have two cards and two accounts, all visible through the Highnote API and in the Dashboard.

Cardholders use their payment card like any other, and at authorization, Highnote decides which credential funds the transaction. The cardholder never sees a secondary PAN.

How it's structured

A FlexibleCredential holds exactly one primary FlexibleCredentialCard and, currently, exactly one secondary one. Provisioning more than one secondary credential fails validation.

Each credential is represented as a FlexibleCredentialCard with the fields: paymentCard, defaultFinancialAccount, isPrimary, and createdAt.

FlexibleCredential
├── FlexibleCredentialCard
│   ├── paymentCard  ← the PAN cardholders carry
│   ├── defaultFinancialAccount  ← e.g., debit
│   ├── isPrimary: true
│   └── createdAt
└── FlexibleCredentialCard
    ├── paymentCard
    ├── defaultFinancialAccount  ← e.g., revolving credit
    ├── isPrimary: false
    └── createdAt

A FlexibleCredential object also carries id, externalId, name, status, createdAt, and updatedAt. The status field has two values, ACTIVE and CLOSED. The remaining fields reach the rest of the object: cards, primaryPaymentCard, accountHolder, cardProduct, and flexibleCredentialActivities.

Highnote issues both the primary and any secondary credential in a single provisionFlexibleCredential call. There is no operation to add a credential to an existing flexible credential.

Secondary credentials are not for cardholder presentation. Highnote does not issue Digital Wallet Tokens (DWTs) for their member cards, and LOST or STOLEN reissue does not apply. A cardholder never holds a secondary PAN, so there is nothing for them to report lost or stolen.

See Reissuing member cards to replace a secondary member card.

Credential selection

The primary credential is always eligible to fund a transaction, and you can configure which secondary credentials do so. Highnote configures the order in which eligible credentials are attempted for your organization. It settles the authorization on the first credential that approves it.

A credential that declines for any reason is passed over, and the next credential is attempted. This means that insufficient funds is not the only thing that triggers fallback. The reason can be a spend rule, a velocity control, or the card's own status.

Authorizations are mutually exclusive per transaction

Highnote does not split or aggregate a single authorization across credentials, so whichever credential approves must cover the full amount on its own. Exactly one credential is debited or charged.

The example below uses an order that attempts the secondary credential first and falls back to the primary. Your organization's configured order may differ.

Authorization	Secondary (tried first)	Primary (fallback)	Result
$35	$40	$60	Approved on secondary credential. It approves the full amount.
$50	$40	$60	Approved on primary credential. The secondary declines, so Highnote falls back.
$100	$40	$60	Declined. Neither credential approves $100 on its own, and Highnote does not aggregate.

Spend Rules and Velocity Controls

Spend rules apply per credential. Because each credential has its own PaymentCard and FinancialAccount, attaching a spend rule with attachSpendRuleToPaymentCard or attachSpendRuleToFinancialAccount scopes it to that credential alone.

A spend rule on a secondary credential redirects a purchase rather than blocking it. That credential declines, Highnote passes it over, and the purchase falls through to the next credential in your configured order. For example, where a debit primary is attempted after a credit secondary, a rule blocking grocery merchants on the secondary sends grocery purchases to the primary. Attaching at the card product level applies the rule to every credential instead.

Velocity controls attach to either side of a credential — its FinancialAccount with attachVelocityRuleToFinancialAccount, or its member card with attachPaymentCardVelocityRule. Either way, the rule's velocityConstraintLevelOverride, set when you create it, decides what its counters aggregate over.

A rule attached to a credential's FinancialAccount defaults to ACCOUNT, which scopes it to that credential alone. Use CARD_LINEAGE when a cap should survive a member card reissue, or ACCOUNT_HOLDER to share one cap across everything the account holder spends, including accounts outside this flexible credential.

Transactions restricted to primary credential

Some transactions are not eligible for credential selection. Rather than declining them, Highnote removes the secondary credentials from consideration and authorizes against the primary credential alone, following the card network's flexible credential rules. The primary still has to approve the transaction on its own.

Two classes of transaction trigger this restriction:

• Installment transactions, identified by the installment payment indicator or an installment point-of-sale environment.
• Transactions at merchant categories the network excludes from credential selection, such as cash access and quasi-cash, money transfer, brokerage, collections, and automated fuel dispensers.

The authoritative list is the card network's, not Highnote's. On Visa, for example, the eligible merchant categories are defined in the Visa flexible credential implementation guide. Contact your Visa representative for the current version.

Plan for this when you choose which credential is primary. A fuel purchase at an automated dispenser, for example, is authorized against the primary credential even when a secondary credential would otherwise have been selected.

Refunds, returns, credits, and reversals

Highnote responds with the same credential used for the original purchase. When Highnote cannot identify the original credential the secondary credential is used. For example, a standalone credit that does not reference a prior purchase.

Disputes

Flexible credential transactions follow Highnote's standard Issuing dispute flow. Subscribers observe dispute lifecycle events on the underlying transaction. Highnote operates the dispute.

See Disputes and Chargebacks for the full subscriber model.

Reissuing member cards

Reissuing a member card (PaymentCard) behaves as it does for any Highnote card: it maintains card lineage by reusing the network-level Payment Account Reference (PAR), and copyNumber and copyPin decide whether the replacement reuses or recreates the PAN and PIN.

Use reissueFlexibleCredentialCards to replace the member cards on a flexible credential.

The reissue criteria and lost/stolen guidance in Manage Cards apply unchanged. In particular, do not reissue stolen cards, and close the card and issue a new one instead so the replacement starts a new lineage. The flexible credential must not be CLOSED.

What flexible credential adds is that member cards are replaced through one operation rather than card by card. scope states which of them the request covers, and has no default:

Scope	Behavior
ALL_MEMBER_CARDS	Replaces every member card on one shared set of options. Omit targets.
TARGETED	Replaces only the member cards named in targets, each free to override the shared options.

Prefer ALL_MEMBER_CARDS. Reissuing the whole flexible credential on one set of options keeps its member cards in step, with one expiration date, one activation state, and one reissue reason. Once they diverge, expirations fall due separately and replacing a cardholder's card becomes several requests instead of one. Reach for TARGETED only when a member card genuinely needs different treatment, such as replacing a single damaged physical card while the rest of the flexible credential stays in force.