API Reference

This reference covers the checkout API in Payment SDK 0.7.0. HighWire is the factory, hw is the initialized instance, and checkout is the object returned by hw.mount().

For installation, server binding, and a complete checkout, use the Integration guide, Plain HTML guide, or React / Next.js guide. The separate @highwirepayments/payment-sdk/collect entry, which returns the device-session key for Direct API charges, is covered in Device screening. Coming from 0.6.0? See Upgrading from 0.6.0.

Methods at a glance

Runtime exports

After loading the pinned CDN build, read the exports from window.HighWire. The global is a namespace, rather than the factory itself.

const HighWire = window.HighWire.default;
const { HighWireError, SDK_VERSION } = window.HighWire;

default and the namespace's named HighWire export refer to the same factory. SDK_VERSION is '0.7.0'. The npm package supplies the matching declarations; use type-only imports with the CDN runtime. Examples below assume this namespace has loaded and run in an async browser function or module.

HighWire.init

HighWire.init(config: HighWireConfig): Promise<HighWireInstance>

Initialize once per checkout page. The returned Promise resolves once the device session settles, or after at most 2 seconds while it keeps loading. A screening failure never rejects it.

Parameters

config is required. It accepts these HighWireConfig fields:

URLs are normalized to their origins. Use the matching key and gateway from onboarding. Register the checkout's origins; see Security & server verification.

Returns and errors

Returns a frozen HighWireInstance with readonly mount and chargeSavedMethod methods. It has no riskSessionKey() method; see Device screening. Invalid fields in a provided configuration object throw HighWireError with HW_UNSUPPORTED synchronously, before a Promise is returned. Omitting the required object or passing null instead causes a plain synchronous TypeError. Put the call itself inside try when handling errors.

hw.mount

hw.mount(options: MountOptions): Promise<Checkout>

Create or reuse the order's payment and draw the configured checkout at the payment step. One checkout may be mounted at a time per instance. The HighWire session chooses the layout; see Drop-in & wallets.

Parameters

options is required. Every MountOptions field is listed below:

See Callbacks for their complete payloads. Checkout idempotency keys are generated by the SDK; mount() accepts no shopper email, merchant key, merchant order ID, or individual payment-method selection. Pass the email to submit(). In plain JavaScript a customerEmail passed to mount() is ignored; TypeScript rejects it.

Returns and errors

Resolves with a Checkout once its parts are mounted. Form readiness and loading errors are reported separately through callbacks, so a resolved mount does not guarantee a usable card field.

Rejections include invalid options (HW_UNSUPPORTED), a refused payment (HW_DECLINED), authorization/transport failures, and attempts to mount while another payment is unresolved. The same rejection reaches onError when provided; show it once. See the error codes.

billingAddressForm: 'full' on any other checkout rejects HW_UNSUPPORTED after the payment is created; mount again with 'none' to reuse that payment.

Keep the container non-interactive until your backend has verified and bound the payment. On the same instance, an open payment is reused for the same amount, currency, and savePaymentMethodForFutureUse. The email plays no part, so two orders with the same amount reuse one payment, even after unmount(). For another order with the same options, use a fresh instance once your backend authorizes it. Another amount creates another payment; another save option creates one once the last payment can no longer capture. While an unresolved payment of a drop-in form that uses your Pay button may still capture, another amount or save option rejects HW_TOKENIZE_IN_PROGRESS. See normalization and remounting.

checkout.submit

checkout.submit(payer?: PayerDetails): Promise<PaymentResult>

Pay with the mounted card field, or with a drop-in form that uses your Pay button. Call only when requiresSubmit is true, the form can take a payment (onChange reports complete, or onAvailabilityChange reports true), and no operation is running. Wallets and drop-in forms with their own button use their own controls.

Parameters

payer carries the shopper's email, so it is required for a card payment. A drop-in form that uses your Pay button can omit it only after one of its attempts on this payment was declined, and only when it collects the billing address itself. Its PayerDetails fields are:

Every BillingAddress field is an optional string, omitted by default:

Email, phone, and billing strings are trimmed; blank values are omitted. Amount, currency, and the save option are fixed at mount, and the shopper's tick is read at submit; submit takes no card values or merchant idempotency key.

A card payment sends line1, city, state, and postalCode, and ignores name, country, and line2. A drop-in form that uses your Pay button sends every address field, uppercases country, and copies the details when called, so later changes to the object do not affect that attempt. It rejects a non-string field, a malformed email, or a country that is not two letters with recovery correct, before anything is sent. The SDK checks name and country; the form validates the rest of the address for the selected country and refuses one without a postal code.

Email on a drop-in form that uses your Pay button

HighWire screens and binds the email before the form's processor can charge the card:

• An omitted email falls back to the email of the payment's last declined attempt. Before any decline, submit() rejects HW_INCOMPLETE.
• A corrected email is screened again. One payment takes up to 3 different emails; past that, submit() rejects HW_INCOMPLETE with recovery correct, as it does for an email HighWire refuses. Submit again with the last email the payment accepted.
• A screening denial rejects HW_DECLINED with recovery recheck.
• A changed email or save box while the payment is live rejects HW_TOKENIZE_IN_PROGRESS with recovery recheck.

After either recheck rejection the payment is kept: a later submit() only reads it, and this checkout takes no other payment.

Returns and errors

Returns the same PaymentResult delivered to onResult. A decline resolves; operational failures reject. Handle the result once. Required 3-D Secure verification opens within this call; keep checkout mounted during it.

A drop-in form that uses your Pay button resolves succeeded, pending, or declined. A card decline resolves declined and calls onResult: with retryable: true the shopper can use another card and submit again; with retryable: false the checkout has ended. When the form refuses the payment details, billing address, or email, submit() rejects HW_INCOMPLETE with recovery correct, and the shopper can correct them and submit again. Its errors carry recovery.

const result = await checkout.submit({
  customerEmail: 'shopper@example.com',
  customerPhone: '+14155550123',
  billingAddress: {
    name: 'Alex Shopper',
    country: 'US',
    line1: '123 Example Street',
    line2: 'Suite 400',
    city: 'San Francisco',
    state: 'CA',
    postalCode: '94105',
  },
});

For a lost answer, retry the same checkout's submit to retain the attempt. A card retry resends the first attempt's email and billing details; edits the shopper made in between are not sent. On a drop-in form that uses your Pay button, a submit after an unknown outcome, a screening denial, or a refused email or save-box change only checks the original payment, for up to 3 minutes; it never sends it again. After unmount, a new submit only rejects, so keep a rejection handler even with onError. See Errors and retry guidance.

checkout.recheck

checkout.recheck(): Promise<PaymentResult>

Parameters: none. Read the payment of a drop-in form that uses your Pay button once more, after an error with recovery recheck or a pending result. It never creates a payment or submits again, and it works after unmount().

Resolves succeeded when the gateway reports the payment succeeded, which ends the checkout, and pending otherwise. A succeeded result carries customerId and paymentMethodId when the shopper saved the card. It does not call onResult: show its result yourself. A pending answer does not permit another payment; check the order on your server first.

Rejections also reach onError until unmount(), and after it only while a submit() is still running. Otherwise only the returned promise rejects, so keep a catch on it:

checkout.unmount

checkout.unmount(): void

Parameters: none. Returns: undefined (void). Remove the checkout's slots and processing state, and restore the container's previous layout attribute. Use during page/component cleanup.

Unmounting does not cancel a charge; an active payment may still call a callback. An unanswered card confirmation rejects HW_DESTROYED. A submission of a drop-in form that uses your Pay button whose outcome is unknown, or that was rejected with recovery recheck, survives unmount and blocks another order on the instance; follow cleanup and recovery. This method returns synchronously without a documented HighWireError rejection.

hw.chargeSavedMethod

hw.chargeSavedMethod(context: SavedMethodChargeContext): Promise<SavedMethodChargeResult>

Charge a card the shopper saved on an earlier checkout. No mounted form is required, and the call can be made after a page reload using the saved identifier and your stored charge key.

Parameters

context is required. Every SavedMethodChargeContext field is required and has no default:

This is the only checkout SDK method that accepts a merchant idempotency key. Reuse is subject to account limits.

Returns and errors

Returns SavedMethodChargeResult with these fields:

const addOn = await hw.chargeSavedMethod({
  paymentMethodId: 'SAVED_PAYMENT_METHOD_ID',
  amount: 500,
  idempotencyKey: 'STABLE_KEY_STORED_WITH_THIS_ADD_ON',
});

A card saved through a drop-in form that uses your Pay button is collected asynchronously: expect pending and settle it from your server. If its issuer asks for 3-D Secure again, the charge does not capture, because this call has no shopper verification step.

Verify every result on your backend. One saved-method call can run per instance; another rejects HW_TOKENIZE_IN_PROGRESS. Validation can reject HW_INCOMPLETE or HW_UNSUPPORTED; changing the amount under an existing key can also reject HW_UNSUPPORTED. Retain the original key for an unknown outcome. See saved-card errors and key recovery rules before starting a new charge.

Callbacks

All callbacks are optional properties of MountOptions; omitting one installs no handler. Their return values are ignored. Card values are never part of a callback payload.

Active payments may call callbacks after unmount. An unanswered card confirm reports HW_DESTROYED through onError and submit rejection. Show each error once.

CardState

PaymentMethod

'card' | 'applePay' | 'googlePay' | 'dropIn'

These are the values passed to onProcessing, and the container's data-hw-processing attribute while a payment is being confirmed. A drop-in form that uses your Pay button reports 'dropIn' when submit() sends a new submission, not when it only checks an earlier one.

PaymentResult

A reopened 3-D Secure challenge can omit paymentMethodId, customerId, and maskedCard. There is no decline-reason field.

Fulfillment requires server verification.

HighWireError

HighWireError extends Error and is exported by the CDN namespace. SDK failures expose:

The exported constructor is new HighWireError(code: HighWireErrorCode, message: string, recovery?: CheckoutRecovery). code and message are required and have no default. SDK failures already provide instances; integrations normally inspect rather than construct them.

try {
  await checkout.submit({ customerEmail: 'shopper@example.com' });
} catch (error) {
  if (error instanceof HighWireError) console.error(error.code, error.recovery);
}

CheckoutRecovery

'correct' | 'retry' | 'wait' | 'recheck' | 'unavailable'

Exported as a type. When an error carries recovery, act on it before its code:

A pending result or a recheck error does not permit another payment. Check the original payment on your server before starting another checkout, even if a later status read shows it declined or expired.

Error codes

The codes below cover the exported HighWireErrorCode union in 0.7.0. Recovery depends on which method failed; a transport error during mount is different from a lost submit answer. When an error carries recovery, follow it before the code.

Configuration and input

Transport and throttling

Form and operation state

Ended checkouts

Reconcile pending, abandoned, or unknown outcomes before remounting. Your backend authorizes another payment; SDK remount permission does not prove that the previous attempt failed.

Saved-card reuse

See the integration retry guide for payment recovery, and safe diagnostics for support.