Page cover

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

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

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)

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

  • BiWeekly = 3

  • Monthly = 4

  • BiMonthly = 5

  • Quarterly = 6

  • SemiAnnually = 7

  • Annually = 8

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
Description

Successful

bool

"true" if the transaction was processed successfully, and "false" if the transaction was not processed successfully.

Message

string

Payment Gateway response message

ProcessorMessage

string

Response from the credit card processing bank.

TransactionId

string

Payment Gateway TransactionId

PaymentGuid

guid

Payment API Payment GUID

PaymentId

interger

Payment API Payment Id

ResponseCode

string

"-100" - Transaction NOT Processed "0" - Approved

PaymentResult

interger

possible values: Pending = 1, Processing = 2, Successful = 3, Failed = 4, Refunded = 5, Cancelled = 6

ProcessStatus

interger

possible values: NotProcessed = 1 , Authorized = 2 , Settled = 4 , Rejected = 5, RefundRequired = 6, AwaitingRefund = 7, Refunded = 8 , Cancelled = 9, Chargeback = 10, RefundRejected = 11

TotalAmount

decimal

The total amount processed toward the cardholder's account.

TokenGuid

guid?

Payment API Token GUID if available to return

ExternalCardToken

string

if available to return - represents 3rd party gateway card token

ExternalCheckToken

string

if available to return - represents 3rd party gateway check token

CardNum

string

last 4 digits of card

CheckAccountNum

string

last 4 digits of check account

PaymentMethodTypeId

interger

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

CardType

string

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

ProcessorGuid

guid

ProcessorGuid used

TranId

string

Unique Tran Id

IsSurchargeEligible

bool?

Was card used Surcharge eligible

TotalSurcharge

decimal?

Total surcharge amount.

AVSResponse

string

Address Verification Response if available

AVSStreetStatus

string

Address Verification Street Status if available

AVSZipStatus

string

Address Verification Zip Status if available

CVVResponse

string

Card Verification Response if available

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.

PreviousPayment Methods processNextCompare Embedded Form and Direct API integration

Last updated