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
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.
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.
const processorClientPaymentResult = await dp.addPaymentMethod(options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
options | PortalAddPaymentMethodOptions | Yes | Available 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.
dp.attachDynamicAmountListener(inputTarget, getItemRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
inputTarget | string | HTMLInputElement | Yes | — |
getItemRef | () => string | null | undefined | Yes | — |
capabilities()
(point 5). What the Direct Payment's CURRENT provider can do. Cached until the processor changes.
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).
dp.clearSelectedTier();clearSession()
Clears all subscription-related session state used by the Direct Payments flow.
dp.clearSession();confirmCardSetup()
Confirms a card setup / vault flow after addPaymentMethod() has mounted the form.
const result = await dp.confirmCardSetup(returnUrl);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
returnUrl | string | No | Where the buyer is sent back to after the provider's own page. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | True when the call worked. |
error | string | No | The reason, when it failed. |
confirmPayment()
Confirms the mounted single-pay or subscription payment flow.
const directPaymentsConfirmPaymentResult = await dp.confirmPayment(options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
options | object | Yes | An invoice built in the browser: a basket of catalogue items that is locked and then paid. |
options.email | string | Yes | The payer's e-mail (receipt and customer record). |
options.name | string | No | Customer's full name, saved to the provider customer alongside the email. |
options.invoice | PortalDirectPaymentInvoice | No | The invoice being paid. |
options.returnUrl | string | No | Where the buyer returns after 3-D Secure. |
options.setup_future_usage | boolean | No | Keep the card for later charges. |
options.user_id | string | No | An id of your own for the payer. |
options.metadata | Record<string, unknown> | No | Extra 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)
const connect = dp.connect;createInvoice()
Creates a fresh, editable invoice instance for the current Direct Payment.
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.
const directPaymentMethodResult = await dp.deletePaymentMethod(methodId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
methodId | string | Yes | The 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.
dp.destroyPayment();estimateTax()
Estimate sales tax for the current provider based on country and state.
const taxEstimateResult = await dp.estimateTax(countryCode, state);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
countryCode | string | Yes | — |
state | string | Yes | The 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)
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.
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.
const count = dp.getAmountForCharge(itemRef, userAmount);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
itemRef | string | Yes | — |
userAmount | number | No | The 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.
const directPayment = await dp.getDirectPayment(id);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | No | If 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.
const result = dp.getDirectPaymentFromSessionStorage();Returns
Returns PortalDirectPayment \| null.
getDirectPaymentRef()
Returns the Direct Payment reference currently stored in session.
const result = dp.getDirectPaymentRef();Returns
Returns string \| null.
getItemBySku()
Returns a single item by SKU from the currently loaded Direct Payment.
const result = dp.getItemBySku(sku);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
sku | string | Yes | Your stock-keeping code. |
Returns
Returns PortalDirectPaymentItem \| null.
getItems()
Returns the item definitions from the currently loaded Direct Payment.
const directPaymentItems = dp.getItems();Returns
Returns an array of PortalDirectPaymentItem.
getSavedPaymentMethods()
Returns vaulted payment methods for the current customer.
const directPaymentsSavedMethods = await dp.getSavedPaymentMethods();Returns
Resolves with an array of PortalDirectPaymentsSavedMethod.
getSelectedTier()
Returns display-ready data for the currently selected subscription tier.
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.
const result = dp.getSelectedTierPlan();Returns
Returns an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
dpId | string | null | Yes | The Direct Payment's reference. |
tier | number | null | Yes | The tier number. |
interval | string | null | Yes | The billing interval, for example month or year. |
tierId | number | null | Yes | The tier's tier_id within the Direct Payment. |
getStoredProcessorId()
Returns the processor reference number saved during payment setup, or null.
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.
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.
const count = await dp.getSubscriptionTierAmountCents(dpId, tierIndex);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
dpId | string | Yes | The Direct Payment's reference. |
tierIndex | number | Yes | The 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.
const count = await dp.getSubscriptionTierPriceIndex(amountCents);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
amountCents | number | Yes | An amount in cents. |
Returns
Resolves with a number.
getTier()
Returns the configured tier record for the given tier_id from the active DP.
const result = dp.getTier(tierId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
tierId | number | Yes | The 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.
const result = dp.getTierById(tierId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
tierId | number | Yes | The 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.
const result = dp.getTierByRef(reference);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
reference | string | Yes | A 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.
const directPaymentTierPrices = dp.getTierPrices(tierId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
tierId | number | Yes | The 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.
const directPaymentTierPrices = dp.getTierPricesById(tierId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
tierId | number | Yes | The 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.
const directPaymentTierPrices = dp.getTierPricesByRef(reference);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
reference | string | Yes | A 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.
await dp.initializeDirectPayment(id, options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | No | The record's id. |
options | object | No | Optional settings. |
options.waitForProcessorConfig | boolean | No | — |
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.
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.
const ok = dp.isItemDynamic(item);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
item | PortalDirectPaymentItem | string | Yes | One 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.
const ok = dp.isSinglePay();Returns
Returns a boolean.
isSubscription()
Returns true when the active Direct Payment uses a subscription checkout flow.
const ok = dp.isSubscription();Returns
Returns a boolean.
listPaymentMethods()
The payer's saved cards, but a failure rejects instead of returning an empty list.
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.
const directPaymentInvoice = await dp.loadPreparedInvoice(data);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
data | object | Yes | The data. |
data.reference_num | string | Yes | The record's reference number. |
data.items | object[] | Yes | — |
data.items[].item_ref | string | Yes | The Direct Payments item reference. |
data.items[].name | string | Yes | The name. |
data.items[].price | number | Yes | — |
data.items[].tax | number | No | — |
data.items[].quantity | number | Yes | How many. |
data.items[].sku | string | No | Your stock-keeping code. |
data.items[].seller_ref | string | No | — |
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)
const notifications = dp.notifications;off()
Unsubscribe a specific handler (or every handler for the event, if omitted).
dp.off(event, handler);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
event | E | Yes | The event to listen for. |
handler | (e: PortalDirectPaymentClientEventPayloads[E]) => void | No | What 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().
const result = dp.on(event, handler);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
event | E | Yes | The event to listen for. |
handler | (e: PortalDirectPaymentClientEventPayloads[E]) => void | Yes | What each client event hands to its listener (dp.on(event, handler)). |
Returns
Returns () => void.
Examples
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.
const result = dp.onProcessorChanged(handler);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
handler | (e: object) => void | Yes | Function called when it happens. |
Returns
Returns () => void.
purchases()
Every paid invoice of the signed-in payer on this Direct Payment, newest first.
const directPaymentPurchases = await dp.purchases(options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
options | object | No | Optional settings. |
options.limit | number | No | The most items to return. |
Returns
Resolves with an array of PortalDirectPaymentPurchase.
resolveDiscount()
Resolve a discount code against the active provider.
const discountResolveResult = await dp.resolveDiscount(discountCode);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
discountCode | string | Yes | — |
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.
const directPaymentsSavedMethods = await dp.savedPaymentMethods();Returns
Resolves with an array of PortalDirectPaymentsSavedMethod.
saveInvoice()
Persists an invoice in the backend as pending before payment authorization.
const directPaymentSavedInvoice = await dp.saveInvoice(invoice, customerEmail, userId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
invoice | PortalDirectPaymentInvoice | Yes | An invoice built in the browser: a basket of catalogue items that is locked and then paid. |
customerEmail | string | Yes | — |
userId | string | No | An 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.
const directPaymentMethodResult = await dp.setDefaultPaymentMethod(methodId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
methodId | string | Yes | The 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.
dp.setSelectedTier(tierId, interval);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
tierId | number | Yes | The tier's tier_id within the Direct Payment. |
interval | string | null | No | The 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.
dp.setSelectedTierPlan(tierId, interval);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
tierId | number | Yes | The tier's tier_id within the Direct Payment. |
interval | string | null | No | The 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.
dp.setUITierPrice(tierId, selector, options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
tierId | number | Yes | The tier's tier_id within the Direct Payment. |
selector | string | Yes | A CSS selector. |
options | PortalDirectPaymentsSetUITierPriceOptions | Yes | Formatting options of setUITierPrice(). |
Examples
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().
await dp.setupSinglePayPayment(options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
options | object | Yes | An invoice built in the browser: a basket of catalogue items that is locked and then paid. |
options.invoice | PortalDirectPaymentInvoice | Yes | The locked invoice to pay. |
options.currency | string | No | ISO currency code (default 'usd'). |
options.description | string | No | Description shown on the provider's dashboard. |
options.mountTarget | string | No | CSS selector of the element to mount the card form in. |
options.onSuccess | () => void | Yes | Called once the form is ready. |
options.onError | (err: unknown) => void | Yes | Called 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.
await dp.setupSubscription(options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
options | PortalDirectPaymentsSetupSubscriptionOptions | Yes | Callbacks of setupSubscription(). |
Returns
Resolves when the call has completed.
setupSubscriptionPayment()
Initializes the subscription payment widget or hosted flow.
await dp.setupSubscriptionPayment(options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
options | PortalDirectPaymentsSetupPaymentOptions | Yes | Options 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().
dp.setupTiers(result, tiers);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
result | PortalDirectPayment | Yes | A Direct Payment: a payment configuration (a catalogue of items, or subscription tiers) bound to a payment provider. |
tiers | PortalDirectPaymentsSetupTierConfig[] | Yes | One tier-selector button for setupTiers(). |
subscription
The signed-in payer's own subscription: read, cancel, resume, change plan.
Type: PortalDirectPaymentSubscriptionAPI (read-only)
const subscription = dp.subscription;updateInvoiceStatus()
Updates the stored status of a pending invoice.
const result = await dp.updateInvoiceStatus(referenceNum, status);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The record's reference number. |
status | string | Yes | The 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.
const ok = await dp.updatePaymentAmount(amount);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
amount | number | Yes | An 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.
dp.useCustomerResolver(resolver);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
resolver | PortalDirectPaymentsPayerResolver | null | Yes | 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. |
Examples
With Site Users
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.
const result = await dp.connect.closeAccount(accountRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
accountRef | string | Yes | The connected account's reference. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | True when the call worked. |
createAccount()
Creates a connected account (prefer setupAccount(), which is idempotent).
const connectedAccount = await dp.connect.createAccount(opts);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
opts | ConnectCreateAccountOptions | Yes | Options of connect.createAccount() / setupAccount(). |
Returns
Resolves with a ConnectedAccount: A connected account (one seller / end user who can be paid).
getAccount()
Reads one account.
const connectedAccount = await dp.connect.getAccount(accountRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
accountRef | string | Yes | The 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.
const result = await dp.connect.getAccountForUser(connectUser);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
connectUser | string | Yes | — |
Returns
Resolves with ConnectedAccount \| null.
getBalance()
The account's balance.
const connectBalance = await dp.connect.getBalance(accountRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
accountRef | string | Yes | The 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.
const capabilityDescriptors = await dp.connect.getCapabilityCatalog(country);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
country | string | Yes | An ISO country code. |
Returns
Resolves with an array of CapabilityDescriptor.
getProfile()
The public Connect settings.
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.
const connectRequirements = await dp.connect.getRequirements(accountRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
accountRef | string | Yes | The connected account's reference. |
Returns
Resolves with an array of ConnectRequirement.
getStatus()
Reads one account with its outstanding requirements.
const connectAccountStatus = await dp.connect.getStatus(accountRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
accountRef | string | Yes | The 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.
const ok = dp.connect.isSupported();Returns
Returns a boolean.
listAccounts()
Lists the accounts of this Direct Payment.
const connectedAccounts = await dp.connect.listAccounts();Returns
Resolves with an array of ConnectedAccount.
listPayouts()
The account's recent payouts.
const connectPayouts = await dp.connect.listPayouts(accountRef, params);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
accountRef | string | Yes | The connected account's reference. |
params | object | No | Extra options. |
params.limit | number | No | The most items to return. |
Returns
Resolves with an array of ConnectPayout.
mountComponent()
Draws one Connect component (payouts, balances...) for an account.
const connectMount = await dp.connect.mountComponent(accountRef, component, target);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
accountRef | string | Yes | The connected account's reference. |
component | ConnectComponentName | Yes | An embeddable Connect UI component, mounted with connect.mountComponent(). |
target | string | HTMLElement | Yes | A 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.
const connectMount = await dp.connect.mountOnboarding(handle, target);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
handle | OnboardingHandle | Yes | One branch per .mode; changing the profile's onboarding_mode changes behaviour with no caller code change. |
target | string | HTMLElement | Yes | Draws 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).
const connectPayout = await dp.connect.requestPayout(accountRef, amountMinor);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
accountRef | string | Yes | The connected account's reference. |
amountMinor | number | Yes | Requests 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).
const result = await dp.connect.setupAccount(opts);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
opts | ConnectCreateAccountOptions & { connect_user: string } | Yes | Options of connect.createAccount() / setupAccount(). |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
account | ConnectedAccount | Yes | — |
created | boolean | Yes | — |
startOnboarding()
Begins onboarding; branch on handle.mode.
const onboardingHandle = await dp.connect.startOnboarding(accountRef, opts);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
accountRef | string | Yes | The connected account's reference. |
opts | StartOnboardingOptions | No | Options 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).
const connectAccountStatus = await dp.connect.submitRequirements(accountRef, payload);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
accountRef | string | Yes | The connected account's reference. |
payload | Record<string, unknown> | Yes | The 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.
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().
const result = await dp.connect.uploadDocument(accountRef, purpose, file);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
accountRef | string | Yes | The connected account's reference. |
purpose | string | Yes | What the sign-in is for. |
file | File | Yes | The file. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
file_id | string | Yes | — |
validateProfile()
Pure — rules, no data.
const connectProfileValidation = dp.connect.validateProfile(p);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
p | ConnectProfileInput | Yes | A 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.
const result = await dp.experimental.capabilities(target, fresh);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
target | PortalDirectPaymentsExperimentalTarget | Yes | What an experimental control acts on: the provider's subscription id, or the processor for disputes. |
fresh | boolean | No | Pass fresh to bypass the cache. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
provider | string | Yes | The provider's name. |
controls | PortalDirectPaymentsExperimentalControl[] | Yes | — |
inspect()
Reads a provider object (customer, subscription, invoice, payment, dispute, plan) by id.
const result = await dp.experimental.inspect(object, id, target);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
object | string | Yes | One of customer, subscription, invoice, payment, dispute, plan. |
id | string | Yes | The record's id. |
target | PortalDirectPaymentsExperimentalTarget | Yes | What 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.
const result = await dp.experimental.preview(key, target, params);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
key | string | Yes | The key. |
target | PortalDirectPaymentsExperimentalTarget | Yes | What an experimental control acts on: the provider's subscription id, or the processor for disputes. |
params | Record<string, unknown> | No | Extra options. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
preview | true | Yes | — |
action | string | Yes | The action. |
dangerous | boolean | Yes | — |
text | string | Yes | The text. |
level | string | Yes | — |
note | string | null | Yes | — |
confirmed | boolean | Yes | — |
run()
Runs a control.
const result = await dp.experimental.run(key, target, params);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
key | string | Yes | The key. |
target | PortalDirectPaymentsExperimentalTarget | Yes | What an experimental control acts on: the provider's subscription id, or the processor for disputes. |
params | Record<string, unknown> | No | Extra 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.
const result = await dp.notifications.get(event);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
event | string | Yes | The event to listen for. |
Returns
Resolves with PortalDirectPaymentNotificationRow \| null.
list()
Every notification setting.
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.
const directPaymentSubscriptionState = await dp.subscription.cancel(options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
options | object | No | Optional 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.
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").
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.
const subscriptionChangePreview = await dp.subscription.previewChange(options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
options | object | Yes | Optional settings. |
options.tier_id | number | Yes | The tier's tier_id within the Direct Payment. |
options.interval | string | No | The 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().
const directPaymentReauthoriseSession = await dp.subscription.reauthorise(token, options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
token | string | Yes | token is renewal_token from get(). |
options | object | Yes | Optional settings. |
options.mountTarget | string | HTMLElement | Yes | A 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.
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.
const result = await dp.subscription.setPaymentMethod(options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
options | object | Yes | Optional settings. |
options.method_id | string | Yes | The 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.
const directPaymentSubscriptionState = await dp.subscription.update(options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
options | object | Yes | Optional settings. |
options.tier_id | number | Yes | The tier's tier_id within the Direct Payment. |
options.interval | string | No | Move 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' | No | now 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
amountand validate against min/max amounts.
invoice.addItem(options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
options | object | Yes | Optional settings. |
options.item_ref | string | Yes | The Direct Payments item reference. |
options.quantity | number | Yes | How many. |
options.amount | number | undefined | No | An amount in currency units. |
options.name | string | No | The name. |
options.seller_ref | string | No | — |
options.interval | string | No | The billing interval, for example month or year. |
clear()
Clears all line items from the invoice.
invoice.clear();getDirectPaymentRef()
Returns the Direct Payment reference associated with the invoice.
const value = invoice.getDirectPaymentRef();Returns
Returns a string.
getEventIdentifier()
Returns the optional event identifier used for webhook/provider correlation.
const result = invoice.getEventIdentifier();Returns
Returns string \| null.
getItem()
Gets a single invoice item by reference number.
const result = invoice.getItem(item_ref);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
item_ref | string | Yes | The Direct Payments item reference. |
Returns
Returns PortalDirectPaymentInvoiceItem \| undefined.
getItems()
Returns the current line items on the invoice.
const directPaymentInvoiceItems = invoice.getItems();Returns
Returns an array of PortalDirectPaymentInvoiceItem.
getReferenceNum()
Returns the generated invoice reference number.
const value = invoice.getReferenceNum();Returns
Returns a string.
getSellerRefs()
Distinct seller_ref values on this invoice, in first-seen order.
const result = invoice.getSellerRefs();Returns
Returns string[].
getSplitItems()
Builds the split_items sent to setupSinglePayPayment()'s intent request; see SplitCalculator::buildSplit().
const result = invoice.getSplitItems();Returns
Returns a list of objects with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
seller_reference_num | string | Yes | The seller's reference. |
order_item_reference_num | string | Yes | The order item's reference. |
line_net | number | Yes | The line's net amount. |
getSubtotal()
Returns the invoice subtotal before tax.
const count = invoice.getSubtotal();Returns
Returns a number.
getTaxTotal()
Returns the invoice tax total.
const count = invoice.getTaxTotal();Returns
Returns a number.
getTotal()
Returns the invoice total including tax.
const count = invoice.getTotal();Returns
Returns a number.
hasItem()
Returns true if the invoice already contains the given item reference.
const ok = invoice.hasItem(item_ref);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
item_ref | string | Yes | The Direct Payments item reference. |
Returns
Returns a boolean.
hasSplit()
True when any item carries a seller_ref.
const ok = invoice.hasSplit();Returns
Returns a boolean.
isLocked()
Returns true when the invoice has been locked and can no longer be modified.
const ok = invoice.isLocked();Returns
Returns a boolean.
lock()
Locks the invoice and generates its reference_num.
invoice.lock();removeItem()
Removes an item from the invoice.
invoice.removeItem(item_ref);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
item_ref | string | Yes | The Direct Payments item reference. |
setEventIdentifier()
Stores an optional event identifier such as a payment intent or subscription ID.
invoice.setEventIdentifier(identifier);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
identifier | string | Yes | — |
unlock()
Unlocks the invoice so it can be modified again.
invoice.unlock();updateItem()
Updates quantity or amount for an existing invoice item.
invoice.updateItem(item_ref, options);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
item_ref | string | Yes | The Direct Payments item reference. |
options | object | Yes | Optional settings. |
options.quantity | number | No | How many. |
options.amount | number | undefined | No | An amount in currency units. |
PortalDirectPaymentReauthoriseSession
A payment-details form mounted by dp.subscription.reauthorise().
destroy()
Removes the form.
directPaymentReauthoriseSession.destroy();provider
The provider the form belongs to.
Type: string
const provider = directPaymentReauthoriseSession.provider;submit()
Sends the entered details; resolves with the outcome and the date of the next charge.
const result = await directPaymentReauthoriseSession.submit();Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | True when the call worked. |
error | string | No | The reason, when it failed. |
next_charge_at | string | No | — |
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.
const directPaymentsSavedMethods = await directPaymentsPayerResolver.paymentMethods(dpRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
dpRef | string | Yes | The 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.
const result = await directPaymentsPayerResolver.resolve(dpRef);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
dpRef | string | Yes | The Direct Payment's reference. |
Returns
Resolves with an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
payer_reference_num | string | Yes | — |
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.
const directPaymentsAPI = window.Portal.directPayments.create(directPaymentId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
directPaymentId | string | Yes | — |
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.
const result = window.Portal.directPayments.findActiveSubscriptionMatch(invoices, subscriptions);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
invoices | PortalDirectPaymentInvoiceListRow[] | Yes | One invoice row of Portal.directPayments.getInvoices(userId). |
subscriptions | object[] | Yes | A list of objects, described below. |
subscriptions[].id | string | No | The record's id. |
subscriptions[].providerPlanId | string | No | The provider's id for the plan. |
subscriptions[].[key: string] | unknown | No | Further fields the server may add. |
Returns
Returns an object with these fields:
| Name | Type | Required | Description |
|---|---|---|---|
matchedPlan | object | Yes | — |
matchedPlan.id | string | No | The record's id. |
matchedPlan.providerPlanId | string | No | The provider's id for the plan. |
matchedPlan.[key: string] | unknown | No | Further fields the server may add. |
invoice | PortalDirectPaymentInvoiceListRow | Yes | — |
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.
const directPaymentInvoiceRecord = await window.Portal.directPayments.getInvoice(referenceNum);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
referenceNum | string | Yes | The 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.
const directPaymentInvoiceListRows = await window.Portal.directPayments.getInvoices(userId);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
userId | string | null | No | An 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.
window.Portal.directPayments.setAuthTokenProvider(provider);Parameters
| Name | Type | Required | Description |
|---|---|---|---|
provider | (() => string | null) | null | Yes | The 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)
const version = window.Portal.directPayments.version;Types
CapabilityDescriptor
One capability a connected account can have in a country (from getCapabilityCatalog()).
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Capability id. |
label | string | Yes | Display name. |
configuration | 'merchant' | 'recipient' | 'customer' | Yes | Which kind of account configuration the capability belongs to. |
ConnectAccountStatus
A connected account together with what it still owes.
Extends ConnectedAccount.
| Name | Type | Required | Description |
|---|---|---|---|
requirements | ConnectRequirement[] | Yes | Outstanding requirements; empty when the account is complete. |
ConnectBalance
A connected account's balance, per currency. Amounts are in the smallest unit.
| Name | Type | Required | Description |
|---|---|---|---|
available | object[] | Yes | Money that can be paid out now. |
available[].amount | number | Yes | An amount in currency units. |
available[].currency | string | Yes | — |
pending | object[] | Yes | Money not yet available. |
pending[].amount | number | Yes | An amount in currency units. |
pending[].currency | string | Yes | — |
ConnectComponentName
An embeddable Connect UI component, mounted with connect.mountComponent().
One of:
account_onboardingaccount_managementnotification_bannerpayoutsbalancesdocumentspayment_disputes
ConnectCreateAccountOptions
Options of connect.createAccount() / setupAccount().
| Name | Type | Required | Description |
|---|---|---|---|
connect_user | string | No | Your own id for the end user the account belongs to (makes setupAccount() idempotent). |
country | string | No | ISO country code. |
entity_type | string | No | individual or company. |
email | string | No | The holder's e-mail. |
display_name | string | No | Name shown to buyers. |
ConnectedAccount
A connected account (one seller / end user who can be paid).
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The account's reference; pass it to every other Connect call. |
status | string | Yes | The account's status, for example 'pending' or 'active'. |
country | string | Yes | ISO country code. |
email | string | null | Yes | The account holder's e-mail. |
charges_enabled | boolean | Yes | True when the account may accept payments. |
payouts_enabled | boolean | Yes | True when the account may receive payouts. |
details_submitted | boolean | Yes | True once the holder finished onboarding. |
disabled_reason | string | null | Yes | Why the account is restricted, when it is. |
default_currency | string | null | Yes | The account's currency. |
ConnectIntegrationMode
Who runs the account's dashboard and how much the platform handles itself.
One of:
self_hostedexpressfull_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:
embeddedhostedapi
ConnectPayout
A payout from a connected account to its bank.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | Payout id. |
amount | number | Yes | Amount in the smallest unit. |
currency | string | Yes | ISO currency code. |
status | string | Yes | pending, paid, failed... |
arrival_date | number | null | Yes | Unix timestamp (seconds) it is expected to arrive. |
ConnectProfileInput
A Connect profile to check with connect.validateProfile() (no network call).
| Name | Type | Required | Description |
|---|---|---|---|
integration_mode | ConnectIntegrationMode | Yes | How connected accounts are managed. |
onboarding_mode | ConnectOnboardingMode | Yes | How onboarding is performed. |
responsibilities | object | Yes | Who 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_percent | number | Yes | The share of each sale the platform keeps, in percent. |
account_configurations | string[] | Yes | The capability sets requested for new accounts (for example merchant). |
charge_model | 'auto' | 'destination' | 'separate_transfers' | No | How a multi-seller sale is moved: let the platform decide (auto), one destination, or separate transfers. |
ConnectProfileValidation
The result of validateProfile().
| Name | Type | Required | Description |
|---|---|---|---|
valid | boolean | Yes | True when the profile has no errors. |
errors | ConnectProfileValidationError[] | Yes | Every problem found. |
ConnectProfileValidationError
One problem found by validateProfile().
| Name | Type | Required | Description |
|---|---|---|---|
field | string | Yes | The profile field at fault. |
code | string | Yes | A stable machine code. |
message | string | Yes | A human-readable explanation. |
ConnectRequirement
One thing a connected account still has to provide.
| Name | Type | Required | Description |
|---|---|---|---|
requirement | string | Yes | The missing item, for example 'individual.id_number'. |
due_by | number | null | Yes | Unix timestamp (seconds) it is due by, or null. |
ConnectSupport
Whether the Direct Payment's provider supports Connect (connect.support()).
| Name | Type | Required | Description |
|---|---|---|---|
supported | boolean | Yes | True when Connect works with the current provider. |
provider | string | Yes | The provider's name. |
reason | string | No | Why 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.
| Name | Type | Required | Description |
|---|---|---|---|
mountTarget | string | HTMLElement | Yes | CSS selector or HTMLElement to mount the provider card form into. |
processor_reference_num | string | No | Processor 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] | unknown | No | Further fields the server may add. |
PortalConfirmPaymentOptions
Options for directPayments.confirmPayment()
| Name | Type | Required | Description |
|---|---|---|---|
email | string | Yes | Customer email address used to update the anonymous provider customer after charge. |
returnUrl | string | No | Return URL for 3DS redirect (Stripe). Defaults to the current page URL with ?charge=success appended. |
user_id | string | No | An id of your own for the payer. |
metadata | Record<string, unknown> | No | Extra 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.
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The Direct Payment's reference. |
name | string | Yes | Display name. |
pay_type | 'SINGLE_PAY' | 'SUBSCRIPTION' | Yes | SINGLE_PAY = one-off charges of catalogue items; SUBSCRIPTION = recurring tiers. |
processor_reference_num | string | No | The 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). |
items | PortalDirectPaymentItem[] | No | The item catalogue (SINGLE_PAY). |
tiers | PortalDirectPaymentTier[] | No | The subscription tiers (SUBSCRIPTION). |
PortalDirectPaymentCapabilities
What the Direct Payment's current provider can do. Ask; do not hardcode.
| Name | Type | Required | Description |
|---|---|---|---|
provider | string | Yes | The provider's name. |
subscriptionCardChange | boolean | Yes | False on PayPal: subscribers change their card at PayPal. |
planChange | boolean | Yes | True when a subscriber can move to another tier. |
savedCards | boolean | Yes | True when the provider can keep cards for later use. |
trial | boolean | Yes | True when free trials are supported. |
deferredStart | boolean | Yes | True when a subscription can start on a future date. |
wallets | string | Yes | Which wallet buttons (Apple Pay, Google Pay...) the provider offers. |
intervals | string[] | Yes | The billing intervals the provider supports. |
planChangeChargesNow | boolean | No | True where the capability exists in some form on this provider (native or built by the platform). |
planChangeAtPeriodEnd | boolean | No | A plan change can be set to happen at the end of the paid period. |
intervalSwitch | 'now' | 'next_cycle' | 'approval' | false | No | How the provider moves a subscription to another interval of its tier: now, next_cycle, approval (the payer approves at the provider first), or false. |
cancelAtPeriodEnd | boolean | No | A cancel can keep access until the end of the paid period. |
resume | boolean | No | A pending cancel can be taken back. |
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:createdsubscription:failedsubscription:canceledsubscription:cancel_failedsubscription:updatedsubscription:update_failedsubscription:resumedsubscription:resume_failedpayment:succeededpayment:failedpaymentmethod:addedpaymentmethod:removedpaymentmethod:changedprocessor:changedpaymentmethod: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.
| Name | Type | Required | Description |
|---|---|---|---|
subscription:created | PortalProcessorClientSubscriptionResult | Yes | A subscription was started. |
subscription:failed | PortalProcessorClientSubscriptionResult | Yes | Starting a subscription failed. |
subscription:canceled | Record<string, unknown> | Yes | The subscription was cancelled. |
subscription:cancel_failed | Record<string, unknown> | Yes | Cancelling failed. |
subscription:updated | Record<string, unknown> | Yes | The plan was changed. |
subscription:update_failed | Record<string, unknown> | Yes | Changing the plan failed. |
subscription:resumed | Record<string, unknown> | Yes | A pending cancel was taken back. |
subscription:resume_failed | Record<string, unknown> | Yes | Resuming failed. |
payment:succeeded | PortalDirectPaymentsConfirmPaymentResult | Yes | A payment was confirmed. |
payment:failed | PortalDirectPaymentsConfirmPaymentResult | Yes | A payment failed. |
paymentmethod:added | Record<string, unknown> | Yes | A card was saved. |
paymentmethod:removed | Record<string, unknown> | Yes | A card was deleted. |
paymentmethod:changed | Record<string, unknown> | Yes | The default card changed. |
paymentmethod:change_failed | Record<string, unknown> | Yes | Changing the card failed. |
processor:changed | object | Yes | The owner switched payment provider; the form was mounted again. |
processor:changed.provider | string | Yes | The provider's name. |
processor:changed.reference_num | string | Yes | The record's reference number. |
processor:changed.binding_version | number | Yes | — |
PortalDirectPaymentInvoiceItem
One line of an invoice (see PortalDirectPaymentInvoice).
| Name | Type | Required | Description |
|---|---|---|---|
item_ref | string | Yes | The catalogue item or tier reference. |
name | string | Yes | Display name. |
price | number | Yes | Unit price in currency units. |
tax | number | Yes | Tax per unit in currency units. |
quantity | number | Yes | Number of units. |
sku | string | No | Your stock-keeping code. |
seller_ref | string | undefined | No | Optional per-line seller attribution; drives hasSplit()/getSplitItems(). |
PortalDirectPaymentInvoiceListRow
One invoice row of Portal.directPayments.getInvoices(userId).
| Name | Type | Required | Description |
|---|---|---|---|
id | number | No | Database id. |
reference_num | string | Yes | The invoice's reference. |
status | string | Yes | Payment status. |
total_amount | number | string | No | Total amount (number or decimal string). |
created_at | string | Yes | ISO creation timestamp. |
parsed_data | Record<string, unknown> | No | The invoice's items, already parsed (item_names, items, payment_method_label,...), when the server could parse them. |
items_data | string | Array<Record<string, unknown>> | No | The raw items, as JSON text or already an array. |
[key: string] | unknown | No | Further fields the server may add. |
PortalDirectPaymentInvoiceRecord
One invoice as Portal.directPayments.getInvoice() returns it.
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The invoice's reference. |
direct_payment_reference_num | string | Yes | The Direct Payment it belongs to. |
processor_reference_num | string | null | Yes | The processor that took (or will take) the payment. |
status | string | Yes | Payment status. |
amount_cents | number | Yes | Amount in cents. |
currency | string | Yes | ISO currency code. |
charge_id | string | null | Yes | The provider's charge id, once paid. |
refunded_cents | number | Yes | Cents given back so far. |
items_data | string | Array<Record<string, unknown>> | Yes | The invoice's items, as JSON text or already an array. |
charged_at | string | null | Yes | ISO date it was charged. |
PortalDirectPaymentItem
One item in a SINGLE_PAY Direct Payment's catalogue — something that can be put on an invoice.
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The item's reference; use it as item_ref on an invoice. |
name | string | No | Internal name. |
title | string | No | Display title. |
description | string | No | Longer description. |
sku | string | No | Your stock-keeping code. |
price | number | string | Yes | The server sends decimals as strings ("64.00"); read them with Number(). attachPricing() does that for you. |
tax | number | string | No | Tax per unit, in currency units (same decimal rules as price). |
price_type | 'FIXED' | 'DYNAMIC' | No | Pricing 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_amount | number | string | null | No | Optional minimum allowed amount for DYNAMIC items (a number or a decimal string). |
max_amount | number | string | null | No | Optional maximum allowed amount for DYNAMIC items (a number or a decimal string). |
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.
| Name | Type | Required | Description |
|---|---|---|---|
success | boolean | No | True when the change was made. |
message | string | No | A message to show. |
[key: string] | unknown | No | Further 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.
| Name | Type | Required | Description |
|---|---|---|---|
event | string | Yes | The event key, for example 'payment.failed'. |
days_before | number[] | null | Yes | For scheduled events: days before the date a reminder goes out. |
active | boolean | Yes | Whether the owner has this notification switched on. |
PortalDirectPaymentPurchase
One paid invoice of the payer, as dp.purchases() returns it.
| Name | Type | Required | Description |
|---|---|---|---|
invoice_reference_num | string | Yes | The invoice's reference. |
direct_payment_reference_num | string | Yes | The Direct Payment it was paid on. |
charged_at | string | null | Yes | ISO date it was charged. |
amount_cents | number | Yes | Amount charged in cents. |
currency | string | null | Yes | ISO currency code. |
status | string | Yes | Payment status. |
provider | string | Yes | The provider that took the payment. |
processor_reference_num | string | Yes | The processor's reference. |
processor_name | string | null | Yes | The processor's display name. |
receipt_url | string | null | Yes | The provider's hosted receipt, when it has one. |
card_brand | string | null | Yes | The card brand, for example 'visa'. |
card_last4 | string | null | Yes | The last four digits of the card. |
refunded_cents | number | Yes | What was given back on this invoice, in cents. |
title | string | null | Yes | The 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.
| Name | Type | Required | Description |
|---|---|---|---|
reference_num | string | Yes | The saved invoice's reference. |
status | string | No | The invoice's status (pending until paid). |
payer_token | string | No | The token that recognises this browser as the payer on later calls; the SDK stores it for you. |
[key: string] | unknown | No | Further fields the server may add. |
PortalDirectPaymentsConfirmPaymentResult
The answer of confirmPayment().
| Name | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | True when the payment was confirmed. |
url | string | No | Where the buyer must be sent next (3-D Secure or a provider-hosted page), when the flow redirects. |
error | string | No | The failure reason shown to the buyer. |
processor_result | Record<string, unknown> | No | The 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).
| Name | Type | Required | Description |
|---|---|---|---|
key | string | Yes | The control's key; pass it to preview() / run(). |
area | string | Yes | The area it belongs to (billing, invoices, cards...). |
scope | 'subscription' | 'processor' | Yes | Whether it acts on a subscription or on the processor. |
label | string | Yes | Display name. |
path | string | Yes | The server path it calls. |
method | 'GET' | 'POST' | Yes | The HTTP method it uses. |
dangerous | boolean | Yes | True when it changes money or data and so needs reason and idempotency_key. |
fields | string[] | Yes | The parameters it accepts. |
level | 'yes' | 'partial' | 'no' | Yes | Whether the provider supports it fully, partly or not. |
note | string | null | Yes | An explanation of the support level. |
confirmed | boolean | Yes | True 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.
| Name | Type | Required | Description |
|---|---|---|---|
subscription_id | string | No | The provider's subscription id. |
processor_reference_num | string | No | The processor's reference (for processor-scope controls such as disputes). |
PortalDirectPaymentsSavedMethod
A saved payment method (a vaulted card or wallet) of a payer.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Yes | The method's id; pass it to deletePaymentMethod() / setDefaultPaymentMethod(). |
provider | string | Yes | The provider the method is stored at. |
cardNumber | string | No | The masked card number, for example '•••• 4242'. |
expiryDate | string | No | The expiry, for example '12/29'. |
cardType | string | No | The card brand. |
cardholderName | string | No | The cardholder's name. |
billingZip | string | No | The billing postcode. |
processor_reference_num | string | No | Which processor this card belongs to. |
is_default | boolean | No | An 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()).
| Name | Type | Required | Description |
|---|---|---|---|
tier | number | null | Yes | The selected tier number, or null when none is selected. |
isFree | boolean | Yes | True when nothing paid is selected (the free plan). |
tierName | string | Yes | The tier's display name. |
priceStr | string | Yes | The price as text, for example '$9.00'. |
interval | string | Yes | The billing interval. |
amountCents | number | Yes | The price in cents. |
PortalDirectPaymentsSetUITierPriceOptions
Formatting options of setUITierPrice().
| Name | Type | Required | Description |
|---|---|---|---|
format | string | No | Price formatting string, e.g. '00.00'. |
currency_symbol | string | No | Currency symbol to display, e.g. '$'. |
billing_period | boolean | No | Append the billing period, such as /month. |
interval | string | No | Show 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.
| Name | Type | Required | Description |
|---|---|---|---|
onSuccess | () => void | Yes | Called once the payment UI is ready. |
onError | (err: unknown) => void | Yes | Called if payment initialization fails. |
mountTarget | string | No | CSS selector or HTMLElement where the payment widget should mount. |
invoice | PortalDirectPaymentInvoice | No | Optional locked invoice representing the selected subscription tier. |
user_id | string | No | Optional user identifier used for provider/customer tracking. |
email | string | No | The 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_code | string | No | A 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()
| Name | Type | Required | Description |
|---|---|---|---|
currency | string | No | Currency 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. |
description | string | No | Description shown on the payment intent / provider dashboard. |
mountTarget | string | No | CSS selector or HTMLElement to mount the card form into. Defaults to '#inline-card-mount'. |
onSuccess | () => void | Yes | Called once the card form has been successfully mounted and is ready for input. |
onError | (err: unknown) => void | Yes | Called if the card form fails to mount (non-fatal — hosted/PayPal still work). |
user_id | string | No | Optional user identifier for provider/customer tracking. |
PortalDirectPaymentsSetupSubscriptionOptions
Callbacks of setupSubscription().
| Name | Type | Required | Description |
|---|---|---|---|
onSuccess | (result: PortalDirectPayment) => void | Yes | Called once the subscription flow has loaded the Direct Payment record. |
onError | (err: unknown) => void | Yes | Called when the subscription flow fails to initialize. |
PortalDirectPaymentsSetupTierConfig
One tier-selector button for setupTiers().
| Name | Type | Required | Description |
|---|---|---|---|
button | string | Yes | ID of the button that should trigger this tier selection. |
tierId | number | Yes | The tier_id to select when the button is clicked. |
cb | () => void | Yes | Callback 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.
| Name | Type | Required | Description |
|---|---|---|---|
status | string | Yes | The provider-normalised status word (older pages read this). |
reference | string | No | The 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_num | string | null | No | The tier the subscription is on. |
contract_status | string | No | The platform's own lifecycle status. One of incomplete, active, past_due, migrating, ending, ended. |
price | object | No | What the subscriber pays per period. |
price.amount_cents | number | Yes | — |
price.currency | string | null | Yes | — |
price.interval | string | null | Yes | The billing interval, for example month or year. |
price.interval_count | number | Yes | — |
next_leg_provider | string | No | The provider that will take the next charge (differs from provider while a move is under way). |
action_required | 'payment_details' | No | Set while the owner has moved to another provider and this subscriber must enter payment details there. |
renewal_token | string | No | With action_required: the token for reauthorise(). |
next_charge_at | string | null | Yes | ISO date of the next charge, or null. |
next_charge_amount_cents | number | null | Yes | The next charge in cents, or null. |
currency | string | null | Yes | ISO currency code. |
cancel_at_period_end | boolean | Yes | True when the subscription will stop at the end of the paid period. |
trial_ends_at | string | null | Yes | ISO date a free trial ends, or null. |
plan_name | string | null | Yes | The plan's display name. |
provider | string | Yes | The provider the subscription runs on. |
canceled_at | string | null | Yes | ISO date the subscription was cancelled through this application, else null. |
access_ends_at | string | null | Yes | ISO date access ends after a cancel, else null. |
billing_state | 'current' | 'past_due' | 'downgraded' | No | Present only when the resolved caller is the payer themselves. |
downgrade_after | string | No | ISO date after which an unpaid subscription is downgraded. |
days_until_downgrade | number | No | Days left until that downgrade. |
scheduled_change | object | No | A 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' | Yes | The action. |
scheduled_change.tier_reference_num | string | null | Yes | — |
scheduled_change.at | string | null | Yes | ISO time it takes effect. |
cancellation_access_ends | 'immediately' | 'period_end' | string | No | The Direct Payment's own rule for when access ends after a cancel, so a client can say it before the payer chooses. |
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.
| Name | Type | Required | Description |
|---|---|---|---|
id | number | No | Database id. |
tier_id | number | No | The 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_num | string | Yes | The tier's reference. |
tier | number | No | The tier number the developer set: starts at 1, several tiers may share it, and it is not a lookup key (use tier_id). |
prices | PortalDirectPaymentTierPrice[] | No | Every price this tier is sold at, default first. A tier with one price lists just that one. |
direct_payment_reference_num | string | No | The Direct Payment the tier belongs to. |
processor_tier_id | string | No | The provider-side plan id. |
custom_title | string | No | Admin-supplied label override (use this as the display name). |
custom_description | string | null | No | Admin-supplied description override. |
original_data | PortalDirectPaymentTierOriginalData | No | The provider's own data for the plan (name, price, interval). |
created_at | string | No | ISO creation timestamp. |
updated_at | string | No | ISO update timestamp. |
Show tier names and prices
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.
| Name | Type | Required | Description |
|---|---|---|---|
id | string | No | Record id. |
processor_id | string | No | The processor the plan lives on. |
provider | string | No | The provider's name. |
name | string | No | The plan's name at the provider. |
description | string | null | No | The plan's description. |
plan_interval | string | No | Billing interval, for example 'month'. |
plan_amount_cents | number | No | Price per interval in cents. |
currency | string | No | ISO currency code. |
trial_days | number | null | No | Free trial length, if any. |
provider_plan_id | string | No | The provider's id for the plan. |
is_active | boolean | No | Whether the plan is sold. |
created_at | string | No | ISO creation timestamp. |
updated_at | string | No | ISO update timestamp. |
PortalDirectPaymentTierPrice
One price of a tier (): how much, in what currency, for which period.
| Name | Type | Required | Description |
|---|---|---|---|
interval | string | Yes | The billing period unit. One of week, month, quarter, year. |
interval_count | number | No | How many intervals per billing (2 + month = every two months). |
amount_cents | number | Yes | Price per billing in cents. |
currency | string | Yes | ISO currency code. |
trial_days | number | null | No | Free trial days at the start, if any. |
is_default | boolean | No | The 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.
| Name | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | True when the code can be used. |
discount | object | No | The discount, when valid. |
discount.discount_code | string | Yes | The code, normalised. |
discount.type | string | Yes | percent or amount. |
discount.percent_off | number | No | The percentage taken off, for a percent discount. |
discount.amount_cents | number | No | The amount taken off in cents, for an amount discount. |
discount.currency | string | Yes | ISO currency code of amount_cents. |
discount.duration | 'once' | 'repeating' | 'forever' | No | Once = the first billing cycle, repeating = duration_cycles cycles, forever. |
discount.duration_cycles | number | null | No | How many cycles a repeating discount lasts. |
message | string | No | Why the code was refused, when it was. |
PortalMoneyHistoryRow
One charge of the payer's money history.
| Name | Type | Required | Description |
|---|---|---|---|
date | string | null | Yes | ISO date of the charge. |
provider | string | Yes | The provider that took it. |
gross_cents | number | Yes | The amount charged, in cents. |
refunded_cents | number | Yes | The amount given back, in cents. |
net_cents | number | Yes | gross_cents - refunded_cents. |
currency | string | Yes | ISO currency code. |
status | string | Yes | Payment status. |
invoice_reference_num | string | null | No | — |
receipt_url | string | null | No | The provider's hosted receipt. |
PortalProcessorClientPaymentResult
The outcome of a payment or card-setup call.
| Name | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | True when it worked. |
status | string | No | The provider's status word. |
error | string | No | The reason, when it failed. |
chargeId | string | No | The provider's charge id. |
PortalProcessorClientSubscriptionResult
The outcome of client.createSubscription() and the subscription:* events.
| Name | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | True when it worked. |
subscription_id | string | No | The provider's subscription id. |
status | string | No | The provider's status word. |
client_secret | string | No | Stripe only: the secret to confirm the payment or setup intent. |
payment_intent | unknown | No | Stripe only: the payment intent (object or id). |
url | string | No | PayPal and hosted flows: where to send the shopper to approve. |
error | string | No | The reason, when it failed. |
raw | unknown | No | The raw provider or server response, for debugging. |
linked | boolean | No | The 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.
| Name | Type | Required | Description |
|---|---|---|---|
from_tier_ref | string | null | Yes | The tier the subscription is on now. |
to_tier_ref | string | Yes | The tier being previewed. |
direction | string | Yes | revert = choosing the plan the subscription is on while a downgrade is scheduled (undoes it). One of upgrade, downgrade, same, revert, unknown. |
due_now_cents | number | Yes | The prorated difference charged today (0 for a downgrade). |
credit_cents | number | Yes | Unused-time credit applied. |
currency | string | Yes | ISO currency code. |
new_price | object | Yes | The price after the change. |
new_price.amount_cents | number | Yes | — |
new_price.currency | string | Yes | — |
new_price.interval | string | Yes | The billing interval, for example month or year. |
new_price.interval_count | number | Yes | — |
next_charge_at | string | null | Yes | ISO date of the next regular charge. |
next_charge_amount_cents | number | null | Yes | The next regular charge in cents. |
takes_effect | 'now' | 'period_end' | Yes | When the change applies. |
charge_now_supported | boolean | Yes | True when the provider can charge the difference immediately. |
estimate | boolean | Yes | True when the amount was worked out from the two prices and the period dates rather than read from the provider. |
text | string[] | Yes | Plain-language lines to show the payer as they are. |
PortalTaxEstimateResult
The answer of estimateTax().
| Name | Type | Required | Description |
|---|---|---|---|
success | boolean | Yes | True when an estimate could be made. |
tax_rate | number | No | The tax rate, as a percentage. |
tax_cents | number | No | The estimated tax in cents. |
description | string | No | What the tax is (for example "CA sales tax"). |
message | string | No | Why no estimate was made, when it was not. |
PublicConnectProfile
The public (non-secret) Connect settings of a Direct Payment, from connect.getProfile().
| Name | Type | Required | Description |
|---|---|---|---|
enabled | boolean | Yes | True when Connect is switched on. |
integration_mode | ConnectIntegrationMode | Yes | How connected accounts are managed. |
onboarding_mode | ConnectOnboardingMode | Yes | How onboarding is performed. |
default_country | string | Yes | ISO country code new accounts default to. |
default_currency | string | Yes | ISO currency code new accounts default to. |
platform_fee_percent | number | Yes | The share of each sale the platform keeps, in percent. |
account_configurations | string[] | Yes | The capability sets requested for new accounts (for example 'merchant'). |
StartOnboardingOptions
Options of connect.startOnboarding().
| Name | Type | Required | Description |
|---|---|---|---|
return_path | string | No | Where the user returns to after finishing (hosted onboarding). |
refresh_path | string | No | Where the user returns to when the onboarding link expired (hosted onboarding). |
components | ConnectComponentName[] | No | The components to include (embedded onboarding). |