Payment Widget

The payment widget is a crucial component for implementing embedded payment sessions. This guide explains how to integrate the widget into your application.

Note: The payment widget is only required when using embedded sessions. For hosted sessions, StableMint handles the payment interface automatically.

Overview

The payment widget provides a seamless payment experience by embedding the payment flow directly within your website. It handles all the necessary UI components, form validations, and payment processing logic.

📦 Installation

The stable-payment-gateway widget can be installed via npm or included via a CDN.

Install the package using your preferred package manager:

npm install ***PACKAGE_NAME***

Once installed, import and register the widget in your application:

import { register } from "***PACKAGE_NAME***";

register({
  ...configs, // custom configurations
  baseUrl: // PIS service url
})

ℹ️ See the Custom Configuration guide for full details on the configs object.

Implementation

The payment widget is implemented as a web component. Here's how to use it in your application:

<stable-payment-gateway
  :session-id="activeSession?.sessionId"
  :currency="activeSession?.currency"
  :country="activeSession?.country"
  :deposit-amount="activeSession?.amount"
  :allowed-payment-methods="JSON.stringify(activeSession?.allowedPaymentMethods)"
  :saved-banks="JSON.stringify(activeSession?.savedBanks)"
  :payment-method="activeSession?.paymentMethod"
  site-id="3"
  @exit="activeSession = null"
  @manual-success-primary-click="handleManualSuccessPrimary"
  @manual-success-secondary-click="handleManualSuccessSecondary"
/>

Using Session Response Data

When you create an embedded session using the /session/embedded endpoint, you'll receive a response that contains all the necessary data to initialize the widget. Here's how to use it:

// Example of handling the embedded session response
const response = await createEmbeddedSession({
  userId: "user123",
  userEmail: "[email protected]",
  userCountryCode: "DE",
  currency: "EUR",
  amount: 100,
});

// The response will contain:
const activeSession = {
  sessionId: response.sessionId, // Required: Unique session identifier
  currency: response.currency, // Required: Payment currency
  country: response.userCountryCode, // Required: User's country code
  amount: response.amount, // Required: Payment amount
  allowedPaymentMethods: response.allowedPaymentMethods, // Required: Available payment methods
  savedBanks: response.savedBanks, // Required: User's saved banks
  paymentMethod: response.paymentMethod, // Optional: Pre-selected payment method
};

// Now you can pass this data to the widget

The response from the embedded session endpoint includes:

Field	Type	Description	Required
sessionId	String	Unique identifier for the session	Yes
currency	String	Payment currency code	Yes
userCountryCode	String	User's country code	Yes
amount	Number	Payment amount	Yes
allowedPaymentMethods	Array	Available payment methods	Yes
savedBanks	Array	User's saved banks	Yes
paymentMethod	String	Pre-selected payment method	No

Component Props

Prop	Type	Description	Required
session-id	String	The ID of the active payment session	Yes
currency	String	The currency code for the payment	Yes
country	String	The country code for the payment	Yes
deposit-amount	String	The amount to be deposited	Yes
allowed-payment-methods	String	JSON string of allowed payment methods	Yes
saved-banks	String	JSON string of user's saved banks	Yes
payment-method	String	The selected payment method	No
site-id	String	Your site identifier	Yes

Events

Event	Description	Payload
exit	Emitted when the user exits the payment flow	None
manual-success-primary-click	Emitted when user clicks primary action after manual transfer	None
manual-success-secondary-click	Emitted when user clicks secondary action after manual transfer	None

Widget Flow

The widget implements a step-based flow:

1. Deposit Initialization (DEPOSIT_INIT)

   • Initial amount input
   • Currency display
   • Terms acceptance

2. Payment Method Selection (PAYMENT_METHOD)

   • Available payment methods display
   • Method selection

3. Manual Transfer Flow

   • Transfer details (MANUAL_TRANSFER)
   • Transfer summary (MANUAL_TRANSFER_SUMMARY)

4. Open Banking Flow

   • Bank selection (BANK_SELECTOR)
   • Bank confirmation (BANK_CONFIRM)
   • Additional fields if required (BANK_EXTRA_FIELDS)

Best Practices

1. Session Management

   • Always validate session data before rendering
   • Handle session expiration
   • Implement proper error handling
   • Clear session data on exit

2. Security

   • Always use HTTPS
   • Implement proper CSP headers
   • Validate all user inputs
   • Sanitize data before passing to the component

3. User Experience

   • Test the widget on different devices
   • Ensure proper loading states
   • Handle errors gracefully
   • Implement proper session management

4. Integration

   • Test thoroughly in sandbox environment
   • Monitor widget events
   • Implement proper error handling
   • Handle component lifecycle properly

5. Performance

   • Load widget assets asynchronously
   • Optimize SVG icons
   • Minimize DOM updates
   • Use proper data serialization for props

Troubleshooting

Common issues and solutions:

1. Widget not loading

   • Check CSP headers
   • Verify asset paths
   • Check network connectivity
   • Ensure web components are supported

2. Payment failures

   • Verify configuration
   • Check payment limits
   • Validate user input
   • Check session validity

3. UI issues

   • Check CSS conflicts
   • Verify responsive design
   • Test on different browsers
   • Ensure proper component mounting

4. Data issues

   • Verify JSON stringification
   • Check prop types
   • Validate session data
   • Handle null/undefined values

5. Flow issues

   • Check payment method availability
   • Verify bank list loading
   • Ensure proper step transitions
   • Handle popup states correctly

For more detailed implementation guides, refer to:

• Embedded Session Documentation
• Payment Session Overview