FrontStream Embedded Payment Form Implementation overview
The key steps to integrate our FrontStream Embedded Payment Form into your website are:
Setup and configure your merchant account.
Integrate our FrontStream Embedded Payment Form into your site.
Test the integration thoroughly using our UAT test site with test cards.
Move to live credentials and ensure proper security practices are followed.
To elaborate further on each of these steps:
Merchant Account setup/creation and configuration
Sign up for a merchant account.
Configure:
Your supported payment method types: credit cards, Apple Pay, Google Pay, and ACH
Your Surcharge configuration – FrontStream Surcharge Program review prior to configuration for Merchant compliance
Embedding Our Payment Form in Your Application
Our payment form supports both one-time payments (for single or multiple line items) and recurring payments. Once your customer selects their payment items and clicks your Payment button, you can initiate the embedded payment process.
1. Initialize the Payment Form (Server-side)
To begin, create a JSON payload that defines the payment details, then POST that to the FrontStreamAuth API.
The API will return a session token, which serves two purposes:
used to launch the embedded payment form in a modal window
used to synchronize the payment result with your starting data
The API requires an API Key for authentication. This must be included in the request payload.
Body
Top-Level Fields
Field
Type
Required
Description
ApiKey
string
✅ Yes
Your API key for authentication.
EmbeddedOptions
object
✅ Yes
Configuration options for the embedded session.
EmbeddedOptions Schema
Field
Type
Required
Description
IpAddress
string
✅ Yes
The client IP address
RedirectUrl
string
✅ Yes
The URL to which the user will be redirected after payment.
PaymentLines
array
✅ Yes
An array of payment line objects specifying amounts and types.
IframeParentDomain
string
✅ Yes
Your application's domain
PoweredByText
string
❌ No
Text to display for branding purposes (e.g., "Powered by Your Company").
PoweredByUrl
string
❌ No
The URL users will be directed to when clicking the PoweredByText.
DonateButtonText
string
❌ No
Text displayed on the submit payment button. Default is "Submit Payment".
Language
string
❌ No
The language of the embedded session. Default is "en".
Theme
string
❌ No
CSS string for custom styling of the embedded session.
ThemeFonts
array
❌ No
Array of fonts to be used in the session.
DefaultCountryCode
string
❌ No
The default country code for user input. Example: "US".
EventId
string
❌ No
Use payment methods configured at a project level
Note: The IP Address must be the client IP address of your application hosting the Embedded Payment Form, and not a server-side IP address. This is to get the best result from reCAPTCHA security.
PaymentLines Schema
Each PaymentLines entry represents a payment type in the transaction.
This is allows Apple Pay and other payment methods to render in the iframe
Once the form is rendered in the iframe, it will handle all further actions until the transaction is either successful or canceled.
3. Implement a return URL endpoint (server-side)
After a successful payment, the form redirects to the return URL (configured in Step 1).
If your merchant setup included receipt emails, the customer will automatically receive a receipt upon a successful transaction via the FrontStream Payment Processing.
Extract the Payment Result
Your return endpoint will receive a one-time-use token as a parameter
Use this token to securely retrieve transaction details from the FrontStreamAuth API
After receiving the payment details, you can handle any additional bookkeeping or notifications that might be needed for your application.
