Credential on File Installments

Overview

Merchant-managed installment payments enable the splitting of purchases into multiple scheduled payments for cards, payment method tokens, and network tokens.

CIT / MIT model

Installment payments follow the customer-initiated transaction (CIT) and merchant-initiated transaction (MIT) model defined in Credential On File Payments:

The first installment is sent as a CIT with full customer authentication.
Follow-on installments are sent as scheduled MITs referencing the initial CIT.

CIT establishes consent and returns a networkTransactionIdentifier. MIT uses that network ID to prove the charge traces back to valid cardholder consent.

CIT payment 1 (first installment)

Use CUSTOMER_INITIATED_INSTALLMENT_FIRST as the payment initiator
Set intendToStore: true in externalCredentialOnFile
Provide installment details: paymentNumber: 1, total amount, frequency, etc.
Response returns both a networkTransactionIdentifier AND a PaymentTransaction.id

MIT payments 2-n (subsequent installments)

Use MERCHANT_INITIATED_INSTALLMENT as the payment initiator
Pass networkTransactionIdentifier in externalCredentialOnFile
Pass firstInstallmentPaymentTransactionId in installmentPayment (from CIT response: transaction.id)
Increment paymentNumber for each payment

Installment payment data

latency

Querying payment data can take 3-5 minutes to appear after a PaymentTransactionEvent is created, due to synchronization between databases.

Both authorization and charge mutations (for supported input types PaymentCard, NetworkToken, and PaymentMethodToken) accept an installmentPayment object in the input. When provided, the resulting PaymentDebitTransaction is associated with a MerchantManagedInstallmentPayment.

To build a list of PaymentTransactions that includes installment details, query the paymentTransactionsConnection and select the installmentPayment field on the PaymentDebitTransaction type.

See Find all payment transactions and Find a payment transaction for the relevant queries.

Highnote vs network tokens

Aspect	Payment Method Token	Network Token
Created by	Highnote (internal tokenization)	Card networks (Visa, Mastercard) or Token Service Provider (TSP)
Storage	Highnote's secure vault	External vault
ID format	`pmt_*` prefix	Raw token number + cryptogram
Use case	Internal COF transactions	External COF transactions

Supported mutations

Operation	Mutation / Query
Authorize card	authorizePaymentCard
Authorize payment method token	authorizePaymentMethodToken
Authorize network token	authorizeNetworkToken
Charge card	chargePaymentCard
Charge payment method token	chargePaymentMethodToken
Charge network token	chargeNetworkToken

Payment cards

tip

Authorizations must be captured with the capturePaymentTransaction mutation. Charges = authorization + capture.

Use the following mutations for standard card payments.

Authorize payment card

The authorizePaymentCard mutation creates an authorization on a card for a merchant managed installment payment when installment-specific fields are provided in the input. This associates the resulting PaymentDebitTransaction with a merchant‑managed installment payment.

Customer-initiated transaction

First installment with cardholder present. Sets intendToStore: true to establish the credential on file.

authorizePaymentCard

Query

mutation AuthorizePaymentCard($input: AuthorizePaymentCardInput!) {
  authorizePaymentCard(input: $input) {
    ... on CardAuthorizationStepSummary {
      transaction {
        id
        networkTransactionIdentifier
        installmentPayment {
          __typename
          totalAmount {
            __typename
            value
            currencyCode
            decimalPlaces
          }
          numberOfInstallments
          paymentAmount {
            __typename
            value
            currencyCode
            decimalPlaces
          }
          frequency
          firstPaymentDate
          paymentNumber
          fundedAmount {
            __typename
            value
            currencyCode
            decimalPlaces
          }
        }
      }
    }
  }
}

Variables

{
  "input": {
    "paymentCard": {
      "cardNumber": "4000000000000002",
      "expiryYear": "29",
      "expiryMonth": "12",
      "securityCode": "111"
    },
    "merchantAcceptorId": "acqma_01",
    "amount": {
      "value": 1000,
      "currencyCode": "USD"
    },
    "idempotencyKey": "UUID_v4",
    "paymentInitiator": "CUSTOMER_INITIATED_INSTALLMENT_FIRST",
    "externalCredentialOnFile": {
      "intendToStore": true
    },
    "installmentPayment": {
      "totalAmount": {
        "value": 6000,
        "currencyCode": "USD"
      },
      "numberOfInstallments": 6,
      "paymentAmount": {
        "value": 1000,
        "currencyCode": "USD"
      },
      "frequency": "MONTHLY",
      "firstPaymentDate": "2025-01-15",
      "paymentNumber": 1,
      "fundedAmount": {
        "value": 0,
        "currencyCode": "USD"
      }
    }
  }
}

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

Result

{
  "data": {
    "authorizePaymentCard": {
      "transaction": {
        "id": "acqpt_01",
        "networkTransactionIdentifier": "532675987658354",
        "installmentPayment": {
          "__typename": "MerchantManagedInstallmentPayment",
          "totalAmount": {
            "__typename": "Amount",
            "value": 6000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "numberOfInstallments": 6,
          "paymentAmount": {
            "__typename": "Amount",
            "value": 1000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "frequency": "MONTHLY",
          "firstPaymentDate": "2025-01-15",
          "paymentNumber": 1,
          "fundedAmount": {
            "__typename": "Amount",
            "value": 0,
            "currencyCode": "USD",
            "decimalPlaces": 2
          }
        }
      }
    }
  }
}

Merchant-initiated transaction

info

firstInstallmentPaymentTransactionId = CIT transaction.id

Subsequent installment using stored credentials. References the first payment via networkTransactionIdentifier and firstInstallmentPaymentTransactionId.

authorizePaymentCard

Query

mutation AuthorizePaymentCard($input: AuthorizePaymentCardInput!) {
  authorizePaymentCard(input: $input) {
    ... on CardAuthorizationStepSummary {
      createdAt
      transaction {
        id
        networkTransactionIdentifier
        installmentPayment {
          __typename
          totalAmount {
            value
            currencyCode
            decimalPlaces
          }
          numberOfInstallments
          paymentAmount {
            value
            currencyCode
            decimalPlaces
          }
          frequency
          firstPaymentDate
          paymentNumber
          fundedAmount {
            value
            currencyCode
            decimalPlaces
          }
          firstInstallmentPaymentTransaction {
            ... on PaymentDebitTransaction {
              id
            }
          }
        }
      }
    }
  }
}

Variables

{
  "input": {
    "paymentCard": {
      "cardNumber": "4000000000000002",
      "expiryYear": "29",
      "expiryMonth": "12"
    },
    "merchantAcceptorId": "acqma_01",
    "amount": {
      "value": 1000,
      "currencyCode": "USD"
    },
    "idempotencyKey": "NEW_UUID_v4",
    "paymentInitiator": "MERCHANT_INITIATED_INSTALLMENT",
    "externalCredentialOnFile": {
      "networkTransactionIdentifier": "532675987658354"
    },
    "installmentPayment": {
      "totalAmount": {
        "value": 6000,
        "currencyCode": "USD"
      },
      "numberOfInstallments": 6,
      "paymentAmount": {
        "value": 1000,
        "currencyCode": "USD"
      },
      "frequency": "MONTHLY",
      "firstPaymentDate": "2025-01-15",
      "paymentNumber": 2,
      "fundedAmount": {
        "value": 1000,
        "currencyCode": "USD"
      },
      "firstInstallmentPaymentTransactionId": "acqpt_01"
    }
  }
}

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

Result

{
  "data": {
    "authorizePaymentCard": {
      "transaction": {
        "id": "acqpt_02",
        "networkTransactionIdentifier": "532675987658354",
        "installmentPayment": {
          "__typename": "MerchantManagedInstallmentPayment",
          "totalAmount": {
            "__typename": "Amount",
            "value": 6000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "numberOfInstallments": 6,
          "paymentAmount": {
            "__typename": "Amount",
            "value": 1000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "frequency": "MONTHLY",
          "firstPaymentDate": "2025-01-15",
          "paymentNumber": 2,
          "fundedAmount": {
            "__typename": "Amount",
            "value": 1000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "firstInstallmentPaymentTransaction": {
            "id": "acqpt_01"
          }
        }
      }
    }
  }
}

Charge payment card

The chargePaymentCard mutation creates a capture on a card for a merchant‑managed installment payment when installment-specific fields are provided in the input. This associates the resulting PaymentDebitTransaction with a merchant‑managed installment payment.

Customer-initiated transaction

First installment with cardholder present. Sets intendToStore: true to establish the credential on file.

chargePaymentCard

Query

mutation ChargePaymentCard($input: ChargePaymentCardInput!) {
  chargePaymentCard(input: $input) {
    __typename
    ... on UserError {
      errors {
        errorPath
        code
        description
      }
    }
    ... on CardCaptureStepSummary {
      createdAt
      transaction {
        __typename
        id
        networkTransactionIdentifier
        installmentPayment {
          ... on MerchantManagedInstallmentPayment {
            fundedAmount {
              currencyCode
              decimalPlaces
              value
            }
            firstInstallmentPaymentTransaction {
              ... on PaymentDebitTransaction {
                id
              }
            }
            firstPaymentDate
            frequency
            numberOfInstallments
            paymentAmount {
              currencyCode
              decimalPlaces
              value
            }
            paymentNumber
            totalAmount {
              currencyCode
              decimalPlaces
              value
            }
          }
        }
      }
    }
  }
}

Variables

{
  "input": {
    "paymentCard": {
      "cardNumber": "4000000000000002",
      "expiryYear": "29",
      "expiryMonth": "12",
      "securityCode": "111"
    },
    "merchantAcceptorId": "acqma_01",
    "amount": {
      "value": 1000,
      "currencyCode": "USD"
    },
    "idempotencyKey": "UUID_v4",
    "paymentInitiator": "CUSTOMER_INITIATED_INSTALLMENT_FIRST",
    "externalCredentialOnFile": {
      "intendToStore": true
    },
    "installmentPayment": {
      "totalAmount": {
        "value": 6000,
        "currencyCode": "USD"
      },
      "numberOfInstallments": 6,
      "paymentAmount": {
        "value": 1000,
        "currencyCode": "USD"
      },
      "frequency": "MONTHLY",
      "firstPaymentDate": "2025-01-15",
      "paymentNumber": 1,
      "fundedAmount": {
        "value": 0,
        "currencyCode": "USD"
      }
    }
  }
}

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

Result

{
  "data": {
    "chargePaymentCard": {
      "transaction": {
        "id": "acqpt_01",
        "networkTransactionIdentifier": "532675987658354",
        "installmentPayment": {
          "__typename": "MerchantManagedInstallmentPayment",
          "totalAmount": {
            "value": 6000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "numberOfInstallments": 6,
          "paymentAmount": {
            "value": 1000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "frequency": "MONTHLY",
          "firstPaymentDate": "2025-01-15",
          "paymentNumber": 1,
          "fundedAmount": {
            "value": 0,
            "currencyCode": "USD",
            "decimalPlaces": 2
          }
        }
      }
    }
  }
}

Merchant-initiated transaction

info

firstInstallmentPaymentTransactionId = CIT transaction.id

Subsequent installment using stored credentials. References the first payment via networkTransactionIdentifier and firstInstallmentPaymentTransactionId.

chargePaymentCard

Query

mutation ChargePaymentCard($input: ChargePaymentCardInput!) {
  chargePaymentCard(input: $input) {
    ... on CardCaptureStepSummary {
      createdAt
      transaction {
        id
        networkTransactionIdentifier
        installmentPayment {
          __typename
          totalAmount {
            value
            currencyCode
            decimalPlaces
          }
          numberOfInstallments
          paymentAmount {
            value
            currencyCode
            decimalPlaces
          }
          frequency
          firstPaymentDate
          paymentNumber
          fundedAmount {
            value
            currencyCode
            decimalPlaces
          }
          firstInstallmentPaymentTransaction {
            ... on PaymentDebitTransaction {
              id
            }
          }
        }
      }
    }
  }
}

Variables

{
  "input": {
    "paymentCard": {
      "cardNumber": "4000000000000002",
      "expiryYear": "29",
      "expiryMonth": "12"
    },
    "merchantAcceptorId": "acqma_01",
    "amount": {
      "value": 1000,
      "currencyCode": "USD"
    },
    "idempotencyKey": "NEW_UUID_v4",
    "paymentInitiator": "MERCHANT_INITIATED_INSTALLMENT",
    "externalCredentialOnFile": {
      "networkTransactionIdentifier": "532675987658354"
    },
    "installmentPayment": {
      "totalAmount": {
        "value": 6000,
        "currencyCode": "USD"
      },
      "numberOfInstallments": 6,
      "paymentAmount": {
        "value": 1000,
        "currencyCode": "USD"
      },
      "frequency": "MONTHLY",
      "firstPaymentDate": "2025-01-15",
      "paymentNumber": 2,
      "fundedAmount": {
        "value": 1000,
        "currencyCode": "USD"
      },
      "firstInstallmentPaymentTransactionId": "acqpt_01"
    }
  }
}

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

Result

{
  "data": {
    "chargePaymentCard": {
      "transaction": {
        "id": "acqpt_02",
        "networkTransactionIdentifier": "532675987658354",
        "installmentPayment": {
          "__typename": "MerchantManagedInstallmentPayment",
          "totalAmount": {
            "value": 6000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "numberOfInstallments": 6,
          "paymentAmount": {
            "value": 1000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "frequency": "MONTHLY",
          "firstPaymentDate": "2025-01-15",
          "paymentNumber": 2,
          "fundedAmount": {
            "value": 1000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "firstInstallmentPaymentTransaction": {
            "id": "acqpt_01"
          }
        }
      }
    }
  }
}

Payment method tokens

tip

Authorizations must be captured with the capturePaymentTransaction mutation. Charges = authorization + capture.

Use the following mutations for payment method token transactions.

Payment method tokens are used by Highnote for internal COF transactions. They have the prefix pmt_* and are stored in Highnote's secure vault.

Authorize payment method token

The authorizePaymentMethodToken mutation creates an authorization on a payment method token for a merchant‑managed installment payment when installment-specific fields are provided in the input. This associates the resulting PaymentDebitTransaction with a merchant‑managed installment payment.

Customer-initiated transaction

First installment with cardholder present. Sets intendToStore: true to establish the credential on file.

authorizePaymentMethodToken

Query

mutation AuthorizePaymentMethodToken(
  $input: AuthorizePaymentMethodTokenInput!
) {
  authorizePaymentMethodToken(input: $input) {
    ... on CardAuthorizationStepSummary {
      transaction {
        id
        networkTransactionIdentifier
        installmentPayment {
          __typename
          totalAmount {
            __typename
            value
            currencyCode
            decimalPlaces
          }
          numberOfInstallments
          paymentAmount {
            __typename
            value
            currencyCode
            decimalPlaces
          }
          frequency
          firstPaymentDate
          paymentNumber
          fundedAmount {
            __typename
            value
            currencyCode
            decimalPlaces
          }
        }
      }
    }
  }
}

Variables

{
  "input": {
    "paymentMethodTokenId": "tkpmc_01",
    "merchantAcceptorId": "acqma_01",
    "amount": {
      "value": 1000,
      "currencyCode": "USD"
    },
    "idempotencyKey": "UUID_v4",
    "paymentInitiator": "CUSTOMER_INITIATED_INSTALLMENT_FIRST",
    "installmentPayment": {
      "totalAmount": {
        "value": 6000,
        "currencyCode": "USD"
      },
      "numberOfInstallments": 6,
      "paymentAmount": {
        "value": 1000,
        "currencyCode": "USD"
      },
      "frequency": "MONTHLY",
      "firstPaymentDate": "2025-01-15",
      "paymentNumber": 1,
      "fundedAmount": {
        "value": 0,
        "currencyCode": "USD"
      }
    }
  }
}

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

Result

{
  "data": {
    "authorizePaymentMethodToken": {
      "transaction": {
        "id": "acqpt_01",
        "networkTransactionIdentifier": "532675987658354",
        "installmentPayment": {
          "__typename": "MerchantManagedInstallmentPayment",
          "totalAmount": {
            "__typename": "Amount",
            "value": 6000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "numberOfInstallments": 6,
          "paymentAmount": {
            "__typename": "Amount",
            "value": 1000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "frequency": "MONTHLY",
          "firstPaymentDate": "2025-01-15",
          "paymentNumber": 1,
          "fundedAmount": {
            "__typename": "Amount",
            "value": 0,
            "currencyCode": "USD",
            "decimalPlaces": 2
          }
        }
      }
    }
  }
}

Merchant-initiated transaction

info

firstInstallmentPaymentTransactionId = CIT transaction.id

Subsequent installment using stored credentials. References the first payment via networkTransactionIdentifier and firstInstallmentPaymentTransactionId.

authorizePaymentMethodToken

Query

mutation AuthorizePaymentMethodToken(
  $input: AuthorizePaymentMethodTokenInput!
) {
  authorizePaymentMethodToken(input: $input) {
    ... on CardAuthorizationStepSummary {
      createdAt
      transaction {
        id
        networkTransactionIdentifier
        installmentPayment {
          __typename
          totalAmount {
            value
            currencyCode
            decimalPlaces
          }
          numberOfInstallments
          paymentAmount {
            value
            currencyCode
            decimalPlaces
          }
          frequency
          firstPaymentDate
          paymentNumber
          fundedAmount {
            value
            currencyCode
            decimalPlaces
          }
          firstInstallmentPaymentTransaction {
            ... on PaymentDebitTransaction {
              id
            }
          }
        }
      }
    }
  }
}

Variables

{
  "input": {
    "paymentMethodTokenId": "tkpmc_01",
    "merchantAcceptorId": "acqma_01",
    "amount": {
      "value": 1000,
      "currencyCode": "USD"
    },
    "idempotencyKey": "NEW_UUID_v4",
    "paymentInitiator": "MERCHANT_INITIATED_INSTALLMENT",
    "installmentPayment": {
      "totalAmount": {
        "value": 6000,
        "currencyCode": "USD"
      },
      "numberOfInstallments": 6,
      "paymentAmount": {
        "value": 1000,
        "currencyCode": "USD"
      },
      "frequency": "MONTHLY",
      "firstPaymentDate": "2025-01-15",
      "paymentNumber": 2,
      "fundedAmount": {
        "value": 1000,
        "currencyCode": "USD"
      },
      "firstInstallmentPaymentTransactionId": "acqpt_01"
    }
  }
}

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

Result

{
  "data": {
    "authorizePaymentMethodToken": {
      "transaction": {
        "id": "acqpt_02",
        "networkTransactionIdentifier": "532675987658354",
        "installmentPayment": {
          "__typename": "MerchantManagedInstallmentPayment",
          "totalAmount": {
            "__typename": "Amount",
            "value": 6000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "numberOfInstallments": 6,
          "paymentAmount": {
            "__typename": "Amount",
            "value": 1000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "frequency": "MONTHLY",
          "firstPaymentDate": "2025-01-15",
          "paymentNumber": 2,
          "fundedAmount": {
            "__typename": "Amount",
            "value": 1000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "firstInstallmentPaymentTransaction": {
            "id": "acqpt_01"
          }
        }
      }
    }
  }
}

Charge payment method token

The chargePaymentMethodToken mutation creates a capture on a payment method token for a merchant‑managed installment payment when installment-specific fields are provided in the input. This associates the resulting PaymentDebitTransaction with a merchant‑managed installment payment.

Customer-initiated transaction

First installment with cardholder present. Sets intendToStore: true to establish the credential on file.

chargePaymentMethodToken

Query

mutation ChargePaymentMethodToken($input: ChargePaymentMethodTokenInput!) {
  chargePaymentMethodToken(input: $input) {
    ... on CardCaptureStepSummary {
      transaction {
        id
        networkTransactionIdentifier
        installmentPayment {
          __typename
          totalAmount {
            __typename
            value
            currencyCode
            decimalPlaces
          }
          numberOfInstallments
          paymentAmount {
            __typename
            value
            currencyCode
            decimalPlaces
          }
          frequency
          firstPaymentDate
          paymentNumber
          fundedAmount {
            __typename
            value
            currencyCode
            decimalPlaces
          }
        }
      }
    }
  }
}

Variables

{
  "input": {
    "paymentMethodTokenId": "tkpmc_01",
    "merchantAcceptorId": "acqma_01",
    "amount": {
      "value": 1000,
      "currencyCode": "USD"
    },
    "idempotencyKey": "UUID_v4",
    "paymentInitiator": "CUSTOMER_INITIATED_INSTALLMENT_FIRST",
    "installmentPayment": {
      "totalAmount": {
        "value": 6000,
        "currencyCode": "USD"
      },
      "numberOfInstallments": 6,
      "paymentAmount": {
        "value": 1000,
        "currencyCode": "USD"
      },
      "frequency": "MONTHLY",
      "firstPaymentDate": "2025-01-15",
      "paymentNumber": 1,
      "fundedAmount": {
        "value": 0,
        "currencyCode": "USD"
      }
    }
  }
}

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

Result

{
  "data": {
    "chargePaymentMethodToken": {
      "transaction": {
        "id": "acqpt_01",
        "networkTransactionIdentifier": "532675987658354",
        "installmentPayment": {
          "__typename": "MerchantManagedInstallmentPayment",
          "totalAmount": {
            "__typename": "Amount",
            "value": 6000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "numberOfInstallments": 6,
          "paymentAmount": {
            "__typename": "Amount",
            "value": 1000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "frequency": "MONTHLY",
          "firstPaymentDate": "2025-01-15",
          "paymentNumber": 1,
          "fundedAmount": {
            "__typename": "Amount",
            "value": 0,
            "currencyCode": "USD",
            "decimalPlaces": 2
          }
        }
      }
    }
  }
}

Merchant-initiated transaction

info

firstInstallmentPaymentTransactionId = CIT transaction.id

Subsequent installment using stored credentials. References the first payment via networkTransactionIdentifier and firstInstallmentPaymentTransactionId.

chargePaymentMethodToken

Query

mutation ChargePaymentMethodToken($input: ChargePaymentMethodTokenInput!) {
  chargePaymentMethodToken(input: $input) {
    ... on CardCaptureStepSummary {
      createdAt
      transaction {
        id
        networkTransactionIdentifier
        installmentPayment {
          __typename
          totalAmount {
            value
            currencyCode
            decimalPlaces
          }
          numberOfInstallments
          paymentAmount {
            value
            currencyCode
            decimalPlaces
          }
          frequency
          firstPaymentDate
          paymentNumber
          fundedAmount {
            value
            currencyCode
            decimalPlaces
          }
          firstInstallmentPaymentTransaction {
            ... on PaymentDebitTransaction {
              id
            }
          }
        }
      }
    }
  }
}

Variables

{
  "input": {
    "paymentMethodTokenId": "tkpmc_01",
    "merchantAcceptorId": "acqma_01",
    "amount": {
      "value": 1000,
      "currencyCode": "USD"
    },
    "idempotencyKey": "NEW_UUID_v4",
    "paymentInitiator": "MERCHANT_INITIATED_INSTALLMENT",
    "installmentPayment": {
      "totalAmount": {
        "value": 6000,
        "currencyCode": "USD"
      },
      "numberOfInstallments": 6,
      "paymentAmount": {
        "value": 1000,
        "currencyCode": "USD"
      },
      "frequency": "MONTHLY",
      "firstPaymentDate": "2025-01-15",
      "paymentNumber": 2,
      "fundedAmount": {
        "value": 1000,
        "currencyCode": "USD"
      },
      "firstInstallmentPaymentTransactionId": "acqpt_01"
    }
  }
}

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

Result

{
  "data": {
    "chargePaymentMethodToken": {
      "transaction": {
        "id": "acqpt_02",
        "networkTransactionIdentifier": "532675987658354",
        "installmentPayment": {
          "__typename": "MerchantManagedInstallmentPayment",
          "totalAmount": {
            "value": 6000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "numberOfInstallments": 6,
          "paymentAmount": {
            "value": 1000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "frequency": "MONTHLY",
          "firstPaymentDate": "2025-01-15",
          "paymentNumber": 2,
          "fundedAmount": {
            "value": 1000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "firstInstallmentPaymentTransaction": {
            "id": "acqpt_01"
          }
        }
      }
    }
  }
}

Network tokens

tip

Authorizations must be captured with the capturePaymentTransaction mutation. Charges = authorization + capture.

Use the following mutations for network token transactions.

Network tokens are used by the card networks for COF transactions external to Highnote. They are comprised of a raw network token number + cryptogram.

Authorize network token

The authorizeNetworkToken mutation creates an authorization on a network token for a merchant‑managed installment payment when installment-specific fields are provided in the input. This associates the resulting PaymentDebitTransaction with a merchant‑managed installment payment.

Customer-initiated transaction

First installment with cardholder present. Sets intendToStore: true to establish the credential on file.

authorizeNetworkToken

Query

mutation AuthorizeNetworkToken($input: AuthorizeNetworkTokenInput!) {
  authorizeNetworkToken(input: $input) {
    ... on CardAuthorizationStepSummary {
      transaction {
        id
        networkTransactionIdentifier
        installmentPayment {
          __typename
          totalAmount {
            __typename
            value
            currencyCode
            decimalPlaces
          }
          numberOfInstallments
          paymentAmount {
            __typename
            value
            currencyCode
            decimalPlaces
          }
          frequency
          firstPaymentDate
          paymentNumber
          fundedAmount {
            __typename
            value
            currencyCode
            decimalPlaces
          }
        }
      }
    }
  }
}

Variables

{
  "input": {
    "networkToken": {
      "cardNumber": "4000000000000002",
      "expiryYear": "29",
      "expiryMonth": "12",
      "networkTokenization": {
        "cryptogram": "test-cryptogram"
      }
    },
    "merchantAcceptorId": "acqma_01",
    "amount": {
      "value": 1000,
      "currencyCode": "USD"
    },
    "idempotencyKey": "UUID_v4",
    "paymentInitiator": "CUSTOMER_INITIATED_INSTALLMENT_FIRST",
    "externalCredentialOnFile": {
      "intendToStore": true
    },
    "installmentPayment": {
      "totalAmount": {
        "value": 6000,
        "currencyCode": "USD"
      },
      "numberOfInstallments": 6,
      "paymentAmount": {
        "value": 1000,
        "currencyCode": "USD"
      },
      "frequency": "MONTHLY",
      "firstPaymentDate": "2025-01-15",
      "paymentNumber": 1,
      "fundedAmount": {
        "value": 0,
        "currencyCode": "USD"
      }
    }
  }
}

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

Result

{
  "data": {
    "authorizeNetworkToken": {
      "transaction": {
        "id": "acqpt_01",
        "networkTransactionIdentifier": "532675987658354",
        "installmentPayment": {
          "__typename": "MerchantManagedInstallmentPayment",
          "totalAmount": {
            "__typename": "Amount",
            "value": 6000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "numberOfInstallments": 6,
          "paymentAmount": {
            "__typename": "Amount",
            "value": 1000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "frequency": "MONTHLY",
          "firstPaymentDate": "2025-01-15",
          "paymentNumber": 1,
          "fundedAmount": {
            "__typename": "Amount",
            "value": 0,
            "currencyCode": "USD",
            "decimalPlaces": 2
          }
        }
      }
    }
  }
}

Merchant-initiated transaction

info

firstInstallmentPaymentTransactionId = CIT transaction.id

Subsequent installment using stored credentials. References the first payment via networkTransactionIdentifier and firstInstallmentPaymentTransactionId.

authorizeNetworkToken

Query

mutation AuthorizeNetworkToken($input: AuthorizeNetworkTokenInput!) {
  authorizeNetworkToken(input: $input) {
    ... on CardAuthorizationStepSummary {
      createdAt
      transaction {
        id
        networkTransactionIdentifier
        installmentPayment {
          __typename
          totalAmount {
            value
            currencyCode
            decimalPlaces
          }
          numberOfInstallments
          paymentAmount {
            value
            currencyCode
            decimalPlaces
          }
          frequency
          firstPaymentDate
          paymentNumber
          fundedAmount {
            value
            currencyCode
            decimalPlaces
          }
          firstInstallmentPaymentTransaction {
            ... on PaymentDebitTransaction {
              id
            }
          }
        }
      }
    }
  }
}

Variables

{
  "input": {
    "networkToken": {
      "cardNumber": "4000000000000002",
      "expiryYear": "29",
      "expiryMonth": "12",
      "networkTokenization": {
        "cryptogram": "test-cryptogram"
      }
    },
    "merchantAcceptorId": "acqma_01",
    "amount": {
      "value": 1000,
      "currencyCode": "USD"
    },
    "idempotencyKey": "NEW_UUID_v4",
    "paymentInitiator": "MERCHANT_INITIATED_INSTALLMENT",
    "externalCredentialOnFile": {
      "networkTransactionIdentifier": "532675987658354"
    },
    "installmentPayment": {
      "totalAmount": {
        "value": 6000,
        "currencyCode": "USD"
      },
      "numberOfInstallments": 6,
      "paymentAmount": {
        "value": 1000,
        "currencyCode": "USD"
      },
      "frequency": "MONTHLY",
      "firstPaymentDate": "2025-01-15",
      "paymentNumber": 2,
      "fundedAmount": {
        "value": 1000,
        "currencyCode": "USD"
      },
      "firstInstallmentPaymentTransactionId": "acqpt_01"
    }
  }
}

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

Result

{
  "data": {
    "authorizeNetworkToken": {
      "transaction": {
        "id": "acqpt_02",
        "networkTransactionIdentifier": "532675987658354",
        "installmentPayment": {
          "__typename": "MerchantManagedInstallmentPayment",
          "totalAmount": {
            "__typename": "Amount",
            "value": 6000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "numberOfInstallments": 6,
          "paymentAmount": {
            "__typename": "Amount",
            "value": 1000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "frequency": "MONTHLY",
          "firstPaymentDate": "2025-01-15",
          "paymentNumber": 2,
          "fundedAmount": {
            "__typename": "Amount",
            "value": 1000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "firstInstallmentPaymentTransaction": {
            "id": "acqpt_01"
          }
        }
      }
    }
  }
}

Charge network token

The chargeNetworkToken mutation creates a capture on a network token for a merchant‑managed installment payment when installment-specific fields are provided in the input. This associates the resulting PaymentDebitTransaction with a merchant‑managed installment payment.

Customer-initiated transaction

First installment with cardholder present. Sets intendToStore: true to establish the credential on file.

chargeNetworkToken

Query

mutation ChargeNetworkToken($input: ChargeNetworkTokenInput!) {
  chargeNetworkToken(input: $input) {
    ... on CardCaptureStepSummary {
      transaction {
        id
        networkTransactionIdentifier
        installmentPayment {
          __typename
          totalAmount {
            __typename
            value
            currencyCode
            decimalPlaces
          }
          numberOfInstallments
          paymentAmount {
            __typename
            value
            currencyCode
            decimalPlaces
          }
          frequency
          firstPaymentDate
          paymentNumber
          fundedAmount {
            __typename
            value
            currencyCode
            decimalPlaces
          }
        }
      }
    }
  }
}

Variables

{
  "input": {
    "networkToken": {
      "cardNumber": "4000000000000002",
      "expiryYear": "29",
      "expiryMonth": "12",
      "networkTokenization": {
        "cryptogram": "test-cryptogram"
      }
    },
    "merchantAcceptorId": "acqma_01",
    "amount": {
      "value": 1000,
      "currencyCode": "USD"
    },
    "idempotencyKey": "UUID_v4",
    "paymentInitiator": "CUSTOMER_INITIATED_INSTALLMENT_FIRST",
    "externalCredentialOnFile": {
      "intendToStore": true
    },
    "installmentPayment": {
      "totalAmount": {
        "value": 6000,
        "currencyCode": "USD"
      },
      "numberOfInstallments": 6,
      "paymentAmount": {
        "value": 1000,
        "currencyCode": "USD"
      },
      "frequency": "MONTHLY",
      "firstPaymentDate": "2025-01-15",
      "paymentNumber": 1,
      "fundedAmount": {
        "value": 0,
        "currencyCode": "USD"
      }
    }
  }
}

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

Result

{
  "data": {
    "chargeNetworkToken": {
      "transaction": {
        "id": "acqpt_01",
        "networkTransactionIdentifier": "532675987658354",
        "installmentPayment": {
          "__typename": "MerchantManagedInstallmentPayment",
          "totalAmount": {
            "__typename": "Amount",
            "value": 6000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "numberOfInstallments": 6,
          "paymentAmount": {
            "__typename": "Amount",
            "value": 1000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "frequency": "MONTHLY",
          "firstPaymentDate": "2025-01-15",
          "paymentNumber": 1,
          "fundedAmount": {
            "__typename": "Amount",
            "value": 0,
            "currencyCode": "USD",
            "decimalPlaces": 2
          }
        }
      }
    }
  }
}

Merchant-initiated transaction

info

firstInstallmentPaymentTransactionId = CIT transaction.id

Subsequent installment using stored credentials. References the first payment via networkTransactionIdentifier and firstInstallmentPaymentTransactionId.

chargeNetworkToken

Query

mutation ChargeNetworkToken($input: ChargeNetworkTokenInput!) {
  chargeNetworkToken(input: $input) {
    ... on CardCaptureStepSummary {
      createdAt
      transaction {
        id
        networkTransactionIdentifier
        installmentPayment {
          __typename
          totalAmount {
            value
            currencyCode
            decimalPlaces
          }
          numberOfInstallments
          paymentAmount {
            value
            currencyCode
            decimalPlaces
          }
          frequency
          firstPaymentDate
          paymentNumber
          fundedAmount {
            value
            currencyCode
            decimalPlaces
          }
          firstInstallmentPaymentTransaction {
            ... on PaymentDebitTransaction {
              id
            }
          }
        }
      }
    }
  }
}

Variables

{
  "input": {
    "networkToken": {
      "cardNumber": "4000000000000002",
      "expiryYear": "29",
      "expiryMonth": "12",
      "networkTokenization": {
        "cryptogram": "test-cryptogram"
      }
    },
    "merchantAcceptorId": "acqma_01",
    "amount": {
      "value": 1000,
      "currencyCode": "USD"
    },
    "idempotencyKey": "NEW_UUID_v4",
    "paymentInitiator": "MERCHANT_INITIATED_INSTALLMENT",
    "externalCredentialOnFile": {
      "networkTransactionIdentifier": "532675987658354"
    },
    "installmentPayment": {
      "totalAmount": {
        "value": 6000,
        "currencyCode": "USD"
      },
      "numberOfInstallments": 6,
      "paymentAmount": {
        "value": 1000,
        "currencyCode": "USD"
      },
      "frequency": "MONTHLY",
      "firstPaymentDate": "2025-01-15",
      "paymentNumber": 2,
      "fundedAmount": {
        "value": 1000,
        "currencyCode": "USD"
      },
      "firstInstallmentPaymentTransactionId": "acqpt_01"
    }
  }
}

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

Result

{
  "data": {
    "chargeNetworkToken": {
      "transaction": {
        "id": "acqpt_02",
        "networkTransactionIdentifier": "532675987658354",
        "installmentPayment": {
          "__typename": "MerchantManagedInstallmentPayment",
          "totalAmount": {
            "__typename": "Amount",
            "value": 6000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "numberOfInstallments": 6,
          "paymentAmount": {
            "__typename": "Amount",
            "value": 1000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "frequency": "MONTHLY",
          "firstPaymentDate": "2025-01-15",
          "paymentNumber": 2,
          "fundedAmount": {
            "__typename": "Amount",
            "value": 1000,
            "currencyCode": "USD",
            "decimalPlaces": 2
          },
          "firstInstallmentPaymentTransaction": {
            "id": "acqpt_01"
          }
        }
      }
    }
  }
}

Mastercard single authorization multiple capture (SAMC)

Mastercard single authorization multiple capture (SAMC) supports the ability to authorize the full amount in a single authorization, while capturing each authorization in multiple installments.

Single authorization multiple capture

Assume a $1000 purchase is to be paid back in four installments of $250:

Make one CIT authorization for the full installment amount ($1000).
Capture each installment amount ($250 each month for 4 months).
Monitor the expiration date for the first CIT authorization (valid for 30 days). To extend for another 30 days, see Request $0 incremental authorization in the Incremental Authorization docs.

Authorize SAMC network token

Customer-initiated transaction

Using Mastercard SAMC, make one customer-initiated transaction network token authorization for the full amount of the payment.

authorizeNetworkToken

Query

mutation AuthorizeNetworkToken($input: AuthorizeNetworkTokenInput!) {
  authorizeNetworkToken(input: $input) {
    ... on CardAuthorizationStepSummary {
      transaction {
        id
        networkTransactionIdentifier
        installmentPayment {
          __typename
          totalAmount {
            __typename
            value
            currencyCode
            decimalPlaces
          }
          numberOfInstallments
          paymentAmount {
            __typename
            value
            currencyCode
            decimalPlaces
          }
          frequency
          firstPaymentDate
          paymentNumber
          fundedAmount {
            __typename
            value
            currencyCode
            decimalPlaces
          }
        }
        responseCode {
          addressCode
          postalCode
          securityCode
          authorizationCode
          processorResponseCode
        }
      }
    }
  }
}

Variables

{
  "input": {
    "networkToken": {
      "cardNumber": "5555555555554444",
      "expiryYear": "29",
      "expiryMonth": "12",
      "networkTokenization": {
        "cryptogram": "MKTfCToAAATiAAdDNDaQAAADFAA="
      }
    },
    "merchantAcceptorId": "acqma_cbc8374266574b9ea7a9feca499f3d55",
    "amount": {
      "value": 100000,
      "currencyCode": "USD"
    },
    "idempotencyKey": "UUID_v4",
    "paymentInitiator": "CUSTOMER_INITIATED_INSTALLMENT_FIRST",
    "externalCredentialOnFile": {
      "intendToStore": true
    },
    "installmentPayment": {
      "totalAmount": {
        "value": 100000,
        "currencyCode": "USD"
      },
      "numberOfInstallments": 4,
      "paymentAmount": {
        "value": 25000,
        "currencyCode": "USD"
      },
      "frequency": "MONTHLY",
      "firstPaymentDate": "2025-01-23",
      "paymentNumber": 1,
      "fundedAmount": {
        "value": 100000,
        "currencyCode": "USD"
      },
      "networkData": {
        "mastercardData": {
          "singleAuthorizationMultipleCaptures": true
        }
      }
    }
  }
}

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

Result

{
  "data": {
    "authorizeNetworkToken": {
      "__typename": "CardAuthorizationStepSummary",
      "createdAt": "2026-01-23T22:43:53.906Z",
      "transaction": {
        "__typename": "PaymentDebitTransactionSummary",
        "id": "acqpt_9b2b14deb2f34543b2b12b62ced47b9c",
        "createdAt": "2026-01-23T22:43:53.906Z",
        "accountingDirection": "DEBIT",
        "authorizedAmount": {
          "value": 100000,
          "currencyCode": "USD"
        },
        "authorizedRemainingAmount": {
          "value": 100000,
          "currencyCode": "USD"
        },
        "settledAmount": null,
        "disbursedAmount": null,
        "canceledAmount": null,
        "refundedAmount": null,
        "networkTransactionIdentifier": "MCCV42I4WSLL",
        "responseCode": {
          "authorizationCode": "QYD9KN",
          "processorResponseCode": "APPROVED",
          "addressCode": "MATCHED",
          "postalCode": "MATCHED",
          "securityCode": "NOT_PROVIDED"
        },
        "installmentPayment": {
          "fundedAmount": {
            "currencyCode": "USD",
            "decimalPlaces": 2,
            "value": 0
          },
          "firstInstallmentPaymentTransaction": null,
          "firstPaymentDate": "2026-01-23",
          "frequency": "MONTHLY",
          "numberOfInstallments": 4,
          "paymentAmount": {
            "currencyCode": "USD",
            "decimalPlaces": 2,
            "value": 25000
          },
          "paymentNumber": 1,
          "totalAmount": {
            "currencyCode": "USD",
            "decimalPlaces": 2,
            "value": 100000
          }
        },
        "instrument": {
          "cardHolder": {
            "email": "",
            "fullName": "",
            "billingAddress": {
              "postalCode": "21345",
              "streetAddress": "2134 Mastercard St",
              "countryCodeAlpha3": "USA"
            }
          }
        }
      }
    }
  }
}

Capture SAMC partial amount

After making a single authorization for the full amount of $1000, use the following mutation multiple times to capture each installment amount of $250.

capturePaymentTransaction

Query

mutation CapturePaymentTransaction($input: CapturePaymentTransactionInput!) {
  capturePaymentTransaction(input: $input) {
    __typename
    ... on UserError {
      errors {
        errorPath
        code
        description
      }
    }
    ... on CardCaptureStepSummary {
      createdAt
      transaction {
        __typename
        id
        createdAt
        accountingDirection
        authorizedAmount {
          value
          currencyCode
        }
        authorizedRemainingAmount {
          value
          currencyCode
        }
        settledAmount {
          value
          currencyCode
        }
        disbursedAmount {
          value
          currencyCode
        }
        canceledAmount {
          value
          currencyCode
        }
        refundedAmount {
          value
          currencyCode
        }
        responseCode {
          processorResponseCode
          addressCode
          postalCode
          securityCode
          authorizationCode
          processorResponseCode
        }
      }
    }
  }
}

Variables

{
  "input": {
    "paymentTransactionId": "acqpt_9b2b14deb2f34543b2b12b62ced47b9c",
    "amount": {
      "value": 25000,
      "currencyCode": "USD"
    },
    "idempotencyKey": "UUID_v4"
  }
}

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

Result

{
  "data": {
    "capturePaymentTransaction": {
      "__typename": "CardCaptureStepSummary",
      "createdAt": "2026-01-23T22:58:25.607Z",
      "transaction": {
        "__typename": "PaymentDebitTransactionSummary",
        "id": "acqpt_9b2b14deb2f34543b2b12b62ced47b9c",
        "createdAt": "2026-01-23T22:58:25.607Z",
        "accountingDirection": "DEBIT",
        "authorizedAmount": {
          "value": 100000,
          "currencyCode": "USD"
        },
        "authorizedRemainingAmount": {
          "value": 75000,
          "currencyCode": "USD"
        },
        "settledAmount": null,
        "disbursedAmount": null,
        "canceledAmount": null,
        "refundedAmount": null,
        "responseCode": {
          "processorResponseCode": "APPROVED",
          "addressCode": "SKIPPED",
          "postalCode": "SKIPPED",
          "securityCode": "SKIPPED",
          "authorizationCode": "0GJCIX"
        }
      }
    }
  }
}

Extend SAMC expiration date

You can extend the expiration date of the original SAMC authorization by running a zero dollar incremental authorization.

Overview​

CIT / MIT model​

CIT payment 1 (first installment)​

MIT payments 2-n (subsequent installments)​

Installment payment data​

Highnote vs network tokens​

Supported mutations​

Payment cards​

Authorize payment card​

Customer-initiated transaction​

authorizePaymentCard​

Merchant-initiated transaction​

authorizePaymentCard​

Charge payment card​

Customer-initiated transaction​

chargePaymentCard​

Merchant-initiated transaction​

chargePaymentCard​

Payment method tokens​

Authorize payment method token​

Customer-initiated transaction​

authorizePaymentMethodToken​

Merchant-initiated transaction​

authorizePaymentMethodToken​

Charge payment method token​

Customer-initiated transaction​

chargePaymentMethodToken​

Merchant-initiated transaction​

chargePaymentMethodToken​

Network tokens​

Authorize network token​

Customer-initiated transaction​

authorizeNetworkToken​

Merchant-initiated transaction​

authorizeNetworkToken​

Charge network token​

Customer-initiated transaction​

chargeNetworkToken​

Merchant-initiated transaction​

chargeNetworkToken​

Mastercard single authorization multiple capture (SAMC)​

Single authorization multiple capture​

Authorize SAMC network token​

Customer-initiated transaction​

authorizeNetworkToken​

Capture SAMC partial amount​

capturePaymentTransaction​

Extend SAMC expiration date​

Overview

CIT / MIT model

CIT payment 1 (first installment)

MIT payments 2-n (subsequent installments)

Installment payment data

Highnote vs network tokens

Supported mutations

Payment cards

Authorize payment card

Customer-initiated transaction

authorizePaymentCard

Merchant-initiated transaction

authorizePaymentCard

Charge payment card

Customer-initiated transaction

chargePaymentCard

Merchant-initiated transaction

chargePaymentCard

Payment method tokens

Authorize payment method token

Customer-initiated transaction

authorizePaymentMethodToken

Merchant-initiated transaction

authorizePaymentMethodToken

Charge payment method token

Customer-initiated transaction

chargePaymentMethodToken

Merchant-initiated transaction

chargePaymentMethodToken

Network tokens

Authorize network token

Customer-initiated transaction

authorizeNetworkToken

Merchant-initiated transaction

authorizeNetworkToken

Charge network token

Customer-initiated transaction

chargeNetworkToken

Merchant-initiated transaction

chargeNetworkToken

Mastercard single authorization multiple capture (SAMC)

Single authorization multiple capture

Authorize SAMC network token

Customer-initiated transaction

authorizeNetworkToken

Capture SAMC partial amount

capturePaymentTransaction

Extend SAMC expiration date