Credential On File Installments

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

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

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

To query installments, refer to Find all payment transactions and Find a payment transaction.

Both authorization and charge mutations (for supported input types PaymentCard, PaymentMethodToken, and NetworkToken) 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.

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

Use the following mutations for standard card payments.

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.

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

firstInstallmentPaymentTransactionId = CIT transaction.id

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

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.

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

firstInstallmentPaymentTransactionId = CIT transaction.id

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

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.

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.

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

firstInstallmentPaymentTransactionId = CIT transaction.id

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

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.

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

firstInstallmentPaymentTransactionId = CIT transaction.id

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

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.

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.

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

firstInstallmentPaymentTransactionId = CIT transaction.id

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

The chargeNetworkToken mutation creates a capture on a network payment 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.

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

firstInstallmentPaymentTransactionId = CIT transaction.id

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

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:

1. Make one CIT authorization for the full installment amount ($1000).
2. Capture each installment amount ($250 each month for 4 months).
3. 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.

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

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

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