Online Payments
Payment networks
Highnote accepts online payments through the following payment networks:
| Payment Network | Rail | Payment Instrument |
|---|---|---|
| Visa | Credit/Debit | Card |
| Mastercard | Credit/Debit | Card |
| Maestro | PIN-less Debit | Card |
| Discover | Credit | Card |
| American Express | Credit | Card |
Integration options
How you integrate with the Highnote API depends on your PCI compliance level. Highnote supports two integration paths:
- Tokenized (non-PCI): Use a Highnote SDK to collect card details and tokenize them into a
PaymentMethodToken. Your servers never handle raw card data, keeping you out of PCI scope. - Direct (PCI SAQ-D): Pass raw card details directly to the Highnote API. This requires PCI SAQ-D compliance because your servers handle cardholder data.
Both paths support the same payment operations (verify, authorize, charge, capture, cancel, refund). The only difference is the input: a paymentMethodTokenId for tokenized integrations, or raw card details (paymentCard) for direct integrations.
Tokenization with Highnote SDKs
For merchants who are not PCI SAQ-D compliant, Highnote provides two SDKs that tokenize card details into a PaymentMethodToken:
- Secure Inputs SDK: Build a custom payment form with your own UI. The SDK renders secure input fields that you style and position.
- Checkout SDK: Drop in a pre-built payment form. The SDK generates the UI for you.
Both SDKs output the same result: a tokenized PaymentMethodToken ID (tkpmc_) that you use with the tokenized mutations below.
Follow the Secure Inputs SDK setup guide and add the following SDK snippet to your payment form:
const secureInputs = await renderFields({
creditCard: {
clientToken: clientTokenFromServer,
cardNumber: {
selector: "#card-number",
},
expiryYear: {
selector: "#expiry-year",
},
expiryMonth: {
selector: "#expiry-month",
},
securityCode: {
selector: "#security-code",
},
cardHolderName: {
selector: "#card-holder-name",
},
},
onSuccess: (element) => {
if (element.name === "card") {
const paymentMethodId = element.paymentMethod.id;
console.log(
"Send this paymentMethodId to your server for payment: ",
paymentMethodId,
);
}
},
onError: (error) => {
console.log("Error: " + error.message);
},
});
Payments process
The standard payment process uses the following steps:
- Verification (optional): Confirm the card is valid with a zero-dollar transaction before authorizing.
- Authorization: The customer's payment details are verified with the issuer, and the funds are held.
- Cancel: If the payment cannot continue, reverse the authorization transaction to release the funds.
- Capture: The held funds are transferred to your merchant settlement financial account after the customer's successful authorization.
- Refund: The held funds are transferred from your merchant settlement financial account back to the customer's account.
- Disburse: The funds due to each merchant account is calculated and moved from Highnote's ledger to the merchant settlement account, including fees and reserve amounts.
Transactions can be processed in two ways, "Dual message" or "Single message".
Dual message
Dual message: Authorize first, then capture later. Use this for transactions where the final amount may change, such as tips or partial shipments.
Single message
Single message: Authorize and capture in a single step using the charge mutation. Use this when the final amount is known at the time of payment.
Tokenized integration (non-PCI)
Use the following mutations if you tokenize card details with a Highnote SDK. These mutations accept a paymentMethodTokenId instead of raw card details.
Verify a payment method token
Before authorizing a transaction, you can verify that a payment method token is valid and able to be used for payment. Token verification runs a zero-dollar transaction to confirm the underlying card details without placing a hold on funds.
Verify Payment Method Token
Query
mutation VerifyPaymentMethodToken($input: VerifyPaymentMethodTokenInput!) {
verifyPaymentMethodToken(input: $input) {
... on PaymentCardVerification {
createdAt
responseCode {
processorResponseCode
addressCode
postalCode
securityCode
}
}
}
}
Variables
{ "input": { "paymentMethodTokenId": "tkpmc_01", "merchantAcceptorId": "acqma_01", "idempotencyKey": "UUID_v4" } }
Result
{
"data": {
"verifyPaymentMethodToken": {
"createdAt": "2024-02-22T17:26:20.474Z",
"responseCode": {
"processorResponseCode": "APPROVED",
"addressCode": "NOT_PROVIDED",
"postalCode": "NOT_PROVIDED",
"securityCode": "MATCHED"
}
}
},
"extensions": {
"requestId": "REQUEST_ID",
"rateLimit": {
"cost": 18,
"limit": 60060,
"remaining": 60041
}
}
}
Authorize a payment method token
Use the following mutation to authorize a payment method token for later capture:
Authorize Payment Method Token
Query
mutation AuthorizePaymentMethodToken(
$input: AuthorizePaymentMethodTokenInput!
) {
authorizePaymentMethodToken(input: $input) {
... on CardAuthorizationStepSummary {
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 {
authorizationCode
processorResponseCode
addressCode
postalCode
securityCode
}
}
}
}
}
Variables
{ "input": { "paymentMethodTokenId": "tkpmc_01", "merchantAcceptorId": "acqma_01", "amount": { "value": 1000, "currencyCode": "USD" }, "idempotencyKey": "UUID_v4", "paymentInitiator": "CUSTOMER_INITIATED_VIA_WEB" } }
Result
{
"data": {
"authorizePaymentMethodToken": {
"createdAt": "2024-02-22T17:26:20.474Z",
"transaction": {
"__typename": "PaymentDebitTransactionSummary",
"id": "acqpt_01",
"createdAt": "2024-02-22T17:26:20.474Z",
"accountingDirection": "DEBIT",
"authorizedAmount": {
"value": 1000,
"currencyCode": "USD"
},
"authorizedRemainingAmount": {
"value": 1000,
"currencyCode": "USD"
},
"settledAmount": null,
"disbursedAmount": null,
"canceledAmount": null,
"refundedAmount": null,
"responseCode": {
"authorizationCode": "Q5Z539",
"processorResponseCode": "APPROVED",
"addressCode": "NOT_PROVIDED",
"postalCode": "NOT_PROVIDED",
"securityCode": "NOT_VERIFIED"
}
}
}
},
"extensions": {
"requestId": "REQUEST_ID",
"rateLimit": {
"cost": 18,
"limit": 60060,
"remaining": 60041
}
}
}
Charge a payment method token
Use the following mutation to authorize and capture a payment in a single step:
Charge Payment Method Token
Query
mutation ChargePaymentMethodToken($input: ChargePaymentMethodTokenInput!) {
chargePaymentMethodToken(input: $input) {
__typename
... on CardCaptureStepSummary {
transaction {
__typename
id
createdAt
accountingDirection
authorizedAmount {
value
currencyCode
}
authorizedRemainingAmount {
value
currencyCode
}
canceledAmount {
value
currencyCode
}
networkTransactionIdentifier
settledAmount {
value
currencyCode
}
disbursedAmount {
value
currencyCode
}
canceledAmount {
value
currencyCode
}
refundedAmount {
value
currencyCode
}
responseCode {
processorResponseCode
addressCode
postalCode
securityCode
}
}
}
}
}
Variables
{ "input": { "paymentMethodTokenId": "tkpmc_01", "merchantAcceptorId": "acqma_01", "amount": { "value": 1000, "currencyCode": "USD" }, "idempotencyKey": "00000000-0000-0000-0000-000000000000", "paymentInitiator": "CUSTOMER_INITIATED_VIA_WEB" } }
Result
{
"data": {
"chargePaymentMethodToken": {
"__typename": "CardCaptureStepSummary",
"transaction": {
"__typename": "PaymentDebitTransactionSummary",
"id": "acqpt_01",
"createdAt": "2024-06-24T18:16:15.297Z",
"accountingDirection": "CREDIT",
"authorizedAmount": {
"value": 1000,
"currencyCode": "USD"
},
"authorizedRemainingAmount": {
"value": 0,
"currencyCode": "USD"
},
"canceledAmount": null,
"networkTransactionIdentifier": null,
"settledAmount": null,
"disbursedAmount": null,
"refundedAmount": null,
"responseCode": {
"processorResponseCode": "APPROVED",
"addressCode": "NOT_PROVIDED",
"postalCode": "NOT_PROVIDED",
"securityCode": "NOT_VERIFIED"
}
}
}
},
"extensions": {
"requestId": "REQUEST_ID",
"rateLimit": {
"cost": 19,
"limit": 60060,
"remaining": 60040
}
}
}
Direct integration (PCI SAQ-D)
The following mutations accept raw card details (PAN, expiry, CVV). Your servers must be PCI SAQ-D compliant to use these mutations.
Use the following mutations if you handle raw card details directly. These mutations accept a paymentCard input with the card number, expiry, and security code.
Verify a payment card
Before authorizing a transaction, you can verify that a payment card is valid and able to be used for payment. Card verification runs a zero-dollar transaction against the card to confirm the card number, expiration date, and security code without placing a hold on funds.
The verification response includes response codes for the processor result, address (AVS), postal code, and security code (CVV). Use these response codes to determine whether to proceed with authorization.
To verify a payment card, provide the card details in the paymentCard input. Optionally, include cardHolder with a billing address to enable address verification (AVS).
Verify Payment Card
Query
mutation VerifyPaymentCard($input: VerifyPaymentCardInput!) {
verifyPaymentCard(input: $input) {
... on PaymentCardVerification {
createdAt
responseCode {
processorResponseCode
addressCode
postalCode
securityCode
}
}
}
}
Variables
{ "input": { "paymentCard": { "cardNumber": "4000000000000002", "expiryYear": "31", "expiryMonth": "12", "securityCode": "111" }, "cardHolder": { "billingAddress": { "streetAddress": "1234 Visa Street", "countryCodeAlpha3": "USA", "extendedAddress": "extended-address", "locality": "Visa", "region": "California", "postalCode": "12345" } }, "merchantAcceptorId": "acqma_01", "idempotencyKey": "UUID_v4" } }
Result
{
"data": {
"verifyPaymentCard": {
"createdAt": "2024-02-22T17:26:20.474Z",
"responseCode": {
"processorResponseCode": "APPROVED",
"addressCode": "MATCHED",
"postalCode": "MATCHED",
"securityCode": "MATCHED"
}
}
},
"extensions": {
"requestId": "REQUEST_ID",
"rateLimit": {
"cost": 18,
"limit": 60060,
"remaining": 60041
}
}
}
Authorize a payment card
Use the following mutation to authorize a payment card for later capture:
Authorize Payment Card
Query
mutation AuthorizePaymentCard($input: AuthorizePaymentCardInput!) {
authorizePaymentCard(input: $input) {
... on CardAuthorizationStepSummary {
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 {
authorizationCode
processorResponseCode
addressCode
postalCode
securityCode
}
}
}
}
}
Variables
{ "input": { "paymentCard": { "cardNumber": "4000000000000002", "expiryYear": "31", "expiryMonth": "12", "securityCode": "111" }, "cardHolder": { "billingAddress": { "streetAddress": "1234 Visa Street", "countryCodeAlpha3": "USA", "extendedAddress": "extended-address", "locality": "Visa", "region": "California", "postalCode": "12345" } }, "merchantAcceptorId": "acqma_01", "amount": { "value": 1000, "currencyCode": "USD" }, "idempotencyKey": "UUID_v4", "paymentInitiator": "CUSTOMER_INITIATED_VIA_WEB" } }
Result
{
"data": {
"authorizePaymentCard": {
"createdAt": "2024-02-22T17:26:20.474Z",
"transaction": {
"__typename": "PaymentDebitTransactionSummary",
"id": "acqpt_01",
"createdAt": "2024-02-22T17:26:20.474Z",
"accountingDirection": "DEBIT",
"authorizedAmount": {
"value": 1000,
"currencyCode": "USD"
},
"authorizedRemainingAmount": {
"value": 1000,
"currencyCode": "USD"
},
"settledAmount": null,
"disbursedAmount": null,
"canceledAmount": null,
"refundedAmount": null,
"responseCode": {
"authorizationCode": "Q5Z539",
"authorizationResponseCode": "UNSPECIFIED",
"addressCode": "NOT_VERIFIED",
"postalCode": "NOT_VERIFIED",
"securityCode": "NOT_VERIFIED"
}
}
}
},
"extensions": {
"requestId": "REQUEST_ID",
"rateLimit": {
"cost": 18,
"limit": 60060,
"remaining": 60041
}
}
}
Charge a payment card
Use the following mutation to authorize and capture a payment in a single step:
Charge Payment Card
Query
mutation ChargePaymentCard($input: ChargePaymentCardInput!) {
chargePaymentCard(input: $input) {
__typename
... 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 {
authorizationCode
processorResponseCode
addressCode
postalCode
securityCode
}
}
}
}
}
Variables
{ "input": { "paymentCard": { "cardNumber": "4229989999000012", "expiryYear": "31", "expiryMonth": "12", "securityCode": "871" }, "cardHolder": { "billingAddress": { "streetAddress": "street-address", "countryCodeAlpha3": "USA", "extendedAddress": "extended-address", "locality": "Los Angeles", "region": "California", "postalCode": "90210" } }, "merchantAcceptorId": "acqma_01", "amount": { "value": 1000, "currencyCode": "USD" }, "idempotencyKey": "UUID_v4", "paymentInitiator": "CUSTOMER_INITIATED_VIA_WEB" } }
Result
{
"data": {
"chargePaymentCard": {
"__typename": "CardCaptureStepSummary",
"createdAt": null,
"transaction": {
"__typename": "PaymentDebitTransactionSummary",
"id": "acqpt_01",
"createdAt": "2024-02-21T17:46:00.650Z",
"accountingDirection": "DEBIT",
"authorizedAmount": {
"value": 0,
"currencyCode": "USD"
},
"authorizedRemainingAmount": {
"value": 0,
"currencyCode": "USD"
},
"settledAmount": null,
"disbursedAmount": null,
"canceledAmount": null,
"refundedAmount": null,
"responseCode": {
"authorizationCode": "",
"processorResponseCode": "UNSPECIFIED",
"addressCode": "NOT_PROVIDED",
"postalCode": "NOT_PROVIDED",
"securityCode": "NOT_VERIFIED"
}
}
}
},
"extensions": {
"requestId": "REQUEST_ID",
"rateLimit": {
"cost": 18
}
}
}
Verification response codes
Both verifyPaymentCard and verifyPaymentMethodToken return a responseCode with the following sub-fields:
| Field | Description |
|---|---|
processorResponseCode | The processor's result, such as APPROVED or EXPIRED_CARD. |
addressCode | Whether the street address matches the issuer's records. |
postalCode | Whether the postal code matches the issuer's records. |
securityCode | Whether the security code (CVV/CVC) matches the issuer's records. |
Each AVS and security code field returns one of the following values: MATCHED, NOT_MATCHED, NOT_PROVIDED, NOT_VERIFIED, SKIPPED, or UNKNOWN.
Cancel a payment
A payment can only be canceled before Highnote captures the payment. When a payment is canceled before capture, no money has moved out of the cardholder's account, resulting in the funds being returned to their account balance.
Payments can be canceled by the cardholder, merchant, issuing bank, acquiring bank, or payment network. Payment cancellations are common in the following use cases:
- Undelivered goods or services
- Duplicate transactions
- Fraud transactions
- The customer asks for a cancellation before goods are shipped
Full and partial payment cancellations are supported for all card networks except American Express. For an overview of use cases for partial cancellations, see Cancel a partial amount.
Cancel full amount
To process a full cancellation, use the following mutation and ensure the value input variable is equal to the full amount of the authorization:
Cancel Payment Transaction - Full
Query
mutation CancelPaymentTransaction($input: CancelPaymentTransactionInput!) {
cancelPaymentTransaction(input: $input) {
__typename
... on CardReversalStepSummary {
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
}
}
}
}
}
Variables
{ "input": { "paymentTransactionId": "acqpt_01", "amount": { "value": 1000, "currencyCode": "USD" }, "idempotencyKey": "UUID_v4" } }
Result
{
"data": {
"cancelPaymentTransaction": {
"__typename": "CardReversalStepSummary",
"createdAt": null,
"transaction": {
"__typename": "PaymentDebitTransactionSummary",
"id": "acqpt_b7b137033fc540209047610d54352f96",
"createdAt": "2024-02-22T17:26:20.474Z",
"accountingDirection": "CREDIT",
"authorizedAmount": {
"value": 1000,
"currencyCode": "USD"
},
"authorizedRemainingAmount": {
"value": 0,
"currencyCode": "USD"
},
"settledAmount": null,
"disbursedAmount": null,
"canceledAmount": {
"value": 1000,
"currencyCode": "USD"
},
"refundedAmount": null,
"responseCode": {
"processorResponseCode": "UNSPECIFIED",
"addressCode": "SKIPPED",
"postalCode": "SKIPPED",
"securityCode": "SKIPPED"
}
}
}
},
"extensions": {
"requestId": "REQUEST_ID",
"rateLimit": {
"cost": 18,
"limit": 60060,
"remaining": 60041
}
}
}
Cancel partial amount
Partial cancellations are not supported for American Express.
Partial cancellations are common in the following use cases:
- A customer returns items from their purchase, but not the entire purchase.
- A customer cancels a service and is refunded the unused portion of the service.
- An error was made in the initial billing, such as overcharging a service or product.
- Only one part of an order was fulfilled or delivered, and the other part is reversed as a refund.
To process a partial cancellation, use the following mutation and enter the partial amount in the value input variable field:
Cancel Payment Transaction - Partial
Query
mutation CancelPaymentTransaction($input: CancelPaymentTransactionInput!) {
cancelPaymentTransaction(input: $input) {
__typename
... on CardReversalStepSummary {
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
}
}
}
}
}
Variables
{ "input": { "paymentTransactionId": "acqpt_01", "amount": { "value": 500, "currencyCode": "USD" }, "idempotencyKey": "UUID_v4" } }
Result
{
"data": {
"cancelPaymentTransaction": {
"__typename": "CardReversalStepSummary",
"createdAt": "2025-10-29T15:34:39.465Z",
"transaction": {
"__typename": "PaymentDebitTransactionSummary",
"id": "acqpt_679dd59764ee4580b44b6655049f6543",
"createdAt": "2025-10-29T15:34:39.465Z",
"accountingDirection": "DEBIT",
"authorizedAmount": {
"value": 1000,
"currencyCode": "USD"
},
"authorizedRemainingAmount": {
"value": 500,
"currencyCode": "USD"
},
"settledAmount": null,
"disbursedAmount": null,
"canceledAmount": {
"value": 500,
"currencyCode": "USD"
},
"refundedAmount": null,
"responseCode": {
"processorResponseCode": "APPROVED",
"addressCode": "SKIPPED",
"postalCode": "SKIPPED",
"securityCode": "SKIPPED"
}
}
}
},
"extensions": {
"requestId": "3259a2e2-290a-95bd-853a-8bf2b2d009a4",
"rateLimit": {
"cost": 18,
"limit": 2500,
"remaining": 2482,
"asOf": "2025-10-29T15:40:00.894Z",
"complexity": {
"limit": 2500,
"remaining": 2482,
"cost": 18
},
"count": {
"limit": 100,
"remaining": 99,
"cost": 1
}
}
}
}
Capture a payment
Capturing a payment transaction moves funds from the customer's account to your merchant account. Full and partial captures are supported for all card networks except for American Express.
Capture full amount
To capture a full amount of an authorized transaction, set the amount.value input field to the full amount of the original authorization.
Set paymentTransactionId to an authorized PaymentTransaction ID (e.g., acqpt_...).
Use the following mutation and input variables to capture the full amount of an authorized payment transaction:
Capture Payment Transaction - Full
Query
mutation CapturePaymentTransaction($input: CapturePaymentTransactionInput!) {
capturePaymentTransaction(input: $input) {
__typename
... 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 {
authorizationCode
processorResponseCode
addressCode
postalCode
securityCode
}
}
}
}
}
Variables
{ "input": { "paymentTransactionId": "acqpt_01", "merchantAcceptorId": "acqma_01", "amount": { "value": 1000, "currencyCode": "USD" }, "idempotencyKey": "UUID_v4" } }
Result
{
"data": {
"capturePaymentTransaction": {
"__typename": "CardCaptureStepSummary",
"createdAt": null,
"transaction": {
"__typename": "PaymentDebitTransactionSummary",
"id": "acqpt_01",
"createdAt": "2024-02-22T17:32:11.361Z",
"accountingDirection": "DEBIT",
"authorizedAmount": {
"value": 1000,
"currencyCode": "USD"
},
"authorizedRemainingAmount": {
"value": 0,
"currencyCode": "USD"
},
"settledAmount": null,
"disbursedAmount": null,
"canceledAmount": null,
"refundedAmount": null,
"responseCode": {
"authorizationCode": "O4KBDO",
"addressCode": "SKIPPED",
"postalCode": "SKIPPED",
"securityCode": "SKIPPED"
}
}
}
},
"extensions": {
"requestId": "REQUEST_ID",
"rateLimit": {
"cost": 18,
"limit": 60060,
"remaining": 60038
}
}
}
Capture partial amount
Partial captures are not supported for American Express.
To capture the partial amount of an authorized transaction, enter a partial amount in the amount.value input field.
Set paymentTransactionId to an authorized PaymentTransaction ID (e.g., acqpt_...).
Partial captures are common in the following use cases:
- A customer places a pre-order or makes a deposit, and only a portion of the total authorization is captured upfront.
- A customer's order is split into multiple shipments and the merchant captures payments separately for each one.
- A merchant offers flexible payment terms, with partial captures collected at an agreed-upon schedule.
- An item from a customer's order is back-ordered and the business captures a payment for only the available items.
Use the following mutation and input variables to capture the partial amount of an authorized payment transaction:
Capture Payment Transaction - Partial
Query
mutation CapturePaymentTransaction($input: CapturePaymentTransactionInput!) {
capturePaymentTransaction(input: $input) {
__typename
... 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 {
authorizationCode
processorResponseCode
addressCode
postalCode
securityCode
}
}
}
}
}
Variables
{ "input": { "paymentTransactionId": "acqpt_02", "merchantAcceptorId": "acqma_01", "amount": { "value": 500, "currencyCode": "USD" }, "idempotencyKey": "UUID_v4" } }
Result
{
"data": {
"capturePaymentTransaction": {
"__typename": "CardCaptureStepSummary",
"createdAt": "2025-10-29T15:51:40.966Z",
"transaction": {
"__typename": "PaymentDebitTransactionSummary",
"id": "acqpt_b6fca90846014bd9a78d3c1d94d76db4",
"createdAt": "2025-10-29T15:51:40.966Z",
"accountingDirection": "DEBIT",
"authorizedAmount": {
"value": 1000,
"currencyCode": "USD"
},
"authorizedRemainingAmount": {
"value": 500,
"currencyCode": "USD"
},
"settledAmount": null,
"disbursedAmount": null,
"canceledAmount": null,
"refundedAmount": null,
"responseCode": {
"authorizationCode": "G50650",
"processorResponseCode": "APPROVED",
"addressCode": "SKIPPED",
"postalCode": "SKIPPED",
"securityCode": "SKIPPED"
}
}
}
},
"extensions": {
"requestId": "a262d929-d475-982e-ad7f-041b934bd7d2",
"rateLimit": {
"cost": 18,
"limit": 2500,
"remaining": 2482,
"asOf": "2025-10-29T15:52:03.655Z",
"complexity": {
"limit": 2500,
"remaining": 2482,
"cost": 18
},
"count": {
"limit": 100,
"remaining": 99,
"cost": 1
}
}
}
}
Capture final amount
When you make a final capture, the Highnote platform schedules a reversal of any remaining authorized amount. For example, if $100 is authorized, and $80 is final captured, then $20 is reversed.
Use the following mutation and input variables to capture the final amount of an authorized payment transaction:
Capture Payment Transaction - Final
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_01", "amount": { "value": 1000, "currencyCode": "USD" }, "captureType": "FINAL_CAPTURE", "idempotencyKey": "UUID_v4" } }
Result
{
"data": {
"capturePaymentTransaction": {
"__typename": "CardCaptureStepSummary",
"createdAt": "2026-01-15T19:28:03.649Z",
"transaction": {
"__typename": "PaymentDebitTransactionSummary",
"id": "acqpt_01",
"createdAt": "2026-01-15T19:28:03.649Z",
"accountingDirection": "DEBIT",
"authorizedAmount": {
"value": 1000,
"currencyCode": "USD"
},
"authorizedRemainingAmount": {
"value": 0,
"currencyCode": "USD"
},
"settledAmount": null,
"disbursedAmount": null,
"canceledAmount": null,
"refundedAmount": null,
"responseCode": {
"processorResponseCode": "APPROVED",
"addressCode": "SKIPPED",
"postalCode": "SKIPPED",
"securityCode": "SKIPPED",
"authorizationCode": "QBTHBA"
}
}
}
},
"extensions": {
"requestId": "15b0c624-8b21-995c-a7f2-1c96299d6b67",
"rateLimit": {
"cost": 18,
"limit": 60060,
"remaining": 60018,
"asOf": "2026-01-15T19:28:18.168Z",
"complexity": {
"limit": 60060,
"remaining": 60018,
"cost": 18
},
"count": {
"limit": 60060,
"remaining": 60053,
"cost": 1
}
}
}
}
Force capture
Contact your Highnote representative to enable Force Capture in your product.
When an authorization is declined, and the cardholder has agreed to the terms, a merchant can, if necessary, submit the transaction by force. The API automatically captures the outstanding declined portion without requiring the user to explicitly specify a capture amount.
Chargeback protection is available when the merchant can provide evidence that the cardholder agreed to the capture of funds.
Use the following forceCapturePaymentTransaction mutation to perform a force capture.
See the docs on simulating declines.
Clearing may be delayed due to the network's review processes.
forceCapturePaymentTransaction
Query
mutation ForceCapturePaymentTransaction(
$input: ForceCapturePaymentTransactionInput!
) {
forceCapturePaymentTransaction(input: $input) {
__typename
... on CardCaptureStepSummary {
createdAt
transaction {
__typename
id
createdAt
accountingDirection
authorizedAmount {
value
currencyCode
}
authorizedRemainingAmount {
value
currencyCode
}
capturedAmount {
value
currencyCode
}
settledAmount {
value
currencyCode
}
disbursedAmount {
value
currencyCode
}
canceledAmount {
value
currencyCode
}
refundedAmount {
value
currencyCode
}
responseCode {
processorResponseCode
addressCode
postalCode
securityCode
}
}
}
... on UserError {
__typename
errors {
description
code
errorPath
}
}
}
}
Variables
{ "input": { "paymentTransactionId": "acqpt_bfb444603f1a4f7fbe65dcc3ccfb3550", "idempotencyKey": "UUID_v4" } }
Result
{
"data": {
"forceCapturePaymentTransaction": {
"__typename": "CardCaptureStepSummary",
"createdAt": "2026-01-27T18:25:26.897Z",
"transaction": {
"__typename": "PaymentDebitTransactionSummary",
"id": "acqpt_bfb444603f1a4f7fbe65dcc3ccfb3550",
"createdAt": "2026-01-27T18:25:26.897Z",
"accountingDirection": "DEBIT",
"authorizedAmount": {
"value": 0,
"currencyCode": "USD"
},
"authorizedRemainingAmount": {
"value": 0,
"currencyCode": "USD"
},
"capturedAmount": {
"value": 333,
"currencyCode": "USD"
},
"settledAmount": null,
"disbursedAmount": null,
"canceledAmount": null,
"refundedAmount": null,
"responseCode": {
"processorResponseCode": "APPROVED",
"addressCode": "SKIPPED",
"postalCode": "SKIPPED",
"securityCode": "SKIPPED"
}
}
}
}
}
Refund a payment
Refunds can only be issued against captured and disbursed transactions.
Refunds are issued after a payment has been captured and funds have been disbursed. Highnote supports full and partial refunds. Multiple partial refunds can be done if the total of the refunds does not exceed the captured amount.
Refund full amount
Use the following mutation to refund the full amount of a payment transaction:
Refund Payment Transaction - Full
Query
mutation RefundPaymentTransaction($input: RefundPaymentTransactionInput!) {
refundPaymentTransaction(input: $input) {
__typename
... on CardCreditStepSummary {
createdAt
transaction {
__typename
id
createdAt
accountingDirection
authorizedAmount {
value
currencyCode
}
authorizedRemainingAmount {
value
currencyCode
}
settledAmount {
value
currencyCode
}
disbursedAmount {
value
currencyCode
}
canceledAmount {
value
currencyCode
}
refundedAmount {
value
currencyCode
}
originatedPaymentTransactionId
}
}
}
}
Variables
{ "input": { "paymentTransactionId": "acqpt_01", "amount": { "value": 1000, "currencyCode": "USD" }, "idempotencyKey": "UUID_v4", "refundReason": "CUSTOMER_REQUESTED" } }
Result
{
"data": {
"refundPaymentTransaction": {
"__typename": "CardCreditStepSummary",
"createdAt": null,
"transaction": {
"__typename": "PaymentCreditTransactionSummary",
"id": "acqpt_02",
"createdAt": "2024-02-22T17:33:52.116Z",
"accountingDirection": "CREDIT",
"authorizedAmount": {
"value": 1000,
"currencyCode": "USD"
},
"authorizedRemainingAmount": {
"value": 0,
"currencyCode": "USD"
},
"settledAmount": null,
"disbursedAmount": null,
"canceledAmount": null,
"refundedAmount": {
"value": 1000,
"currencyCode": "USD"
},
"originatedPaymentTransactionId": "acqpt_01"
}
}
},
"extensions": {
"requestId": "REQUEST_ID",
"rateLimit": {
"cost": 17,
"limit": 60060,
"remaining": 60042
}
}
}
Refund partial amount
To refund a partial amount, ensure the amount value provided in the RefundPaymentTransaction mutation does not exceed the authorizedAmount.
Use the following mutation to refund a partial amount of a payment transaction. In the response payload, note the difference between the authorizedAmount and refundedAmount:
Refund Payment Transaction - Partial
Query
mutation RefundPaymentTransaction($input: RefundPaymentTransactionInput!) {
refundPaymentTransaction(input: $input) {
__typename
... on CardCreditStepSummary {
createdAt
transaction {
__typename
id
createdAt
accountingDirection
authorizedAmount {
value
currencyCode
}
authorizedRemainingAmount {
value
currencyCode
}
settledAmount {
value
currencyCode
}
disbursedAmount {
value
currencyCode
}
canceledAmount {
value
currencyCode
}
refundedAmount {
value
currencyCode
}
originatedPaymentTransactionId
}
}
}
}
Variables
{ "input": { "paymentTransactionId": "acqpt_01", "amount": { "value": 500, "currencyCode": "USD" }, "idempotencyKey": "UUID_v4", "refundReason": "CUSTOMER_REQUESTED" } }
Result
{
"data": {
"refundPaymentTransaction": {
"__typename": "CardCreditStepSummary",
"createdAt": null,
"transaction": {
"__typename": "PaymentCreditTransactionSummary",
"id": "acqpt_02",
"createdAt": "2024-02-22T17:33:52.116Z",
"accountingDirection": "CREDIT",
"authorizedAmount": {
"value": 1000,
"currencyCode": "USD"
},
"authorizedRemainingAmount": {
"value": 0,
"currencyCode": "USD"
},
"settledAmount": null,
"disbursedAmount": null,
"canceledAmount": null,
"refundedAmount": {
"value": 500,
"currencyCode": "USD"
},
"originatedPaymentTransactionId": "acqpt_01"
}
}
},
"extensions": {
"requestId": "REQUEST_ID",
"rateLimit": {
"cost": 17,
"limit": 60060,
"remaining": 60042
}
}
}
Find all payment transactions
Querying payment data can take 3-5 minutes to appear after a PaymentTransactionEvent is created, due to synchronization between databases.
Use the following query to create a list view of all payment transactions:
ListPaymentTransactions
Query
query ListPaymentTransactions($first: Int) {
paymentTransactions(first: $first) {
__typename
pageInfo {
hasNextPage
hasPreviousPage
startCursor
endCursor
}
edges {
cursor
node {
__typename
id
createdAt
updatedAt
steps {
__typename
createdAt
amount {
value
currencyCode
}
transaction {
id
accountingDirection
}
events {
__typename
createdAt
updatedAt
amount {
value
currencyCode
}
}
}
status
accountingDirection
authorizedAmount {
value
currencyCode
}
authorizedAmount {
value
currencyCode
}
settledAmount {
value
currencyCode
}
disbursedAmount {
value
currencyCode
}
canceledAmount {
value
currencyCode
}
refundedAmount {
value
currencyCode
}
responseCode {
authorizationCode
processorResponseCode
addressCode
postalCode
securityCode
}
totalFeeAmount {
value
currencyCode
}
totalPayableAmount {
value
currencyCode
}
fees {
__typename
feeAmount {
value
currencyCode
}
accountingDirection
}
instrument {
__typename
... on PaymentCardInstrument {
createdAt
last4
expiryYear
expiryMonth
brand
}
}
... on PaymentCreditTransaction {
originatedPaymentTransaction {
__typename
id
createdAt
updatedAt
}
}
... on PaymentDebitTransaction {
refunds {
__typename
id
createdAt
updatedAt
}
}
}
}
}
}
Variables
{
"first": 2
}
Result
{
"data": {
"paymentTransactions": {
"__typename": "PaymentTransactionsConnection",
"pageInfo": {
"hasNextPage": true,
"hasPreviousPage": false,
"startCursor": "dD0yMDI0LTAyLTIyVDE3JTNBMzMlM0E1Mi4xMTYwMDAwMDBaJmk9YWNxcHRfYjZiYWU3NjY4M2UyNDdlOGI0MWQ1ZmRiYmVjNjkwNDQ",
"endCursor": "dD0yMDI0LTAyLTIyVDE3JTNBMzIlM0ExMS4zNjEwMDAwMDBaJmk9YWNxcHRfYzY2ZjZlMDgxN2NjNDEzZmI0NTgxMjJhZTIwNTA4Y2Q"
},
"edges": [
{
"cursor": "dD0yMDI0LTAyLTIyVDE3JTNBMzMlM0E1Mi4xMTYwMDAwMDBaJmk9YWNxcHRfYjZiYWU3NjY4M2UyNDdlOGI0MWQ1ZmRiYmVjNjkwNDQ",
"node": {
"__typename": "PaymentCreditTransaction",
"id": "acqpt_01",
"createdAt": "2024-02-22T17:33:52.116Z",
"updatedAt": "2024-02-22T17:33:52.118Z",
"steps": [
{
"__typename": "CardCapturedStep",
"createdAt": "2024-02-22T17:33:52.177Z",
"amount": {
"value": 1000000000,
"currencyCode": "USD"
},
"transaction": {
"id": "acqpt_01",
"accountingDirection": "DEBIT"
},
"events": [
{
"__typename": "CardPaymentCapturingEvent",
"createdAt": "2024-02-22T17:33:52.178Z",
"updatedAt": "2024-02-22T17:33:52.178Z",
"amount": {
"value": 1000000000,
"currencyCode": "USD"
}
}
]
},
{
"__typename": "CardAuthorizedStep",
"createdAt": "2024-02-22T17:33:52.116Z",
"amount": {
"value": 1000000000,
"currencyCode": "USD"
},
"transaction": {
"id": "acqpt_01",
"accountingDirection": "DEBIT"
},
"events": [
{
"__typename": "CardPaymentAuthorizedEvent",
"createdAt": "2024-02-22T17:33:52.177Z",
"updatedAt": "2024-02-22T17:33:52.179Z",
"amount": {
"value": 1000000000,
"currencyCode": "USD"
}
}
]
}
],
"status": "PENDING",
"accountingDirection": "CREDIT",
"authorizedAmount": null,
"settledAmount": null,
"disbursedAmount": null,
"canceledAmount": null,
"refundedAmount": null,
"responseCode": {
"authorizationCode": "84QNMZ",
"processorResponseCode": "APPROVED",
"addressCode": "UNSPECIFIED",
"postalCode": "UNSPECIFIED",
"securityCode": "UNSPECIFIED"
},
"totalFeeAmount": {
"value": 0,
"currencyCode": "USD"
},
"totalPayableAmount": {
"value": 0,
"currencyCode": "USD"
},
"fees": null,
"instrument": {
"__typename": "PaymentCardInstrument",
"createdAt": "2024-02-22T17:33:52.116Z",
"last4": "",
"expiryYear": "31",
"expiryMonth": "12",
"brand": "VISA"
},
"originatedPaymentTransaction": {
"__typename": "PaymentDebitTransaction",
"id": "acqpt_01",
"createdAt": "2024-02-22T17:32:11.361Z",
"updatedAt": "2024-02-22T17:32:11.380Z"
}
}
},
{
"cursor": "dD0yMDI0LTAyLTIyVDE3JTNBMzIlM0ExMS4zNjEwMDAwMDBaJmk9YWNxcHRfYzY2ZjZlMDgxN2NjNDEzZmI0NTgxMjJhZTIwNTA4Y2Q",
"node": {
"__typename": "PaymentDebitTransaction",
"id": "acqpt_01",
"createdAt": "2024-02-22T17:32:11.361Z",
"updatedAt": "2024-02-22T17:32:11.380Z",
"steps": [
{
"__typename": "CardCapturedStep",
"createdAt": "2024-02-22T17:32:28.122Z",
"amount": {
"value": 1000000000,
"currencyCode": "USD"
},
"transaction": {
"id": "acqpt_01",
"accountingDirection": "DEBIT"
},
"events": [
{
"__typename": "CardPaymentCapturingEvent",
"createdAt": "2024-02-22T17:32:28.122Z",
"updatedAt": "2024-02-22T17:32:28.122Z",
"amount": {
"value": 1000000000,
"currencyCode": "USD"
}
}
]
},
{
"__typename": "CardAuthorizedStep",
"createdAt": "2024-02-22T17:32:11.361Z",
"amount": {
"value": 1000000000,
"currencyCode": "USD"
},
"transaction": {
"id": "acqpt_01",
"accountingDirection": "DEBIT"
},
"events": [
{
"__typename": "CardPaymentAuthorizedEvent",
"createdAt": "2024-02-22T17:32:11.380Z",
"updatedAt": "2024-02-22T17:32:11.380Z",
"amount": {
"value": 1000000000,
"currencyCode": "USD"
}
}
]
}
],
"status": "PENDING",
"accountingDirection": "DEBIT",
"authorizedAmount": null,
"settledAmount": null,
"disbursedAmount": null,
"canceledAmount": null,
"refundedAmount": null,
"responseCode": {
"authorizationCode": "O4KBDO",
"authorizationResponseCode": "APPROVED",
"addressCode": "UNSPECIFIED",
"postalCode": "UNSPECIFIED",
"securityCode": "UNSPECIFIED"
},
"totalFeeAmount": {
"value": 0,
"currencyCode": "USD"
},
"totalPayableAmount": {
"value": 0,
"currencyCode": "USD"
},
"fees": null,
"instrument": {
"__typename": "PaymentCardInstrument",
"createdAt": "2024-02-22T17:32:11.361Z",
"last4": "",
"expiryYear": "31",
"expiryMonth": "12",
"brand": "VISA"
},
"refunds": [
{
"__typename": "PaymentCreditTransaction",
"id": "acqpt_01",
"createdAt": "2024-02-22T17:33:52.116Z",
"updatedAt": "2024-02-22T17:33:52.118Z"
}
]
}
}
]
}
},
"extensions": {
"requestId": "REQUEST_ID",
"rateLimit": {
"cost": 38,
"limit": 60060,
"remaining": 59659
}
}
}
Find a payment transaction
Use the following query to find a single payment transaction:
PaymentTransaction
Query
fragment PaymentTransactionEvent on PaymentTransactionEvent {
__typename
createdAt
updatedAt
amount {
value
currencyCode
}
}
query PaymentTransaction($id: ID!) {
node(id: $id) {
__typename
... on PaymentTransaction {
id
createdAt
updatedAt
steps {
__typename
createdAt
amount {
value
currencyCode
}
events {
...PaymentTransactionEvent
}
transaction {
id
accountingDirection
}
}
status
events {
...PaymentTransactionEvent
}
accountingDirection
authorizedAmount {
value
currencyCode
}
authorizedAmount {
value
currencyCode
}
settledAmount {
value
currencyCode
}
disbursedAmount {
value
currencyCode
}
canceledAmount {
value
currencyCode
}
refundedAmount {
value
currencyCode
}
responseCode {
authorizationCode
processorResponseCode
addressCode
postalCode
securityCode
}
totalFeeAmount {
value
currencyCode
}
totalPayableAmount {
value
currencyCode
}
fees {
__typename
feeAmount {
value
currencyCode
}
accountingDirection
}
instrument {
__typename
... on PaymentCardInstrument {
createdAt
last4
expiryYear
expiryMonth
brand
}
}
... on PaymentCreditTransaction {
originatedPaymentTransaction {
__typename
id
createdAt
updatedAt
}
}
... on PaymentDebitTransaction {
refunds {
__typename
id
createdAt
updatedAt
}
}
}
}
}
Variables
{
"id": "acqpt_01"
}
Result
{
"data": {
"node": {
"__typename": "PaymentDebitTransaction",
"id": "acqpt_01",
"createdAt": "2024-02-17T06:26:54.892Z",
"updatedAt": "2024-02-17T06:26:56.174Z",
"steps": [
{
"__typename": "CardAuthorizedStep",
"createdAt": "2024-02-17T06:26:54.903Z",
"amount": {
"value": 1000000000,
"currencyCode": "USD"
},
"events": [
{
"__typename": "CardPaymentAuthorizedEvent",
"createdAt": "2024-02-17T06:26:55.962Z",
"updatedAt": "2024-02-17T06:26:55.962Z",
"amount": {
"value": 1000000000,
"currencyCode": "USD"
}
}
],
"transaction": {
"id": "acqpt_01",
"accountingDirection": "DEBIT"
}
}
],
"status": "PENDING",
"events": [
{
"__typename": "CardPaymentAuthorizedEvent",
"createdAt": "2024-02-17T06:26:55.962Z",
"updatedAt": "2024-02-17T06:26:55.962Z",
"amount": {
"value": 1000000000,
"currencyCode": "USD"
}
}
],
"accountingDirection": "DEBIT",
"authorizedAmount": null,
"settledAmount": null,
"disbursedAmount": null,
"canceledAmount": null,
"refundedAmount": null,
"responseCode": {
"authorizationCode": "FCV1U6",
"addressCode": "UNSPECIFIED",
"postalCode": "UNSPECIFIED",
"securityCode": "UNSPECIFIED"
},
"totalFeeAmount": null,
"totalPayableAmount": null,
"fees": null,
"instrument": {
"__typename": "PaymentCardInstrument",
"createdAt": "2024-02-17T06:26:54.880Z",
"last4": "",
"expiryYear": "31",
"expiryMonth": "12",
"brand": "VISA"
},
"refunds": null
}
},
"extensions": {
"requestId": "REQUEST_ID",
"rateLimit": {
"cost": 21,
"limit": 60060,
"remaining": 60039
}
}
}