Ctrlk
Page cover
For the complete documentation index, see llms.txt. This page is also available as Markdown.

How to implement

FrontStream Embedded Payment Form Implementation overview

The key steps to integrate our FrontStream Embedded Payment Form into your website are:

  1. Setup and configure your merchant account.

  2. Integrate our FrontStream Embedded Payment Form into your site.

  3. Test the integration thoroughly using our UAT test site with test cards.

  4. 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"). If not provided, defaults to "FrontStream"

PoweredByUrl

string

❌ No

The URL users will be directed to when clicking the PoweredByText. If not provided, defaults to https://www.frontstream.com

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".

ExternalEventId

string

❌ No

Customer event Id which can be used in Payment API reporting

ExternalEventName

string

❌ No

Customer event name which can be used in Payment API reporting

TokenizeCard

bool

❌ No

If set to 'True', when a Card or ACH Check account is entered, will generate and return a token Guid for use in future payments.

ExternalCardToken

string

❌ No

Customer credit card token generated outside of the Embedded Form (e.g. Argofire)

ExternalCheckToken

string

❌ No

ACH account token generated outside of the embedded form

TokenGuid

string

❌ No

Card/ACH Token generated from a previous embedded form payment

TranId

string

❌ No

Your systems unique id/reference/invoice - Max Length (100)

ShowTransactionId

bool

❌ No

'True' will display the TranId on the checkout form

TransactionIdText

string

❌ No

The text to display in front of the TranId. Example: "Invoice#:"

FirstName

string

❌ No

Customer First name -Max Length (50)

LastName

string

❌ No

Customer Last name -Max Length (50)

Email

string

❌ No

Customer email -Max Length (100)

Street

string

❌ No

Customer Street -Max Length (50)

City

string

❌ No

Customer City -Max Length (50)

State

string

❌ No

Customer State -2 char US state code, 3 char may be used for other non-US

Zip

string

❌ No

Customer Zip - Max Length (10)

Country

string

❌ No

Customer Country - 2 char country code - Example: "US".

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

ExternalLineId

string

❌ No

Use this to track individual line items -Max Length (100)

Payment Types

  • Donation=1

  • Auction=3

  • Ticket=4

  • Registration=5

  • PaymentNoFee=12

Recurring Options

  • None=0

  • Daily = 1

  • Weekly = 2

  • Bi-Weekly = 3

  • Monthly = 4

  • Bi-Monthly = 5

  • Quarterly = 6

  • Semi-Annually = 7

  • Annually = 8

  • Semi-Monthly = 9

Example Response Codes

Example payload:

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:

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.

Example initial screen
Example Contact step
Example Payment step
Example Confirmation step

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:

Response Data
Field
Type
Nullable
Notes

SessionId

guid

No

Outer response wrapper — your session identifier.

Successful

bool

No

true when the transaction processed successfully.

Message

string

Yes

Payment Gateway response message.

ProcessorMessage

string

Yes

Response from the credit card processing bank.

TransactionId

string

Yes

Payment Gateway transaction ID.

PaymentGuid

guid

No

Payment API payment GUID.

PaymentId

integer

No

Payment API payment ID.

ResponseCode

string

Yes

-100 indicates an unprocessed transaction. 0 indicates approval.

PaymentResult

integer

No

Pending = 1 (not currently used), Processing = 2 (not currently used), Successful = 3, Failed = 4, Refunded = 5, Cancelled = 6.

ProcessStatus

int

No

1 = Not Processed, 2 = Awaiting Auth, 4 = Authorized, 5 = Rejected.

TotalAmount

decimal

No

Total amount processed toward the cardholder's account.

TokenGuid

guid

Yes

Payment API token GUID, when available.

ExternalCardToken

string

Yes

Third-party gateway card token, when available.

ExternalCheckToken

string

Yes

Third-party gateway check token, when available.

ExternalCustomerId

string

Yes

Payment gateway-generated customer identifier.

ExternalConstituentId

string

Yes

Your system's customer identifier — returned as provided.

CardNum

string

Yes

Last four card digits.

CheckAccountNum

string

Yes

Last four check-account digits.

PaymentMethodTypeId

integer

Yes

None = 0, AmericanExpress = 1, MasterCard = 2, Visa = 3, Discover = 4, DinersClub = 5, ACH = 7, GOOGLEPAY = 8, APPLEPAY = 9.

CardType

string

Yes

American Express, Mastercard, Visa, Discover, Diners Club, or Undefined.

ProcessorGuid

guid

Yes

Payment processor identifier.

OrganizationGuid

guid

Yes

Organization identifier.

RecurringProfileGuid

guid

Yes

Recurring payment profile identifier, when applicable.

PaymentResultTransactionModel

array

Yes

Fee and commission breakdown per transaction source. See sub-fields below.

FirstName

string

Yes

LastName

string

Yes

EmailAddress

string

Yes

ExpMonth

string

Yes

Card expiration month, using two digits.

ExpYear

string

Yes

Card expiration year, using two digits.

Currency

string

Yes

ISO currency code, such as USD.

PayTheFee

bool

No

Whether the donor covered the processing fee.

TranId

string

Yes

Client's unique ID, reference, or invoice number.

IsSurchargeEligible

bool

Yes

Whether the card is surcharge eligible.

TotalSurcharge

decimal

Yes

Total surcharge amount.

AVSResponse

string

Yes

Address Verification response, when available.

AVSStreetStatus

string

Yes

Address Verification street status, when available.

AVSZipStatus

string

Yes

Address Verification ZIP status, when available.

CVVResponse

string

Yes

Card Verification response, when available.

SessionId

string

No

Embedded Payment Form session identifier. Use it to look up transaction details.

PaymentResultTransactionModel sub-fields
Field
Type
Nullable
Notes

TransactionSourceGroupId

string

Yes

Transaction source group identifier.

PaymentAmount

decimal

Yes

Payment amount for this source.

CardFeeRate

decimal

Yes

CardFeeAmount

decimal

Yes

CardTypeFeeAmount

decimal

Yes

TotalCommissionRate

decimal

Yes

TotalCommissionAmount

decimal

Yes

PartnerCommissionRate

decimal

Yes

PartnerCommissionAmount

decimal

Yes

FsCommissionRate

decimal

Yes

FrontStream commission rate.

FsCommissionAmount

decimal

Yes

FrontStream commission amount.

TotalFees

decimal

Yes

Total fees for this source.

MaxOverridePartnerCommissionRate

decimal

No

MinOverridePartnerCommissionRate

decimal

No

PerTransFee

decimal

Yes

Per-transaction fee.

Tip

decimal

No

CardFeeOnFeeAmount

decimal

Yes

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:

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.

Interested in creating and configuring a Payment Link?

Simply use your same API Key configured for embedding our FrontStream Payment Form to create and configure a 'one-click' Payment Link to accept payments. Creating and configuring your pay link uses similar parameters as creating your Embedded Payment Form session token request described in Step 1 above. Creating a Payment Link is described here:

Create a Payment Link
PreviousPayment Methods process
NextCreate a Payment Link

Last updated