# 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)
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".
{% hint style="info" %}
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.
{% endhint %}
***
#### **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
{% tabs %}
{% tab title="201" %}
```json
{
bd150dd5-aca9-48cb-9446-f2adf156cd04
}
```
{% endtab %}
{% tab title="400" %}
```json
{
"error": "Invalid API Key"
}
```
{% endtab %}
{% endtabs %}
#### 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**:
{% tabs %}
{% tab title="JavaScript" %}
```javascript
vm.embeddedModel = $uibModal.open({
animation: false,
backdrop: 'static',
keyboard: false,
template:
`
|
| **CardType** | `string` | American Express, Mastercard, Visa, Discover, Diners Club, Undefined |
| **ProcessorGuid** | `guid` | ProcessorGuid used |
| **TranId** | `string` | The client's unique id/reference/invoice # |
| **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 |
| **EPFSessionId** | `string` | Identifier of the Payement Form session. Can be used to lookup transaction details |
***
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**:
### **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:
{% content-ref url="/pages/wjVWdURdFCVjIAin6EDx" %}
[Create a Payment Link](/introducing-our-embedded-form/create-a-payment-link.md)
{% endcontent-ref %}
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://developers.frontstream.com/introducing-our-embedded-form/how-to-implement.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.