Skip to content

Direct Payments ​

Take one-off payments and subscriptions. Portal.directPayments is a factory: call create(ref) to get a client for one Direct Payment, then build an invoice, mount the card form and confirm the payment.

Quick start ​

ts
const invoices = await window.Portal.directPayments.getInvoices();
console.log(invoices.length, 'invoices');

API reference ​

ConnectMount ​

A mounted Connect UI; call unmount() to remove it.

unmount() ​

Removes the component from the page.

ts
connectMount.unmount();

dp ​

A Direct Payments client bound to one Direct Payment (Portal.directPayments.create(ref)). It builds invoices, mounts the provider's payment form, confirms the payment, manages saved cards and subscriptions, and emits lifecycle events.

The flow is: browser builds an invoice from the catalogue → mounts the form → confirms. The server only verifies prices; every charge is an invoice of catalogue items.

addPaymentMethod() ​

Mounts a card-entry UI to add a new payment method. If no processor client is initialized, it will initialize one from session data or options.

Available options properties:

  • mountTarget: CSS selector or HTMLElement where the payment UI should mount.
  • processor_reference_num: Optional processor reference to initialize the processor client when no session processor is available.
  • customer_id: Optional customer identifier to associate the new payment method with a specific customer.
  • Additional provider-specific fields may also be supplied.
ts
const processorClientPaymentResult = await dp.addPaymentMethod(options);

Parameters

NameTypeRequiredDescription
optionsPortalAddPaymentMethodOptionsYesAvailable options properties: - mountTarget: CSS selector or HTMLElement where the payment UI should mount.

Returns

Resolves with a PortalProcessorClientPaymentResult: The outcome of a payment or card-setup call.

attachDynamicAmountListener() ​

Attaches live amount updates for wallet-enabled payment forms.

ts
dp.attachDynamicAmountListener(inputTarget, getItemRef);

Parameters

NameTypeRequiredDescription
inputTargetstring | HTMLInputElementYes—
getItemRef() => string | null | undefinedYes—

capabilities() ​

(point 5). What the Direct Payment's CURRENT provider can do. Cached until the processor changes.

ts
const directPaymentCapabilities = await dp.capabilities();

Returns

Resolves with a PortalDirectPaymentCapabilities: What the Direct Payment's current provider can do.

clearSelectedTier() ​

Clears the chosen tier and its interval, so nothing is selected (the free plan).

ts
dp.clearSelectedTier();

clearSession() ​

Clears all subscription-related session state used by the Direct Payments flow.

ts
dp.clearSession();

confirmCardSetup() ​

Confirms a card setup / vault flow after addPaymentMethod() has mounted the form.

ts
const result = await dp.confirmCardSetup(returnUrl);

Parameters

NameTypeRequiredDescription
returnUrlstringNoWhere the buyer is sent back to after the provider's own page.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
successbooleanYesTrue when the call worked.
errorstringNoThe reason, when it failed.

confirmPayment() ​

Confirms the mounted single-pay or subscription payment flow.

ts
const directPaymentsConfirmPaymentResult = await dp.confirmPayment(options);

Parameters

NameTypeRequiredDescription
optionsobjectYesAn invoice built in the browser: a basket of catalogue items that is locked and then paid.
options.emailstringYesThe payer's e-mail (receipt and customer record).
options.namestringNoCustomer's full name, saved to the provider customer alongside the email.
options.invoicePortalDirectPaymentInvoiceNoThe invoice being paid.
options.returnUrlstringNoWhere the buyer returns after 3-D Secure.
options.setup_future_usagebooleanNoKeep the card for later charges.
options.user_idstringNoAn id of your own for the payer.
options.metadataRecord<string, unknown>NoExtra data stored with the payment.

Returns

Resolves with a PortalDirectPaymentsConfirmPaymentResult: The answer of confirmPayment().

connect ​

Connected accounts, reached only through this instance — never a top-level window.Portal.connect. Lazily resolved from the already-known processor; see PortalDirectPaymentConnectAPI's own comment.

Type: PortalDirectPaymentConnectAPI (read-only)

ts
const connect = dp.connect;

createInvoice() ​

Creates a fresh, editable invoice instance for the current Direct Payment.

ts
const directPaymentInvoice = await dp.createInvoice();

Returns

Resolves with a PortalDirectPaymentInvoice: An invoice built in the browser: a basket of catalogue items that is locked and then paid.

deletePaymentMethod() ​

Deletes a saved payment method.

ts
const directPaymentMethodResult = await dp.deletePaymentMethod(methodId);

Parameters

NameTypeRequiredDescription
methodIdstringYesThe saved payment method's id.

Returns

Resolves with a PortalDirectPaymentMethodResult: The answer to deleting or defaulting a saved payment method.

destroyPayment() ​

Unmounts payment UI and destroys the underlying processor client.

ts
dp.destroyPayment();

estimateTax() ​

Estimate sales tax for the current provider based on country and state.

ts
const taxEstimateResult = await dp.estimateTax(countryCode, state);

Parameters

NameTypeRequiredDescription
countryCodestringYes—
statestringYesThe state or region.

Returns

Resolves with a PortalTaxEstimateResult: The answer of estimateTax().

experimental ​

Experimental

Not part of the documented contract. It may change or disappear.

Not part of the documented contract. The processor API's experimental billing controls, for an administrator: pause / resume, cancel on a date, trial, billing day, quantity, price phases, one-off charges and credits, invoices, cards, customer details, disputes. capabilities() returns every control with the payer's provider's answer (yes, partial, no) and whether that answer has been confirmed on a sandbox; preview() says what a control would do; run() does it (a dangerous one needs reason and idempotency_key).

Type: PortalDirectPaymentsExperimentalApi (read-only)

ts
const experimental = dp.experimental;

forgetPayer() ​

Forget the payer this browser was recognised as (the stored payer token). Call it before a checkout that creates a NEW account, so the account gets a payer of its own instead of the previous visitor's.

ts
dp.forgetPayer();

getAmountForCharge() ​

Resolves the final charge amount for an item in dollars.

  • FIXED items return item.price + item.tax.
  • DYNAMIC items validate and return the supplied amount.
ts
const count = dp.getAmountForCharge(itemRef, userAmount);

Parameters

NameTypeRequiredDescription
itemRefstringYes—
userAmountnumberNoThe amount the shopper chose.

Returns

Returns a number.

getDirectPayment() ​

Retrieves the current Direct Payment record. If id is omitted, returns the active initialized Direct Payment from session.

ts
const directPayment = await dp.getDirectPayment(id);

Parameters

NameTypeRequiredDescription
idstringNoIf id is omitted, returns the active initialized Direct Payment from session.

Returns

Resolves with a PortalDirectPayment: A Direct Payment: a payment configuration (a catalogue of items, or subscription tiers) bound to a payment provider.

getDirectPaymentFromSessionStorage() ​

The Direct Payment record loaded by the last initializeDirectPayment(), read back from session storage; null before one was loaded.

ts
const result = dp.getDirectPaymentFromSessionStorage();

Returns

Returns PortalDirectPayment \| null.

getDirectPaymentRef() ​

Returns the Direct Payment reference currently stored in session.

ts
const result = dp.getDirectPaymentRef();

Returns

Returns string \| null.

getItemBySku() ​

Returns a single item by SKU from the currently loaded Direct Payment.

ts
const result = dp.getItemBySku(sku);

Parameters

NameTypeRequiredDescription
skustringYesYour stock-keeping code.

Returns

Returns PortalDirectPaymentItem \| null.

getItems() ​

Returns the item definitions from the currently loaded Direct Payment.

ts
const directPaymentItems = dp.getItems();

Returns

Returns an array of PortalDirectPaymentItem.

getSavedPaymentMethods() ​

Returns vaulted payment methods for the current customer.

ts
const directPaymentsSavedMethods = await dp.getSavedPaymentMethods();

Returns

Resolves with an array of PortalDirectPaymentsSavedMethod.

getSelectedTier() ​

Returns display-ready data for the currently selected subscription tier.

ts
const directPaymentsSelectedTier = dp.getSelectedTier();

Returns

Returns a PortalDirectPaymentsSelectedTier: Display-ready data about the subscription tier currently selected (getSelectedTier()).

getSelectedTierPlan() ​

Reads the selected DP ID, the chosen tier's tier number, chosen interval (null = the tier's default price) and tier_id (null when no tier is chosen) from session storage.

ts
const result = dp.getSelectedTierPlan();

Returns

Returns an object with these fields:

NameTypeRequiredDescription
dpIdstring | nullYesThe Direct Payment's reference.
tiernumber | nullYesThe tier number.
intervalstring | nullYesThe billing interval, for example month or year.
tierIdnumber | nullYesThe tier's tier_id within the Direct Payment.

getStoredProcessorId() ​

Returns the processor reference number saved during payment setup, or null.

ts
const result = dp.getStoredProcessorId();

Returns

Returns string \| null.

getStoredSubscriptionId() ​

Returns the provider subscription ID captured when the subscription was created during payment setup, or null.

Provider confirm calls do not echo the subscription ID back, and Stripe does not append it to the 3DS return URL — read it from here at registration time.

ts
const result = dp.getStoredSubscriptionId();

Returns

Returns string \| null.

getSubscriptionTierAmountCents() ​

Returns the price in cents for a tier at the given sorted index. Returns 0 when the index is out of range.

ts
const count = await dp.getSubscriptionTierAmountCents(dpId, tierIndex);

Parameters

NameTypeRequiredDescription
dpIdstringYesThe Direct Payment's reference.
tierIndexnumberYesThe 0-based index of the tier, cheapest first.

Returns

Resolves with a number.

getSubscriptionTierPriceIndex() ​

Returns the 0-based sorted tier index for the given amount in cents. Returns -1 when no matching tier is found.

ts
const count = await dp.getSubscriptionTierPriceIndex(amountCents);

Parameters

NameTypeRequiredDescription
amountCentsnumberYesAn amount in cents.

Returns

Resolves with a number.

getTier() ​

Returns the configured tier record for the given tier_id from the active DP.

ts
const result = dp.getTier(tierId);

Parameters

NameTypeRequiredDescription
tierIdnumberYesThe tier's tier_id within the Direct Payment.

Returns

Returns PortalDirectPaymentTier \| null.

getTierById() ​

The tier with this tier_id within the Direct Payment. Null for an unknown id. Needs the Direct Payment loaded.

ts
const result = dp.getTierById(tierId);

Parameters

NameTypeRequiredDescription
tierIdnumberYesThe tier's tier_id within the Direct Payment.

Returns

Returns PortalDirectPaymentTier \| null.

getTierByRef() ​

The tier with this reference_num, whatever its tier number (two tiers may share a tier number). Null for an unknown reference. Needs the Direct Payment loaded.

ts
const result = dp.getTierByRef(reference);

Parameters

NameTypeRequiredDescription
referencestringYesA reference.

Returns

Returns any \| null.

getTierPrices() ​

Every price a tier is sold at, default first; empty for an unknown tier_id. Needs the Direct Payment loaded.

ts
const directPaymentTierPrices = dp.getTierPrices(tierId);

Parameters

NameTypeRequiredDescription
tierIdnumberYesThe tier's tier_id within the Direct Payment.

Returns

Returns an array of PortalDirectPaymentTierPrice.

getTierPricesById() ​

Every price the tier with this tier_id is sold at, default first; empty for an unknown id. Needs the Direct Payment loaded.

ts
const directPaymentTierPrices = dp.getTierPricesById(tierId);

Parameters

NameTypeRequiredDescription
tierIdnumberYesThe tier's tier_id within the Direct Payment.

Returns

Returns an array of PortalDirectPaymentTierPrice.

getTierPricesByRef() ​

Every price the tier with this reference is sold at, default first; empty for an unknown reference. Needs the Direct Payment loaded.

ts
const directPaymentTierPrices = dp.getTierPricesByRef(reference);

Parameters

NameTypeRequiredDescription
referencestringYesA reference.

Returns

Returns an array of PortalDirectPaymentTierPrice.

initializeDirectPayment() ​

Fetches the Direct Payment configuration and initializes the active DP session. Call before any methods that depend on the current Direct Payment context.

ts
await dp.initializeDirectPayment(id, options);

Parameters

NameTypeRequiredDescription
idstringNoThe record's id.
optionsobjectNoOptional settings.
options.waitForProcessorConfigbooleanNo—

Returns

Resolves when the call has completed.

isConnect() ​

Returns true when the active Direct Payment uses the CONNECT pay type — dynamic line items, funds split across connected accounts.

ts
const ok = dp.isConnect();

Returns

Returns a boolean.

isItemDynamic() ​

Returns true when the specified item is configured as DYNAMIC-priced. Use this to decide whether to show a custom amount input on the page.

ts
const ok = dp.isItemDynamic(item);

Parameters

NameTypeRequiredDescription
itemPortalDirectPaymentItem | stringYesOne item in a SINGLE_PAY Direct Payment's catalogue — something that can be put on an invoice.

Returns

Returns a boolean.

isSinglePay() ​

Returns true when the active Direct Payment uses a single-pay checkout flow.

ts
const ok = dp.isSinglePay();

Returns

Returns a boolean.

isSubscription() ​

Returns true when the active Direct Payment uses a subscription checkout flow.

ts
const ok = dp.isSubscription();

Returns

Returns a boolean.

listPaymentMethods() ​

The payer's saved cards, but a failure rejects instead of returning an empty list.

ts
const directPaymentsSavedMethods = await dp.listPaymentMethods();

Returns

Resolves with an array of PortalDirectPaymentsSavedMethod.

loadPreparedInvoice() ​

The CONNECT counterpart to createInvoice(): loads an already-locked invoice from data a trusted server (market's own backend) already computed and persisted via saveInvoice()'s endpoint — never built through addItem()'s static-catalog validation, which a CONNECT Direct Payment has no catalog for by design.

ts
const directPaymentInvoice = await dp.loadPreparedInvoice(data);

Parameters

NameTypeRequiredDescription
dataobjectYesThe data.
data.reference_numstringYesThe record's reference number.
data.itemsobject[]Yes—
data.items[].item_refstringYesThe Direct Payments item reference.
data.items[].namestringYesThe name.
data.items[].pricenumberYes—
data.items[].taxnumberNo—
data.items[].quantitynumberYesHow many.
data.items[].skustringNoYour stock-keeping code.
data.items[].seller_refstringNo—

Returns

Resolves with a PortalDirectPaymentInvoice: An invoice built in the browser: a basket of catalogue items that is locked and then paid.

notifications ​

Read-only — no save()/create() here. Configuration of notifications is an operator act performed against the authenticated admin API, never the public SDK.

Type: PortalDirectPaymentNotificationsAPI (read-only)

ts
const notifications = dp.notifications;

off() ​

Unsubscribe a specific handler (or every handler for the event, if omitted).

ts
dp.off(event, handler);

Parameters

NameTypeRequiredDescription
eventEYesThe event to listen for.
handler(e: PortalDirectPaymentClientEventPayloads[E]) => voidNoWhat each client event hands to its listener (dp.on(event, handler)).

on() ​

Subscribe to a client-side lifecycle event. Returns an unsubscribe function. A throwing listener never breaks the payment flow — each runs in its own try/catch. Listeners registered here persist across destroyPayment().

ts
const result = dp.on(event, handler);

Parameters

NameTypeRequiredDescription
eventEYesThe event to listen for.
handler(e: PortalDirectPaymentClientEventPayloads[E]) => voidYesWhat each client event hands to its listener (dp.on(event, handler)).

Returns

Returns () => void.

Examples

ts
const dp = window.Portal.directPayments.create('DP_REF');
const stop = dp.on('payment:succeeded', (result) => {
  window.location.href = result.url || '/thanks';
});
// later: stop();

onProcessorChanged() ​

Called when the owner switched processor while this page was open: the payment form was mounted again for the new provider (in the same place). Same as on('processor:changed', handler). Returns an unsubscribe function.

ts
const result = dp.onProcessorChanged(handler);

Parameters

NameTypeRequiredDescription
handler(e: object) => voidYesFunction called when it happens.

Returns

Returns () => void.

purchases() ​

Every paid invoice of the signed-in payer on this Direct Payment, newest first.

ts
const directPaymentPurchases = await dp.purchases(options);

Parameters

NameTypeRequiredDescription
optionsobjectNoOptional settings.
options.limitnumberNoThe most items to return.

Returns

Resolves with an array of PortalDirectPaymentPurchase.

resolveDiscount() ​

Resolve a discount code against the active provider.

ts
const discountResolveResult = await dp.resolveDiscount(discountCode);

Parameters

NameTypeRequiredDescription
discountCodestringYes—

Returns

Resolves with a PortalDiscountResolveResult: The answer of resolveDiscount(): whether a code is valid and what it gives.

savedPaymentMethods() ​

The installed resolver's saved payment methods for this Direct Payment, or [] with none installed. Never throws.

ts
const directPaymentsSavedMethods = await dp.savedPaymentMethods();

Returns

Resolves with an array of PortalDirectPaymentsSavedMethod.

saveInvoice() ​

Persists an invoice in the backend as pending before payment authorization.

ts
const directPaymentSavedInvoice = await dp.saveInvoice(invoice, customerEmail, userId);

Parameters

NameTypeRequiredDescription
invoicePortalDirectPaymentInvoiceYesAn invoice built in the browser: a basket of catalogue items that is locked and then paid.
customerEmailstringYes—
userIdstringNoAn id of your own for the user.

Returns

Resolves with a PortalDirectPaymentSavedInvoice: What the server answers when an invoice is saved: its reference and status, and the payer token to keep for this browser.

setDefaultPaymentMethod() ​

Sets a saved payment method as the default.

ts
const directPaymentMethodResult = await dp.setDefaultPaymentMethod(methodId);

Parameters

NameTypeRequiredDescription
methodIdstringYesThe saved payment method's id.

Returns

Resolves with a PortalDirectPaymentMethodResult: The answer to deleting or defaulting a saved payment method.

setSelectedTier() ​

Selects one specific tier by its tier_id, and optionally which of its prices (year…). Needs the Direct Payment loaded; an unknown tier_id throws.

ts
dp.setSelectedTier(tierId, interval);

Parameters

NameTypeRequiredDescription
tierIdnumberYesThe tier's tier_id within the Direct Payment.
intervalstring | nullNoThe billing interval, for example month or year.

setSelectedTierPlan() ​

Stores the selected tier by its tier_id, and optionally which of its prices (year…); without one it is the tier's default price. Same as setSelectedTier.

ts
dp.setSelectedTierPlan(tierId, interval);

Parameters

NameTypeRequiredDescription
tierIdnumberYesThe tier's tier_id within the Direct Payment.
intervalstring | nullNoThe billing interval, for example month or year.

setUITierPrice() ​

Formats a tier price string and writes it into the page. Useful for rendering plan cards after subscription setup.

ts
dp.setUITierPrice(tierId, selector, options);

Parameters

NameTypeRequiredDescription
tierIdnumberYesThe tier's tier_id within the Direct Payment.
selectorstringYesA CSS selector.
optionsPortalDirectPaymentsSetUITierPriceOptionsYesFormatting options of setUITierPrice().

Examples

ts
const dp = window.Portal.directPayments.create('DP_REF');
await dp.initializeDirectPayment();
dp.setUITierPrice(2, '#gold-price', { currency_symbol: '$', billing_period: true });

setupSinglePayPayment() ​

Mounts the payment form for a single-pay charge. Must be called after getDirectPayment(). Pass a locked invoice; finish with confirmPayment().

ts
await dp.setupSinglePayPayment(options);

Parameters

NameTypeRequiredDescription
optionsobjectYesAn invoice built in the browser: a basket of catalogue items that is locked and then paid.
options.invoicePortalDirectPaymentInvoiceYesThe locked invoice to pay.
options.currencystringNoISO currency code (default 'usd').
options.descriptionstringNoDescription shown on the provider's dashboard.
options.mountTargetstringNoCSS selector of the element to mount the card form in.
options.onSuccess() => voidYesCalled once the form is ready.
options.onError(err: unknown) => voidYesCalled when the form could not be mounted.

Returns

Resolves when the call has completed.

setupSubscription() ​

Loads subscription pricing and stores the DP payload in session state.

ts
await dp.setupSubscription(options);

Parameters

NameTypeRequiredDescription
optionsPortalDirectPaymentsSetupSubscriptionOptionsYesCallbacks of setupSubscription().

Returns

Resolves when the call has completed.

setupSubscriptionPayment() ​

Initializes the subscription payment widget or hosted flow.

ts
await dp.setupSubscriptionPayment(options);

Parameters

NameTypeRequiredDescription
optionsPortalDirectPaymentsSetupPaymentOptionsYesOptions of setupSubscriptionPayment(): mounts the subscription payment form.

Returns

Resolves when the call has completed.

setupTiers() ​

Binds tier selector buttons using the provided configuration array. Call this inside the onSuccess callback of setupSubscription().

ts
dp.setupTiers(result, tiers);

Parameters

NameTypeRequiredDescription
resultPortalDirectPaymentYesA Direct Payment: a payment configuration (a catalogue of items, or subscription tiers) bound to a payment provider.
tiersPortalDirectPaymentsSetupTierConfig[]YesOne tier-selector button for setupTiers().

subscription ​

The signed-in payer's own subscription: read, cancel, resume, change plan.

Type: PortalDirectPaymentSubscriptionAPI (read-only)

ts
const subscription = dp.subscription;

updateInvoiceStatus() ​

Updates the stored status of a pending invoice.

ts
const result = await dp.updateInvoiceStatus(referenceNum, status);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe record's reference number.
statusstringYesThe status word.

Returns

Resolves with the server's record as a plain object.

updatePaymentAmount() ​

Updates the rendered payment amount for a hosted single-pay card form.

ts
const ok = await dp.updatePaymentAmount(amount);

Parameters

NameTypeRequiredDescription
amountnumberYesAn amount in currency units.

Returns

Resolves with a boolean.

useCustomerResolver() ​

Install (or clear, with null) the payer resolver for this Direct Payment instance — the "third door" for a page with no façade module in front of it (a bare payment block). Only meaningful for a signed-in host page; a guest checkout installs none.: the resolver is used for savedPaymentMethods(); the payer itself is resolved by the server from the signed-in identity or the payer token, and user_id is no longer stamped.

ts
dp.useCustomerResolver(resolver);

Parameters

NameTypeRequiredDescription
resolverPortalDirectPaymentsPayerResolver | nullYesThe Direct Payments SDK remains a standalone product that does not import Site Users — it accepts this small interface, and Portal.siteUsers.create(module).paymentsResolver() is simply the one implementation that ships in this estate.

Examples

With Site Users

ts
const dp = window.Portal.directPayments.create('DP_REF');
const su = window.Portal.siteUsers.create('SITE_USERS_MODULE_REF');
dp.useCustomerResolver(su.paymentsResolver());

dp.connect ​

dp.connect — connected accounts (marketplace sellers) of a CONNECT Direct Payment. Reached only through a Direct Payments instance, never a top-level Portal.connect.

closeAccount() ​

Closes an account.

ts
const result = await dp.connect.closeAccount(accountRef);

Parameters

NameTypeRequiredDescription
accountRefstringYesThe connected account's reference.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
successbooleanYesTrue when the call worked.

createAccount() ​

Creates a connected account (prefer setupAccount(), which is idempotent).

ts
const connectedAccount = await dp.connect.createAccount(opts);

Parameters

NameTypeRequiredDescription
optsConnectCreateAccountOptionsYesOptions of connect.createAccount() / setupAccount().

Returns

Resolves with a ConnectedAccount: A connected account (one seller / end user who can be paid).

getAccount() ​

Reads one account.

ts
const connectedAccount = await dp.connect.getAccount(accountRef);

Parameters

NameTypeRequiredDescription
accountRefstringYesThe connected account's reference.

Returns

Resolves with a ConnectedAccount: A connected account (one seller / end user who can be paid).

getAccountForUser() ​

The end user's account for this Direct Payment, addressed by the calling application's own id for them; null when there is none yet.

ts
const result = await dp.connect.getAccountForUser(connectUser);

Parameters

NameTypeRequiredDescription
connectUserstringYes—

Returns

Resolves with ConnectedAccount \| null.

getBalance() ​

The account's balance.

ts
const connectBalance = await dp.connect.getBalance(accountRef);

Parameters

NameTypeRequiredDescription
accountRefstringYesThe connected account's reference.

Returns

Resolves with a ConnectBalance: A connected account's balance, per currency.

getCapabilityCatalog() ​

The capabilities an account can have in a country.

ts
const capabilityDescriptors = await dp.connect.getCapabilityCatalog(country);

Parameters

NameTypeRequiredDescription
countrystringYesAn ISO country code.

Returns

Resolves with an array of CapabilityDescriptor.

getProfile() ​

The public Connect settings.

ts
const publicConnectProfile = await dp.connect.getProfile();

Returns

Resolves with a PublicConnectProfile: The public (non-secret) Connect settings of a Direct Payment, from connect.getProfile().

getRequirements() ​

What the account still has to provide.

ts
const connectRequirements = await dp.connect.getRequirements(accountRef);

Parameters

NameTypeRequiredDescription
accountRefstringYesThe connected account's reference.

Returns

Resolves with an array of ConnectRequirement.

getStatus() ​

Reads one account with its outstanding requirements.

ts
const connectAccountStatus = await dp.connect.getStatus(accountRef);

Parameters

NameTypeRequiredDescription
accountRefstringYesThe connected account's reference.

Returns

Resolves with a ConnectAccountStatus: A connected account together with what it still owes.

isSupported() ​

True when the current provider supports Connect at all.

ts
const ok = dp.connect.isSupported();

Returns

Returns a boolean.

listAccounts() ​

Lists the accounts of this Direct Payment.

ts
const connectedAccounts = await dp.connect.listAccounts();

Returns

Resolves with an array of ConnectedAccount.

listPayouts() ​

The account's recent payouts.

ts
const connectPayouts = await dp.connect.listPayouts(accountRef, params);

Parameters

NameTypeRequiredDescription
accountRefstringYesThe connected account's reference.
paramsobjectNoExtra options.
params.limitnumberNoThe most items to return.

Returns

Resolves with an array of ConnectPayout.

mountComponent() ​

Draws one Connect component (payouts, balances...) for an account.

ts
const connectMount = await dp.connect.mountComponent(accountRef, component, target);

Parameters

NameTypeRequiredDescription
accountRefstringYesThe connected account's reference.
componentConnectComponentNameYesAn embeddable Connect UI component, mounted with connect.mountComponent().
targetstring | HTMLElementYesA CSS selector or element.

Returns

Resolves with a ConnectMount: A mounted Connect UI; call unmount() to remove it.

mountOnboarding() ​

Draws an embedded onboarding handle into target.

ts
const connectMount = await dp.connect.mountOnboarding(handle, target);

Parameters

NameTypeRequiredDescription
handleOnboardingHandleYesOne branch per .mode; changing the profile's onboarding_mode changes behaviour with no caller code change.
targetstring | HTMLElementYesDraws an embedded onboarding handle into target.

Returns

Resolves with a ConnectMount: A mounted Connect UI; call unmount() to remove it.

requestPayout() ​

Requests a payout of amountMinor (smallest currency unit).

ts
const connectPayout = await dp.connect.requestPayout(accountRef, amountMinor);

Parameters

NameTypeRequiredDescription
accountRefstringYesThe connected account's reference.
amountMinornumberYesRequests a payout of amountMinor (smallest currency unit).

Returns

Resolves with a ConnectPayout: A payout from a connected account to its bank.

setupAccount() ​

The end user's entry point: creates the account, or returns the existing one (idempotent on connect_user). Follow with startOnboarding(account.reference_num).

ts
const result = await dp.connect.setupAccount(opts);

Parameters

NameTypeRequiredDescription
optsConnectCreateAccountOptions & { connect_user: string }YesOptions of connect.createAccount() / setupAccount().

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
accountConnectedAccountYes—
createdbooleanYes—

startOnboarding() ​

Begins onboarding; branch on handle.mode.

ts
const onboardingHandle = await dp.connect.startOnboarding(accountRef, opts);

Parameters

NameTypeRequiredDescription
accountRefstringYesThe connected account's reference.
optsStartOnboardingOptionsNoOptions of connect.startOnboarding().

Returns

Resolves with a OnboardingHandle: One branch per .mode; changing the profile's onboarding_mode changes behaviour with no caller code change.

submitRequirements() ​

Sends requested details (API onboarding mode).

ts
const connectAccountStatus = await dp.connect.submitRequirements(accountRef, payload);

Parameters

NameTypeRequiredDescription
accountRefstringYesThe connected account's reference.
payloadRecord<string, unknown>YesThe data to send.

Returns

Resolves with a ConnectAccountStatus: A connected account together with what it still owes.

support() ​

Like isSupported() but with the provider's name and the reason when unsupported.

ts
const connectSupport = dp.connect.support();

Returns

Returns a ConnectSupport: Whether the Direct Payment's provider supports Connect (connect.support()).

uploadDocument() ​

Uploads an identity or business document; resolves with the file id to reference in submitRequirements().

ts
const result = await dp.connect.uploadDocument(accountRef, purpose, file);

Parameters

NameTypeRequiredDescription
accountRefstringYesThe connected account's reference.
purposestringYesWhat the sign-in is for.
fileFileYesThe file.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
file_idstringYes—

validateProfile() ​

Pure — rules, no data.

ts
const connectProfileValidation = dp.connect.validateProfile(p);

Parameters

NameTypeRequiredDescription
pConnectProfileInputYesA Connect profile to check with connect.validateProfile() (no network call).

Returns

Returns a ConnectProfileValidation: The result of validateProfile().

dp.experimental ​

Experimental

Not part of the documented contract. It may change or disappear.

See PortalDirectPaymentsAPI.experimental.

capabilities() ​

Lists every control with the provider's support level. Pass fresh to bypass the cache.

ts
const result = await dp.experimental.capabilities(target, fresh);

Parameters

NameTypeRequiredDescription
targetPortalDirectPaymentsExperimentalTargetYesWhat an experimental control acts on: the provider's subscription id, or the processor for disputes.
freshbooleanNoPass fresh to bypass the cache.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
providerstringYesThe provider's name.
controlsPortalDirectPaymentsExperimentalControl[]Yes—

inspect() ​

Reads a provider object (customer, subscription, invoice, payment, dispute, plan) by id.

ts
const result = await dp.experimental.inspect(object, id, target);

Parameters

NameTypeRequiredDescription
objectstringYesOne of customer, subscription, invoice, payment, dispute, plan.
idstringYesThe record's id.
targetPortalDirectPaymentsExperimentalTargetYesWhat an experimental control acts on: the provider's subscription id, or the processor for disputes.

Returns

Resolves with unknown.

preview() ​

Says what a control would do, without doing it.

ts
const result = await dp.experimental.preview(key, target, params);

Parameters

NameTypeRequiredDescription
keystringYesThe key.
targetPortalDirectPaymentsExperimentalTargetYesWhat an experimental control acts on: the provider's subscription id, or the processor for disputes.
paramsRecord<string, unknown>NoExtra options.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
previewtrueYes—
actionstringYesThe action.
dangerousbooleanYes—
textstringYesThe text.
levelstringYes—
notestring | nullYes—
confirmedbooleanYes—

run() ​

Runs a control.

ts
const result = await dp.experimental.run(key, target, params);

Parameters

NameTypeRequiredDescription
keystringYesThe key.
targetPortalDirectPaymentsExperimentalTargetYesWhat an experimental control acts on: the provider's subscription id, or the processor for disputes.
paramsRecord<string, unknown>NoExtra options.

Returns

Resolves with the server's record as a plain object.

dp.notifications ​

dp.notifications — read-only view of which e-mail notifications the owner enabled.

get() ​

One notification setting by event key, or null.

ts
const result = await dp.notifications.get(event);

Parameters

NameTypeRequiredDescription
eventstringYesThe event to listen for.

Returns

Resolves with PortalDirectPaymentNotificationRow \| null.

list() ​

Every notification setting.

ts
const directPaymentNotificationRows = await dp.notifications.list();

Returns

Resolves with an array of PortalDirectPaymentNotificationRow.

dp.subscription ​

dp.subscription — what a signed-in subscriber can do with their own subscription. Every action returns the refreshed, normalised subscription, never a bare acknowledgement. ()

cancel() ​

Without an argument (or when: 'now'): immediate at the provider; when access ends is the Direct Payment's own cancellation_access_ends policy.when: 'period_end' stops renewal and keeps access to the end of the paid period.

ts
const directPaymentSubscriptionState = await dp.subscription.cancel(options);

Parameters

NameTypeRequiredDescription
optionsobjectNoOptional settings.
options.when'now' | 'period_end'No—

Returns

Resolves with a PortalDirectPaymentSubscriptionState: The signed-in payer's own subscription, as dp.subscription.get() returns it.

get() ​

Reads the payer's current subscription.

ts
const directPaymentSubscriptionState = await dp.subscription.get();

Returns

Resolves with a PortalDirectPaymentSubscriptionState: The signed-in payer's own subscription, as dp.subscription.get() returns it.

history() ​

The payer-scoped read of the same charge/refund tables the admin Money ledger reads — no charge id, no refund reason, no operator attribution ('s own "much smaller projection").

ts
const moneyHistoryRows = await dp.subscription.history();

Returns

Resolves with an array of PortalMoneyHistoryRow.

previewChange() ​

What changing plan would cost and when it takes effect. Read-only.

ts
const subscriptionChangePreview = await dp.subscription.previewChange(options);

Parameters

NameTypeRequiredDescription
optionsobjectYesOptional settings.
options.tier_idnumberYesThe tier's tier_id within the Direct Payment.
options.intervalstringNoThe billing interval, for example month or year.

Returns

Resolves with a PortalSubscriptionChangePreview: The answer of dp.subscription.previewChange().

reauthorise() ​

Mounts the NEW provider's payment-details form for a subscriber the owner has moved, on the developer's own page (the hosted renewal page needs no code). token is renewal_token from get().

ts
const directPaymentReauthoriseSession = await dp.subscription.reauthorise(token, options);

Parameters

NameTypeRequiredDescription
tokenstringYestoken is renewal_token from get().
optionsobjectYesOptional settings.
options.mountTargetstring | HTMLElementYesA CSS selector or element to mount into.

Returns

Resolves with a PortalDirectPaymentReauthoriseSession: A payment-details form mounted by dp.subscription.reauthorise().

resume() ​

Takes back a cancel that has not landed yet; nothing is charged. Rejects with DP_E_NOT_RESUMABLE once the subscription has ended.

ts
const directPaymentSubscriptionState = await dp.subscription.resume();

Returns

Resolves with a PortalDirectPaymentSubscriptionState: The signed-in payer's own subscription, as dp.subscription.get() returns it.

setPaymentMethod() ​

Makes a saved card the one the subscription is charged to. — rejects with DP_E_PM_CHANGE_NOT_SUPPORTED on PayPal (the funding instrument is changed by the payer, at PayPal, never here) and with DP_E_PAYMENT_METHOD_NOT_CARD for a non-card method_id on Stripe/Square.

ts
const result = await dp.subscription.setPaymentMethod(options);

Parameters

NameTypeRequiredDescription
optionsobjectYesOptional settings.
options.method_idstringYesThe saved payment method's id.

Returns

Resolves with PortalDirectPaymentSubscriptionState \| object.

update() ​

Moves the subscription to another tier (and optionally another price interval). tier_id is the tier's own id in this Direct Payment (), never a provider price/plan id. proration is Stripe's own vocabulary; ignored by providers with no such concept.

ts
const directPaymentSubscriptionState = await dp.subscription.update(options);

Parameters

NameTypeRequiredDescription
optionsobjectYesOptional settings.
options.tier_idnumberYesThe tier's tier_id within the Direct Payment.
options.intervalstringNoMove to this one of the tier's prices (year…); none keeps the interval the payer is on.
options.proration'create_prorations' | 'none' | 'always_invoice'No—
options.when'now' | 'period_end'Nonow takes a downgrade at once instead of at the end of the paid period.

Returns

Resolves with a PortalDirectPaymentSubscriptionState: The signed-in payer's own subscription, as dp.subscription.get() returns it.

invoice ​

An invoice built in the browser: a basket of catalogue items that is locked and then paid. Every charge — a one-off payment or a subscription — is an invoice. Create one with directPayments.createInvoice(). The server re-checks prices; the browser only describes the basket.

addItem() ​

Adds a line item to the invoice.

  • Tier items derive their price from the Direct Payment configuration.
  • DYNAMIC items require amount and validate against min/max amounts.
ts
invoice.addItem(options);

Parameters

NameTypeRequiredDescription
optionsobjectYesOptional settings.
options.item_refstringYesThe Direct Payments item reference.
options.quantitynumberYesHow many.
options.amountnumber | undefinedNoAn amount in currency units.
options.namestringNoThe name.
options.seller_refstringNo—
options.intervalstringNoThe billing interval, for example month or year.

clear() ​

Clears all line items from the invoice.

ts
invoice.clear();

getDirectPaymentRef() ​

Returns the Direct Payment reference associated with the invoice.

ts
const value = invoice.getDirectPaymentRef();

Returns

Returns a string.

getEventIdentifier() ​

Returns the optional event identifier used for webhook/provider correlation.

ts
const result = invoice.getEventIdentifier();

Returns

Returns string \| null.

getItem() ​

Gets a single invoice item by reference number.

ts
const result = invoice.getItem(item_ref);

Parameters

NameTypeRequiredDescription
item_refstringYesThe Direct Payments item reference.

Returns

Returns PortalDirectPaymentInvoiceItem \| undefined.

getItems() ​

Returns the current line items on the invoice.

ts
const directPaymentInvoiceItems = invoice.getItems();

Returns

Returns an array of PortalDirectPaymentInvoiceItem.

getReferenceNum() ​

Returns the generated invoice reference number.

ts
const value = invoice.getReferenceNum();

Returns

Returns a string.

getSellerRefs() ​

Distinct seller_ref values on this invoice, in first-seen order.

ts
const result = invoice.getSellerRefs();

Returns

Returns string[].

getSplitItems() ​

Builds the split_items sent to setupSinglePayPayment()'s intent request; see SplitCalculator::buildSplit().

ts
const result = invoice.getSplitItems();

Returns

Returns a list of objects with these fields:

NameTypeRequiredDescription
seller_reference_numstringYesThe seller's reference.
order_item_reference_numstringYesThe order item's reference.
line_netnumberYesThe line's net amount.

getSubtotal() ​

Returns the invoice subtotal before tax.

ts
const count = invoice.getSubtotal();

Returns

Returns a number.

getTaxTotal() ​

Returns the invoice tax total.

ts
const count = invoice.getTaxTotal();

Returns

Returns a number.

getTotal() ​

Returns the invoice total including tax.

ts
const count = invoice.getTotal();

Returns

Returns a number.

hasItem() ​

Returns true if the invoice already contains the given item reference.

ts
const ok = invoice.hasItem(item_ref);

Parameters

NameTypeRequiredDescription
item_refstringYesThe Direct Payments item reference.

Returns

Returns a boolean.

hasSplit() ​

True when any item carries a seller_ref.

ts
const ok = invoice.hasSplit();

Returns

Returns a boolean.

isLocked() ​

Returns true when the invoice has been locked and can no longer be modified.

ts
const ok = invoice.isLocked();

Returns

Returns a boolean.

lock() ​

Locks the invoice and generates its reference_num.

ts
invoice.lock();

removeItem() ​

Removes an item from the invoice.

ts
invoice.removeItem(item_ref);

Parameters

NameTypeRequiredDescription
item_refstringYesThe Direct Payments item reference.

setEventIdentifier() ​

Stores an optional event identifier such as a payment intent or subscription ID.

ts
invoice.setEventIdentifier(identifier);

Parameters

NameTypeRequiredDescription
identifierstringYes—

unlock() ​

Unlocks the invoice so it can be modified again.

ts
invoice.unlock();

updateItem() ​

Updates quantity or amount for an existing invoice item.

ts
invoice.updateItem(item_ref, options);

Parameters

NameTypeRequiredDescription
item_refstringYesThe Direct Payments item reference.
optionsobjectYesOptional settings.
options.quantitynumberNoHow many.
options.amountnumber | undefinedNoAn amount in currency units.

PortalDirectPaymentReauthoriseSession ​

A payment-details form mounted by dp.subscription.reauthorise().

destroy() ​

Removes the form.

ts
directPaymentReauthoriseSession.destroy();

provider ​

The provider the form belongs to.

Type: string

ts
const provider = directPaymentReauthoriseSession.provider;

submit() ​

Sends the entered details; resolves with the outcome and the date of the next charge.

ts
const result = await directPaymentReauthoriseSession.submit();

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
successbooleanYesTrue when the call worked.
errorstringNoThe reason, when it failed.
next_charge_atstringNo—

PortalDirectPaymentsPayerResolver ​

The Direct Payments SDK remains a standalone product that does not import Site Users — it accepts this small interface, and Portal.siteUsers.create(module).paymentsResolver() is simply the one implementation that ships in this estate. A host page wiring its own account system implements the same two methods and gets the same behaviour.

paymentMethods() ​

Saved methods for this payer on the DP's ACTIVE binding. Never lists a retired binding's cards.

ts
const directPaymentsSavedMethods = await directPaymentsPayerResolver.paymentMethods(dpRef);

Parameters

NameTypeRequiredDescription
dpRefstringYesThe Direct Payment's reference.

Returns

Resolves with an array of PortalDirectPaymentsSavedMethod.

resolve() ​

The payer this checkout is for, or null to let DP create an anonymous one.

ts
const result = await directPaymentsPayerResolver.resolve(dpRef);

Parameters

NameTypeRequiredDescription
dpRefstringYesThe Direct Payment's reference.

Returns

Resolves with an object with these fields:

NameTypeRequiredDescription
payer_reference_numstringYes—

window.Portal.directPayments ​

The public factory object exposed on window.Portal.directPayments.

Use create(directPaymentId) to obtain a Direct Payments client instance scoped to a specific Direct Payment and reuse it throughout the page.

create() ​

Creates a reusable Direct Payments client instance for the given DP ID.

ts
const directPaymentsAPI = window.Portal.directPayments.create(directPaymentId);

Parameters

NameTypeRequiredDescription
directPaymentIdstringYes—

Returns

Returns a PortalDirectPaymentsAPI: A Direct Payments client bound to one Direct Payment (Portal.directPayments.create(ref)).

findActiveSubscriptionMatch() ​

Finds the first invoice that matches an active subscription plan.

ts
const result = window.Portal.directPayments.findActiveSubscriptionMatch(invoices, subscriptions);

Parameters

NameTypeRequiredDescription
invoicesPortalDirectPaymentInvoiceListRow[]YesOne invoice row of Portal.directPayments.getInvoices(userId).
subscriptionsobject[]YesA list of objects, described below.
subscriptions[].idstringNoThe record's id.
subscriptions[].providerPlanIdstringNoThe provider's id for the plan.
subscriptions[].[key: string]unknownNoFurther fields the server may add.

Returns

Returns an object with these fields:

NameTypeRequiredDescription
matchedPlanobjectYes—
matchedPlan.idstringNoThe record's id.
matchedPlan.providerPlanIdstringNoThe provider's id for the plan.
matchedPlan.[key: string]unknownNoFurther fields the server may add.
invoicePortalDirectPaymentInvoiceListRowYes—

getInvoice() ​

Retrieve one invoice by its reference — status, amount_cents, currency, charge_id, refunded_cents, items_data. The read a selling façade's order view uses to resolve payment facts it does not store itself.

ts
const directPaymentInvoiceRecord = await window.Portal.directPayments.getInvoice(referenceNum);

Parameters

NameTypeRequiredDescription
referenceNumstringYesThe record's reference number.

Returns

Resolves with a PortalDirectPaymentInvoiceRecord: One invoice as Portal.directPayments.getInvoice() returns it.

getInvoices() ​

Retrieve invoices for a user without creating a Direct Payments instance.

ts
const directPaymentInvoiceListRows = await window.Portal.directPayments.getInvoices(userId);

Parameters

NameTypeRequiredDescription
userIdstring | nullNoAn id of your own for the user.

Returns

Resolves with an array of PortalDirectPaymentInvoiceListRow.

setAuthTokenProvider() ​

For a page on a different origin from the server: a function returning the signed-in caller's bearer token, sent on every Direct Payments request as Authorization: Bearer …. Pass null to clear it.

ts
window.Portal.directPayments.setAuthTokenProvider(provider);

Parameters

NameTypeRequiredDescription
provider(() => string | null) | nullYesThe provider's name.

version ​

The contract version of this build (1.1.0 = the Direct Payments contract of 08). Sent to the server as X-DP-SDK.

Type: string (read-only)

ts
const version = window.Portal.directPayments.version;

Types ​

CapabilityDescriptor ​

One capability a connected account can have in a country (from getCapabilityCatalog()).

NameTypeRequiredDescription
idstringYesCapability id.
labelstringYesDisplay name.
configuration'merchant' | 'recipient' | 'customer'YesWhich kind of account configuration the capability belongs to.

ConnectAccountStatus ​

A connected account together with what it still owes.

Extends ConnectedAccount.

NameTypeRequiredDescription
requirementsConnectRequirement[]YesOutstanding requirements; empty when the account is complete.

ConnectBalance ​

A connected account's balance, per currency. Amounts are in the smallest unit.

NameTypeRequiredDescription
availableobject[]YesMoney that can be paid out now.
available[].amountnumberYesAn amount in currency units.
available[].currencystringYes—
pendingobject[]YesMoney not yet available.
pending[].amountnumberYesAn amount in currency units.
pending[].currencystringYes—

ConnectComponentName ​

An embeddable Connect UI component, mounted with connect.mountComponent().

One of:

  • account_onboarding
  • account_management
  • notification_banner
  • payouts
  • balances
  • documents
  • payment_disputes

ConnectCreateAccountOptions ​

Options of connect.createAccount() / setupAccount().

NameTypeRequiredDescription
connect_userstringNoYour own id for the end user the account belongs to (makes setupAccount() idempotent).
countrystringNoISO country code.
entity_typestringNoindividual or company.
emailstringNoThe holder's e-mail.
display_namestringNoName shown to buyers.

ConnectedAccount ​

A connected account (one seller / end user who can be paid).

NameTypeRequiredDescription
reference_numstringYesThe account's reference; pass it to every other Connect call.
statusstringYesThe account's status, for example 'pending' or 'active'.
countrystringYesISO country code.
emailstring | nullYesThe account holder's e-mail.
charges_enabledbooleanYesTrue when the account may accept payments.
payouts_enabledbooleanYesTrue when the account may receive payouts.
details_submittedbooleanYesTrue once the holder finished onboarding.
disabled_reasonstring | nullYesWhy the account is restricted, when it is.
default_currencystring | nullYesThe account's currency.

ConnectIntegrationMode ​

Who runs the account's dashboard and how much the platform handles itself.

One of:

  • self_hosted
  • express
  • full_dashboard

ConnectOnboardingMode ​

How a user completes onboarding: a component embedded in your page, a provider-hosted page, or your own forms via the API.

One of:

  • embedded
  • hosted
  • api

ConnectPayout ​

A payout from a connected account to its bank.

NameTypeRequiredDescription
idstringYesPayout id.
amountnumberYesAmount in the smallest unit.
currencystringYesISO currency code.
statusstringYespending, paid, failed...
arrival_datenumber | nullYesUnix timestamp (seconds) it is expected to arrive.

ConnectProfileInput ​

A Connect profile to check with connect.validateProfile() (no network call).

NameTypeRequiredDescription
integration_modeConnectIntegrationModeYesHow connected accounts are managed.
onboarding_modeConnectOnboardingModeYesHow onboarding is performed.
responsibilitiesobjectYesWho bears processing fees and losses: the platform (application) or the provider.
responsibilities.fees_collector'application' | 'stripe'Yes—
responsibilities.losses_collector'application' | 'stripe'Yes—
platform_fee_percentnumberYesThe share of each sale the platform keeps, in percent.
account_configurationsstring[]YesThe capability sets requested for new accounts (for example merchant).
charge_model'auto' | 'destination' | 'separate_transfers'NoHow a multi-seller sale is moved: let the platform decide (auto), one destination, or separate transfers.

ConnectProfileValidation ​

The result of validateProfile().

NameTypeRequiredDescription
validbooleanYesTrue when the profile has no errors.
errorsConnectProfileValidationError[]YesEvery problem found.

ConnectProfileValidationError ​

One problem found by validateProfile().

NameTypeRequiredDescription
fieldstringYesThe profile field at fault.
codestringYesA stable machine code.
messagestringYesA human-readable explanation.

ConnectRequirement ​

One thing a connected account still has to provide.

NameTypeRequiredDescription
requirementstringYesThe missing item, for example 'individual.id_number'.
due_bynumber | nullYesUnix timestamp (seconds) it is due by, or null.

ConnectSupport ​

Whether the Direct Payment's provider supports Connect (connect.support()).

NameTypeRequiredDescription
supportedbooleanYesTrue when Connect works with the current provider.
providerstringYesThe provider's name.
reasonstringNoWhy it is not supported, when it is not.

OnboardingHandle ​

One branch per .mode; changing the profile's onboarding_mode changes behaviour with no caller code change.

One of:

  • an object with mode: 'embedded', client_secret: string, components: string[]
  • an object with mode: 'hosted', url: string, expires_at: number \| null
  • an object with mode: 'api', requirements: ConnectRequirement[], liveness_fallback?: OnboardingHandle

PortalAddPaymentMethodOptions ​

Options for directPayments.addPaymentMethod().

Use processor_reference_num to supply the processor from the DP record when no subscription-setup flow has previously run on the page.

NameTypeRequiredDescription
mountTargetstring | HTMLElementYesCSS selector or HTMLElement to mount the provider card form into.
processor_reference_numstringNoProcessor reference number used to lazy-initialize the ProcessorClient. Pass PortalDirectPayment.processor_reference_num here when calling from a single-pay (charge) page that has never invoked setupSubscriptionPayment. Not required if a prior subscription setup or charge flow already stored the processor reference in session storage.
[key: string]unknownNoFurther fields the server may add.

PortalConfirmPaymentOptions ​

Options for directPayments.confirmPayment()

NameTypeRequiredDescription
emailstringYesCustomer email address used to update the anonymous provider customer after charge.
returnUrlstringNoReturn URL for 3DS redirect (Stripe). Defaults to the current page URL with ?charge=success appended.
user_idstringNoAn id of your own for the payer.
metadataRecord<string, unknown>NoExtra key/value data stored with the payment.

PortalDirectPayment ​

A Direct Payment: a payment configuration (a catalogue of items, or subscription tiers) bound to a payment provider.

NameTypeRequiredDescription
reference_numstringYesThe Direct Payment's reference.
namestringYesDisplay name.
pay_type'SINGLE_PAY' | 'SUBSCRIPTION'YesSINGLE_PAY = one-off charges of catalogue items; SUBSCRIPTION = recurring tiers.
processor_reference_numstringNoThe processor reference number linked to this Direct Payment. Present on the record returned by getDirectPayment(). Pass this to addPaymentMethod({ processor_reference_num }) when calling the card-vault flow from a single-pay context (where no subscription setup flow has run and no processor_reference_num exists in session storage).
itemsPortalDirectPaymentItem[]NoThe item catalogue (SINGLE_PAY).
tiersPortalDirectPaymentTier[]NoThe subscription tiers (SUBSCRIPTION).

PortalDirectPaymentCapabilities ​

What the Direct Payment's current provider can do. Ask; do not hardcode.

NameTypeRequiredDescription
providerstringYesThe provider's name.
subscriptionCardChangebooleanYesFalse on PayPal: subscribers change their card at PayPal.
planChangebooleanYesTrue when a subscriber can move to another tier.
savedCardsbooleanYesTrue when the provider can keep cards for later use.
trialbooleanYesTrue when free trials are supported.
deferredStartbooleanYesTrue when a subscription can start on a future date.
walletsstringYesWhich wallet buttons (Apple Pay, Google Pay...) the provider offers.
intervalsstring[]YesThe billing intervals the provider supports.
planChangeChargesNowbooleanNoTrue where the capability exists in some form on this provider (native or built by the platform).
planChangeAtPeriodEndbooleanNoA plan change can be set to happen at the end of the paid period.
intervalSwitch'now' | 'next_cycle' | 'approval' | falseNoHow the provider moves a subscription to another interval of its tier: now, next_cycle, approval (the payer approves at the provider first), or false.
cancelAtPeriodEndbooleanNoA cancel can keep access until the end of the paid period.
resumebooleanNoA pending cancel can be taken back.
ts
const dp = window.Portal.directPayments.create('DP_REF');
const caps = await dp.capabilities();
if (!caps.subscriptionCardChange) {
  const button = document.getElementById('change-card');
  if (button !== null) {
    button.hidden = true;
  }
}

PortalDirectPaymentClientEvent ​

Client-side lifecycle events, subscribed to with dp.on(event, handler). Local emissions only — no transport, no relationship to the server-side email events beyond sharing a name.

One of:

  • subscription:created
  • subscription:failed
  • subscription:canceled
  • subscription:cancel_failed
  • subscription:updated
  • subscription:update_failed
  • subscription:resumed
  • subscription:resume_failed
  • payment:succeeded
  • payment:failed
  • paymentmethod:added
  • paymentmethod:removed
  • paymentmethod:changed
  • processor:changed
  • paymentmethod:change_failed

PortalDirectPaymentClientEventPayloads ​

What each client event hands to its listener (dp.on(event, handler)). Events with no fixed shape carry the server's record.

NameTypeRequiredDescription
subscription:createdPortalProcessorClientSubscriptionResultYesA subscription was started.
subscription:failedPortalProcessorClientSubscriptionResultYesStarting a subscription failed.
subscription:canceledRecord<string, unknown>YesThe subscription was cancelled.
subscription:cancel_failedRecord<string, unknown>YesCancelling failed.
subscription:updatedRecord<string, unknown>YesThe plan was changed.
subscription:update_failedRecord<string, unknown>YesChanging the plan failed.
subscription:resumedRecord<string, unknown>YesA pending cancel was taken back.
subscription:resume_failedRecord<string, unknown>YesResuming failed.
payment:succeededPortalDirectPaymentsConfirmPaymentResultYesA payment was confirmed.
payment:failedPortalDirectPaymentsConfirmPaymentResultYesA payment failed.
paymentmethod:addedRecord<string, unknown>YesA card was saved.
paymentmethod:removedRecord<string, unknown>YesA card was deleted.
paymentmethod:changedRecord<string, unknown>YesThe default card changed.
paymentmethod:change_failedRecord<string, unknown>YesChanging the card failed.
processor:changedobjectYesThe owner switched payment provider; the form was mounted again.
processor:changed.providerstringYesThe provider's name.
processor:changed.reference_numstringYesThe record's reference number.
processor:changed.binding_versionnumberYes—

PortalDirectPaymentInvoiceItem ​

One line of an invoice (see PortalDirectPaymentInvoice).

NameTypeRequiredDescription
item_refstringYesThe catalogue item or tier reference.
namestringYesDisplay name.
pricenumberYesUnit price in currency units.
taxnumberYesTax per unit in currency units.
quantitynumberYesNumber of units.
skustringNoYour stock-keeping code.
seller_refstring | undefinedNoOptional per-line seller attribution; drives hasSplit()/getSplitItems().

PortalDirectPaymentInvoiceListRow ​

One invoice row of Portal.directPayments.getInvoices(userId).

NameTypeRequiredDescription
idnumberNoDatabase id.
reference_numstringYesThe invoice's reference.
statusstringYesPayment status.
total_amountnumber | stringNoTotal amount (number or decimal string).
created_atstringYesISO creation timestamp.
parsed_dataRecord<string, unknown>NoThe invoice's items, already parsed (item_names, items, payment_method_label,...), when the server could parse them.
items_datastring | Array<Record<string, unknown>>NoThe raw items, as JSON text or already an array.
[key: string]unknownNoFurther fields the server may add.

PortalDirectPaymentInvoiceRecord ​

One invoice as Portal.directPayments.getInvoice() returns it.

NameTypeRequiredDescription
reference_numstringYesThe invoice's reference.
direct_payment_reference_numstringYesThe Direct Payment it belongs to.
processor_reference_numstring | nullYesThe processor that took (or will take) the payment.
statusstringYesPayment status.
amount_centsnumberYesAmount in cents.
currencystringYesISO currency code.
charge_idstring | nullYesThe provider's charge id, once paid.
refunded_centsnumberYesCents given back so far.
items_datastring | Array<Record<string, unknown>>YesThe invoice's items, as JSON text or already an array.
charged_atstring | nullYesISO date it was charged.

PortalDirectPaymentItem ​

One item in a SINGLE_PAY Direct Payment's catalogue — something that can be put on an invoice.

NameTypeRequiredDescription
reference_numstringYesThe item's reference; use it as item_ref on an invoice.
namestringNoInternal name.
titlestringNoDisplay title.
descriptionstringNoLonger description.
skustringNoYour stock-keeping code.
pricenumber | stringYesThe server sends decimals as strings ("64.00"); read them with Number(). attachPricing() does that for you.
taxnumber | stringNoTax per unit, in currency units (same decimal rules as price).
price_type'FIXED' | 'DYNAMIC'NoPricing model for this item. - 'FIXED' – price is predetermined; the charge amount is resolved server-side. - 'DYNAMIC' – no predetermined price; the caller must pass amount when adding the item to an invoice.
min_amountnumber | string | nullNoOptional minimum allowed amount for DYNAMIC items (a number or a decimal string).
max_amountnumber | string | nullNoOptional maximum allowed amount for DYNAMIC items (a number or a decimal string).
ts
const dp = window.Portal.directPayments.create('DP_REF');
await dp.initializeDirectPayment();
const item = dp.getItems().find((i) => i.sku === 'TSHIRT');
if (item) {
  console.log(Number(item.price) + Number(item.tax || 0));
}

PortalDirectPaymentMethodResult ​

The answer to deleting or defaulting a saved payment method.

NameTypeRequiredDescription
successbooleanNoTrue when the change was made.
messagestringNoA message to show.
[key: string]unknownNoFurther fields the server may add.

PortalDirectPaymentNotificationRow ​

One notification setting of a Direct Payment, read-only on the public SDK — see DirectPaymentNotificationController::publicList() for exactly what fields are (and are never) exposed.

NameTypeRequiredDescription
eventstringYesThe event key, for example 'payment.failed'.
days_beforenumber[] | nullYesFor scheduled events: days before the date a reminder goes out.
activebooleanYesWhether the owner has this notification switched on.

PortalDirectPaymentPurchase ​

One paid invoice of the payer, as dp.purchases() returns it.

NameTypeRequiredDescription
invoice_reference_numstringYesThe invoice's reference.
direct_payment_reference_numstringYesThe Direct Payment it was paid on.
charged_atstring | nullYesISO date it was charged.
amount_centsnumberYesAmount charged in cents.
currencystring | nullYesISO currency code.
statusstringYesPayment status.
providerstringYesThe provider that took the payment.
processor_reference_numstringYesThe processor's reference.
processor_namestring | nullYesThe processor's display name.
receipt_urlstring | nullYesThe provider's hosted receipt, when it has one.
card_brandstring | nullYesThe card brand, for example 'visa'.
card_last4string | nullYesThe last four digits of the card.
refunded_centsnumberYesWhat was given back on this invoice, in cents.
titlestring | nullYesThe name of the first item on the invoice (a plan or a one-off item), when it has one.

PortalDirectPaymentSavedInvoice ​

What the server answers when an invoice is saved: its reference and status, and the payer token to keep for this browser.

NameTypeRequiredDescription
reference_numstringYesThe saved invoice's reference.
statusstringNoThe invoice's status (pending until paid).
payer_tokenstringNoThe token that recognises this browser as the payer on later calls; the SDK stores it for you.
[key: string]unknownNoFurther fields the server may add.

PortalDirectPaymentsConfirmPaymentResult ​

The answer of confirmPayment().

NameTypeRequiredDescription
successbooleanYesTrue when the payment was confirmed.
urlstringNoWhere the buyer must be sent next (3-D Secure or a provider-hosted page), when the flow redirects.
errorstringNoThe failure reason shown to the buyer.
processor_resultRecord<string, unknown>NoThe raw Stripe PaymentIntent (id, application_fee_amount, transfer_group) when the invoice carried a split.

PortalDirectPaymentsExperimentalControl ​

Experimental

Not part of the documented contract. It may change or disappear.

One experimental billing control as the server describes it (GET processors/capabilities).

NameTypeRequiredDescription
keystringYesThe control's key; pass it to preview() / run().
areastringYesThe area it belongs to (billing, invoices, cards...).
scope'subscription' | 'processor'YesWhether it acts on a subscription or on the processor.
labelstringYesDisplay name.
pathstringYesThe server path it calls.
method'GET' | 'POST'YesThe HTTP method it uses.
dangerousbooleanYesTrue when it changes money or data and so needs reason and idempotency_key.
fieldsstring[]YesThe parameters it accepts.
level'yes' | 'partial' | 'no'YesWhether the provider supports it fully, partly or not.
notestring | nullYesAn explanation of the support level.
confirmedbooleanYesTrue when the answer was checked on a sandbox.

PortalDirectPaymentsExperimentalTarget ​

Experimental

Not part of the documented contract. It may change or disappear.

What an experimental control acts on: the provider's subscription id, or the processor for disputes.

NameTypeRequiredDescription
subscription_idstringNoThe provider's subscription id.
processor_reference_numstringNoThe processor's reference (for processor-scope controls such as disputes).

PortalDirectPaymentsSavedMethod ​

A saved payment method (a vaulted card or wallet) of a payer.

NameTypeRequiredDescription
idstringYesThe method's id; pass it to deletePaymentMethod() / setDefaultPaymentMethod().
providerstringYesThe provider the method is stored at.
cardNumberstringNoThe masked card number, for example '•••• 4242'.
expiryDatestringNoThe expiry, for example '12/29'.
cardTypestringNoThe card brand.
cardholderNamestringNoThe cardholder's name.
billingZipstringNoThe billing postcode.
processor_reference_numstringNoWhich processor this card belongs to.
is_defaultbooleanNoAn internal pointer this app tracks for all three providers uniformly (none of their own "default" concepts, where one exists at all, is what this app's own subscription billing reads).

PortalDirectPaymentsSelectedTier ​

Display-ready data about the subscription tier currently selected (getSelectedTier()).

NameTypeRequiredDescription
tiernumber | nullYesThe selected tier number, or null when none is selected.
isFreebooleanYesTrue when nothing paid is selected (the free plan).
tierNamestringYesThe tier's display name.
priceStrstringYesThe price as text, for example '$9.00'.
intervalstringYesThe billing interval.
amountCentsnumberYesThe price in cents.

PortalDirectPaymentsSetUITierPriceOptions ​

Formatting options of setUITierPrice().

NameTypeRequiredDescription
formatstringNoPrice formatting string, e.g. '00.00'.
currency_symbolstringNoCurrency symbol to display, e.g. '$'.
billing_periodbooleanNoAppend the billing period, such as /month.
intervalstringNoShow the tier's price for this interval (month, year…) instead of its default one. One of week, month, quarter, year.

PortalDirectPaymentsSetupPaymentOptions ​

Options of setupSubscriptionPayment(): mounts the subscription payment form.

NameTypeRequiredDescription
onSuccess() => voidYesCalled once the payment UI is ready.
onError(err: unknown) => voidYesCalled if payment initialization fails.
mountTargetstringNoCSS selector or HTMLElement where the payment widget should mount.
invoicePortalDirectPaymentInvoiceNoOptional locked invoice representing the selected subscription tier.
user_idstringNoOptional user identifier used for provider/customer tracking.
emailstringNoThe customer's real email, when the page already knows it at setup time. Leave unset on flows that collect the email after payment — the subscription is then created against the pre-created customer ID alone rather than a placeholder.
discount_codestringNoA discount code the customer entered (check it first with resolveDiscount()). The server refuses the subscription with DISCOUNT_E_INVALID if it is not honoured. The subscription is created when the form mounts, so a code entered later means mounting again with a new invoice and the code.

PortalDirectPaymentsSetupSinglePayOptions ​

Options for directPayments.setupSinglePayPayment()

NameTypeRequiredDescription
currencystringNoCurrency code. Defaults to 'usd'. The DP reference and processor ID are resolved automatically from session storage (populated when getDirectPayment() was last called) — no IDs need to be passed by the caller.
descriptionstringNoDescription shown on the payment intent / provider dashboard.
mountTargetstringNoCSS selector or HTMLElement to mount the card form into. Defaults to '#inline-card-mount'.
onSuccess() => voidYesCalled once the card form has been successfully mounted and is ready for input.
onError(err: unknown) => voidYesCalled if the card form fails to mount (non-fatal — hosted/PayPal still work).
user_idstringNoOptional user identifier for provider/customer tracking.

PortalDirectPaymentsSetupSubscriptionOptions ​

Callbacks of setupSubscription().

NameTypeRequiredDescription
onSuccess(result: PortalDirectPayment) => voidYesCalled once the subscription flow has loaded the Direct Payment record.
onError(err: unknown) => voidYesCalled when the subscription flow fails to initialize.

PortalDirectPaymentsSetupTierConfig ​

One tier-selector button for setupTiers().

NameTypeRequiredDescription
buttonstringYesID of the button that should trigger this tier selection.
tierIdnumberYesThe tier_id to select when the button is clicked.
cb() => voidYesCallback executed when the button is clicked.

PortalDirectPaymentSubscriptionState ​

The signed-in payer's own subscription, as dp.subscription.get() returns it. Identity is resolved server-side; nothing the browser sends chooses whose subscription is read.

NameTypeRequiredDescription
statusstringYesThe provider-normalised status word (older pages read this).
referencestringNoThe subscription CONTRACT. reference never changes, even when the owner moves the subscription to another provider; contract_status is ours and includes migrating. status stays the provider-normalised word older pages read.
tier_reference_numstring | nullNoThe tier the subscription is on.
contract_statusstringNoThe platform's own lifecycle status. One of incomplete, active, past_due, migrating, ending, ended.
priceobjectNoWhat the subscriber pays per period.
price.amount_centsnumberYes—
price.currencystring | nullYes—
price.intervalstring | nullYesThe billing interval, for example month or year.
price.interval_countnumberYes—
next_leg_providerstringNoThe provider that will take the next charge (differs from provider while a move is under way).
action_required'payment_details'NoSet while the owner has moved to another provider and this subscriber must enter payment details there.
renewal_tokenstringNoWith action_required: the token for reauthorise().
next_charge_atstring | nullYesISO date of the next charge, or null.
next_charge_amount_centsnumber | nullYesThe next charge in cents, or null.
currencystring | nullYesISO currency code.
cancel_at_period_endbooleanYesTrue when the subscription will stop at the end of the paid period.
trial_ends_atstring | nullYesISO date a free trial ends, or null.
plan_namestring | nullYesThe plan's display name.
providerstringYesThe provider the subscription runs on.
canceled_atstring | nullYesISO date the subscription was cancelled through this application, else null.
access_ends_atstring | nullYesISO date access ends after a cancel, else null.
billing_state'current' | 'past_due' | 'downgraded'NoPresent only when the resolved caller is the payer themselves.
downgrade_afterstringNoISO date after which an unpaid subscription is downgraded.
days_until_downgradenumberNoDays left until that downgrade.
scheduled_changeobjectNoA plan change or a cancellation waiting for the end of the paid period (null when none). For cancel, at is when access ends.
scheduled_change.action'tier' | 'cancel'YesThe action.
scheduled_change.tier_reference_numstring | nullYes—
scheduled_change.atstring | nullYesISO time it takes effect.
cancellation_access_ends'immediately' | 'period_end' | stringNoThe Direct Payment's own rule for when access ends after a cancel, so a client can say it before the payer chooses.
ts
const dp = window.Portal.directPayments.create('DP_REF');
const sub = await dp.subscription.get();
if (sub.cancel_at_period_end) {
  console.log('Ends', sub.access_ends_at);
} else {
  console.log('Next charge', sub.next_charge_at, (sub.next_charge_amount_cents || 0) / 100);
}

PortalDirectPaymentTier ​

One subscription tier (plan) of a SUBSCRIPTION Direct Payment.

NameTypeRequiredDescription
idnumberNoDatabase id.
tier_idnumberNoThe tier's number within its own Direct Payment: unique there, never reused there, never changed by an edit. Hardcode it to pick this tier ().
reference_numstringYesThe tier's reference.
tiernumberNoThe tier number the developer set: starts at 1, several tiers may share it, and it is not a lookup key (use tier_id).
pricesPortalDirectPaymentTierPrice[]NoEvery price this tier is sold at, default first. A tier with one price lists just that one.
direct_payment_reference_numstringNoThe Direct Payment the tier belongs to.
processor_tier_idstringNoThe provider-side plan id.
custom_titlestringNoAdmin-supplied label override (use this as the display name).
custom_descriptionstring | nullNoAdmin-supplied description override.
original_dataPortalDirectPaymentTierOriginalDataNoThe provider's own data for the plan (name, price, interval).
created_atstringNoISO creation timestamp.
updated_atstringNoISO update timestamp.

Show tier names and prices

ts
const dp = window.Portal.directPayments.create('DP_REF');
const record = await dp.getDirectPayment();
const tiers = record.tiers || [];
tiers.forEach((tier) => {
  const price = tier.prices ? tier.prices[0] : undefined;
  const title = tier.custom_title || (tier.original_data ? tier.original_data.name : undefined);
  console.log(title, price ? price.amount_cents / 100 : undefined, price ? price.interval : undefined);
});

PortalDirectPaymentTierOriginalData ​

The payment provider's own description of a subscription plan behind a tier. Informational.

NameTypeRequiredDescription
idstringNoRecord id.
processor_idstringNoThe processor the plan lives on.
providerstringNoThe provider's name.
namestringNoThe plan's name at the provider.
descriptionstring | nullNoThe plan's description.
plan_intervalstringNoBilling interval, for example 'month'.
plan_amount_centsnumberNoPrice per interval in cents.
currencystringNoISO currency code.
trial_daysnumber | nullNoFree trial length, if any.
provider_plan_idstringNoThe provider's id for the plan.
is_activebooleanNoWhether the plan is sold.
created_atstringNoISO creation timestamp.
updated_atstringNoISO update timestamp.

PortalDirectPaymentTierPrice ​

One price of a tier (): how much, in what currency, for which period.

NameTypeRequiredDescription
intervalstringYesThe billing period unit. One of week, month, quarter, year.
interval_countnumberNoHow many intervals per billing (2 + month = every two months).
amount_centsnumberYesPrice per billing in cents.
currencystringYesISO currency code.
trial_daysnumber | nullNoFree trial days at the start, if any.
is_defaultbooleanNoThe tier's own price (the one it is created with); the others are added for another interval.

PortalDiscountResolveResult ​

The answer of resolveDiscount(): whether a code is valid and what it gives.

NameTypeRequiredDescription
successbooleanYesTrue when the code can be used.
discountobjectNoThe discount, when valid.
discount.discount_codestringYesThe code, normalised.
discount.typestringYespercent or amount.
discount.percent_offnumberNoThe percentage taken off, for a percent discount.
discount.amount_centsnumberNoThe amount taken off in cents, for an amount discount.
discount.currencystringYesISO currency code of amount_cents.
discount.duration'once' | 'repeating' | 'forever'NoOnce = the first billing cycle, repeating = duration_cycles cycles, forever.
discount.duration_cyclesnumber | nullNoHow many cycles a repeating discount lasts.
messagestringNoWhy the code was refused, when it was.

PortalMoneyHistoryRow ​

One charge of the payer's money history.

NameTypeRequiredDescription
datestring | nullYesISO date of the charge.
providerstringYesThe provider that took it.
gross_centsnumberYesThe amount charged, in cents.
refunded_centsnumberYesThe amount given back, in cents.
net_centsnumberYesgross_cents - refunded_cents.
currencystringYesISO currency code.
statusstringYesPayment status.
invoice_reference_numstring | nullNo—
receipt_urlstring | nullNoThe provider's hosted receipt.

PortalProcessorClientPaymentResult ​

The outcome of a payment or card-setup call.

NameTypeRequiredDescription
successbooleanYesTrue when it worked.
statusstringNoThe provider's status word.
errorstringNoThe reason, when it failed.
chargeIdstringNoThe provider's charge id.

PortalProcessorClientSubscriptionResult ​

The outcome of client.createSubscription() and the subscription:* events.

NameTypeRequiredDescription
successbooleanYesTrue when it worked.
subscription_idstringNoThe provider's subscription id.
statusstringNoThe provider's status word.
client_secretstringNoStripe only: the secret to confirm the payment or setup intent.
payment_intentunknownNoStripe only: the payment intent (object or id).
urlstringNoPayPal and hosted flows: where to send the shopper to approve.
errorstringNoThe reason, when it failed.
rawunknownNoThe raw provider or server response, for debugging.
linkedbooleanNoThe server already wrote the Direct Payments link in the same request, so the page need not report the subscription.

PortalSubscriptionChangePreview ​

The answer of dp.subscription.previewChange(). text is the plain-language lines every client shows as they are.

NameTypeRequiredDescription
from_tier_refstring | nullYesThe tier the subscription is on now.
to_tier_refstringYesThe tier being previewed.
directionstringYesrevert = choosing the plan the subscription is on while a downgrade is scheduled (undoes it). One of upgrade, downgrade, same, revert, unknown.
due_now_centsnumberYesThe prorated difference charged today (0 for a downgrade).
credit_centsnumberYesUnused-time credit applied.
currencystringYesISO currency code.
new_priceobjectYesThe price after the change.
new_price.amount_centsnumberYes—
new_price.currencystringYes—
new_price.intervalstringYesThe billing interval, for example month or year.
new_price.interval_countnumberYes—
next_charge_atstring | nullYesISO date of the next regular charge.
next_charge_amount_centsnumber | nullYesThe next regular charge in cents.
takes_effect'now' | 'period_end'YesWhen the change applies.
charge_now_supportedbooleanYesTrue when the provider can charge the difference immediately.
estimatebooleanYesTrue when the amount was worked out from the two prices and the period dates rather than read from the provider.
textstring[]YesPlain-language lines to show the payer as they are.

PortalTaxEstimateResult ​

The answer of estimateTax().

NameTypeRequiredDescription
successbooleanYesTrue when an estimate could be made.
tax_ratenumberNoThe tax rate, as a percentage.
tax_centsnumberNoThe estimated tax in cents.
descriptionstringNoWhat the tax is (for example "CA sales tax").
messagestringNoWhy no estimate was made, when it was not.

PublicConnectProfile ​

The public (non-secret) Connect settings of a Direct Payment, from connect.getProfile().

NameTypeRequiredDescription
enabledbooleanYesTrue when Connect is switched on.
integration_modeConnectIntegrationModeYesHow connected accounts are managed.
onboarding_modeConnectOnboardingModeYesHow onboarding is performed.
default_countrystringYesISO country code new accounts default to.
default_currencystringYesISO currency code new accounts default to.
platform_fee_percentnumberYesThe share of each sale the platform keeps, in percent.
account_configurationsstring[]YesThe capability sets requested for new accounts (for example 'merchant').

StartOnboardingOptions ​

Options of connect.startOnboarding().

NameTypeRequiredDescription
return_pathstringNoWhere the user returns to after finishing (hosted onboarding).
refresh_pathstringNoWhere the user returns to when the onboarding link expired (hosted onboarding).
componentsConnectComponentName[]NoThe components to include (embedded onboarding).