Skip to main content

Simulate Flexible Credentials

Overview​

This page explains how to simulate an authorization against a flexible credential in the Test environment, so you can see which credential funds a transaction before you send live traffic.

Two mutations do this, one for a card and one for a digital wallet token. Both run the same credential-selection logic Highnote applies in production and return the same SimulateAuthorizationPayload union as a real authorization — AccessDeniedError, AuthorizationEvent, or UserError.

Prerequisites​

Simulate a card authorization​

Use simulateFlexibleCredentialAuthorization to simulate an authorization against a flexible credential. For an authorization driven by a digital wallet token, use Simulate a digital wallet token authorization instead.

Pass the PaymentCard ID of the primary member card as cardId. The input is SimulateFlexibleCredentialAuthorizationInput; only cardId and amount are required.

The secondary credential is not always eligible. A credit secondary enters credential selection only while its Instant Credit strategy is enabled and the activation window is open. Even then it approves only if its available credit covers the full amount; otherwise it declines and selection falls through to the next credential. Outside the window it drops out of selection and the authorization runs on the primary credential.

Both examples below assume an enabled strategy inside an open window, and an order that attempts the secondary credential before the primary. Highnote configures that order for your organization, so yours may differ. See Credential selection.

Approved on the secondary credential​

A $35 authorization against a credential whose credit secondary has $40 of available credit. The secondary is attempted first, approves the full amount, and the transaction settles there.

SimulateFlexibleCredentialAuthorization​
Query
mutation SimulateFlexibleCredentialAuthorization(
  $input: SimulateFlexibleCredentialAuthorizationInput!
) {
  simulateFlexibleCredentialAuthorization(input: $input) {
    __typename
    ... on AuthorizationEvent {
      id
      transaction {
        ... on Node {
          id
        }
      }
      responseCode
      approvedAmount {
        value
        currencyCode
      }
      merchantDetails {
        countryCodeAlpha3
        category
        name
        description
      }
      pointOfServiceDetails {
        terminalSupportsPartialApproval
      }
      createdAt
    }
    ... on UserError {
      errors {
        errorPath
        code
        description
      }
    }
  }
}
Variables
{
  "input": {
    "amount": {
      "value": 3500,
      "currencyCode": "USD"
    },
    "cardId": "PAYMENT_CARD_ID_PRIMARY",
    "merchantDetails": {
      "name": "HIGHNOTE_PLATFORM",
      "description": "FLEXIBLE_CREDENTIAL_SINGLE_SOURCE",
      "category": "GENERAL_SERVICES",
      "countryCodeAlpha3": "USA"
    },
    "pointOfServiceDetails": {
      "terminalSupportsPartialApproval": true
    }
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "simulateFlexibleCredentialAuthorization": {
      "__typename": "AuthorizationEvent",
      "id": "TRANSACTION_EVENT_ID",
      "transaction": {
        "id": "TRANSACTION_ID"
      },
      "responseCode": "APPROVED",
      "approvedAmount": {
        "value": 3500,
        "currencyCode": "USD"
      },
      "merchantDetails": {
        "countryCodeAlpha3": "USA",
        "category": "GENERAL_SERVICES",
        "name": "HIGHNOTE_PLATFORM",
        "description": "FLEXIBLE_CREDENTIAL_SINGLE_SOURCE"
      },
      "pointOfServiceDetails": {
        "terminalSupportsPartialApproval": true
      },
      "createdAt": "2026-04-01T15:30:00.000Z"
    }
  }
}

Declined on every credential​

A $100 authorization with $40 of available credit on the credit secondary and $60 on the debit primary. The secondary is attempted first and declines, and so does the primary on fallback. Highnote does not aggregate across credentials, so the transaction declines.

SimulateFlexibleCredentialAuthorization​
Query
mutation SimulateFlexibleCredentialAuthorization(
  $input: SimulateFlexibleCredentialAuthorizationInput!
) {
  simulateFlexibleCredentialAuthorization(input: $input) {
    __typename
    ... on AuthorizationEvent {
      id
      transaction {
        ... on Node {
          id
        }
      }
      responseCode
      approvedAmount {
        value
        currencyCode
      }
      merchantDetails {
        countryCodeAlpha3
        category
        name
        description
      }
      pointOfServiceDetails {
        terminalSupportsPartialApproval
      }
      createdAt
    }
    ... on UserError {
      errors {
        errorPath
        code
        description
      }
    }
  }
}
Variables
{
  "input": {
    "amount": {
      "value": 10000,
      "currencyCode": "USD"
    },
    "cardId": "PAYMENT_CARD_ID_PRIMARY",
    "merchantDetails": {
      "name": "HIGHNOTE_PLATFORM",
      "description": "FLEXIBLE_CREDENTIAL_AGGREGATE_NEED",
      "category": "GENERAL_SERVICES",
      "countryCodeAlpha3": "USA"
    },
    "pointOfServiceDetails": {
      "terminalSupportsPartialApproval": true
    }
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "simulateFlexibleCredentialAuthorization": {
      "__typename": "AuthorizationEvent",
      "id": "TRANSACTION_EVENT_ID",
      "transaction": {
        "id": "TRANSACTION_ID"
      },
      "responseCode": "INSUFFICIENT_FUNDS",
      "approvedAmount": {
        "value": 0,
        "currencyCode": "USD"
      },
      "merchantDetails": {
        "countryCodeAlpha3": "USA",
        "category": "GENERAL_SERVICES",
        "name": "HIGHNOTE_PLATFORM",
        "description": "FLEXIBLE_CREDENTIAL_AGGREGATE_NEED"
      },
      "pointOfServiceDetails": {
        "terminalSupportsPartialApproval": true
      },
      "createdAt": "2026-04-01T15:30:00.000Z"
    }
  }
}

Simulate a digital wallet token authorization​

Use simulateDigitalWalletTokenFlexibleCredentialAuthorization to simulate an authorization driven by a digital wallet token. The required input is cardDigitalWalletTokenId, the ID of a CardDigitalWalletToken whose underlying PaymentCard is the primary member card of a flexible credential.

The token resolves to the primary member card and routing proceeds from there. Highnote does not issue digital wallet tokens for the member cards of secondary credentials.

SimulateDigitalWalletTokenFlexibleCredentialAuthorization​
Query
mutation SimulateDigitalWalletTokenFlexibleCredentialAuthorization(
  $input: SimulateDigitalWalletTokenFlexibleCredentialAuthorizationInput!
) {
  simulateDigitalWalletTokenFlexibleCredentialAuthorization(input: $input) {
    __typename
    ... on AuthorizationEvent {
      id
      transaction {
        ... on Node {
          id
        }
      }
      responseCode
      approvedAmount {
        value
        currencyCode
      }
      merchantDetails {
        countryCodeAlpha3
        category
        name
        description
      }
      pointOfServiceDetails {
        terminalSupportsPartialApproval
      }
      createdAt
    }
    ... on UserError {
      errors {
        errorPath
        code
        description
      }
    }
  }
}
Variables
{
  "input": {
    "amount": {
      "value": 3500,
      "currencyCode": "USD"
    },
    "cardDigitalWalletTokenId": "CARD_DIGITAL_WALLET_TOKEN_ID",
    "merchantDetails": {
      "name": "HIGHNOTE_PLATFORM",
      "description": "FLEXIBLE_CREDENTIAL_DWT",
      "category": "GENERAL_SERVICES",
      "countryCodeAlpha3": "USA"
    },
    "pointOfServiceDetails": {
      "terminalSupportsPartialApproval": true
    }
  }
}
⚠️ Please login to execute queries. Visit the dashboard to authenticate.
Result
{
  "data": {
    "simulateDigitalWalletTokenFlexibleCredentialAuthorization": {
      "__typename": "AuthorizationEvent",
      "id": "TRANSACTION_EVENT_ID",
      "transaction": {
        "id": "TRANSACTION_ID"
      },
      "responseCode": "APPROVED",
      "approvedAmount": {
        "value": 3500,
        "currencyCode": "USD"
      },
      "merchantDetails": {
        "countryCodeAlpha3": "USA",
        "category": "GENERAL_SERVICES",
        "name": "HIGHNOTE_PLATFORM",
        "description": "FLEXIBLE_CREDENTIAL_DWT"
      },
      "pointOfServiceDetails": {
        "terminalSupportsPartialApproval": true
      },
      "createdAt": "2026-04-01T15:30:00.000Z"
    }
  }
}

What simulators prove about your integration​

The simulators run the same credential-selection routing logic as production authorizations. Successful runs in the Test environment exercise the following:

  • Credential eligibility. A credit secondary is attempted only while its Instant Credit window is open, and it approves only if its available credit covers the full amount.
  • Credential-selection order. Highnote attempts eligible credentials in the order configured for your organization, and settles on the first one that approves.
  • Mutually exclusive routing. Each transaction debits or charges exactly one credential.
  • Primary-credential restriction. Installment transactions and transactions at restricted merchant categories authorize against the primary credential instead of entering credential selection. See Transactions restricted to primary credential.

Treat the simulator decline reasons as the contract for production decline reasons. The simulators do not, however, exercise downstream settlement, clearing, or chargeback flows. Those follow the standard Issuing transaction lifecycle and are out of scope for these mutations.

Automate your integration​

To automate your integration, subscribe to the following notification events:

The details provided in the payloads from these events can be used for the following use cases:

  • Automate your application or website's transaction processing workflows
  • Create account holder notifications and alerts
  • Reconcile which credential funded each transaction