SDK API Reference

createPaymentFrame(options)

Creates or reuses an iframe in the supplied container.

interface CheckoutParams {
  target: PaymentTarget.Checkout
  checkoutId: string
  clientSecret: string
  parentOrigin?: string
}

interface Options {
  el: HTMLElement
  origin?: string
  params: CheckoutParams
}

origin is the Belong frame origin. Checkout frames default to BELONG_CHECKOUT_ORIGIN (https://checkin.belong.net); legacy payment frames continue to default to https://app.belong.net. parentOrigin is the store origin. In a browser the SDK fills parentOrigin from window.location.origin when it is omitted.

The SDK puts clientSecret and parentOrigin in the URL fragment. Fragments are not sent in HTTP requests, so the checkout secret does not enter web-server access logs or referrer headers.

isPaymentEvent(event, expectedOrigin?)

Validates the message payload. When expectedOrigin is provided, it also requires an exact origin match.

Always check both the origin and event.source === frame.contentWindow in production.

Use the exported BELONG_CHECKOUT_ORIGIN constant for hosted checkout events so URL generation and message validation stay aligned.

PaymentTarget.Checkout

Opens /checkout/{checkoutId} instead of the legacy /payments route.

PaymentEvent

enum PaymentEvent {
  Loaded = 'loaded',
  PaymentSuccess = 'payment-success',
  PaymentError = 'payment-error',
  PaymentCanceled = 'payment-canceled',
}

The existing event payload types remain backward-compatible. Checkout success may also include checkoutId, externalOrderId, and transactionHash.