How to implement
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 FrontStream Auth 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
Endpoint
URL:
https://auth.frontstream.com/api/Authenticate/StartEmbeddedSession
Method:
POST
Content-Type:
application/json
Authentication
The API requires an API Key for authentication. This must be included in the request payload.
Body
Top-Level Fields
ApiKey
string
✅ Yes
Your API key for authentication.
EmbeddedOptions
object
✅ Yes
Configuration options for the embedded session.
EmbeddedOptions Schema
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
PaymentLines Schema
Each PaymentLines
entry represents a payment type in the transaction.
Amount
number
✅ Yes
The amount to be charged.
Type
integer
✅ Yes
Payment type identifier
Recurring
integer
✅ Yes
Indicates if the payment is recurring
Example Response Codes
{
bd150dd5-aca9-48cb-9446-f2adf156cd04
}
Example payload:
{
"ApiKey": "83d4a25d-345d-488e-b667-c2b6ccbaf83b",
"EmbeddedOptions": {
"IpAddress": "73.219.23.94",
"RedirectUrl": "https://www.yourcompany.com/ThankYouPage",
"PaymentLines": [
{
"Amount": 100.0,
"Type": 1,
"Recurring": 0
},
{
"Amount": 20.0,
"Type": 5,
"Recurring": 0
},
{
"Amount": 50.0,
"Type": 5,
"Recurring": 0
}
],
"PoweredByText": "Your Company",
"PoweredByUrl": "https://www.yourcompany.com/",
"DonateButtonText": "Submit Payment",
"Language": "en",
"Theme": ".p-card-title{ color: rgb(255, 255, 255) !important; font-family: Open Sans !important}.EPF__body{ background-color: rgb(0, 0, 0); } .card {background: transparent !important;} .p-card{background: transparent !important;} .surface-card{background: transparent !important;}.p-card-title{ color: rgb(255, 255, 255) !important; font-family: Open Sans !important}.EPF__subheading__text{ color: rgb(255, 255, 255) !important; font-family: Open Sans !important}.EPF__body__text,.p-field-checkbox,.p-steps .p-steps-item .p-steps-title{ color: rgb(255, 255, 255) !important; font-family: Montserrat !important}.p-button-label{color:rgb(19, 5, 5) !important; font-family:Roboto;}.p-button{background-color:rgb(34, 136, 231) !important;border-radius:25px;border-color: transparent !important;}.p-button:hover{background-color:rgb(21, 110, 193) !important;}.p-button-label:hover{color:rgb(44, 30, 30) !important}.gpay-card-info-container{border-radius:25px!important;}.EPF__link__text{ color: rgb(216, 243, 255) !important; font-family: Montserrat !important}.EPF__form-element, .p-dropdown{ border:none !important; -webkit-box-shadow: none; box-shadow:none; background-color: transparent; border-bottom: 0.055rem solid gray !important; }.p-steps .p-steps-item.p-highlight .p-steps-number{background: rgb(34, 136, 231) !important;}.epf-cc {color: rgb(255, 255, 255);}.epf-cc-selected {color: rgb(34, 136, 231);}.p-button {color: rgb(19, 5, 5) !important;}.EPF__form-element:focus{color: #495057; -webkit-box-shadow: none !important; box-shadow:none !important; background-color: #FFFFFF !important; border-color: #4A4A4A !important;}.EPF_form-element--error{ -webkit-box-shadow: none !important; box-shadow:none !important; background-color: #F6CCD1 !important; border-color: #DC143C !important;}.EPF_form-element--error:focus{background-color: #F6CCD1 !important;}.has-error .input-group-addon { background-color: #F6CCD1 !important }.select--error { background: #F6CCD1 }.select--error ~ .fa-angle-down { display:none }.select--error:focus ~ .fa-angle-down { display: inline }.select--error:focus ~ .fa-exclamation-circle { display: none}.select--error:focus { background-color: #F6CCD1 }.exclamation-textArea { padding-top: 3.75rem }.form-field--invalid {border-color: #d0021b !important;}.form-field--invalid .p-dropdown {border-color: #d0021b !important;}.EPF__form-element, .p-dropdown{border-radius: 0 !important; }.EPF_form-element:focus{ -webkit-box-shadow: none !important; box-shadow:none !important; background-color: transparent !important; border-color: #4A4A4A !important;}.EPF_form-element--error{ -webkit-box-shadow: none !important; box-shadow:none !important; background-color: transparent !important; border-color: #DC143C !important;}.EPF_form-element--error:focus{background-color: #F6CCD1 !important; }.has-error .form-control{ -webkit-box-shadow: none !important; box-shadow:none !important; background-color: transparent !important;}.has-error .form-control:focus{ -webkit-box-shadow: none !important; box-shadow:none !important; background-color: transparent !important;}.EPF__form-element{color: rgb(255, 255, 255); }.p-inputtext{color: rgb(255, 255, 255)}.EPF__form-element::placeholder{color: rgb(255, 255, 255)}",
"ThemeFonts": [
"Open Sans:400,500,600,700 ",
"Montserrat:400, 700 ",
"Roboto:400, 700 "
],
"DefaultCountryCode": "US",
"IframeParentDomain": "dev-www.mygiving.net"
}
}
2. Launch the Payment Form (Client-side)
Once you have the session token, you can display the payment form using an iframe modal.
Example Client Code:
vm.embeddedModel = $uibModal.open({
animation: false,
backdrop: 'static',
keyboard: false,
template:
`<div>
<button class="close-button" id="closeButton" type="button" ng-click="vm.closeIframe()">×</button>
<iframe id="frontstream_embedded_frame" height="730" width="100%" allow="payment *" scrolling="yes" marginheight="0" marginwidth="0"
src="https://epf.frontstream.com/checkout?token=${sessionToken}">
</iframe>
</div>`,
controller: "embeddedModalController",
controllerAs: "vm",
windowClass: 'modal-fullscreen'
});
vm.closeIframe = function () {
$uibModalInstance.close();
};
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 FrontStream Auth API
After receiving the payment details, you can handle any additional bookkeeping or notifications that might be needed for your application.
Endpoint
URL:
https://auth.frontstream.com/api/
Verification/VerifyAuthToken?Code=bd150dd5-aca9-48cb-9446-f2adf156cd04
Method:
GET
Content-Type:
application/json
Example Response:
{
"SessionId": "db168625-b7d0-4f8f-9fc9-362090da77c4",
"PaymentResult": {
"Successful": true,
"Message": "Approved",
"EmailAddress": "[email protected]",
"ProcessorMessage": "Successful transaction.",
"TransactionId": "19468728",
"PaymentGuid": "a771a923-eb9a-4197-8d88-ed6d2d0a7801",
"PaymentId": 33536,
"ResponseCode": "0",
"PaymentResult": 3,
"ProcessStatus": 2,
"TotalAmount": 25.0,
"AVSStreetStatus": null,
"AVSZipStatus": null,
"CVVResponse": null,
"TokenGuid": null,
"RecurringProfileGuid": null,
"PaymentResultTransactionModel": [
{
"TransactionSourceGroupId": "1",
"PaymentAmount": 25.0,
"CardFeeRate": 3.49,
"CardFeeAmount": 0.87,
"CardTypeFeeAmount": 0.0,
"TotalCommissionRate": 1.5,
"TotalCommissionAmount": 0.38,
"PartnerCommissionRate": 0.0,
"PartnerCommissionAmount": 0.0,
"FsCommissionRate": 1.5,
"FsCommissionAmount": 0.38,
"TotalFees": 1.55,
"MaxOverridePartnerCommissionRate": 4.99,
"MinOverridePartnerCommissionRate": 4.99,
"PerTransFee": 0.3,
"Tip": 0.0,
"CardFeeOnFeeAmount": 0.0
}
],
"OrganizationGuid": "18ec932d-86f4-4cbd-93f2-c1855b09d42c",
"FirstName": "Javier",
"LastName": "Mendez",
"PostalCode": "90210",
"AddressLine1": "Test",
"City": "Test",
"ProvinceCode": "CA",
"CountryCode": "US",
"CardNum": "2220",
"CardType": "Visa",
"ExpMonth": "04",
"ExpYear": "27",
"Currency": "USD",
"PaymentMethodTypeId": 3,
"PayTheFee": false,
"IsSurchargeEligible": false,
"TotalSurcharge": null,
"CheckAccountNum": null
}
}
4. Show the Thank You Page (Client-side)
Display a confirmation message to the customer.
Include any relevant details about their transaction.
Example Thank You Page:

📌 Reference
For a full working example, check our GitHub Repository:
https://github.com/frontstream-devops/Embedded-payment-demo
Test the Integration
Test your payment form integration with test credentials before going live.
Simulate various payment scenarios like successful payments, failed payments, and declined cards to ensure everything works smoothly.
Review receipts.
Go Live
Once testing is complete, switch to your production merchant credentials.
Ensure you use your live credentials and that your website is using a secure HTTPS connection.
Security Measures
Use HTTPS: Ensure your website is served over HTTPS to securely transmit information.
Track and Manage Payments
Use our existing dashboards to track payment status and view transaction details.
By following these steps, you can successfully integrate our secure and functional FrontStream Embedded Payment Form into your website.
Last updated