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:
1. used to launch the embedded payment form in a modal window
2. 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

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.

Field

Type

Required

Description

Amount

number

✅ Yes

The amount to be charged.

Type

integer

✅ Yes

Payment type identifier

Recurring

integer

✅ Yes

Indicates if the payment is recurring

Payment Types

Donation=1
Auction=3
Ticket=4
Registration=5
PaymentNoFee=12

Recurring Options

None=0
Daily = 1
Weekly = 2
BiWeekly = 3
Monthly = 4
BiMonthly = 5
Quarterly = 6
SemiAnnually = 7
Annually = 8

Example Response Codes

{
  bd150dd5-aca9-48cb-9446-f2adf156cd04
}

{
  "error": "Invalid API Key"
}

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();
};

@media (max-width: 767px) {
  .modal.modal-fullscreen, .bootstrap-fs-modal .modal {
    box-shadow: 0px 0px 0px 100px white;
  }
  .modal.modal-fullscreen .modal-dialog, .bootstrap-fs-modal .modal .modal-dialog {
    margin: 0;
    height: 100%;
    max-width: 100%;
  }
  .modal.modal-fullscreen .modal-dialog .modal-content, .bootstrap-fs-modal .modal .modal-dialog .modal-content {
    border-style: none;
    border-radius: 0;
    height: 100%;
  }
  .modal.modal-fullscreen .modal-dialog .modal-content .modal-header, .bootstrap-fs-modal .modal .modal-dialog .modal-content .modal-header {
    justify-content: flex-start;
    min-height: 50px;
    line-height: 50px;
    padding: 0;
    background-color: #f8f8f8;
  }
  .modal.modal-fullscreen .modal-dialog .modal-content .modal-header .modal-title, .bootstrap-fs-modal .modal .modal-dialog .modal-content .modal-header .modal-title {
    white-space: nowrap;
    line-height: 50px;
    font-size: 1.1rem;
  }
  .modal.modal-fullscreen .modal-dialog .modal-content .modal-header .close, .bootstrap-fs-modal .modal .modal-dialog .modal-content .modal-header .close {
    float: none;
    order: -1;
    margin: 0;
    padding: 0;
    margin-right: 12px;
    height: 50px;
    color: transparent;
    text-shadow: none;
    opacity: 1;
  }
  .modal.modal-fullscreen .modal-dialog .modal-content .modal-header .close:before, .bootstrap-fs-modal .modal .modal-dialog .modal-content .modal-header .close:before {
    border-style: solid;
    border-color: #007bff;
    border-width: 0.15em 0.15em 0 0;
    content: '';
    display: inline-block;
    height: 0.5em;
    left: 0.55em;
    position: relative;
    top: 0.28em;
    transform: rotate(-45deg);
    vertical-align: top;
    width: 0.5em;
    transform: rotate(-135deg);
  }
  .modal.modal-fullscreen .modal-dialog .modal-content .modal-footer, .bootstrap-fs-modal .modal .modal-dialog .modal-content .modal-footer {
    position: absolute;
    top: 0;
    right: 0;
    padding: 0;
    margin: 0 10px 0 0;
    height: 50px;
    min-height: 50px;
    line-height: 50px;
    background-color: #f8f8f8;
  }
  .modal.modal-fullscreen .modal-dialog .modal-content .modal-footer .btn, .bootstrap-fs-modal .modal .modal-dialog .modal-content .modal-footer .btn {
    border: none;
    background-color: transparent;
    margin: 0 0 0 10px;
    padding: 0;
    outline: none;
    box-shadow: none;
    font-size: 1.0rem;
    color: #007bff;
  }
  .modal.modal-fullscreen .modal-dialog .modal-content .modal-footer .btn:hover, .modal.modal-fullscreen .modal-dialog .modal-content .modal-footer .btn:active, .bootstrap-fs-modal .modal .modal-dialog .modal-content .modal-footer .btn:hover, .bootstrap-fs-modal .modal .modal-dialog .modal-content .modal-footer .btn:active {
    text-decoration: underline;
  }
  .modal.modal-fullscreen .modal-dialog .modal-content .modal-footer .btn[data-dismiss="modal"], .bootstrap-fs-modal .modal .modal-dialog .modal-content .modal-footer .btn[data-dismiss="modal"] {
    display: none;
  }
  .modal.modal-fullscreen .modal-dialog .modal-content .modal-footer .material-icons, .bootstrap-fs-modal .modal .modal-dialog .modal-content .modal-footer .material-icons {
    vertical-align: middle;
  }
  .modal.modal-fullscreen .modal-dialog .modal-content .modal-footer .fa, .bootstrap-fs-modal .modal .modal-dialog .modal-content .modal-footer .fa {
    vertical-align: middle;
    font-size: 1.25em;
  }
  .modal.modal-fullscreen .modal-dialog .modal-content .modal-body, .bootstrap-fs-modal .modal .modal-dialog .modal-content .modal-body {
    flex-shrink: 3;
    overflow: auto;
    -webkit-overflow-scrolling: touch;
  }
  .modal.modal-fullscreen-bottom-footer .modal-dialog .modal-content .modal-footer, .modal-fullscreen-bottom-footer .modal .modal-dialog .modal-content .modal-footer {
    position: inherit;
    top: inherit;
    right: inherit;
    padding: 15px;
    margin: 0;
  }
  .modal.modal-fullscreen-bottom-footer .modal-dialog .modal-content .modal-footer .btn, .modal-fullscreen-bottom-footer .modal .modal-dialog .modal-content .modal-footer .btn {
    margin: 0 0 0 18px;
  }
}
@media (min-width: 768px) {
  .modal.modal-fullscreen .modal-dialog .modal-content, .bootstrap-fs-modal .modal .modal-dialog .modal-content {
    max-height: calc(100vh - 60px);
  }
  .modal.modal-fullscreen .modal-dialog .modal-content .modal-body, .bootstrap-fs-modal .modal .modal-dialog .modal-content .modal-body {
    flex-shrink: 3;
    overflow: auto;
    -webkit-overflow-scrolling: touch;
  }
}

  .close-button {
      position: absolute;
      top: 10px;
      right: 10px;
      font-size: 24px;
      color: #444444;
      background-color: rgba(250, 250, 250, 0.5); /* Semi-transparent background */
      border: none;
      border-radius: 50%;
      width: 36px;
      height: 36px;
      cursor: pointer;
      display: flex;
      align-items: center;
      justify-content: center;
      transition: background-color 0.3s ease;
  }

      .close-button:hover {
          background-color: rgba(245, 245, 245, 0.7);
      }

Note the use of allow="payment *"

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 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
  }
}

Payment Methods

AmericanExpress = 1
MasterCard = 2
Visa = 3
Discover = 4
DinersClub = 5
JCB = 6
ACH = 7
GooglePay = 8
ApplePay=9
Stripe=10

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.

PreviousPayment Methods process NextCompare Embedded Form and Direct API integration

Last updated 2 days ago