Payments

Open a Stripe or Asaas payment or subscription checkout with one call.

Quick start

Add Payments1 in the Designer. Use the example in a page method.

// In the payment button's async OnClick handler.
// Edit1 contains the purchase source key from your application backend.
await Payments1.Pay(Edit1.value);

Configure once

1. In RestGo, configure and activate a Stripe or Asaas gateway, its payment source, credentials, webhooks, and HTTP(S) success/cancel URLs. The trusted application backend creates the purchase.
2. In WebRAD, enable RestGo integration → Connection → Application SDK and configure the instance URL. The customer must sign in through Authentication; the component uses that shared session.
3. Add Payments from Nonvisual. Select Payments1 and set Gateway slug to the configured gateway's slug.
4. Add an Edit named Edit1 and a Button named Button1. Open the button's Interaction tab and double-click OnClick. Paste the quick-start statement into the generated method body.

Edit1 contains a purchase source key, such as 123, kept as a string. Price, currency, ownership and recurrence come from the configured RestGo source. The input is not a provider payment ID or an amount. Keys returned as PostgreSQL int8 values must stay strings to preserve precision.

Both Payments1 and this.Payments1 refer to the concrete typed component in the page or reusable. Type Payments1. and use Ctrl+Space for Monaco completion. Public method names are case-sensitive.

Pay with one call

To pay a known purchase from an async button handler:

await Payments1.Pay('123');

To use the purchase key entered in Edit1:

await Payments1.Pay(Edit1.value);

Pay restores an existing customer session, recovers or prepares the attempt, preserves its idempotency key, creates the checkout when necessary, waits for its URL, saves the operation ID and opens the hosted provider checkout. The customer completes payment there. Normal button code needs no manual PrepareCheckout, WaitForCheckout, OpenCheckout, checkpoint storage or StopWatching calls.

Start a subscription

Use this in the subscription button's async OnClick handler:

await Payments1.Subscribe(Edit1.value);

The purchase source must contain the configured subscription product and recurrence. To use the Inspector's Mode setting instead of choosing a method explicitly:

await Payments1.Checkout(Edit1.value);

Pay always selects payment, Subscribe selects subscription, and Checkout uses the configured mode. These calls return a RestGoPaymentOperation. If a saved operation is already confirmed, they return it without creating another charge or reopening checkout. Matching concurrent actions share one workflow; a conflicting action reports busy.

Confirm the payment

Select Payments1, open Interaction, and double-click OnPaymentSucceeded, the default event. In the generated handler body:

import type { WebPayments, WebPaymentsCheckoutEventDetail } from '@webrad/runtime';
// Keep the signature generated by Interaction; copy the body into that method.
class Example {
  public async Payments1PaymentSucceeded(
    sender: WebPayments,
    event: CustomEvent<WebPaymentsCheckoutEventDetail>,
  ): Promise<void> {
    Message('Payment confirmed: ' + event.detail.operation.id);
  }
}

This body belongs to the generated Payments event handler, whose event is a CustomEvent<WebPaymentsCheckoutEventDetail>. Use OnSubscriptionActivated for subscription confirmation and OnSubscriptionCanceled for cancellation or its scheduling. The full typed signatures appear in Events below.

Opening checkout is not financial confirmation. checkoutState describes checkout preparation, status describes financial state, and synchronizationPending / synchronizationError describe updating the application's purchase source. A confirmed payment may still have a pending source update. Backend authorization and fulfillment remain authoritative.

On a return page or in a refresh action, code can wait for confirmation:

const operation = await Payments1.WaitForConfirmation();
Message(operation.status);

To also wait for the purchase's source update:

const operation = await Payments1.WaitForConfirmation({
  waitForSynchronization: true,
});
Message(operation.status);

WaitForConfirmation understands payment success and subscription activation. A timeout is local and never changes the financial state or creates another charge. The backend continues processing after a local wait stops.

Return, refresh and recovery

Automatic resume restores this instance's saved attempt after session restoration, queries an already known operation ID and observes pending changes. It never creates a charge or redirects back to checkout. Automatic lookup uses the component's runtime ID, including reusable placement identity.

On another return page, or to recover explicitly:

const operation = await Payments1.Resume();
if (operation) Message(operation.status);

Resume can use the selected attempt or the most recent saved attempt for the API, customer and gateway. To choose a purchase:

const operation = await Payments1.Resume(Edit1.value);
if (operation) Message(operation.status);

For a subscription saved under a different Inspector mode:

const operation = await Payments1.Resume(Edit1.value, { mode: 'subscription' });
if (operation) Message(operation.status);

Explicit Resume can recover a lost creation response by replaying the original saved key and body. It never opens checkout. Refresh only queries a known operation and does not create one:

const operation = await Payments1.Refresh();
if (operation) Message(operation.status);

The gateway uses fixed return URLs configured in RestGo. A redirect or success flag in the URL is not payment proof. Preview/F9 has changing loopback addresses; the configured return URL does not automatically return into that Preview. Hosted provider checkout is subject to browser/frame restrictions. Native custom-scheme return handling requires a separate platform/server contract.

History and cancellation

Load the first page from a history action:

const items = await Payments1.LoadHistory();
Message(items.length);

Load the next page from a separate Load more action:

const items = await Payments1.LoadMore();
Message(items.length);

LoadHistory replaces history with one page. LoadMore appends and deduplicates records, returns the accumulated readonly array and does nothing on the final page. history, nextCursor, hasMore and OnHistoryChange support the application's list UI. Pages contain up to 50 operations ordered by UUID and omit checkout URLs. GetOperation(id) selects a history operation without inventing a purchase association; cross-device purchase lookup still requires an application-owned durable link.

In the cancel button's handler, after the customer chooses cancellation:

const operation = await Payments1.CancelSubscription();
Message(operation.provider.cancelAtPeriodEnd
  ? 'Cancellation scheduled for the paid period.'
  : operation.status);

The selected or resumed subscription supplies the operation ID automatically. Stripe schedules cancellation with the provider; Asaas removes recurrence while preserving the paid period in the normalized result. Inspect provider.periodEnd and provider.cancelAtPeriodEnd. Cancellation does not request a refund. Refresh, history and cancellation coordinate background observation internally.

Defaults and UI state

Auto resume, Auto watch and Persist attempts default to true. Poll interval (ms) defaults to 2000 and Poll timeout (ms) to 60000. The timeout bounds local workflow/observation, not the purchase's financial lifetime. Enabled never initiates a charge by itself.

Use state, busy and watching for activity; status and checkoutState for the selected operation; canOpenCheckout and canCancelSubscription for actions; and synchronizationPending / synchronizationError for source updates. OnStateChange and OnHistoryChange provide typed changes. Each page/reusable placement owns its runtime state and shares the project's RestGO customer session.

Default persistence stores recovery data before POST and before navigation, scoped to API, customer, gateway, source and mode. Browser storage and Web Locks, or a runtime-only custom storage adapter, preserve the same purchase key across participating instances/tabs. Tokens, provider secrets and checkout URLs are excluded. Browser records are not cross-device storage or Project Model configuration. Unavailable storage/locking or corrupt recovery data raises an error instead of silently generating another key. Disabling Persist attempts is an explicit advanced choice that makes the application responsible for durable recovery.

Clear, StopWatching, abort and disposal affect local state/work; they do not cancel the server transaction. Clear retains durable attempts. Logout, account changes and replacing the RestGO client cancel obsolete work and prevent late checkout opening.

Handle errors in one place

Use try/catch in the click handler, or bind OnError in Interaction. Choose one place to display a message:

try {
  await Payments1.Pay(Edit1.value);
} catch (error: unknown) {
  Message(error instanceof Error ? error.message : String(error));
}

HTTP failures retain RestGoError status, code and message; local workflow failures use WebPaymentsError.kind. An uncertain checkout keeps its original recovery data and requires observation/support. Neither a network failure nor an unknown financial status starts another charge automatically.

Advanced control

Pay, Subscribe and Checkout open checkout by default. An authored custom UI can opt out of navigation:

const operation = await Payments1.Pay(Edit1.value, { openCheckout: false });
Message(operation.checkoutState);

The existing lower-level APIs remain available. PrepareCheckout is synchronous, CreateCheckout sends a prepared attempt without opening checkout, and WaitForCheckout / OpenCheckout provide manual control. ExportCheckpoint / RestoreCheckpoint support custom recovery integration. Prefer the one-call actions for the standard flow.

For direct transport-level calls, see the RestGO SDK payments API. It uses the customer's Authentication JWT exclusively. Administrative and provider credentials stay in RestGo. The documentation's editable examples do not execute payments on this website.

More examples

// Paste into Button1Click; Edit1 contains a backend purchase key.
Button1.enabled = false;
try {
  await Payments1.Pay(Edit1.value);
} catch (error: unknown) {
  Message(error instanceof Error ? error.message : String(error));
} finally {
  Button1.enabled = true;
}

import type { WebPayments, WebPaymentsCheckoutEventDetail } from '@webrad/runtime';
class Example {
  public async Payments1PaymentSucceeded(
    sender: WebPayments,
    event: CustomEvent<WebPaymentsCheckoutEventDetail>,
  ): Promise<void> {
    Message('Payment confirmed: ' + event.detail.operation.id);
    console.log(sender.synchronizationPending);
  }
}

import type { WebPayments, WebPaymentsErrorEventDetail } from '@webrad/runtime';
class Example {
  public async Payments1Error(
    sender: WebPayments,
    event: CustomEvent<WebPaymentsErrorEventDetail>,
  ): Promise<void> {
    Message(event.detail.error.message);
    console.log(event.detail.action, event.detail.operationId, sender.state);
  }
}

const operation = await Payments1.Refresh();
if (operation) {
  Message(operation.status);
  console.log(operation.synchronizationPending, operation.synchronizationError);
}

const operation = await Payments1.Resume(undefined, { watch: false });
if (operation) Message(operation.status);

// The operation must belong to the authenticated customer.
const operation = await Payments1.CancelSubscription('00000000-0000-4000-8000-000000000001');
console.log(operation.provider.periodEnd, operation.provider.cancelAtPeriodEnd);

Inspector properties

Component options and defaults. Fields without runtime access are configured in the Inspector.

API in code

Pay(sourceKey: string, options?: WebPaymentsCheckoutOptions): Promise<import("@webrad/restgo-sdk").RestGoPaymentOperation>;

await Payments1.Pay('123');

Subscribe(sourceKey: string, options?: WebPaymentsCheckoutOptions): Promise<import("@webrad/restgo-sdk").RestGoPaymentOperation>;

await Payments1.Subscribe('123');

Checkout(sourceKey: string, options?: WebPaymentsCheckoutOptions): Promise<import("@webrad/restgo-sdk").RestGoPaymentOperation>;

await Payments1.Checkout('123');

Resume(sourceKey?: string, options?: WebPaymentsResumeOptions): Promise<import("@webrad/restgo-sdk").RestGoPaymentOperation | null>;

await Payments1.Resume();

Refresh(options?: import("@webrad/restgo-sdk").RestGoPaymentRequestOptions): Promise<import("@webrad/restgo-sdk").RestGoPaymentOperation | null>;

await Payments1.Refresh();

LoadHistory(options?: import("@webrad/restgo-sdk").RestGoPaymentListOptions): Promise<readonly import("@webrad/restgo-sdk").RestGoPaymentOperation[]>;

await Payments1.LoadHistory();

LoadMore(options?: import("@webrad/restgo-sdk").RestGoPaymentRequestOptions): Promise<readonly import("@webrad/restgo-sdk").RestGoPaymentOperation[]>;

await Payments1.LoadMore();

WaitForConfirmation(options?: WebPaymentsConfirmationOptions): Promise<import("@webrad/restgo-sdk").RestGoPaymentOperation>;

await Payments1.WaitForConfirmation();

PrepareCheckout(sourceKey: string, mode?: import("@webrad/restgo-sdk").RestGoPaymentMode): WebPaymentsCheckpoint;

Payments1.PrepareCheckout('123', 'payment');

CreateCheckout(options?: import("@webrad/restgo-sdk").RestGoPaymentRequestOptions): Promise<import("@webrad/restgo-sdk").RestGoPaymentOperation>;

// Advanced: the normal one-call action is Payments1.Pay('123').
Payments1.PrepareCheckout('123', 'payment');
const operation = await Payments1.CreateCheckout();
console.log(operation.id, operation.checkoutState);

GetOperation(id: string, options?: import("@webrad/restgo-sdk").RestGoPaymentRequestOptions): Promise<import("@webrad/restgo-sdk").RestGoPaymentOperation>;

await Payments1.GetOperation('00000000-0000-4000-8000-000000000001');

ListOperations(options?: import("@webrad/restgo-sdk").RestGoPaymentListOptions): Promise<import("@webrad/restgo-sdk").RestGoPaymentOperationList>;

await Payments1.ListOperations();

CancelSubscription(options?: import("@webrad/restgo-sdk").RestGoPaymentRequestOptions): Promise<import("@webrad/restgo-sdk").RestGoPaymentOperation>;
CancelSubscription(id: string, options?: import("@webrad/restgo-sdk").RestGoPaymentRequestOptions): Promise<import("@webrad/restgo-sdk").RestGoPaymentOperation>;

await Payments1.CancelSubscription();

WaitForCheckout(id?: string, options?: WebPaymentsObservationOptions): Promise<import("@webrad/restgo-sdk").RestGoPaymentOperation>;

await Payments1.WaitForCheckout();

StartWatching(id?: string, options?: WebPaymentsObservationOptions): void;

Payments1.StartWatching();

StopWatching(): void;

Payments1.StopWatching();

OpenCheckout(): void;

Payments1.OpenCheckout();

ExportCheckpoint(): WebPaymentsCheckpoint;

Payments1.ExportCheckpoint();

RestoreCheckpoint(value: unknown): WebPaymentsCheckpoint;

// Advanced: normal Pay/Subscribe/Resume manage persistence automatically.
const checkpoint = Payments1.ExportCheckpoint();
Payments1.Clear();
Payments1.RestoreCheckpoint(checkpoint);

Clear(): void;

Payments1.Clear();

dispose(): void;

// Call only when disposing of an instance whose lifecycle you control.
Payments1.dispose();

bindEvent(eventName: string, handler: WebComponentEventHandler<this> | null): () => void;

emit(eventName: string, detail?: unknown): boolean;

Events

Link methods in Interaction. How to use events.

import type { WebPayments, WebPaymentsCheckoutEventDetail } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Payments1PaymentSucceeded(
    sender: WebPayments,
    event: CustomEvent<WebPaymentsCheckoutEventDetail>,
  ): Promise<void> {
    console.log(event.detail);
    const { operation } = event.detail;
    console.log(operation);
  }
}

import type { WebPayments, WebPaymentsCheckoutEventDetail } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Payments1SubscriptionActivated(
    sender: WebPayments,
    event: CustomEvent<WebPaymentsCheckoutEventDetail>,
  ): Promise<void> {
    console.log(event.detail);
    const { operation } = event.detail;
    console.log(operation);
  }
}

import type { WebPayments, WebPaymentsCheckoutEventDetail } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Payments1SubscriptionCanceled(
    sender: WebPayments,
    event: CustomEvent<WebPaymentsCheckoutEventDetail>,
  ): Promise<void> {
    console.log(event.detail);
    const { operation } = event.detail;
    console.log(operation);
  }
}

import type { WebPayments, WebPaymentsCheckoutEventDetail } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Payments1CheckoutCreated(
    sender: WebPayments,
    event: CustomEvent<WebPaymentsCheckoutEventDetail>,
  ): Promise<void> {
    console.log(event.detail);
    const { operation } = event.detail;
    console.log(operation);
  }
}

import type { WebPayments, WebPaymentsCheckoutEventDetail } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Payments1CheckoutReady(
    sender: WebPayments,
    event: CustomEvent<WebPaymentsCheckoutEventDetail>,
  ): Promise<void> {
    console.log(event.detail);
    const { operation } = event.detail;
    console.log(operation);
  }
}

import type { WebPayments, WebPaymentsCheckoutEventDetail } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Payments1CheckoutOpened(
    sender: WebPayments,
    event: CustomEvent<WebPaymentsCheckoutEventDetail>,
  ): Promise<void> {
    console.log(event.detail);
    const { operation } = event.detail;
    console.log(operation);
  }
}

import type { WebPayments, WebPaymentsOperationEventDetail } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Payments1OperationChange(
    sender: WebPayments,
    event: CustomEvent<WebPaymentsOperationEventDetail>,
  ): Promise<void> {
    console.log(event.detail);
    const { previous, operation } = event.detail;
    console.log(previous, operation);
  }
}

import type { WebPayments, WebPaymentsSynchronizationEventDetail } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Payments1SynchronizationChange(
    sender: WebPayments,
    event: CustomEvent<WebPaymentsSynchronizationEventDetail>,
  ): Promise<void> {
    console.log(event.detail);
    const { operation, pending, error } = event.detail;
    console.log(operation, pending, error);
  }
}

import type { WebPayments, WebPaymentsHistoryEventDetail } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Payments1HistoryChange(
    sender: WebPayments,
    event: CustomEvent<WebPaymentsHistoryEventDetail>,
  ): Promise<void> {
    console.log(event.detail);
    const { items, nextCursor, hasMore } = event.detail;
    console.log(items, nextCursor, hasMore);
  }
}

import type { WebPayments, WebPaymentsStateEventDetail } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Payments1StateChange(
    sender: WebPayments,
    event: CustomEvent<WebPaymentsStateEventDetail>,
  ): Promise<void> {
    console.log(event.detail);
    const { previous, state } = event.detail;
    console.log(previous, state);
  }
}

import type { WebPayments, WebPaymentsResumeEventDetail } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Payments1Restored(
    sender: WebPayments,
    event: CustomEvent<WebPaymentsResumeEventDetail>,
  ): Promise<void> {
    console.log(event.detail);
    const { checkpoint, operation, automatic } = event.detail;
    console.log(checkpoint, operation, automatic);
  }
}

import type { WebPayments, WebPaymentsErrorEventDetail } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Payments1Error(
    sender: WebPayments,
    event: CustomEvent<WebPaymentsErrorEventDetail>,
  ): Promise<void> {
    console.log(event.detail);
    const { action, operationId, error } = event.detail;
    console.log(action, operationId, error);
  }
}

import type { WebPayments, WebPaymentsRequestEventDetail } from '@webrad/runtime';
// Copy this method into the page class and link it in Interaction.
class Example {
  public async Payments1RequestComplete(
    sender: WebPayments,
    event: CustomEvent<WebPaymentsRequestEventDetail>,
  ): Promise<void> {
    console.log(event.detail);
    const { action, operationId, error } = event.detail;
    console.log(action, operationId, error);
  }
}