Activate Instant Credit

Overview

Instant Credit turns on the credit credential of a flexible credential for a bounded window. Outside that window the credit credential is not eligible, and transactions run on the primary credential as usual.

Activating Instant Credit sets three things:

Whether the credit credential is on — it becomes eligible for authorization.
Its available credit — how much it can spend.
How long it stays on — the activation window.

The mutation is asynchronous. It returns an activation with status PENDING, and the credit credential becomes eligible once the activation reaches COMPLETE.

Repayment is separate

Instant Credit governs whether the credit credential can spend and how much. It does not move money or settle a balance. Repayment is its own flow.

How it works

While Instant Credit is active, the credit credential is eligible for authorization for the window you set. It joins credential selection like any other eligible credential: Highnote attempts it in your organization's configured order and uses the first credential that approves the full amount.

The credit credential is attempted whenever the activation window is open. If its available credit doesn't cover the amount, it declines and selection falls through to the next credential.

When the window ends — by expiry or cancellation — the credit credential stops being eligible and drops out of selection on the next authorization.

Before you start

To activate Instant Credit, the flexible credential needs a credit secondary credential — a secondary credential issued on a credit BIN and backed by JIT funding with a pseudo balance. You set this up when you provision the flexible credential; there is nothing to activate without it.

Highnote currently supports exactly one credit secondary per flexible credential.

Activate Instant Credit

Call activateFlexibleCredentialInstantCredit with the credential's ID, the available-credit adjustment, and the window.

ActivateFlexibleCredentialInstantCredit

Query

mutation ActivateFlexibleCredentialInstantCredit(
  $input: ActivateFlexibleCredentialInstantCreditInput!
) {
  activateFlexibleCredentialInstantCredit(input: $input) {
    __typename
    ... on FlexibleCredentialInstantCreditActivation {
      id
      status
      flexibleCredential {
        id
        strategies {
          __typename
          id
          status
          effectiveFrom
          effectiveThrough
        }
      }
    }
    ... on UserError {
      errors {
        code
        description
        errorPath
      }
    }
    ... on AccessDeniedError {
      message
    }
  }
}

Variables

{
  "input": {
    "flexibleCredentialId": "FLEXIBLE_CREDENTIAL_ID",
    "availableCredit": {
      "mode": "SET",
      "amount": {
        "value": 5000,
        "currencyCode": "USD"
      }
    },
    "duration": {
      "value": 1,
      "units": "DAYS"
    },
    "idempotencyKey": "00000000-0000-4000-8000-000000000000"
  }
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "activateFlexibleCredentialInstantCredit": {
      "__typename": "FlexibleCredentialInstantCreditActivation",
      "id": "INSTANT_CREDIT_ACTIVATION_ID",
      "status": "PENDING",
      "flexibleCredential": {
        "id": "FLEXIBLE_CREDENTIAL_ID",
        "strategies": null
      }
    }
  }
}

The response is a FlexibleCredentialInstantCreditActivation carrying an id and a status. Failures surface as UserError or AccessDeniedError in the response rather than as transport errors, so check __typename before reading the activation.

Set the available credit

availableCredit.mode decides how amount is applied. amount is an AmountInput — a value in the currency's minor units and a required currencyCode. { value: 5000, currencyCode: "USD" } is $50.00.

Mode	Effect	Window
`SET`	Replace the available credit with `amount` (absolute).	Requires `duration`. Opens or replaces the window.
`INCREMENT`	Add `amount` to the current available credit.	Requires an already-active window.

Use SET to start a window, or to resize the credit and the window together. Use INCREMENT to top up the credit during a window that is already open.

Set the window

duration is a value and a units (SECONDS, MINUTES, HOURS, or DAYS). The window runs from now to now + duration.

SET requires duration. The new expiry is now + duration.
INCREMENT takes duration optionally. Omit it to keep the current expiry, or provide one to extend the window. A shorter expiry is rejected — use SET to shorten.
duration: { value: 0, units: SECONDS } cancels now. The window closes immediately and the credit credential stops being eligible on the next authorization.

Read the activation status

The mutation returns immediately with status PENDING. Observe the outcome two ways.

The activation's own status:

Status	Meaning
`PENDING`	Accepted and in progress.
`COMPLETE`	Finished. The credit credential is enabled for the window.
`FAILED`	The activation did not take effect.

And the current strategy on the flexible credential. Read strategies and filter on __typename.

FlexibleCredentialStrategies

Query

query FlexibleCredentialStrategies($id: ID!) {
  node(id: $id) {
    ... on FlexibleCredential {
      id
      strategies {
        __typename
        id
        status
        effectiveFrom
        effectiveThrough
      }
    }
  }
}

Variables

{
  "id": "FLEXIBLE_CREDENTIAL_ID"
}

⚠️ Please login to execute queries. Visit the dashboard to authenticate.

Result

{
  "data": {
    "node": {
      "id": "FLEXIBLE_CREDENTIAL_ID",
      "strategies": [
        {
          "__typename": "InstantCreditFlexibleCredentialStrategy",
          "id": "INSTANT_CREDIT_STRATEGY_ID",
          "status": "ACTIVE",
          "effectiveFrom": "2026-04-01T15:30:00.000Z",
          "effectiveThrough": "2026-04-02T15:30:00.000Z"
        }
      ]
    }
  }
}

An InstantCreditFlexibleCredentialStrategy with status: ACTIVE and an effectiveThrough in the future means the credit credential is currently enabled.

Change or cancel a window

While a window is open, you can act on it without waiting for it to expire:

Goal	Call
Add available credit	`INCREMENT` with a positive `amount`, no `duration`.
Extend the window	`INCREMENT` with a `duration` later than the current expiry.
Add credit and extend	`INCREMENT` with a positive `amount` and a later `duration`.
Replace credit and/or window	`SET` with the new `amount` and `duration`.
Cancel now	`duration: { value: 0, units: SECONDS }`.

A window you do nothing to simply expires at effectiveThrough.

Send an idempotency key

Send a UUIDv4 idempotencyKey with every request. Highnote processes only the first request carrying a given key and returns that original response to repeats for up to 24 hours. Retry a timed-out request with the same key — a new key can start a second activation.

One activation at a time

A second activation on a credential whose activation is still in progress is rejected with INSTANT_CREDIT_ALREADY_IN_PROGRESS. Retry once the first reaches a terminal status.

Handle failures

Recoverable failures come back as UserError in the response — check __typename, then read each error's code and human-readable description.

Code	Meaning
`INSTANT_CREDIT_SET_REQUIRES_DURATION`	`SET` was sent without a `duration`.
`INSTANT_CREDIT_INCREMENT_REQUIRES_ACTIVE_WINDOW`	`INCREMENT` was sent with no window open.
`INSTANT_CREDIT_INCREMENT_CANNOT_SHORTEN_WINDOW`	An `INCREMENT` `duration` would end the window earlier than it does now. Use `SET` to shorten.
`INSTANT_CREDIT_INCREMENT_NO_OP`	`INCREMENT` with `amount` `0` and no `duration` — nothing to do.
`INSTANT_CREDIT_SET_AMOUNT_NEGATIVE` / `INSTANT_CREDIT_INCREMENT_AMOUNT_NEGATIVE`	`amount.value` is negative.
`INSTANT_CREDIT_ALREADY_IN_PROGRESS`	Another activation on this credential is still in progress.

A transient service error does not return a UserError; the mutation returns no activation. Retry with the same idempotencyKey.

An activation that starts and then fails reaches status: FAILED rather than returning a synchronous error.

Next steps

Review how the credit credential participates once enabled in Credential selection.
Scope what the credit credential can buy with spend rules and velocity controls.

Overview​

How it works​

Before you start​

Activate Instant Credit​

ActivateFlexibleCredentialInstantCredit​

Set the available credit​

Set the window​

Read the activation status​

FlexibleCredentialStrategies​

Change or cancel a window​

Send an idempotency key​

Handle failures​

Next steps​

Overview

How it works

Before you start

Activate Instant Credit

ActivateFlexibleCredentialInstantCredit

Set the available credit

Set the window

Read the activation status

FlexibleCredentialStrategies

Change or cancel a window

Send an idempotency key

Handle failures

Next steps