# Welcome Welcome to the GitBook Starter Template! Here you'll get an overview of all the amazing features GitBook offers to help you build beautiful, interactive documentation. You'll see some of the best parts of GitBook in action — and find help on how you can turn this template into your own. ### Jump right in
Getting StartedCreate your first site/pages/CyH2xJQs9yWJ1S8BYNav
BasicsLearn the basics of GitBook/pages/7aUFmnCMx9m4smGncsXL
Publish your docsShare your docs online/pages/JjjojIyKxaiBPzzLwvtg
# Quickstart
Beautiful documentation starts with the content you create — and GitBook makes it easy to get started with any pre-existing content. {% hint style="info" %} Want to learn about writing content from scratch? Head to the [Basics](https://github.com/GitbookIO/onboarding-template/blob/main/getting-started/broken-reference/README.md) section to learn more. {% endhint %} ### Import GitBook supports importing content from many popular writing tools and formats. If your content already exists, you can upload a file or group of files to be imported.
### Sync a repository GitBook also allows you to set up a bi-directional sync with an existing repository on GitHub or GitLab. Setting up Git Sync allows you and your team to write content in GitBook or in code, and never have to worry about your content becoming out of sync. # Publish your docs Once you’ve finished writing, editing, or importing your content, you can publish your work to the web as a docs site. Once published, your site will be accessible online only to your selected audience. You can publish your site and find related settings from your docs site's homepage.
# Editor GitBook has a powerful block-based editor that allows you to seamlessly create, update, and enhance your content.
### Writing content GitBook offers a range of block types for you to add to your content inline — from simple text and tables, to code blocks and more. These elements will make your pages more useful to readers, and offer extra information and context. Either start typing below, or press `/` to see a list of the blocks you can insert into your page. ### Add a new block {% stepper %} {% step %} ### Open the insert block menu Press `/` on your keyboard to open the insert block menu. {% endstep %} {% step %} ### Search for the block you need Try searching for “Stepper”, for exampe, to insert the stepper block. {% endstep %} {% step %} ### Insert and edit your block Click or press Enter to insert your block. From here, you’ll be able to edit it as needed. {% endstep %} {% endstepper %} # Markdown GitBook supports many different types of content, and is backed by Markdown — meaning you can copy and paste any existing Markdown files directly into the editor!
Feel free to test it out and copy the Markdown below by hovering over the code block in the upper right, and pasting into a new line underneath. ```markdown # Heading This is some paragraph text, with a [link](https://docs.gitbook.com) to our docs. ## Heading 2 - Point 1 - Point 2 - Point 3 ``` {% hint style="info" %} If you have multiple files, GitBook makes it easy to import full repositories too — allowing you to keep your GitBook content in sync. {% endhint %} # Images & media GitBook allows you to add images and media easily to your docs. Simply drag a file into the editor, or use the file manager in the upper right corner to upload multiple images at once.

Add alt text and captions to your images

{% hint style="info" %} You can also add images simply by copying and pasting them directly into the editor — and GitBook will automatically add it to your file manager. {% endhint %} # Interactive blocks In addition to the default Markdown you can write, GitBook has a number of out-of-the-box interactive blocks you can use. You can find interactive blocks by pressing `/` from within the editor.
### Tabs {% tabs %} {% tab title="First tab" %} Each tab is like a mini page — it can contain multiple other blocks, of any type. So you can add code blocks, images, integration blocks and more to individual tabs in the same tab block. {% endtab %} {% tab title="Second tab" %} Add images, embedded content, code blocks, and more. ```javascript const handleFetchEvent = async (request, context) => { return new Response({message: "Hello World"}); }; ``` {% endtab %} {% endtabs %} ### Expandable sections
Click me to expand Expandable blocks are helpful in condensing what could otherwise be a lengthy paragraph. They are also great in step-by-step guides and FAQs.
### Drawings ### Embedded content {% embed url="" %} {% hint style="info" %} GitBook supports thousands of embedded websites out-of-the-box, simply by pasting their links. Feel free to check out which ones[ are supported natively](https://iframely.com). {% endhint %} # OpenAPI You can sync GitBook pages with an OpenAPI or Swagger file or a URL to include auto-generated API methods in your documentation. ### OpenAPI block GitBook's OpenAPI block is powered by [Scalar](https://scalar.com/), so you can test your APIs directly from your docs. {% openapi src="" path="/pet" method="post" %} {% endopenapi %} # Integrations GitBook integrations allow you to connect your GitBook spaces to some of your favorite platforms and services. You can install integrations into your GitBook page from the *Integrations* menu in the top left.
### Types of integrations
AnalyticsTrack analytics from your docshttps://www.gitbook.com/integrations#analytics
SupportAdd support widgets to your docshttps://www.gitbook.com/integrations#support
InteractiveAdd extra functionality to your docshttps://www.gitbook.com/integrations#interactive
Visitor AuthenticationProtect your docs and require sign-inhttps://www.gitbook.com/integrations#visitor-authentication
# Introducing our Embedded Form The **FrontStream Embedded Payment Form** provides a secure and flexible solution for integrating payments on customer websites via an iframe. This form supports multiple payment methods, including credit cards, debit cards, Apple Pay, Google Pay, and ACH, while ensuring PCI DSS compliance. ### Key Features: * **Frontend**: The payment form is embedded as an iframe, customizable for branding, mobile-responsive, and secure. It includes fields for payment information, which is tokenized and encrypted before transmission. * **Payment Gateway Integration**: The form communicates with the PCI DSS-compliant **ArgoFire** gateway, handling authorization, tokenization, and settlement of payments. * **Tokenization & Encryption**: Payment details are encrypted and tokenized, ensuring sensitive information is never exposed to the customer’s servers. * **Security & Compliance**: The iframe and payment processing are hosted in a secure, PCI-certified environment, outsourcing PCI DSS compliance to FrontStream. * **Customization & Management**: A self-service portal allows customers to generate and customize the iframe code, select payment methods, and manage preferences. ### User Flow: 1. **Initiation**: User accesses the embedded form. 2. **Data Entry**: User enters payment details, which are securely processed within the iframe. 3. **Transaction Processing**: The payment is authorized by the payment gateway. 4. **Confirmation**: Transaction details are provided to the customer. 5. **Receipts**: A receipt is emailed to the purchaser or donor. ### Benefits: * **PCI Scope Reduction**: Customers are not required to handle sensitive payment data, reducing PCI DSS certification requirements. * **Security**: Ensures secure payment processing with encryption and tokenization. * **Ease of Integration**: Simple integration with minimal development effort. * **Multi-Payment Support**: Supports a variety of payment options. * **Multi-Purchase Items & Surcharging**: Allows multiple items in a single transaction and customizable surcharge options. This solution ensures a seamless, secure, and PCI-compliant payment experience for customers. ### For more information please **contact us** at: {% embed url="" %} # Overview and Features ## FrontStream Embedded Payment Form Overview and Features ### Overview This document outlines the architecture and security measures for an embedded payment form that can be integrated into customer websites or portals via an iframe. This form allows customers to accept multiple payment types, including credit cards, debit cards, Apple Pay, Google Pay, and ACH, without handling sensitive cardholder data, thus removing the need for PCI DSS certification on the customer's part. ### Objective To provide a secure, flexible, and compliant solution for customers to embed a payment form within their site. The embedded payment form will facilitate a seamless checkout experience, supporting various payment methods while ensuring compliance with PCI DSS requirements. ### Architecture Components 1\. **Frontend** (Embedded Payment Form via iframe) * The payment form is delivered to the customer’s site through an iframe hosted on our domain and is mobile responsive. * The iframe contains fields for the payment information: card number, expiration date, CVV, etc., all of which are tokenized and encrypted before transmission. * Customizable UI elements allow branding options for the customer, ensuring the iframe matches their portal's aesthetic while preserving the integrity and security of the payment fields. * A client-side code library is provided to integrate the payment form into the application. Server-side code is provided to initiate the payment session. 2\. **Payment Gateway Integration** * The iframe communicates with the FrontStream secure, PCI DSS-compliant ArgoFire payment gateway that processes with either a Merchant Account or with the FrontStream Global Fund (DAF). * The ArgoFire gateway manages the processing of payments, including handling authorization, tokenization, and settlement processes. * The form is configured to support multiple payment methods: credit cards, debit cards, Apple Pay, Google Pay, and ACH, providing customers with a comprehensive range of options. 3\. **Tokenization and Encryption** * Payment details entered by the end-user are sent over HTTPS through a secured backend server proxy. * Payment details entered by the end-user are immediately encrypted within the iframe. * Card and account information is tokenized by the payment gateway, which generates a unique, secure token representing the payment data. This token is used to complete the transaction without exposing sensitive cardholder information to the customer’s servers. 4\. **Security and Compliance** * Since all sensitive payment data is captured within the iframe and processed by the payment gateway, customers are not exposed to sensitive cardholder data, effectively "outsourcing" PCI DSS compliance to our infrastructure. * The iframe is hosted in a secure, PCI DSS-certified environment, leveraging HTTPS and HSTS to prevent data interception. * The solution meets or exceeds PCI DSS requirements for iframe-based payments, ensuring compliance without impacting the customer’s PCI scope. 5\. **Embedded Form Customization and Management** * A self-service portal allows customers to generate iframe code and customize the embedded form’s appearance (e.g., colors, fonts) while maintaining security standards. * Customers can configure payment methods based on their preferences and business needs (e.g., enabling or disabling Apple Pay, Google Pay, or ACH). ### User Flow 1. **Initiation**: The end-user accesses the payment form embedded within the customer's site. 2. **Data** **Entry**: The end-user enters payment details, which are secured within the iframe, ensuring no sensitive information is passed to the customer’s servers. 3. **Transaction Processing**: The payment information is sent to the configured payment gateway API, which authorizes the transaction. 4. **Confirmation**: The customer receives transaction metadata, allowing them to confirm the payment without handling sensitive data directly. 5. **Receipts**: The purchaser or donor receives a receipt sent to their email detailing the transaction. ### Benefits * **PCI Scope Reduction**: As the iframe handles all sensitive data, the customer’s environment is exempt from PCI DSS certification. * **Security**: Encrypted data transmission, tokenization, and gateway handling ensure secure processing. * **Ease of Integration**: The iframe-based solution minimizes development work, requiring only simple integration to enable secure payments on the customer’s website. * **Multi-Payment Support**: The solution provides flexible payment options, catering to diverse customer preferences. * **Multi-Purchase Items**: Multiple items can be purchased with a single transaction (registrations, donations, purchase items, etc). * **Surcharging Support**: The solution allows surcharge options that are configured for the organization. This architecture provides a seamless, secure, and PCI-compliant solution for embedded payments. # Payment Methods process ## How our FrontStream Embedded Payment Form Handles Payment Methods Our **FrontStream Embedded Payment Form** handles multiple payment methods by dynamically adjusting the form based on the user’s choice of payment method. Example flow: 1. **Payment Method Selection**: * The form allows users to select from different payment methods (credit/debit card, Google Pay, Apple Pay, ACH, etc.). 2. **Show Relevant Fields**: * Based on the user’s selection, the embedded form will display the appropriate fields for that payment method. * **For credit/debit cards**: Show card number, expiration date, and CVV fields. * **For Google Pay/Apple Pay**: Show the respective wallet buttons (which, when clicked, launches the wallet’s payment interface). * **For ACH**: Display fields for the user to enter their bank account and routing numbers. 3. **Payment Processing and Surcharging**: * The end-user enters payment details, which are secured within the iframe, ensuring that no sensitive information is transmitted to the customer's servers. * Once the user submits the form, the **FrontStream Embedded Payment Form** processes the payment using the selected method. * For **Surcharging**, the **FrontStream Embedded Payment Form** will calculate and display any applicable fee before proceeding with payment processing simplifying the surcharging implementation process. 4. **Confirmation**: The customer receives transaction metadata, allowing them to confirm the payment without handling sensitive data directly. 5. **Receipts**: The purchaser or donor receives a receipt sent to their email detailing the transaction. # 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**
FieldTypeRequiredDescription
ApiKeystring✅ YesYour API key for authentication.
EmbeddedOptionsobject✅ YesConfiguration options for the embedded session.
*** #### **EmbeddedOptions Schema**
FieldTypeRequiredDescription
IpAddressstring✅ YesThe client IP address
RedirectUrlstring✅ YesThe URL to which the user will be redirected after payment.
PaymentLinesarray✅ YesAn array of payment line objects specifying amounts and types.
IframeParentDomainstring✅ YesYour application's domain
PoweredByTextstring❌ NoText to display for branding purposes (e.g., "Powered by Your Company"). If not provided, defaults to "FrontStream"
PoweredByUrlstring❌ NoThe URL users will be directed to when clicking the PoweredByText. If not provided, defaults to https://www.frontstream.com
DonateButtonTextstring❌ NoText displayed on the submit payment button. Default is "Submit Payment".
Languagestring❌ NoThe language of the embedded session. Default is "en".
Themestring❌ NoCSS string for custom styling of the embedded session.
ThemeFontsarray❌ NoArray of fonts to be used in the session.
DefaultCountryCodestring❌ NoThe default country code for user input. Example: "US".
ExternalEventIdstring❌ NoCustomer event Id which can be used in Payment API reporting
ExternalEventNamestring❌ NoCustomer event name which can be used in Payment API reporting
TokenizeCardbool❌ NoIf set to 'True', when a Card or ACH Check account is entered, will generate and return a token Guid for use in future payments.
ExternalCardTokenstring❌ NoCustomer credit card token generated outside of the Embedded Form (e.g. Argofire)
ExternalCheckTokenstring❌ NoACH account token generated outside of the embedded form
TokenGuidstring❌ NoCard/ACH Token generated from a previous embedded form payment
TranIdstring❌ NoYour systems unique id/reference/invoice - Max Length (100)
ShowTransactionIdbool❌ No'True' will display the TranId on the checkout form
TransactionIdTextstring❌ NoThe text to display in front of the TranId. Example: "Invoice#:"
FirstNamestring❌ NoCustomer First name -Max Length (50)
LastNamestring❌ NoCustomer Last name -Max Length (50)
Emailstring❌ NoCustomer email -Max Length (100)
Streetstring❌ NoCustomer Street -Max Length (50)
Citystring❌ NoCustomer City -Max Length (50)
Statestring❌ NoCustomer State -2 char US state code, 3 char may be used for other non-US
Zipstring❌ NoCustomer Zip - Max Length (10)
Countrystring❌ NoCustomer 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: 
{
  "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**: {% tabs %} {% tab title="JavaScript" %} ```javascript vm.embeddedModel = $uibModal.open({ animation: false, backdrop: 'static', keyboard: false, template: `
`, controller: "embeddedModalController", controllerAs: "vm", windowClass: 'modal-fullscreen' }); vm.closeIframe = function () { $uibModalInstance.close(); }; ``` {% endtab %} {% tab title="CSS" %} ```css @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); } ``` {% endtab %} {% endtabs %} {% hint style="info" %} Note the use of allow="payment \*" This is allows Apple Pay and other payment methods to render in the iframe {% endhint %} 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: ```json { "SessionId": "db168625-b7d0-4f8f-9fc9-362090da77c4", "PaymentResult": { "Successful": true, "Message": "Approved", "EmailAddress": "mycustomer@mailinator.com", "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, "ExternalCardToken": null, "ExternalCheckToken": null, "ExternalCustomerId": 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, "EPFSessionId": "84d61097-3d96-4342-92c1-09417a64e19b", "TranId": "112233" } } ```
Response Data
FieldTypeNullableNotes
SessionIdguidNoOuter response wrapper — your session identifier.
SuccessfulboolNotrue when the transaction processed successfully.
MessagestringYesPayment Gateway response message.
ProcessorMessagestringYesResponse from the credit card processing bank.
TransactionIdstringYesPayment Gateway transaction ID.
PaymentGuidguidNoPayment API payment GUID.
PaymentIdintegerNoPayment API payment ID.
ResponseCodestringYes-100 indicates an unprocessed transaction. 0 indicates approval.
PaymentResultintegerNoPending = 1 (not currently used), Processing = 2 (not currently used), Successful = 3, Failed = 4, Refunded = 5, Cancelled = 6.
ProcessStatusintNo1 = Not Processed, 2 = Awaiting Auth, 4 = Authorized, 5 = Rejected.
TotalAmountdecimalNoTotal amount processed toward the cardholder's account.
TokenGuidguidYesPayment API token GUID, when available.
ExternalCardTokenstringYesThird-party gateway card token, when available.
ExternalCheckTokenstringYesThird-party gateway check token, when available.
ExternalCustomerIdstringYesPayment gateway-generated customer identifier.
ExternalConstituentIdstringYesYour system's customer identifier — returned as provided.
CardNumstringYesLast four card digits.
CheckAccountNumstringYesLast four check-account digits.
PaymentMethodTypeIdintegerYesNone = 0, AmericanExpress = 1, MasterCard = 2, Visa = 3, Discover = 4, DinersClub = 5, ACH = 7, GOOGLEPAY = 8, APPLEPAY = 9.
CardTypestringYesAmerican Express, Mastercard, Visa, Discover, Diners Club, or Undefined.
ProcessorGuidguidYesPayment processor identifier.
OrganizationGuidguidYesOrganization identifier.
RecurringProfileGuidguidYesRecurring payment profile identifier, when applicable.
PaymentResultTransactionModelarrayYesFee and commission breakdown per transaction source. See sub-fields below.
FirstNamestringYes
LastNamestringYes
EmailAddressstringYes
ExpMonthstringYesCard expiration month, using two digits.
ExpYearstringYesCard expiration year, using two digits.
CurrencystringYesISO currency code, such as USD.
PayTheFeeboolNoWhether the donor covered the processing fee.
TranIdstringYesClient's unique ID, reference, or invoice number.
IsSurchargeEligibleboolYesWhether the card is surcharge eligible.
TotalSurchargedecimalYesTotal surcharge amount.
AVSResponsestringYesAddress Verification response, when available.
AVSStreetStatusstringYesAddress Verification street status, when available.
AVSZipStatusstringYesAddress Verification ZIP status, when available.
CVVResponsestringYesCard Verification response, when available.
SessionIdstringNoEmbedded Payment Form session identifier. Use it to look up transaction details.
PaymentResultTransactionModel sub-fields
FieldTypeNullableNotes
TransactionSourceGroupIdstringYesTransaction source group identifier.
PaymentAmountdecimalYesPayment amount for this source.
CardFeeRatedecimalYes
CardFeeAmountdecimalYes
CardTypeFeeAmountdecimalYes
TotalCommissionRatedecimalYes
TotalCommissionAmountdecimalYes
PartnerCommissionRatedecimalYes
PartnerCommissionAmountdecimalYes
FsCommissionRatedecimalYesFrontStream commission rate.
FsCommissionAmountdecimalYesFrontStream commission amount.
TotalFeesdecimalYesTotal fees for this source.
MaxOverridePartnerCommissionRatedecimalNo
MinOverridePartnerCommissionRatedecimalNo
PerTransFeedecimalYesPer-transaction fee.
TipdecimalNo
CardFeeOnFeeAmountdecimalYes
***
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) {% endcontent-ref %} # Create a Payment Link ## Create a link to accept payments easy! Introducing our **FrontStream Pay Link/Hosted Payment Page** - a unique URL that when clicked, directs users to our FrontStream secure online payment page, allowing your customers to make payments without needing a website or payment gateway integration. Collect payments via email, messaging apps, social media, phone texts, and add the Pay-link to your website or in your own Pay Now button and accept payments in a **‘one-click’** process. ### Example demo Pay Link: {% embed url="" %} ### Create and Configure your Pay Link: To help you get started please see our **FrontStream Payment API** and reference our Pay Link creation API**:** {% content-ref url="/pages/LJoHw7TcmdLaQaSX7vem" %} [Welcome to our Payment API](/welcome-to-our-payment-api) {% endcontent-ref %} And using our **Payment API** please see our **Pay Link** creation API: {% content-ref url="/pages/wXuyvMLquUEuEoNOuoOO" %} [Create and configure Pay links](/welcome-to-our-payment-api/api-references/create-and-configure-pay-links) {% endcontent-ref %} # Compare Embedded Form and Direct API integration ## FrontStream Payment integration options for your website or application When evaluating payment integration options for your website or application, both **embedded payment forms** and **direct API integrations** offer benefits. The choice between them primarily depends on factors such as technical expertise, user experience, flexibility, and security needs. When looking at the comparison, also keep in mind both approaches can be used together depending on Payment Integration needs. Below is a comparison of each approach we offer at FrontStream: ### **Benefits of FrontStream Embedded Payment Form** 1. **Simplicity and Ease of Implementation** * **Faster Setup:** Our **FrontStream Embedded Payment Form** comes pre-built and requires minimal coding. You simply need to integrate into your existing site with an iframe and small code snippet, which makes it a good option for non-technical teams. * **Fewer Development Resources Needed:** Since the form is hosted by FrontStream, you do not need to manage or implement the payment logic, security, or compliance requirements yourself. This saves time and resources. 2. **Security and Compliance (PCI DSS)** * **Reduced PCI DSS Scope:** Because the sensitive data (credit card details) is handled by FrontStream, the scope of PCI DSS (Payment Card Industry Data Security Standard) compliance is minimized for your business. This significantly reduces the burden of compliance and security concerns on your end. * **Security Features:** Our **FrontStream Embedded Payment Form** comes with built-in security features like tokenization, fraud protection, and encryption, which are automatically updated by FrontStream to meet industry standards. 3. **Faster User Experience** * **Seamless Checkout:** Our **FrontStream Embedded Payment Form** provides a seamless experience for users by offering a pre-built, optimized interface for payment. This ensures that the checkout process is user-friendly and consistent. * **Mobile-Optimized:** Our Embedded Form is designed to work smoothly on mobile devices, providing better user experience across platforms. 4. **No Need for Advanced Developer Skills** * If you don’t have a dedicated development team or technical expertise, integrating our **FrontStream Embedded Payment Form** is a straightforward way to implement payments without needing to build and maintain custom integrations. 5. **Customize Branding** * A self-service portal allows customers to generate iframe code and customize the **FrontStream Embedded Payment Form’s** appearance (e.g., colors, fonts) to closely match your current site’s theme while maintaining security standards. 6. **Support for Multiple Payment Methods** * **Pre-built Support:** Our Embedded Form supports various payment methods (credit cards, debit cards, Apple Pay, Google Pay, and ACH), saving you the work of integrating multiple payment methods manually. ### **Benefits of a Direct API Payment Integration** 1. **Greater Control and Customization** * **Full Control over the User Experience:** With a direct API integration, you have complete control over the entire checkout flow, design, and functionality. This allows you to create a more unique, branded experience tailored to your application. * **Advanced Features:** Direct API integrations often provide access to a broader range of features such as reporting or custom payment workflows. You can customize your integration to fit specific business needs. 2. **Flexibility** * **Full API Access:** Direct access to the API means you can query transaction details, control payment flows, and create custom payment processing logic. 3. **Full Branding Control** * **Custom Styling and Interaction:** You can match the design of your payment form to your site’s theme and add advanced interactive features like real-time validation, dynamic pricing, or personalized recommendations. 4. **Advanced Features** * **Integration with Other Services:** A direct API can be integrated with other parts of your business infrastructure, such as customer management systems, analytics platforms, or inventory systems, creating a more streamlined and data-driven business operation. ### **Comparison Summary** | | **Embedded Payment Form** | **Direct API Payment Integration** | **Similarities** | | ------------------- | --------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Ease of Setup** | Simple, requires minimal coding | Requires significant development effort | Both solutions can be integrated with existing business infrastructures | | **Customization** | Some customization, theming, and design | Control over UI, design, and functionality | Both options allow for some level of customization | | **Security** | Managed by FrontStream, lower PCI DSS scope | More responsibility for compliance and security by customer | Both are PCI Level 1 compliant | | **User Experience** | Pre-designed and optimized for mobile and desktop | Customizable UI and user flow | Both aim to deliver seamless and optimized user experience | | **Payment Methods** | Credit cards, debit cards, Apple Pay, Google Pay, and ACH | Flexibility to integrate multiple methods | Both support: Credit cards, debit cards, Apple Pay, Google Pay, and ACH | | **Maintenance** | FrontStream handles updates and security | Full responsibility on customer for maintenance and updates |

Both options offer security features to protect sensitive data and assist businesses in meeting PCI DSS compliance requirements, although the level of responsibility and scope vary between them.

| | **Cost** | Lower initial cost (fewer developer resources required) | Higher cost due to development and maintenance | | ### Key similarities **Key similarities** between the **FrontStream Embedded Payment Form** and **Direct API Payment Integration** can be summarized as follows: 1. **Payment Functionality**: Both solutions enable businesses to process payments securely, supporting multiple payment methods such as credit cards, debit cards, Apple Pay, Google Pay, and ACH. 2. **Security and Compliance**: Both options provide security features to ensure the protection of sensitive data and help businesses meet PCI DSS compliance requirements, though the scope and responsibility differ. 3. **Customization and Branding**: Both options allow for some level of customization, whether through the Embedded Payment Form's theming and design or the complete control over UI and payment flow with a Direct API integration. 4. **User Experience**: Both aim to deliver a seamless and optimized user experience, whether through a pre-built form optimized for mobile and desktop or a fully customizable checkout process via the API. 5. **Integration Flexibility**: Both solutions can be integrated with existing business infrastructures, but while the Embedded Payment Form is easier and faster to set up, the Direct API offers greater flexibility and control over the integration. 6. **Cost Considerations**: Both have different cost structures based on the level of development effort required. The Embedded Payment Form is more cost-effective for businesses with fewer technical resources, while the Direct API integration requires more development but offers deeper customization. Both approaches also allow for combining the solutions, depending on a business's payment integration needs, offering a balance between ease of use and customization. ### **Decision** * **FrontStream Embedded Payment Form:** Best for businesses that prioritize simplicity, security, and quick deployment without needing full control over the payment flow. It’s ideal for businesses or those looking to save on development costs for ease of integration into an existing site for supporting Payment Processing quickly and securely. * **Direct API Payment Integration:** Best for businesses that need a highly customized payment solution with full control over branding, user experience, and advanced features the Embedded Payment Form may not fully address. Choosing the right option will depend on your specific business goals, resources, and technical expertise. Or include both options in your Payment Integration. # Welcome to our Payment API ## Welcome to our FrontStream Payment API! The **FrontStream Payment API** documentation provides everything needed to begin processing payments, whether for charity organizations or direct merchants. It includes an **Overview of features**, a **Quick Start Guide** to help users get up and running and also offers detailed **API references** for more advanced usage. The goal is to make integrating payment processing simple for users and api partners in charitable giving or direct merchant environments. Here you will find all the necessary documentation to begin processing payments, either for your preferred charity organization or as a direct merchant. ## Let's get you started! Start with our Payment API Overview of features to get you interested {% content-ref url="/pages/HypQ3Tld3eqSbnOtuMmQ" %} [Overview](/welcome-to-our-payment-api/overview) {% endcontent-ref %} Then take a look at our Quick Start to begin your payment journey {% content-ref url="/pages/98kJeckCoWR8G0B9rI4e" %} [Quick Start](/welcome-to-our-payment-api/quick-start) {% endcontent-ref %} Or jump right into our API references {% content-ref url="/pages/0fJ5kq2BRgIYSe3scZiO" %} [API references](/welcome-to-our-payment-api/api-references) {% endcontent-ref %} ### For more information please **contact us** at: {% embed url="" %} # Overview ### Payment API summary Our **FrontStream Payment API** offers a robust set of endpoints designed to manage payment-related operations securely. It provides comprehensive tools for processing transactions—whether for donations to charity non-profit organizations or payments to for-profit merchants—along with fee calculation, charity data management, webhook notifications, and detailed transaction reporting for our Integrated Partners. This enables seamless integration with payment processing systems and other related platforms. Below is an overview of the key features and functionality supported by this API: ### Authentication & Access Control: Our Endpoints require an **AccessToken** to authenticate API requests and this token is provided after successful authentication through the `/api/ClientSession` endpoint. **1. Retrieve a ClientSession (POST** [**`/api/ClientSession`**](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/authenticate#post-api-clientsession)**)** * **Purpose**: This endpoint is used to authenticate an application and generate an API AccessToken. * **Responses**: * `200 OK`: Successful authentication, returns an AccessToken. * `400 Bad Request`: Authentication failure. * **Request**: The request body contains FrontStream assigned `Client Specific` data. ## Create and configure Pay links **2. Create a Pay Link (POST** [**`/api/payLink`**](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/pay-links#post-api-paylink)**)** * **Purpose**: Returns a Pay link URL configured to your specific parameters that when ‘clicked’ will render our FrontStream Payment Form your customers can use to make payments. * **Parameters**: Requires an `AccessToken` and includes optional and required body parameters for successful Pay Link creation. * **Responses**: * `200 OK`: Returns a Pay Link URL. * `400 Bad Request`: If the Pay Link creation fails. * `404 Not Found`: If no Pay Link are found. ### Finding your favorite Charity **3. Charity Search (GET** [**`/api/CharitySearch`**](/welcome-to-our-payment-api/api-references/test-payment-api-features/charity-search#get-api-charitysearch)**)** * **Purpose**: Looking to Donate to a particular Charity Organization? This allows searching for nonprofit charities based on various optional filters such as name, EIN, city, and state. * **Parameters**: Parameters include charity name, EIN, charity source, city, state, pagination options like `PageIndex` and `PageSize`, and sorting options. * **Responses**: * `200 OK`: Returns search results for charities. * `400 Bad Request`: If the search request is malformed. * `404 Not Found`: If no matching charities are found. ### Tokenization 4. **Tokenize Credit Cards or Bank Account data (POST** [**`/api/tokenize`**](/welcome-to-our-payment-api/api-references/test-payment-api-features/tokenization#post-api-tokenize) **`and`** [**`/api/tokenizeAch`**](/welcome-to-our-payment-api/api-references/test-payment-api-features/tokenization#post-api-tokenizeach)**`)`** * **Purpose**: Securely tokenize cards and bank data and return newly created token to use to process subsequent payment transactions. * **Parameters**: Requires an `AccessToken` and includes optional and required body parameters for successful transactions. * **Responses**: * `201 Created`: Returns a newly created token. * `400 Bad Request`: If the token creation fails. ### Make Payments **5. Make Payment (POST** [**`/api/payment`**](/welcome-to-our-payment-api/api-references/test-payment-api-features/payment#post-api-payment) **`or`** [**`/api/paymentAch`**](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/payments#post-api-paymentach) **`or`** [**`/api/paymentToken`**](/welcome-to-our-payment-api/api-references/test-payment-api-features/tokenization#post-api-paymenttoken)**)** * **Purpose**: Initiates a payment transaction with card or bank data or newly created tokens. * **Parameters**: Requires an `AccessToken` and includes optional and required body parameters for successful transactions. * **Responses**: * `201 Created`: Returns the details of the created payment. * `400 Bad Request`: If the payment creation fails. ### Help cover Fees **6. Fees Calculation (GET** [**`/api/fee`**](/welcome-to-our-payment-api/api-references/test-payment-api-features/fee#get-api-fee)**)** * **Purpose**: Used in our Non-Profit space to help cover any fees on Donations giving the option for all of a donation to go to a Charity. Calculates various fees based on transaction details, including transaction amount, source grouping, and other parameters like charity ID, card type, cover the fee flag, etc. * **Parameters**: Includes optional and required parameters like `Amount`, `TransactionSourceGroupId`, `PayFee`, etc. * **Responses**: * `200 OK`: Returns calculated fee details. * `400 Bad Request`: If fee calculation fails. * `404 Not Found`: If fees are not found. * **Details**: Detailed breakdown of fees such as card fees, commission rates, partner overrides, etc. ### Transaction Reporting **7. Generate Transaction Report (POST** [**`/api/sourceTransactionsReport`**](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/reports#post-api-sourcetransactionsreport)**)** * **Purpose**: Generates a report on transactions, filtered by various criteria. * **Parameters**: Requires an `AccessToken` and a request body containing the report filters. * **Responses**: * `200 OK`: Returns the generated transactions report. * `400 Bad Request`: If report generation fails. ### And get Webhook Notifications **8. Set up and test Notifications for example - Notification Test (POST** [**`/api/notificationTest`**](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/notifications#post-api-notificationtest)**)** * **Purpose**: Sends a test notification to an integration source API, useful for testing notification payloads. * **Parameters**: Requires `url` (endpoint) and `payload` (notification data). * **Responses**: * `200 OK`: Successfully sent the notification. * `400 Bad Request`: If the notification fails. #### API Structure: * The API is designed with a set of resources organized by functional groups (e.g., **Authentication**, **Charity Search**, **Payments, Token Payments, Fees**, **Reports,** and **Notifications**). * It supports various HTTP methods like `GET`, `POST`, and utilizes JSON for data exchange. The **FrontStream Payment API** offers a complete set of tools for managing transactions, fees, charity data, and reporting, allowing for smooth integration with payment processing systems and other related platforms. Take the next step into our Quick Start guide. # Quick Start ## Let's get you set up and ready to start using the Payment API ### Use your Client credentials Let's make sure you can gain access to our **FrontStream** **Payment API**. As a **FrontStream API Partner** you will be set up with secure credentials to gain access and authenticate your requests. Use your FrontStream assigned ClientId and ClientSecret to retrieve a one time use AccessToken for gaining access to our different API endpoints. Missing your credentials? Please contact us at: {% embed url="" %} To try a test and directly interact with the API endpoint click "Test It" and use an embedded API client to send requests with custom headers and variables, then see the live response; essentially letting you test this API directly within this page. When testing please use our Demo URL: `https://demo-payments.frontstream.com/api/ClientSession` ## This will create an API AccessToken for an Application > Return HTTP Status Code 200 (OK) with AccessToken > \ > Returns HTTP Status Code 400 if could not authenticate ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/ClientSession":{"post":{"tags":["Authenticate"],"summary":"This will create an API AccessToken for an Application","description":"Return HTTP Status Code 200 (OK) with AccessToken\r\nReturns HTTP Status Code 400 if could not authenticate","requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/ClientSessionRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/ClientSessionRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/ClientSessionRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/ClientSessionRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationClientSessionResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"ClientSessionRequest":{"required":["ClientId","ClientSecret"],"type":"object","properties":{"ClientId":{"type":"string","description":"Unique identifier for the API Partner; provided by FrontStream"},"ClientSecret":{"maxLength":500,"type":"string","description":"Key specifically paired to the clientId"}},"additionalProperties":false,"description":""},"AuthenticationClientSessionResponse":{"type":"object","properties":{"Token":{"type":"string","description":"This is the AccessToken you will use for any other API call","nullable":true},"ClientId":{"type":"string","description":"Unique identifier for the API Partner; provided by FrontStream","format":"uuid"},"ExpirationDate":{"type":"string","description":"The date and time at which the AccessToken will no longer be valid if not used first. Will always be 5 hours from when the response is sent.","format":"date-time"}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ### Client Session Example Take a look at how you might call this method: {% tabs %} {% tab title="C#" %} ```csharp using System; using System.Net.Http; using System.Text; using System.Threading.Tasks; public class Program { public static async Task Main(string[] args) { using (var client = new HttpClient()) { var url = "/api/ClientSession"; var requestBody = new { ClientId = "text", ClientSecret = "text" }; var content = new StringContent( Newtonsoft.Json.JsonConvert.SerializeObject(requestBody), Encoding.UTF8, "application/json-patch+json" ); var response = await client.PostAsync(url, content); var responseData = await response.Content.ReadAsStringAsync(); Console.WriteLine(responseData); } } } ``` {% endtab %} {% tab title="Postman" %} To make the API request in Postman, follow these steps: 1. **Method**: Set to `POST`. 2. **URL**: Enter the API endpoint URL (e.g., `https://demo-payments.frontstream.com/api/ClientSession`). 3. **Headers**: * Key: `Content-Type` * Value: `application/json-patch+json` 4. **Body**: Select `raw`, then choose `JSON` format. Paste the following JSON: ```json { "ClientId": "text", "ClientSecret": "text" } ``` 5. **Send**: Click the `Send` button and view the response in the output section. {% endtab %} {% endtabs %} ### For more information please **contact us** at: {% embed url="" %} ### Ready to make your first Payment request? Dive into the API reference specifics next: {% content-ref url="/pages/0fJ5kq2BRgIYSe3scZiO" %} [API references](/welcome-to-our-payment-api/api-references) {% endcontent-ref %} # API references ## Dive into the specifics! ### Create and configure a Payment Link! Learn how to create a 'one-click' pay link to accept payments using our **FrontStream Payment Form**. Detail here: {% content-ref url="/pages/wXuyvMLquUEuEoNOuoOO" %} [Create and configure Pay links](/welcome-to-our-payment-api/api-references/create-and-configure-pay-links) {% endcontent-ref %} ### Search for a Charity! Start off and search for the Charity Organization you wish to make a Donation to and make a difference. {% content-ref url="/pages/iqsy24phCC6D7zSdVcAy" %} [Search for a Charity for your Donation](/welcome-to-our-payment-api/api-references/search-for-a-charity-for-your-donation) {% endcontent-ref %} ### Make a Donation! Found your Charity and ready to make a Donation? Learn how here: {% content-ref url="/pages/2FpFP6tr0KVyPp9oXwN9" %} [Make a Payment](/welcome-to-our-payment-api/api-references/make-a-payment) {% endcontent-ref %} ### Understand your Fees! Ready to cover your fees so your entire amount goes to a Charity? Calculate fees here: {% content-ref url="/pages/N2zDNwJosCaasfGNcXoz" %} [Learn how to cover Fees](/welcome-to-our-payment-api/api-references/learn-how-to-cover-fees) {% endcontent-ref %} ### Pull a Transaction Report! Want to see transaction details? Learn how here: {% content-ref url="/pages/YhDXpsHBIZoN0CsoQKFY" %} [Retrieve Transactions report](/welcome-to-our-payment-api/api-references/retrieve-transactions-report) {% endcontent-ref %} ### Receive webhook Notifications! Want to know a transaction event? Let's help you set up Notifications here: {% content-ref url="/pages/nZ0GbMKXP0y4h4sMVK80" %} [Set up and receive Notifications](/welcome-to-our-payment-api/api-references/set-up-and-receive-notifications) {% endcontent-ref %} ### Continue to dive into each API reference details! Dive into the specifics of each Payment API endpoint by checking our our complete documentation here: {% content-ref url="/pages/RHVd5m3IA7J3yMH2ePSH" %} [Each API reference specifics!](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics) {% endcontent-ref %} # Create and configure Pay links **Payment API - Paylink - API specification-** calling our Payment API POST `/api/paylink` will return a Pay link URL configured to your specific parameters that when ‘clicked’ will render our FrontStream Payment Form your customers can use to make payments. **Key Details:** * **API Version:** v1 * **Endpoint:** [`/api/paylink`](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/pay-links#post-api-paylink) * **Method:** POST * **Purpose:** Returns a configured 'clickable' Pay Link URL for accepting payments. **Responses:** * **200 (Success)**: Returns a pay link URL. * **400 (Bad Request):** If pay link creation throws exception. * **404 (Not Found):** If pay link data is not found. **Components:** * **PayLinkUrl Response:** Returns the pay link URL. * **BrokenRule:** Represents an error in pay link url creation with an error code and message. * **ProblemDetails:** Details for any error response, including status, title, and description. ### Create, configure, and return Pay Link URL See how to create and configure your Pay Link URL through the POST /api/paylink here: {% content-ref url="/pages/c95d5ed8a9177aebaccfb628cfa58ed8642be771" %} [Pay Links](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/pay-links) {% endcontent-ref %} # Search for a Charity for your Donation **Payment API** - **CharitySearch - API specification** provides searching for nonprofit charity organizations you would like to make a donation to. **API Overview:** * **API Version:** v1 * **Endpoint:** [`/api/CharitySearch`](/welcome-to-our-payment-api/api-references/test-payment-api-features/charity-search#get-api-charitysearch) * **Method:** GET This endpoint supports a **GET** request for searching nonprofit charities with various filters. **Parameters:** 1. **Name** (optional): Partial or full name of the charity (max 70 characters). 2. **EIN** (optional): Valid US/CA Nonprofit EIN or Tax ID (9–15 characters). 3. **CharitySource** (optional): Specifies whether the charity is from the US (1) or Canada (2). 4. **City** (optional): City name associated with the charity's address (max 30 characters). 5. **State** (optional): State code (ISO standard 2-letter code). 6. **PageIndex** (optional): Page number for paginated results (default is 1). 7. **PageSize** (optional): Number of results per page (default is 10). 8. **SortColumn** (optional): Column by which to sort the results (default is NpoName). 9. **SortDesc** (optional): Boolean to specify whether to sort in descending order. **Responses:** * **200 OK**: Returns charity search data in JSON format with details like total results, pagination, and charity records. * **400 Bad Request**: If the request has errors, it returns a list of broken rules. * **404 Not Found**: If no charity records match the search criteria, a detailed problem message is returned. **Data Models:** 1. **CharitySearchResults**: Contains total result count, total pages, and a list of charity records. 2. **CharitySearchResultsList**: Includes details for each charity, such as: * CharityId: Unique identifier * NpoName: Charity name * EIN: Tax ID * Address: Charity's address * NpoEligibilityFlag: Indicates tax-deductible donation eligibility * ParentOrgName: Parent charity (if applicable) * NTEEcode: IRS classification code for US charities 3. **BrokenRule**: Describes errors in the request with an error code and message. 4. **ProblemDetails**: Provides detailed error messages if the data is not found or there is an issue. ### Try out our Charity Search API This API is useful for searching charity organizations by various criteria and retrieving detailed records. {% content-ref url="/pages/5J0Jg3izotCZ4l4Dq0zV" %} [Charity Search](/welcome-to-our-payment-api/api-references/test-payment-api-features/charity-search) {% endcontent-ref %} # Make a Payment **Payment API - Make Payments -** **API specifications** by tokenizing card or check bank data, or by inputting card or check bank data, or create a recurring contract, and processing a payment with details operations and response formats. **API Overview:** * **API Version:** v1 * **Endpoints:** [`/api/tokenize`](/welcome-to-our-payment-api/api-references/test-payment-api-features/tokenization#post-api-tokenize) or [`/api/tokenizeAch`](/welcome-to-our-payment-api/api-references/test-payment-api-features/tokenization#post-api-tokenizeach) or [`/api/paymentToken`](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/payments#post-api-paymenttoken) or [`/api/recurringProfile`](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/recurring-contracts#post-api-recurringprofile) or [`/api/paymentAch`](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/payments#post-api-paymentach) or [`/api/payment`](/welcome-to-our-payment-api/api-references/test-payment-api-features/payment#post-api-payment) * **Method:** POST * **Purpose:** Facilitates payment transactions. **Key Parameters for Payment:** * **Optional Parameters:** * **CharityId**, **ProcessorGuid**: Identifiers for the charity organization and processor. * Search for your Charity here: [Search for a Charity for your Donation](/welcome-to-our-payment-api/api-references/search-for-a-charity-for-your-donation) * ProcessorGuid will be provided by FrontStream. * **Card details**: Credit card number, type, expiration date, CVV, and name on card (optional). * **Billing and Shipping details**: Address, email, city, state, zip, etc. * **Transaction and Fee Details**: Includes transaction amounts, tip, commission rate overrides, and fees. * **Required Parameters:** * **Email**, **IpAddress**, **NameOnCard**, **Transactions** (mandatory for each payment). **Response Details:** * A successful transaction will return information including: * **Successful**: A boolean indicating if the payment was successful. * **Message**: General response message. * **TransactionId**: Unique identifier for the transaction. * **PaymentGuid**: Unique payment GUID. * **Transaction Status**: Indicates if the payment is successful, pending, or failed. * **Fees**: Transaction-related fee details. **Schemas:** * The API uses several schemas to define the request and response structures, such as: * **PaymentRequest**: Defines the required fields for initiating a payment. * **PaymentResponse**: Defines the expected response structure, including success flags, messages, transaction IDs, and fees. * **FeeResponse**: Details the various fees, including card processing and commission rates. * **BrokenRule**: Used for error handling, containing error codes and messages. **Transaction Breakdown:** * Multiple transaction items can be submitted in a single payment request, each with its own fee, amount, and type (e.g., donation fee, peer-to-peer fee, ticket fee). **Payment Method Types:** * Supported payment methods include credit cards (AMEX, Visa, Mastercard, etc.), Google Pay, Apple Pay, ACH, and Stripe. **Error Handling:** * **400 (Bad Request)**: If payment creation fails, an array of errors is returned detailing why the request failed. This API is designed to handle complex payments with options for fee coverage, transaction splitting, and integration with external systems (e.g., ticketing or donation platforms). ### Payment Example See how to make a Payment here: {% content-ref url="/pages/2GwjMbuPyTm2n5fnpv6S" %} [Payment](/welcome-to-our-payment-api/api-references/test-payment-api-features/payment) {% endcontent-ref %} ### Also Make Payments by Tokens See how to tokenize card and bank data and use created tokens to make payments here: {% content-ref url="/pages/64usJLEpxXWiahIQ83vE" %} [Tokenization](/welcome-to-our-payment-api/api-references/test-payment-api-features/tokenization) {% endcontent-ref %} ### Interested in creating Recurring Payments? We also support creating, updating, and processing Recurring Contracts supporting your billing frequency needs. Our webhook notifications if configured will also notify when contracts are processed. Please see further details here: {% content-ref url="/pages/e888bb0f44675dc3392898d81f6682a1b8cd7aa8" %} [Recurring Contracts](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/recurring-contracts) {% endcontent-ref %} # Learn how to cover Fees **Payment API - Fee - API specification** calculates fees based on the transaction amount and source grouping, with various optional parameters affecting the fee calculation. Used in our Non-Profit space to help cover any fees on Donations giving the option for all of a donation to go to a Charity. **Key Details:** * **API Version:** v1 * **Endpoint:** [`/api/fee`](/welcome-to-our-payment-api/api-references/test-payment-api-features/fee#get-api-fee) * **Method:** GET * **Tags:** Fees * **Summary:** Calculates fees based on amount and transaction source. * **Required Parameters:** * **Amount:** Transaction amount (required). * **TransactionSourceGroupId:** Transaction type (10 = api partner fee). * **PayFee:** A flag indicating whether the transaction fee is covered. * **Optional Parameters:** * **ProcessorGuid, CharityId, OrganizationGuid, IntegrationSourceGuid, TokenGuid**: Used to specify the processor, charity, and integration details. * **CommissionRateOverride:** Allows setting a custom commission rate (within contract limits). * **CardProcessingFeeOverride:** Overrides default card processing fees. * **Tip:** Donor's tip amount (if applicable). * **CreditCardTypeId:** Used for card-specific fee calculation. (possible values - 1 - AMEX, 2 - MC, 3 - VISA, 4 - DISCOVER, 5 - DINERSCLUB, 7 - MAESTRO **Responses:** * **200 (Success)**: Returns the calculated fees in JSON format. * **400 (Bad Request):** If there's an exception in fee calculation. * **404 (Not Found):** If the fees cannot be found. **Components:** * **FeeResponse:** Describes the calculated fee details (e.g., commission rates, card fees, total fees, and overrides). * **BrokenRule:** Represents an error in fee calculation with an error code and message. * **ProblemDetails:** Details for any error response, including status, title, and description. The API enables fee calculations with flexibility to account for various factors such as commission overrides, card type fees, and tips. ### Calculate Fees See how to cover and calculate your fees here: {% content-ref url="/pages/GeKo3WqMep3ReP22cv4M" %} [Fee](/welcome-to-our-payment-api/api-references/test-payment-api-features/fee) {% endcontent-ref %} # Retrieve Transactions report **Payment API - SourceTransactionsReport or OrganizationTransactionReport- API specification-** calling our Payment API POST `api/sourceTransactionsReport` and `/api/exportSourceTransactionsReport` will return transaction history details by Integration Source. Or for our Non-Profit Organizations calling our `api/organizationTransactionReport` and `api/exportOrganizationTransactionReport` will return transaction history details by valid Organization Guid. **Key Details:** * **API Version:** v1 * **Endpoint:** [`/api/sourceTransactionsReport`](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/reports#post-api-sourcetransactionsreport) and [`/api/exportSourceTransactionsReport`](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/reports#post-api-exportsourcetransactionsreport) and [`api/organizationTransactionReport`](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/reports#post-api-organizationtransactionsreport) and [`api/exportOrganizationTransactionReport`](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/reports#post-api-exportorganizationtransactionsreport) * **Method:** POST * **Purpose:** Returns a transaction details. **Responses:** * **200 (Success)**: Returns a report details. * **400 (Bad Request):** Failure to create throws exception. **Components:** * **TransactionReportDetails Response:** Returns the transaction report details. * **BrokenRule:** Represents an error in report creation with an error code and message. * **ProblemDetails:** Details for any error response, including status, title, and description. For the above two endpoint URLs: `/api/sourceTransactionsReport` and `api/organizationTransactionReport` will return the report data as a JSON response, and `/api/exportSourceTransactionsReport` and `api/exportOrganizationTransactionReport` will return the same data as a CSV or Excel format. #### Body Parameter Definitions: | **Parameter** | **Description** | **Notes** | **Required?** | | --------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------- | ------------- | | **Filters** | -- | -- | Yes | | **Name** | Name of the column to be filtered. | String, refer to response data field names for possible values | Yes | | **Operation** | Which constraint operation to use when applying the filter. | Integer, see list of possible values below | Yes | | **Values** | Array of filter terms to search for using the selected name and operation type. | String | Yes | | **SortColumns** | -- | -- | No | | **Name** | Name of the column by which to sort the results. | String, refer to response data field names for possible values | No | | **Descending** | Determines if the sort will be ascending or descending. | Boolean | No | | **Order** | If sorting by multiple columns, this determines the order in which the sorting is applied. | Integer, required when more than one sorting column is present | Yes\* | | **PageSize** | How many records to return per page. | Integer | No | | **PageIndex** | Which page of results to return. Starts at 1 (0 will also return the first page). | Integer | Yes | | **Format** | **Export endpoint only:** determines which file type the report will be exported to. | Valid values: "csv" or "excel" | Yes | #### Operation Field Values: | **Value** | **Name** | **Description** | | --------- | ---------------- | ------------------------------------------------------------------------------------------------- | | 2 | ExactMatch | Filters for records that exactly match the provided search term. | | 3 | StartsWith | Filters for records that start with the provided search term. | | 4 | EndsWith | Filters for records that end with the provided search term. | | 5 | Contains | Filters for records that contain the provided search term. | | 6 | Before | Used for date-type columns, finds records where the date is prior to the provided date. | | 7 | After | Used for date-type columns, finds records where the date is after the provided date. | | 9 | GreaterThan | Compares numbers. Filters for records that are greater than the provided search term. | | 10 | LessThan | Compares numbers. Filters for records that are less than the provided search term. | | 11 | Equals | Compares numbers. Filters for records that are equal to the provided search term. | | 12 | GreaterThanEqual | Compares numbers. Filters for records that are equal to or greater than the provided search term. | | 13 | LessThanEqual | Compares numbers. Filters for records that are equal to or less than the provided search term. | | 18 | NotContains | Inverse of Contains. | | 19 | NotExactMatch | Inverse of ExactMatch. | | 20 | NotStarts | Inverse of StartsWith. | | 21 | NotEnds | Inverse of EndsWith. | | 22 | NotEquals | Inverse of Equals. | ### Retrieve Transaction Report details #### Example Request: Here is a Sample request to get transactions report filters by PaymentDate after (operation 7 = After) January 1st 2026 (2026-01-01) sorted by PaymentDate column desc, returning pageIndex 1 and page size 1000 records: ``` POST /api/sourceTransactionsReport { "Filters": [ { "Name": "PaymentDate", "Operation": 7, "Values": [ "2026-01-01" ] } ], "SortColumns": [ { "Name": "PaymentDate", "Descending": true, "Order": 0 } ], "PageSize": 1000, "PageIndex": 1 } ``` See report api here: {% content-ref url="/pages/06d66eda5d38d375032208f2371a0e41e399dbca" %} [Reports](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/reports) {% endcontent-ref %} # Set up and receive Notifications **Payment API - Notifications - API specifications -** **Step 1.** Configure your Notifications URL by configuring your Notification Configuration using our Payment API PUT `/api/notificationConfig` . **Key Details:** * **API Version:** v1 * **Endpoint:** [`/api/notificationConfig`](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/notifications#put-api-notificationconfig) * **Method:** PUT * **Purpose:** To configure an Integration Sources Notification URL to accept our FrontStream transaction notification status payloads as transactions are updated or newly processed for example recurring contracts . **Responses:** * **200 (Success)**: Returns saved notification config. * **400 (Bad Request):** Throws exception if the notification config was not saved. #### Example PUT request ``` PUT /api/notificationConfig { "NotificationConfigs": [ { "NotificationConfigurationTypeId": "1", // This should always be equal to "1" "NotificationProtocolTypeId": "1", // Use only "1" (WEB) for now. "2" (Email) not yet supported "NotificationUrl": "string", // Url to post our notification to. Example: https://{yourenvironment.yourdomain}.com/api/yourNotification endpoint "Retries": 0, // number of retries to try again failed notifications - currently retries 10 times by default or set to 0 "AccessToken": "string", // optional - if access token needed to hit your notification url "IsDeleted": false // set to true if you wish to soft-delete configuration, otherwise set to false } ] } ``` **Step 2.** Test your Notifications URL can retrieve a transactions notification payload by using our Payment API POST `/api/notificationTest` . **Key Details:** * **API Version:** v1 * **Endpoint:** [`/api/notificationTest`](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/notifications#post-api-notificationtest) * **Method:** POST * **Purpose:** To test a configured Integration Sources Notification URL can accept our FrontStream transaction notification status payloads as transactions are updated or newly processed for example recurring contracts . * **Parameters:** * **Url:** Integration Source endpoint to post notification payload to. Example: https\://{yourenvironment.yourdomain}.com/api/yourNotification endpoint.. * **Payload:** test payload posting over to Url * **AccessToken:** optional if access token is required to hit notification url. **Responses:** * **200 (Success)**: * **400 (Bad Request):** Throws exception if unable to send notification. #### Example POST notificationTest request ``` POST /api/notificationTest { ?Url = "", // your URL to post notification to. &AccessToken=testToken // optional if required to hit notification URL. &Payload = { "PaymentId": 55514, "PaymentGuid": "4f2835cb-1afe-482b-aea6-bf6ea7061828", "PaymentDate": "2026-01-20T15:20:07.948", "PaymentExternalId": "19498411", "OriginalExternalID": "19498411", "RecurringProfileId": null, "RecurringProfileGuid": null, "NextBillDate": null, "ProcessStatus": 2, "ProcessStatusValue": "Awaiting Authorization", "PaymentResult": 3, "PaymentResultValue": "Successful", "Amount": 105.53, "DistributionType": null, "DistributionTypeValue": null, "DistributionStatus": "Processing", "DistributionId": null, "SourceGuid": "12345678-9012-1234-5678-123456789012", "SourceName": "DonationForm", "CharityId": null, "OrganizationGuid": "12345678-9012-1234-5678-123456789012", "OrganizationName": "TEST SOCIETY", "Ein": "00-0000000", "SalesforceAccountId": null, "FgExternalId": null, "BfgExternalId": null, "ArtezExternalId": null, "ArtezInstanceGuid": null, "ExternalConstituentId": null, "FirstName": "TEST", "LastName": "NAME", "Email": "test@testemail.com", "CardHolderName": "Test name", "CCLastDigits": "2222", "CCType": "Visa", "IpAddress": "127.0.0.1", "ExternalEventId": "9922", "ExternalEventGuid": null, "ExternalEventName": null, "ShippingFee": 0, "TaxableBenefit": 0, "TranId": "885ecade-735c-4b8c-9cfd-2870ebca049f", "Tip": 0, "VoidRequestDate": null, "VoidReason": null, "RefundRequestDate": null, "RefundReason": null, "ProcessorId": 1, "ProcessorGuid": "12345678-9012-1234-5678-123456789012", "PaymentMethodTypeId": 3, "Surcharge": null, "IsSurchargeEligible": false, "CheckLastDigits": null, "CheckNumber": null, "CheckTypeId": null, "CheckAccountTypeId": null, "FsApplicationFee": null, "EpfSessionId": "c2bdd62b-0f22-45fe-83f6-119a24e54f82", "PaymentLines": [ { "PaymentLineId": 50256, "PaymentId": 55514, "CreatedDate": "2026-01-20T15:20:09.5520567Z", "ModifiedDate": "2026-01-20T15:20:09.45", "IsDeleted": false, "Amount": 100, "CardFeeAmount": 3.49, "CardTypeFeeAmount": 0, "CommissionAmount": 1.5, "PayFee": true, "TransactionSourceGroupId": 1, "CardFeeRate": 3.49, "TotalCommissionRate": 1.5, "TotalCommissionAmount": 1.5, "PartnerCommissionRate": 0, "PartnerCommissionAmount": 0, "FsCommissionRate": 1.5, "FsCommissionAmount": 1.5, "TotalFees": 5.53, "PerTransFee": 0.35, "ExternalLineId": null, "Tip": 0, "CommissionRateOverride": null, "CardFeeOnFeeAmount": 0.19, "Tax": 0 } ] } } ``` **Step 3. Optional:** If you would like to retrieve previous notifications by Payment identifier please use our Payment API GET `/api/notifications`. **Key Details:** * **API Version:** v1 * **Endpoint:** [`/api/notification`](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/notifications#get-api-notifications) * **Method:** GET * **Purpose:** Check your notifications by Payment idenfiers. * **Parameters:** * **PaymentId:** Payment API Payment Id. * **PaymentExternalId:** Payment Gateway TransactionId. **Responses:** * **200 (Success)**: Returns all Notifications by PaymentId or PaymentExternalId. * **400 (Bad Request):** Throws exception If the Notifications are not found. #### Example GET Notifications request ``` GET api/notifications?paymentId=12345 ``` ### Create, configure, and test your Notifications See how to create, configure, and test Notifications here: {% content-ref url="/pages/4db80e18f611a59f5d4f47cec31dde81f4be38f6" %} [Notifications](/welcome-to-our-payment-api/api-references/test-payment-api-features/each-api-reference-specifics/notifications) {% endcontent-ref %} # Test Payment API Features # Charity Search To try a test and directly interact with the API endpoint click "Test It" and use an embedded API client to send requests with custom headers and variables, then see the live response; essentially letting you test this API directly within this page. When testing please use our Demo URL: `https://demo-payments.frontstream.com/api/CharitySearch` ## GET /api/CharitySearch > Nonprofit Charity Search ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/CharitySearch":{"get":{"tags":["Charity Search"],"summary":"Nonprofit Charity Search","description":"","parameters":[{"name":"Name","in":"query","description":"optional - Charity Name - partial or full name","schema":{"maxLength":70,"type":"string"}},{"name":"EIN","in":"query","description":"optional - Valid US/CA Nonprofit EIN/Tax ID. For US EINs, the dash proceeding the first two numbers is optional; the endpoint will handle it either way (i.e. 12-3456789 and 123456789 are both valid and will result in the same record being returned)","schema":{"maxLength":15,"minLength":9,"type":"string"}},{"name":"CharitySource","in":"query","description":"optional - This should be either 1 (US) or 2 (Canada) - Default to US","schema":{"type":"integer","format":"int32"}},{"name":"City","in":"query","description":"optional - Searches the city name of charity addresses","schema":{"maxLength":30,"type":"string"}},{"name":"State","in":"query","description":"optional - Searches the state code of charity addresses - ISO Standard two digit State code. (VA, NY)","schema":{"maxLength":2,"type":"string"}},{"name":"PageIndex","in":"query","description":"Defaults to 1 - The page of results to display (i.e. if there are 100 overall results to your search and you provide this as 3 with a PageSize=10, this will return results #21 through #30)","schema":{"type":"integer","format":"int32"}},{"name":"PageSize","in":"query","description":"Defaults to 10 - The number of results to display per page.","schema":{"type":"integer","format":"int32"}},{"name":"SortColumn","in":"query","description":"Default SortColumn NpoName - Indicates which SearchResults field to sort by (see response example for valid values). Only supports sorting by one column.","schema":{"type":"string"}},{"name":"SortDesc","in":"query","description":"true/false - Determine to order the results by descending values of the selected column (or NpoName if not selected).","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Returns Charity Search Data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharitySearchResults"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}},"404":{"description":"If Charity Search Data not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"CharitySearchResults":{"type":"object","properties":{"TotalResultCount":{"type":"integer","description":"How many total possible results there are for your search.","format":"int32"},"TotalPages":{"type":"integer","description":"How many pages of data exist based on your selected PageSize.","format":"int32"},"PageIndex":{"type":"integer","description":"Confirms what you passed in the querystring.","format":"int32"},"PageSize":{"type":"integer","description":"Confirms what you passed in the querystring.","format":"int32"},"SearchResults":{"type":"array","items":{"$ref":"#/components/schemas/CharitySearchResultsList"},"description":"Each record in the array represents a full Charity Record.","nullable":true}},"additionalProperties":false,"description":""},"CharitySearchResultsList":{"type":"object","properties":{"CharityId":{"type":"string","description":"Unique Identifier for the Charity in the Payment API.","nullable":true},"NpoName":{"type":"string","description":"Name of the Charity in the Payment API database.","nullable":true},"EIN":{"type":"string","description":"The United States EIN or Canadian Tax ID of the Charity.","nullable":true},"Address1":{"type":"string","description":"Address Line 1 of the Charity's address.","nullable":true},"Address2":{"type":"string","description":"Address Line 2 of the Charity's address.","nullable":true},"City":{"type":"string","description":"City of the Charity's address.","nullable":true},"State":{"type":"string","description":"State of the Charity's address.","nullable":true},"Zip":{"type":"string","description":"Postal Code of the Charity's address.","nullable":true},"Country":{"type":"string","description":"Country of the Charity's address.","nullable":true},"NpoEligibilityFlag":{"type":"boolean","description":"Indicates whether or not the organization is currently able to receive tax-deductible donations based on United States IRS filings."},"ParentOrgName":{"type":"string","description":"This will return the same value as NpoName if the Charity has no Parent organization, but if a particular organization has indicated that it is a child organization of a larger Charity (such as a regional chapter of a nationwide charity), the Parent Charity name will appear here.","nullable":true},"NTEEcode":{"type":"string","description":"The Charity's NTEE code as defined by United States IRS filings. This is not a required classification, and thus may not exist for all records (and will not exist for Canadian charity records).","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}}} ``` ### Charity Search Example Take a look at how you may call this method: {% tabs %} {% tab title="C#" %} ```csharp using System; using System.Net.Http; using System.Threading.Tasks; using Newtonsoft.Json; public class CharitySearchParams { public string Name { get; set; } public string EIN { get; set; } public int? CharitySource { get; set; } public string City { get; set; } public string State { get; set; } public int PageIndex { get; set; } = 1; public int PageSize { get; set; } = 10; public string SortColumn { get; set; } = "NpoName"; public bool SortDesc { get; set; } = false; } public class CharitySearchResponse { public int TotalResultCount { get; set; } public int TotalPages { get; set; } public int PageIndex { get; set; } public int PageSize { get; set; } public object[] SearchResults { get; set; } } public class Program { private static async Task Main(string[] args) { var charitySearchParams = new CharitySearchParams { Name = "Red Cross", EIN = "123456789", City = "New York", State = "NY", PageIndex = 1, PageSize = 10 }; var url = "https://demo-payments.frontstream.com/api/CharitySearch"; using (var client = new HttpClient()) { var query = $"?Name={charitySearchParams.Name}&EIN={charitySearchParams.EIN}&City={charitySearchParams.City}&State={charitySearchParams.State}&PageIndex={charitySearchParams.PageIndex}&PageSize={charitySearchParams.PageSize}&SortColumn={charitySearchParams.SortColumn}&SortDesc={charitySearchParams.SortDesc}"; var response = await client.GetAsync(url + query); if (response.IsSuccessStatusCode) { var data = await response.Content.ReadAsStringAsync(); var charitySearchResponse = JsonConvert.DeserializeObject(data); Console.WriteLine($"Total Results: {charitySearchResponse.TotalResultCount}"); } else { Console.WriteLine("Error: " + response.StatusCode); } } } } ``` {% endtab %} {% tab title="Postman" %} #### Postman Example for CharitySearch API: 1. **Method**: `GET` 2. **URL**: `https://demo-payments.fronstream.com/api/CharitySearch` 3. **Params**: * `Name`: `Red Cross` (optional, charity name) * `EIN`: `123456789` (optional, EIN or Tax ID) * `City`: `New York` (optional, city) * `State`: `NY` (optional, state code) * `PageIndex`: `1` (optional, default 1) * `PageSize`: `10` (optional, default 10) * `SortColumn`: `NpoName` (optional, default sorting by name) * `SortDesc`: `false` (optional, sort order) After setting these parameters, click **Send** to view the results. {% endtab %} {% endtabs %} # Tokenization To try a test and directly interact with the API endpoint click "Test It" and use an embedded API client to send requests with custom headers and variables, then see the live response; essentially letting you test this API directly within this page. When testing please use our Demo URL: `https://demo-payments.frontstream.com/api/tokenize` ## POST /api/tokenize > Tokenize a credit card ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/tokenize":{"post":{"tags":["Tokenization"],"summary":"Tokenize a credit card","description":"","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/GetTokenRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/GetTokenRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/GetTokenRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/GetTokenRequest"}}}},"responses":{"201":{"description":"Returns the newly created token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTokenResponse"}}}},"400":{"description":"If it fails to create a token","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"GetTokenRequest":{"required":["CardNum","City","Country","Email","ExpMonth","ExpYear","NameOnCard","Street"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"IntegrationSource":{"type":"string","description":"internal use","nullable":true},"CardNum":{"maxLength":30,"type":"string","description":"Valid Credit card number"},"CardType":{"maxLength":20,"type":"string","description":"optional (max: 20) - \"American Express\", \"Mastercard\", \"Visa\", \"Discover\", \"Diners Club\" - will be set internally based on cardNum","nullable":true},"ExpMonth":{"maxLength":2,"minLength":2,"type":"string","description":"example: \"01\" for January - required"},"ExpYear":{"maxLength":2,"minLength":2,"type":"string","description":"example: \"29\" for 2029 - required"},"CVNum":{"maxLength":4,"type":"string","description":"optional (max: 4) - valid CVV - please provide for CVV checks","nullable":true},"NameOnCard":{"maxLength":25,"type":"string","description":"required - Name on Card"},"Email":{"maxLength":100,"type":"string","description":"required - valid contact email","format":"email"},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - please provide for best interchange and avs checks - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000","nullable":true},"Street":{"maxLength":50,"type":"string","description":"required - please provide for best interchange and avs checks"},"City":{"maxLength":50,"type":"string","description":"required - please provide for best interchange and avs checks"},"State":{"maxLength":50,"type":"string","description":"optional - 2 char US state code, 3 char may be used for other non-US","nullable":true},"Country":{"maxLength":2,"type":"string","description":"required - 2 char country code"},"Currency":{"maxLength":3,"type":"string","description":"optional - 3 char currency code - Example for US - \"USD\", for CA - \"CAD\"","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ConstituentId per Product","nullable":true},"ExternalCustomerId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ArgoFire Gateway CustomerKey for pre-existing ArgoFire customers without a Payment API token record","nullable":true},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing First Name","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing Last Name","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"client ip address (max: 40) where transaction originates","nullable":true}},"additionalProperties":false,"description":""},"GetTokenResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"This is \"true\" tokenization process was successful, and \"false\" if unsuccessful."},"Message":{"type":"string","description":"Get Token response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Get Token Processor response message","nullable":true},"TransactionId":{"type":"string","description":"Not currently used and may be null","nullable":true},"TokenGuid":{"type":"string","description":"The unique GUID associated with the credit card or bank token you created that is used with the api/paymentToken endpoint","format":"uuid"},"ExternalCardToken":{"type":"string","description":"ExternalCardToken if available to return - represents 3rd party gateway card token","nullable":true},"ExternalCheckToken":{"type":"string","description":"ExternalCheckToken if available to return - represents 3rd party gateway check token","nullable":true},"ExternalCustomerId":{"type":"string","description":"ExternalCustomerId if available to return - represents 3rd party gateway customer id tied to gateway token","nullable":true},"ExternalConstituentId":{"type":"string","description":"Partner's constituent/donor id provided at tokenize time","nullable":true},"ResponseCode":{"type":"string","description":"Response Code - Successful = \"OK\" or \"0\", any other response code unsuccessful","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ### Tokenize bank data ## POST /api/tokenizeAch > Tokenize ACH/check account ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/tokenizeAch":{"post":{"tags":["Tokenization"],"summary":"Tokenize ACH/check account","description":"","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/GetTokenAchRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/GetTokenAchRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/GetTokenAchRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/GetTokenAchRequest"}}}},"responses":{"201":{"description":"Returns the newly created token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTokenResponse"}}}},"400":{"description":"If it fails to create a token","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"GetTokenAchRequest":{"required":["CheckAccountNumber","CheckAccountTypeId","CheckRoutingNumber","CheckTypeId","City","Country","Email","NameOnCheck","Street"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"CheckRoutingNumber":{"maxLength":9,"type":"string","description":"required - Valid Check Bank Routing Number - formats -\r\nUS: Enter 9-digits,\r\nCA: Enter 9-digits (Format: 0YYYXXXXX: A mandatory leading zero. YYY: The 3-digit institution number. XXXXX: The 5-digit transit number),\r\nAU: Enter 6-digits - BSB Number (Bank State Branch) without hyphen"},"CheckAccountNumber":{"maxLength":20,"type":"string","description":"required - Valid Check Account Number - formats -\r\nUS: Enter 8-12 digits,\r\nCA: Enter 7-12 digits,\r\nAU: Enter 3-9 digits"},"CheckNumber":{"maxLength":10,"type":"string","description":"optional (max: 10) - Valid Check Number","nullable":true},"CheckAccountTypeId":{"type":"string","description":"required for Check ACH transactions - possible values -\r\n 1 - Checking,\r\n 2 - Saving"},"CheckTypeId":{"type":"string","description":"required for Check ACH transactions - possible values -\r\n 1 - Personal,\r\n 2 - Corporate,\r\n 3 - Government"},"NameOnCheck":{"maxLength":25,"type":"string","description":"required - Name on ACH Check Account"},"Email":{"maxLength":100,"type":"string","description":"required - valid contact email","format":"email"},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000","nullable":true},"Street":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing street"},"City":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing city"},"State":{"maxLength":50,"type":"string","description":"optional - 2 char US state code, 3 char may be used for other non-US","nullable":true},"Country":{"maxLength":2,"type":"string","description":"optional - 2 char country code"},"Currency":{"maxLength":3,"type":"string","description":"optional - 3 char currency code - Example for US - \"USD\", for CA - \"CAD\"","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ConstituentId per Product","nullable":true},"ExternalCustomerId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ArgoFire Gateway CustomerKey for pre-existing ArgoFire customers without a Payment API token record","nullable":true},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing First Name","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing Last Name","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"client ip address (max: 40) where transaction originates","nullable":true}},"additionalProperties":false},"GetTokenResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"This is \"true\" tokenization process was successful, and \"false\" if unsuccessful."},"Message":{"type":"string","description":"Get Token response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Get Token Processor response message","nullable":true},"TransactionId":{"type":"string","description":"Not currently used and may be null","nullable":true},"TokenGuid":{"type":"string","description":"The unique GUID associated with the credit card or bank token you created that is used with the api/paymentToken endpoint","format":"uuid"},"ExternalCardToken":{"type":"string","description":"ExternalCardToken if available to return - represents 3rd party gateway card token","nullable":true},"ExternalCheckToken":{"type":"string","description":"ExternalCheckToken if available to return - represents 3rd party gateway check token","nullable":true},"ExternalCustomerId":{"type":"string","description":"ExternalCustomerId if available to return - represents 3rd party gateway customer id tied to gateway token","nullable":true},"ExternalConstituentId":{"type":"string","description":"Partner's constituent/donor id provided at tokenize time","nullable":true},"ResponseCode":{"type":"string","description":"Response Code - Successful = \"OK\" or \"0\", any other response code unsuccessful","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ### Process a Payment using newly created token ## Make a payment by credit card or ACH check token > Request example: > \ > POST /api/paymentToken > \ > { > \ > "ProcessorGuid": "12345678-9012-3456-7890-dc84772c0032", > \ > "TokenGuid": "87654321-9012-3456-7890-123456789012", > \ > "Transactions": > \ > \[ > \ > { > \ > "TransactionSourceGroupId": "12", > \ > "Amount": "1.00", > \ > } > \ > ] > \ > } ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/paymentToken":{"post":{"tags":["Payments"],"summary":"Make a payment by credit card or ACH check token","description":" Request example:\r\n POST /api/paymentToken\r\n\t{\r\n \t\t\"ProcessorGuid\": \"12345678-9012-3456-7890-dc84772c0032\",\r\n \"TokenGuid\": \"87654321-9012-3456-7890-123456789012\",\r\n \"Transactions\":\r\n [\r\n {\r\n \"TransactionSourceGroupId\": \"12\",\r\n \"Amount\": \"1.00\", \r\n }\r\n ]\r\n\t}","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/PaymentTokenRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/PaymentTokenRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/PaymentTokenRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/PaymentTokenRequest"}}}},"responses":{"201":{"description":"Returns the newly created payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"If it fails to create a payment","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"PaymentTokenRequest":{"required":["Transactions"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"TokenGuid":{"type":"string","description":"optional if using ExternalCardToken or ExternalCheckToken instead of TokenGuid - Valid Token Guid from a Tokenized card through Payment API","nullable":true},"ExternalCardToken":{"maxLength":200,"type":"string","description":"internal use","nullable":true},"ExternalCheckToken":{"maxLength":200,"type":"string","description":"internal use","nullable":true},"TranId":{"maxLength":100,"type":"string","description":"optional (max: 100) - system unique id for Dup Checking per Integration Source transaction (where integration source has DupCheckEnabled) that will be checked against successfully processed prior TranIds for Duplicates","nullable":true},"EpfSessionId":{"type":"string","description":"internal use - FrontStream unique Embedded Payment Form Session Id if available","nullable":true},"BillingDescriptor":{"maxLength":22,"type":"string","description":"optional (max: 22) - descriptor to show on bank statement","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"client ip address (max: 40) where transaction originates","nullable":true},"ShippingFee":{"maxLength":7,"type":"string","description":"optional (max: 7) - fee for shipping that will be added to the total amount","nullable":true},"TaxableBenefit":{"maxLength":7,"type":"string","description":"optional (max: 7) - If part of the donation being passed in is taxable, include that amount here. No calculations are performed using this value, it is simply a placeholder to be used for your own reporting; all commission and credit card fees still apply as normal.","nullable":true},"Transactions":{"type":"array","items":{"$ref":"#/components/schemas/PaymentTransTypeRequest"},"description":"required - 1 to n transactions to break down transaction line items"},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) to override zip created during token creation - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000","nullable":true},"Street":{"maxLength":50,"type":"string","description":"optional (max: 50) to override street created during token creation","nullable":true},"City":{"maxLength":50,"type":"string","description":"optional (max: 50) to override city created during token creation","nullable":true},"State":{"maxLength":50,"type":"string","description":"optional (max: 50) to override state created during token creation","nullable":true},"Country":{"maxLength":2,"type":"string","description":"optional (max: 2) to override country created during token creation","nullable":true},"Currency":{"maxLength":3,"type":"string","description":"optional (max: 3) to override currency created during token creation","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - Donor Identifier per Product","nullable":true},"ExternalEventId":{"maxLength":10,"type":"string","description":"optional (max: 10) - Event Identifier per Product","nullable":true},"ExternalEventGuid":{"type":"string","description":"optional - Event Guid per Product","nullable":true},"ExternalEventName":{"maxLength":500,"type":"string","description":"optional (max: 500) - Event Name per Product","nullable":true},"AFShieldAdditional":{"$ref":"#/components/schemas/AFShieldPaymentRequest"},"Surcharge":{"maxLength":7,"type":"string","description":"optional (max: 7) - calculated surcharge amount","nullable":true}},"additionalProperties":false,"description":""},"PaymentTransTypeRequest":{"required":["Amount","TransactionSourceGroupId"],"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","description":"required - For Direct Merchant (For Profit) Api Partners should set to PaymentNoFee (12), other values are for Non Profit transactions - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;\r\n 13 - EventDonationFee;\r\n 14 - SponsorshipFee\r\n 15 - MembershipFee"},"Amount":{"maxLength":7,"type":"string","description":"required - Amount of line item without the fees included, Payment api will calculate fees for you"},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction. Indicates if the donor intends to cover the processing fees for the donation (primary used for Non Profit transactions like a donation)"},"CommissionRateOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - The percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract.","nullable":true},"CardProcessingFeeOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - Overrides the default percentage processing fee","nullable":true},"ExternalLineId":{"maxLength":100,"type":"string","description":"optional (max: 100) - use this to track individual line item IDs if necessary.","nullable":true},"Tip":{"maxLength":7,"type":"string","description":"optional (max: 7) - An amount taken up front for the API Partner if Donor decides to apply a tip. Added to the total amount to charge on the donor’s card . Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true},"Tax":{"maxLength":7,"type":"string","description":"optional (max: 7) - A tax amount taken up front. Added to the total amount to charge on the donor’s card. Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true}},"additionalProperties":false,"description":""},"AFShieldPaymentRequest":{"type":"object","properties":{"ProductDescription":{"maxLength":256,"type":"string","nullable":true},"ProductItem":{"maxLength":256,"type":"string","nullable":true},"ProductType":{"maxLength":256,"type":"string","nullable":true},"ProductQuantity":{"maxLength":3,"type":"string","nullable":true},"SessionId":{"maxLength":32,"type":"string","nullable":true},"BillToPhoneNumber":{"maxLength":32,"type":"string","nullable":true},"ShippingAddressStreet1":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressStreet2":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressCountry":{"maxLength":2,"type":"string","nullable":true},"ShippingAddressCity":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressEmail":{"maxLength":64,"type":"string","format":"email","nullable":true},"ShippingAddressName":{"maxLength":64,"type":"string","nullable":true},"ShippingAddressZip":{"maxLength":10,"type":"string","nullable":true},"ShippingAddressState":{"maxLength":50,"type":"string","nullable":true},"ShipToPhoneNumber":{"maxLength":32,"type":"string","nullable":true},"ShipToPremiseForUK":{"maxLength":256,"type":"string","nullable":true},"ShipToStreetForUK":{"maxLength":256,"type":"string","nullable":true},"BillToPremiseForUK":{"maxLength":256,"type":"string","nullable":true},"BillToStreetForUK":{"maxLength":256,"type":"string","nullable":true}},"additionalProperties":false,"description":""},"PaymentResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"As one would guess, this is \"true\" if the transaction was processed successfully, and \"false\" if the transaction was not processed successfully."},"Message":{"type":"string","description":"Payment Gateway response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Response from the processing bank.","nullable":true},"AuthCode":{"type":"string","description":"AuthCode from the processor.","nullable":true},"TransactionId":{"type":"string","description":"Payment Gateway TransactionId","nullable":true},"PaymentGuid":{"type":"string","description":"Payment API Payment GUID","format":"uuid"},"PaymentId":{"type":"integer","description":"Payment API Payment Id","format":"int32"},"ResponseCode":{"type":"string","description":"Response Code - Approved = 0, Not processed = -100 with more possible values - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"PaymentResult":{"$ref":"#/components/schemas/PaymentResult"},"ProcessStatus":{"$ref":"#/components/schemas/ProcessStatus"},"TotalAmount":{"type":"number","description":"The total amount processed toward the cardholder's account.","format":"double"},"TotalSurcharge":{"type":"number","description":"The total surcharge amount if available.","format":"double","nullable":true},"AVSStreetStatus":{"type":"string","description":"Address Verification Street Status if available.","nullable":true},"AVSZipStatus":{"type":"string","description":"Address Verification Zip Status if available.","nullable":true},"AVSResponse":{"type":"string","description":"Address Verification Response if available. AVS and CVV response values covered more here - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"CVVResponse":{"type":"string","description":"Card Verification Response if available. AVS and CVV response values covered more here - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"ExternalCardToken":{"type":"string","description":"ExternalCardToken if available to return - represents 3rd party gateway card token","nullable":true},"ExternalCheckToken":{"type":"string","description":"ExternalCheckToken if available to return - represents 3rd party gateway check token","nullable":true},"ExternalCustomerId":{"type":"string","description":"ExternalCustomerId if available to return - represents 3rd party gateway customer id tied to gateway token","nullable":true},"ExternalConstituentId":{"type":"string","description":"ExternalConstituentId if available to return - merchant-supplied constituent/donor id linked to this token","nullable":true},"TokenGuid":{"type":"string","description":"Payment API Token GUID if available to return","format":"uuid","nullable":true},"TransactionFees":{"type":"array","items":{"$ref":"#/components/schemas/FeeResponse"},"description":"Fee Response","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use","format":"uuid"},"ProcessorGuid":{"type":"string","description":"ProcessorGuid used","format":"uuid","nullable":true},"FirstName":{"type":"string","nullable":true},"LastName":{"type":"string","nullable":true},"EmailAddress":{"type":"string","nullable":true},"PostalCode":{"type":"string","nullable":true},"AddressLine1":{"type":"string","nullable":true},"City":{"type":"string","nullable":true},"ProvinceCode":{"type":"string","nullable":true},"CountryCode":{"type":"string","nullable":true},"CardNum":{"type":"string","description":"last 4 digits of card","nullable":true},"CardType":{"type":"string","description":"possible values if available: American Express, Mastercard, Visa, Discover, Diners Club, Undefined","nullable":true},"ExpMonth":{"type":"string","nullable":true},"ExpYear":{"type":"string","nullable":true},"Currency":{"type":"string","nullable":true},"PaymentMethodTypeId":{"type":"integer","description":"possible values if available:\r\nNone = 0,\r\nAmericanExpress = 1,\r\nMasterCard = 2,\r\nVisa = 3,\r\nDiscover = 4,\r\nDinersClub = 5,\r\nACH = 7,\r\nGOOGLEPAY = 8,\r\nAPPLEPAY = 9","format":"int32","nullable":true},"IsSurchargeEligible":{"type":"boolean","description":"Was card used Surcharge eligible","nullable":true},"CheckAccountNum":{"type":"string","description":"last 4 digits of check account","nullable":true},"TranId":{"type":"string","description":"unique tran id per Integration Source if available","nullable":true},"EpfSessionId":{"type":"string","description":"FrontStream unique Embedded Payment Form Session Id if available","nullable":true},"PaymentDate":{"type":"string","description":"Payment Date of transaction","format":"date-time"}},"additionalProperties":false,"description":"See more response code definitions here: https://developers.frontstream.com/welcome-to-our-payment-api/api-references/test-payment-api-features/response-codes"},"PaymentResult":{"enum":[1,2,3,4,5,6],"type":"integer","format":"int32"},"ProcessStatus":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12],"type":"integer","format":"int32"},"FeeResponse":{"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","nullable":true},"PaymentAmount":{"type":"number","description":"This is the amount charged to the donor. Will be equal to the sum of the Amount parameters if payFee=false, but if payFee=true, then this will be the amount that will be charged to the donor in order to have the net post-disbursement donation be equal to the Amount parameters.","format":"double","nullable":true},"CardFeeRate":{"type":"number","description":"example 2.5% - applied to EVERY donation. This is the FrontStream card processing fee. The percentage of the PaymentAmount that will be taken for credit card fees. Expressed as a human-readable percentage rather than a decimal value, it is intended to be able to be displayed directly on a page without needing to be converted.","format":"double","nullable":true},"CardFeeAmount":{"type":"number","description":"This is the amount that is owed to the gateway for the example 2.5% that FrontStream collects from the transaction.\r\n 2.5% of transaction amount if donor is not paying the fee, otherwise 2.5% of the transaction + card fee.","format":"double","nullable":true},"CardTypeFeeAmount":{"type":"number","description":"A per transaction fee configured by card type (VI, MC, DI, AMEX, etc.) per API Partner's Contract other wise 0 (zero)","format":"double","nullable":true},"TotalCommissionRate":{"type":"number","description":"The Total percentage of Commissions that FrontStream takes from a given transaction.\r\nThis rate = Partner CommissionRate + FS CommissionRate","format":"double","nullable":true},"TotalCommissionAmount":{"type":"number","description":"The product of the transaction times the Total commission rate.","format":"double","nullable":true},"PartnerCommissionRate":{"type":"number","description":"The Partner Commission percentage taken on behalf of the Partner from a given transaction.","format":"double","nullable":true},"PartnerCommissionAmount":{"type":"number","description":"The product of the transaction times the Partner commission rate.","format":"double","nullable":true},"FsCommissionRate":{"type":"number","description":"The FrontStream Commission percentage that FrontStream takes from a given transaction.","format":"double","nullable":true},"FsCommissionAmount":{"type":"number","description":"The product of the transaction times the FrontStream commission rate.","format":"double","nullable":true},"TotalFees":{"type":"number","description":"The sum of all fees applied to a transaction amount. (TotalCommission + CardFee + FlatFee + CardFeeOnFee)","format":"double","nullable":true},"MaxOverridePartnerCommissionRate":{"type":"number","description":"The derived minimum partner override rate and maximum partner override rate\r\n\r\nMaxOverridePartnerCommissionRate = TotalFees = (PartnerCommission rate) + (Card Fee Rate) + (Fs Commission Rate)\r\nMinOverridePartnerCommissionRate = (Card Fee rate) + (Fs Commission rate)","format":"double"},"MinOverridePartnerCommissionRate":{"type":"number","format":"double"},"PerTransFee":{"type":"number","description":"The flat amount that will be taken from the PaymentAmount for any Per-Transaction Fees as configured in your contract.","format":"double","nullable":true},"Tip":{"type":"number","description":"The flat amount that will be paid out to the API Partner if Donor decides to add a tip regardless of payFee true or false.","format":"double"},"CardFeeOnFeeAmount":{"type":"number","format":"double","nullable":true},"Tax":{"type":"number","format":"double","nullable":true},"AchFeeRate":{"type":"number","description":"The ACH processing fee rate applied to this transaction.","format":"double","nullable":true},"AchFeeAmount":{"type":"number","description":"The ACH processing fee amount for this transaction.","format":"double","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ### Tokenize Example Take a look at how you might call this method: {% tabs %} {% tab title="C#" %} ``` // Some code ``` {% endtab %} {% tab title="Postman" %} {% endtab %} {% endtabs %} # Payment To try a test and directly interact with the API endpoint click "Test It" and use an embedded API client to send requests with custom headers and variables, then see the live response; essentially letting you test this API directly within this page. When testing please use our Demo URL: `https://demo-payments.frontstream.com/api/payment` ## POST /api/payment > Make a payment ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/payment":{"post":{"tags":["Payments"],"summary":"Make a payment","description":"","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"responses":{"201":{"description":"Returns the newly created payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"If it fails to create a payment","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"PaymentRequest":{"required":["Email","IpAddress","NameOnCard","Transactions"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"MKey":{"maxLength":500,"type":"string","description":"internal use - Used by FrontStream only","nullable":true},"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"CardNum":{"maxLength":30,"type":"string","description":"optional - Valid Credit card number - required for non-Wallet transaction","nullable":true},"CardType":{"maxLength":20,"type":"string","description":"optional (max: 20) - \"American Express\", \"Mastercard\", \"Visa\", \"Discover\", \"Diners Club\" - will be set internally based on cardNum","nullable":true},"ExpMonth":{"maxLength":2,"type":"string","description":"optional (max: 2) - example: \"01\" for January - required for non-Wallet transaction","nullable":true},"ExpYear":{"maxLength":2,"type":"string","description":"optional (max: 2) - example: \"29\" for 2029 - required for non-Wallet transaction","nullable":true},"CVNum":{"maxLength":4,"type":"string","description":"optional (max: 4) - valid CVV - please provide for CVV checks","nullable":true},"NameOnCard":{"maxLength":25,"type":"string","description":"required - Name on Card"},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - please provide for best interchange and avs checks - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000","nullable":true},"Street":{"maxLength":50,"type":"string","description":"optional (max: 50) - please provide for best interchange and avs checks","nullable":true},"Email":{"maxLength":100,"type":"string","description":"required - valid contact email","format":"email"},"City":{"maxLength":50,"type":"string","description":"optional (max: 50) - please provide for best interchange and avs checks","nullable":true},"State":{"maxLength":50,"type":"string","description":"optional - 2 char US state code, 3 char may be used for other non-US","nullable":true},"Country":{"maxLength":2,"type":"string","description":"optional (max: 2) - 2 char country code","nullable":true},"Currency":{"maxLength":3,"type":"string","description":"optional (max: 3) - 3 char currency code - Example for US - \"USD\", for CA - \"CAD\"","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - Donor Identifier per Product","nullable":true},"ExternalCustomerId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ArgoFire Gateway CustomerKey for pre-existing ArgoFire customers without a Payment API token record","nullable":true},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing First Name","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing Last Name","nullable":true},"BillingDescriptor":{"maxLength":22,"type":"string","description":"optional (max: 22) - descriptor to show on bank statement","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"required - client ip address where transaction originates"},"ExternalEventId":{"maxLength":10,"type":"string","description":"optional (max: 10) - Event Identifier per Product","nullable":true},"ExternalEventGuid":{"type":"string","description":"optional - Event Guid per Product","nullable":true},"ExternalEventName":{"maxLength":500,"type":"string","description":"optional (max: 500) - Event Name per Product","nullable":true},"ShippingFee":{"maxLength":7,"type":"string","description":"optional (max: 7) - fee for shipping that will be added to the total amount","nullable":true},"TaxableBenefit":{"maxLength":7,"type":"string","description":"optional (max: 7) - If part of the donation being passed in is taxable, include that amount here. No calculations are performed using this value, it is simply a placeholder to be used for your own reporting; all commission and credit card fees still apply as normal.","nullable":true},"TranId":{"maxLength":100,"type":"string","description":"optional (max: 100) - system unique id for Dup Checking per Integration Source transaction (where integration source has DupCheckEnabled) that will be checked against successfully processed prior TranIds for Duplicates","nullable":true},"EpfSessionId":{"type":"string","description":"internal use - FrontStream unique Embedded Payment Form Session Id if available","nullable":true},"Transactions":{"type":"array","items":{"$ref":"#/components/schemas/PaymentTransTypeRequest"},"description":"required - 1 to n transactions to break down transaction line items"},"AFShieldAdditional":{"$ref":"#/components/schemas/AFShieldPaymentRequest"},"PaymentMethodTypeId":{"type":"string","description":"internal use - GooglePay (8) or Apple Pay (9) - possible values -\r\n \"8\" - GOOGLEPAY,\r\n \"9\" - APPLEPAY","nullable":true},"ExternalPaymentData":{"maxLength":5000,"type":"string","description":"internal use for Wallet transactions","nullable":true},"Surcharge":{"maxLength":7,"type":"string","description":"optional (max: 7) - calculated surcharge amount that will be added to the total amount","nullable":true},"Tokenize":{"type":"boolean","description":"optional - set to true to tokenize card at time of purchase","nullable":true}},"additionalProperties":false,"description":""},"PaymentTransTypeRequest":{"required":["Amount","TransactionSourceGroupId"],"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","description":"required - For Direct Merchant (For Profit) Api Partners should set to PaymentNoFee (12), other values are for Non Profit transactions - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;\r\n 13 - EventDonationFee;\r\n 14 - SponsorshipFee\r\n 15 - MembershipFee"},"Amount":{"maxLength":7,"type":"string","description":"required - Amount of line item without the fees included, Payment api will calculate fees for you"},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction. Indicates if the donor intends to cover the processing fees for the donation (primary used for Non Profit transactions like a donation)"},"CommissionRateOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - The percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract.","nullable":true},"CardProcessingFeeOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - Overrides the default percentage processing fee","nullable":true},"ExternalLineId":{"maxLength":100,"type":"string","description":"optional (max: 100) - use this to track individual line item IDs if necessary.","nullable":true},"Tip":{"maxLength":7,"type":"string","description":"optional (max: 7) - An amount taken up front for the API Partner if Donor decides to apply a tip. Added to the total amount to charge on the donor’s card . Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true},"Tax":{"maxLength":7,"type":"string","description":"optional (max: 7) - A tax amount taken up front. Added to the total amount to charge on the donor’s card. Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true}},"additionalProperties":false,"description":""},"AFShieldPaymentRequest":{"type":"object","properties":{"ProductDescription":{"maxLength":256,"type":"string","nullable":true},"ProductItem":{"maxLength":256,"type":"string","nullable":true},"ProductType":{"maxLength":256,"type":"string","nullable":true},"ProductQuantity":{"maxLength":3,"type":"string","nullable":true},"SessionId":{"maxLength":32,"type":"string","nullable":true},"BillToPhoneNumber":{"maxLength":32,"type":"string","nullable":true},"ShippingAddressStreet1":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressStreet2":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressCountry":{"maxLength":2,"type":"string","nullable":true},"ShippingAddressCity":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressEmail":{"maxLength":64,"type":"string","format":"email","nullable":true},"ShippingAddressName":{"maxLength":64,"type":"string","nullable":true},"ShippingAddressZip":{"maxLength":10,"type":"string","nullable":true},"ShippingAddressState":{"maxLength":50,"type":"string","nullable":true},"ShipToPhoneNumber":{"maxLength":32,"type":"string","nullable":true},"ShipToPremiseForUK":{"maxLength":256,"type":"string","nullable":true},"ShipToStreetForUK":{"maxLength":256,"type":"string","nullable":true},"BillToPremiseForUK":{"maxLength":256,"type":"string","nullable":true},"BillToStreetForUK":{"maxLength":256,"type":"string","nullable":true}},"additionalProperties":false,"description":""},"PaymentResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"As one would guess, this is \"true\" if the transaction was processed successfully, and \"false\" if the transaction was not processed successfully."},"Message":{"type":"string","description":"Payment Gateway response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Response from the processing bank.","nullable":true},"AuthCode":{"type":"string","description":"AuthCode from the processor.","nullable":true},"TransactionId":{"type":"string","description":"Payment Gateway TransactionId","nullable":true},"PaymentGuid":{"type":"string","description":"Payment API Payment GUID","format":"uuid"},"PaymentId":{"type":"integer","description":"Payment API Payment Id","format":"int32"},"ResponseCode":{"type":"string","description":"Response Code - Approved = 0, Not processed = -100 with more possible values - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"PaymentResult":{"$ref":"#/components/schemas/PaymentResult"},"ProcessStatus":{"$ref":"#/components/schemas/ProcessStatus"},"TotalAmount":{"type":"number","description":"The total amount processed toward the cardholder's account.","format":"double"},"TotalSurcharge":{"type":"number","description":"The total surcharge amount if available.","format":"double","nullable":true},"AVSStreetStatus":{"type":"string","description":"Address Verification Street Status if available.","nullable":true},"AVSZipStatus":{"type":"string","description":"Address Verification Zip Status if available.","nullable":true},"AVSResponse":{"type":"string","description":"Address Verification Response if available. AVS and CVV response values covered more here - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"CVVResponse":{"type":"string","description":"Card Verification Response if available. AVS and CVV response values covered more here - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"ExternalCardToken":{"type":"string","description":"ExternalCardToken if available to return - represents 3rd party gateway card token","nullable":true},"ExternalCheckToken":{"type":"string","description":"ExternalCheckToken if available to return - represents 3rd party gateway check token","nullable":true},"ExternalCustomerId":{"type":"string","description":"ExternalCustomerId if available to return - represents 3rd party gateway customer id tied to gateway token","nullable":true},"ExternalConstituentId":{"type":"string","description":"ExternalConstituentId if available to return - merchant-supplied constituent/donor id linked to this token","nullable":true},"TokenGuid":{"type":"string","description":"Payment API Token GUID if available to return","format":"uuid","nullable":true},"TransactionFees":{"type":"array","items":{"$ref":"#/components/schemas/FeeResponse"},"description":"Fee Response","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use","format":"uuid"},"ProcessorGuid":{"type":"string","description":"ProcessorGuid used","format":"uuid","nullable":true},"FirstName":{"type":"string","nullable":true},"LastName":{"type":"string","nullable":true},"EmailAddress":{"type":"string","nullable":true},"PostalCode":{"type":"string","nullable":true},"AddressLine1":{"type":"string","nullable":true},"City":{"type":"string","nullable":true},"ProvinceCode":{"type":"string","nullable":true},"CountryCode":{"type":"string","nullable":true},"CardNum":{"type":"string","description":"last 4 digits of card","nullable":true},"CardType":{"type":"string","description":"possible values if available: American Express, Mastercard, Visa, Discover, Diners Club, Undefined","nullable":true},"ExpMonth":{"type":"string","nullable":true},"ExpYear":{"type":"string","nullable":true},"Currency":{"type":"string","nullable":true},"PaymentMethodTypeId":{"type":"integer","description":"possible values if available:\r\nNone = 0,\r\nAmericanExpress = 1,\r\nMasterCard = 2,\r\nVisa = 3,\r\nDiscover = 4,\r\nDinersClub = 5,\r\nACH = 7,\r\nGOOGLEPAY = 8,\r\nAPPLEPAY = 9","format":"int32","nullable":true},"IsSurchargeEligible":{"type":"boolean","description":"Was card used Surcharge eligible","nullable":true},"CheckAccountNum":{"type":"string","description":"last 4 digits of check account","nullable":true},"TranId":{"type":"string","description":"unique tran id per Integration Source if available","nullable":true},"EpfSessionId":{"type":"string","description":"FrontStream unique Embedded Payment Form Session Id if available","nullable":true},"PaymentDate":{"type":"string","description":"Payment Date of transaction","format":"date-time"}},"additionalProperties":false,"description":"See more response code definitions here: https://developers.frontstream.com/welcome-to-our-payment-api/api-references/test-payment-api-features/response-codes"},"PaymentResult":{"enum":[1,2,3,4,5,6],"type":"integer","format":"int32"},"ProcessStatus":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12],"type":"integer","format":"int32"},"FeeResponse":{"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","nullable":true},"PaymentAmount":{"type":"number","description":"This is the amount charged to the donor. Will be equal to the sum of the Amount parameters if payFee=false, but if payFee=true, then this will be the amount that will be charged to the donor in order to have the net post-disbursement donation be equal to the Amount parameters.","format":"double","nullable":true},"CardFeeRate":{"type":"number","description":"example 2.5% - applied to EVERY donation. This is the FrontStream card processing fee. The percentage of the PaymentAmount that will be taken for credit card fees. Expressed as a human-readable percentage rather than a decimal value, it is intended to be able to be displayed directly on a page without needing to be converted.","format":"double","nullable":true},"CardFeeAmount":{"type":"number","description":"This is the amount that is owed to the gateway for the example 2.5% that FrontStream collects from the transaction.\r\n 2.5% of transaction amount if donor is not paying the fee, otherwise 2.5% of the transaction + card fee.","format":"double","nullable":true},"CardTypeFeeAmount":{"type":"number","description":"A per transaction fee configured by card type (VI, MC, DI, AMEX, etc.) per API Partner's Contract other wise 0 (zero)","format":"double","nullable":true},"TotalCommissionRate":{"type":"number","description":"The Total percentage of Commissions that FrontStream takes from a given transaction.\r\nThis rate = Partner CommissionRate + FS CommissionRate","format":"double","nullable":true},"TotalCommissionAmount":{"type":"number","description":"The product of the transaction times the Total commission rate.","format":"double","nullable":true},"PartnerCommissionRate":{"type":"number","description":"The Partner Commission percentage taken on behalf of the Partner from a given transaction.","format":"double","nullable":true},"PartnerCommissionAmount":{"type":"number","description":"The product of the transaction times the Partner commission rate.","format":"double","nullable":true},"FsCommissionRate":{"type":"number","description":"The FrontStream Commission percentage that FrontStream takes from a given transaction.","format":"double","nullable":true},"FsCommissionAmount":{"type":"number","description":"The product of the transaction times the FrontStream commission rate.","format":"double","nullable":true},"TotalFees":{"type":"number","description":"The sum of all fees applied to a transaction amount. (TotalCommission + CardFee + FlatFee + CardFeeOnFee)","format":"double","nullable":true},"MaxOverridePartnerCommissionRate":{"type":"number","description":"The derived minimum partner override rate and maximum partner override rate\r\n\r\nMaxOverridePartnerCommissionRate = TotalFees = (PartnerCommission rate) + (Card Fee Rate) + (Fs Commission Rate)\r\nMinOverridePartnerCommissionRate = (Card Fee rate) + (Fs Commission rate)","format":"double"},"MinOverridePartnerCommissionRate":{"type":"number","format":"double"},"PerTransFee":{"type":"number","description":"The flat amount that will be taken from the PaymentAmount for any Per-Transaction Fees as configured in your contract.","format":"double","nullable":true},"Tip":{"type":"number","description":"The flat amount that will be paid out to the API Partner if Donor decides to add a tip regardless of payFee true or false.","format":"double"},"CardFeeOnFeeAmount":{"type":"number","format":"double","nullable":true},"Tax":{"type":"number","format":"double","nullable":true},"AchFeeRate":{"type":"number","description":"The ACH processing fee rate applied to this transaction.","format":"double","nullable":true},"AchFeeAmount":{"type":"number","description":"The ACH processing fee amount for this transaction.","format":"double","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` When testing please use our Demo URL: `https://demo-payments.frontstream.com/api/paymentAch` ## POST /api/paymentAch > Make an ach payment ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/paymentAch":{"post":{"tags":["Payments"],"summary":"Make an ach payment","description":"","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/PaymentAchRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/PaymentAchRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/PaymentAchRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/PaymentAchRequest"}}}},"responses":{"201":{"description":"Returns the newly created payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"If it fails to create a payment","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"PaymentAchRequest":{"required":["CheckAccountNumber","CheckAccountTypeId","CheckRoutingNumber","CheckTypeId","Email","IpAddress","NameOnCheck","State","Transactions"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"MKey":{"maxLength":500,"type":"string","description":"internal use - Used by FrontStream only","nullable":true},"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"CheckRoutingNumber":{"maxLength":9,"type":"string","description":"required - Valid Check Bank Routing Number - formats -\r\nUS: Enter 9-digits,\r\nCA: Enter 9-digits (Format: 0YYYXXXXX: A mandatory leading zero. YYY: The 3-digit institution number. XXXXX: The 5-digit transit number),\r\nAU: Enter 6-digits - BSB Number (Bank State Branch) without hyphen"},"CheckAccountNumber":{"maxLength":20,"type":"string","description":"required - Valid Check Account Number - formats -\r\nUS: Enter 8-12 digits,\r\nCA: Enter 7-12 digits,\r\nAU: Enter 3-9 digits"},"CheckNumber":{"maxLength":10,"type":"string","description":"optional (max: 10) - Valid Check Number","nullable":true},"CheckAccountTypeId":{"type":"string","description":"required for Check ACH transactions - possible values -\r\n 1 - Checking,\r\n 2 - Savings"},"CheckTypeId":{"type":"string","description":"required for Check ACH transactions - possible values -\r\n 1 - Personal,\r\n 2 - Corporate,\r\n 3 - Government"},"NameOnCheck":{"maxLength":25,"type":"string","description":"required - Name on ACH Check Account"},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000","nullable":true},"Street":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing street","nullable":true},"Email":{"maxLength":100,"type":"string","description":"required - valid contact email","format":"email"},"City":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing city","nullable":true},"State":{"maxLength":50,"type":"string","description":"required - 2 char US state code, 3 char may be used for other non-US"},"Country":{"maxLength":2,"type":"string","description":"optional - 2 char country code","nullable":true},"Currency":{"maxLength":3,"type":"string","description":"optional - 3 char currency code - Example for US - \"USD\", for CA - \"CAD\"","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - Donor Identifier per Product","nullable":true},"ExternalCustomerId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ArgoFire Gateway CustomerKey for pre-existing ArgoFire customers without a Payment API token record","nullable":true},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing First Name","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing Last Name","nullable":true},"BillingDescriptor":{"maxLength":22,"type":"string","description":"optional (max: 22) - descriptor to show on bank statement","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"required - client ip address where transaction originates"},"ExternalEventId":{"maxLength":10,"type":"string","description":"optional (max: 10) - Event Identifier per Product","nullable":true},"ExternalEventGuid":{"type":"string","description":"optional - Event Guid per Product","nullable":true},"ExternalEventName":{"maxLength":500,"type":"string","description":"optional (max: 500) - Event Name per Product","nullable":true},"ShippingFee":{"maxLength":7,"type":"string","description":"optional (max: 7) - fee for shipping that will be added to the total amount","nullable":true},"TaxableBenefit":{"maxLength":7,"type":"string","description":"optional (max: 7) - If part of the donation being passed in is taxable, include that amount here. No calculations are performed using this value, it is simply a placeholder to be used for your own reporting; all commission and credit card fees still apply as normal.","nullable":true},"TranId":{"maxLength":100,"type":"string","description":"optional (max: 100) - system unique id for Dup Checking per Integration Source transaction (where integration source has DupCheckEnabled) that will be checked against successfully processed prior TranIds for Duplicates","nullable":true},"EpfSessionId":{"type":"string","description":"internal use - FrontStream unique Embedded Payment Form Session Id if available","nullable":true},"Transactions":{"type":"array","items":{"$ref":"#/components/schemas/PaymentTransTypeRequest"},"description":"required - 1 to n transactions to break down transaction line items"},"PaymentMethodTypeId":{"type":"string","description":"optional - if used please set to 7 for ACH or will be set internally","nullable":true},"Tokenize":{"type":"boolean","description":"optional - set to true to tokenize check at time of purchase","nullable":true}},"additionalProperties":false},"PaymentTransTypeRequest":{"required":["Amount","TransactionSourceGroupId"],"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","description":"required - For Direct Merchant (For Profit) Api Partners should set to PaymentNoFee (12), other values are for Non Profit transactions - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;\r\n 13 - EventDonationFee;\r\n 14 - SponsorshipFee\r\n 15 - MembershipFee"},"Amount":{"maxLength":7,"type":"string","description":"required - Amount of line item without the fees included, Payment api will calculate fees for you"},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction. Indicates if the donor intends to cover the processing fees for the donation (primary used for Non Profit transactions like a donation)"},"CommissionRateOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - The percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract.","nullable":true},"CardProcessingFeeOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - Overrides the default percentage processing fee","nullable":true},"ExternalLineId":{"maxLength":100,"type":"string","description":"optional (max: 100) - use this to track individual line item IDs if necessary.","nullable":true},"Tip":{"maxLength":7,"type":"string","description":"optional (max: 7) - An amount taken up front for the API Partner if Donor decides to apply a tip. Added to the total amount to charge on the donor’s card . Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true},"Tax":{"maxLength":7,"type":"string","description":"optional (max: 7) - A tax amount taken up front. Added to the total amount to charge on the donor’s card. Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true}},"additionalProperties":false,"description":""},"PaymentResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"As one would guess, this is \"true\" if the transaction was processed successfully, and \"false\" if the transaction was not processed successfully."},"Message":{"type":"string","description":"Payment Gateway response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Response from the processing bank.","nullable":true},"AuthCode":{"type":"string","description":"AuthCode from the processor.","nullable":true},"TransactionId":{"type":"string","description":"Payment Gateway TransactionId","nullable":true},"PaymentGuid":{"type":"string","description":"Payment API Payment GUID","format":"uuid"},"PaymentId":{"type":"integer","description":"Payment API Payment Id","format":"int32"},"ResponseCode":{"type":"string","description":"Response Code - Approved = 0, Not processed = -100 with more possible values - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"PaymentResult":{"$ref":"#/components/schemas/PaymentResult"},"ProcessStatus":{"$ref":"#/components/schemas/ProcessStatus"},"TotalAmount":{"type":"number","description":"The total amount processed toward the cardholder's account.","format":"double"},"TotalSurcharge":{"type":"number","description":"The total surcharge amount if available.","format":"double","nullable":true},"AVSStreetStatus":{"type":"string","description":"Address Verification Street Status if available.","nullable":true},"AVSZipStatus":{"type":"string","description":"Address Verification Zip Status if available.","nullable":true},"AVSResponse":{"type":"string","description":"Address Verification Response if available. AVS and CVV response values covered more here - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"CVVResponse":{"type":"string","description":"Card Verification Response if available. AVS and CVV response values covered more here - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"ExternalCardToken":{"type":"string","description":"ExternalCardToken if available to return - represents 3rd party gateway card token","nullable":true},"ExternalCheckToken":{"type":"string","description":"ExternalCheckToken if available to return - represents 3rd party gateway check token","nullable":true},"ExternalCustomerId":{"type":"string","description":"ExternalCustomerId if available to return - represents 3rd party gateway customer id tied to gateway token","nullable":true},"ExternalConstituentId":{"type":"string","description":"ExternalConstituentId if available to return - merchant-supplied constituent/donor id linked to this token","nullable":true},"TokenGuid":{"type":"string","description":"Payment API Token GUID if available to return","format":"uuid","nullable":true},"TransactionFees":{"type":"array","items":{"$ref":"#/components/schemas/FeeResponse"},"description":"Fee Response","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use","format":"uuid"},"ProcessorGuid":{"type":"string","description":"ProcessorGuid used","format":"uuid","nullable":true},"FirstName":{"type":"string","nullable":true},"LastName":{"type":"string","nullable":true},"EmailAddress":{"type":"string","nullable":true},"PostalCode":{"type":"string","nullable":true},"AddressLine1":{"type":"string","nullable":true},"City":{"type":"string","nullable":true},"ProvinceCode":{"type":"string","nullable":true},"CountryCode":{"type":"string","nullable":true},"CardNum":{"type":"string","description":"last 4 digits of card","nullable":true},"CardType":{"type":"string","description":"possible values if available: American Express, Mastercard, Visa, Discover, Diners Club, Undefined","nullable":true},"ExpMonth":{"type":"string","nullable":true},"ExpYear":{"type":"string","nullable":true},"Currency":{"type":"string","nullable":true},"PaymentMethodTypeId":{"type":"integer","description":"possible values if available:\r\nNone = 0,\r\nAmericanExpress = 1,\r\nMasterCard = 2,\r\nVisa = 3,\r\nDiscover = 4,\r\nDinersClub = 5,\r\nACH = 7,\r\nGOOGLEPAY = 8,\r\nAPPLEPAY = 9","format":"int32","nullable":true},"IsSurchargeEligible":{"type":"boolean","description":"Was card used Surcharge eligible","nullable":true},"CheckAccountNum":{"type":"string","description":"last 4 digits of check account","nullable":true},"TranId":{"type":"string","description":"unique tran id per Integration Source if available","nullable":true},"EpfSessionId":{"type":"string","description":"FrontStream unique Embedded Payment Form Session Id if available","nullable":true},"PaymentDate":{"type":"string","description":"Payment Date of transaction","format":"date-time"}},"additionalProperties":false,"description":"See more response code definitions here: https://developers.frontstream.com/welcome-to-our-payment-api/api-references/test-payment-api-features/response-codes"},"PaymentResult":{"enum":[1,2,3,4,5,6],"type":"integer","format":"int32"},"ProcessStatus":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12],"type":"integer","format":"int32"},"FeeResponse":{"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","nullable":true},"PaymentAmount":{"type":"number","description":"This is the amount charged to the donor. Will be equal to the sum of the Amount parameters if payFee=false, but if payFee=true, then this will be the amount that will be charged to the donor in order to have the net post-disbursement donation be equal to the Amount parameters.","format":"double","nullable":true},"CardFeeRate":{"type":"number","description":"example 2.5% - applied to EVERY donation. This is the FrontStream card processing fee. The percentage of the PaymentAmount that will be taken for credit card fees. Expressed as a human-readable percentage rather than a decimal value, it is intended to be able to be displayed directly on a page without needing to be converted.","format":"double","nullable":true},"CardFeeAmount":{"type":"number","description":"This is the amount that is owed to the gateway for the example 2.5% that FrontStream collects from the transaction.\r\n 2.5% of transaction amount if donor is not paying the fee, otherwise 2.5% of the transaction + card fee.","format":"double","nullable":true},"CardTypeFeeAmount":{"type":"number","description":"A per transaction fee configured by card type (VI, MC, DI, AMEX, etc.) per API Partner's Contract other wise 0 (zero)","format":"double","nullable":true},"TotalCommissionRate":{"type":"number","description":"The Total percentage of Commissions that FrontStream takes from a given transaction.\r\nThis rate = Partner CommissionRate + FS CommissionRate","format":"double","nullable":true},"TotalCommissionAmount":{"type":"number","description":"The product of the transaction times the Total commission rate.","format":"double","nullable":true},"PartnerCommissionRate":{"type":"number","description":"The Partner Commission percentage taken on behalf of the Partner from a given transaction.","format":"double","nullable":true},"PartnerCommissionAmount":{"type":"number","description":"The product of the transaction times the Partner commission rate.","format":"double","nullable":true},"FsCommissionRate":{"type":"number","description":"The FrontStream Commission percentage that FrontStream takes from a given transaction.","format":"double","nullable":true},"FsCommissionAmount":{"type":"number","description":"The product of the transaction times the FrontStream commission rate.","format":"double","nullable":true},"TotalFees":{"type":"number","description":"The sum of all fees applied to a transaction amount. (TotalCommission + CardFee + FlatFee + CardFeeOnFee)","format":"double","nullable":true},"MaxOverridePartnerCommissionRate":{"type":"number","description":"The derived minimum partner override rate and maximum partner override rate\r\n\r\nMaxOverridePartnerCommissionRate = TotalFees = (PartnerCommission rate) + (Card Fee Rate) + (Fs Commission Rate)\r\nMinOverridePartnerCommissionRate = (Card Fee rate) + (Fs Commission rate)","format":"double"},"MinOverridePartnerCommissionRate":{"type":"number","format":"double"},"PerTransFee":{"type":"number","description":"The flat amount that will be taken from the PaymentAmount for any Per-Transaction Fees as configured in your contract.","format":"double","nullable":true},"Tip":{"type":"number","description":"The flat amount that will be paid out to the API Partner if Donor decides to add a tip regardless of payFee true or false.","format":"double"},"CardFeeOnFeeAmount":{"type":"number","format":"double","nullable":true},"Tax":{"type":"number","format":"double","nullable":true},"AchFeeRate":{"type":"number","description":"The ACH processing fee rate applied to this transaction.","format":"double","nullable":true},"AchFeeAmount":{"type":"number","description":"The ACH processing fee amount for this transaction.","format":"double","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ### Payment Example Take a look at how you might call this method: {% tabs %} {% tab title="C#" %} ``` // Some code ``` {% endtab %} {% tab title="Postman" %} {% endtab %} {% endtabs %} # Fee To try a test and directly interact with the API endpoint click "Test It" and use an embedded API client to send requests with custom headers and variables, then see the live response; essentially letting you test this API directly within this page. When testing please use our Demo URL: `https://demo-payments.frontstream.com/api/fee` ## Calculates Fees based on Amount and Transaction Source Grouping > Used in our Non-Profit space to help cover any fees on Donations giving the option for all of a donation to go to a Charity. ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/fee":{"get":{"tags":["Fees"],"summary":"Calculates Fees based on Amount and Transaction Source Grouping","description":"Used in our Non-Profit space to help cover any fees on Donations giving the option for all of a donation to go to a Charity.","parameters":[{"name":"ProcessorGuid","in":"query","description":"optional - Identifies Processor being used by an API Partner","schema":{"type":"string"}},{"name":"CharityId","in":"query","description":"optional - Valid CharityId from Charity Search","schema":{"type":"string"}},{"name":"OrganizationGuid","in":"query","description":"internal use - Valid Panorama Organization Guid","schema":{"type":"string"}},{"name":"IntegrationSourceGuid","in":"query","description":"internal use - Identifies integrated Product","schema":{"type":"string"}},{"name":"TokenGuid","in":"query","description":"Payment API Token GUID. Card Type of Token will be used in Fee Calculation. If using TokenGuid then do not set CreditCardTypeId parameter","schema":{"type":"string"}},{"name":"Amount","in":"query","description":"required - transaction amount","required":true,"schema":{"maxLength":7,"type":"string"}},{"name":"TransactionSourceGroupId","in":"query","description":"required - API Partners should set to 10 if API Partner fees configured - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;","required":true,"schema":{"type":"string"}},{"name":"PayFee","in":"query","description":"required - cover the fees flag for the transaction. Indicates if the donor intends to cover the processing fees for the donation","required":true,"schema":{"type":"boolean"}},{"name":"CommissionRateOverride","in":"query","description":"optional - The percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract.","schema":{"type":"number","format":"double"}},{"name":"CardProcessingFeeOverride","in":"query","description":"optional - Overrides the default percentage processing fee","schema":{"type":"number","format":"double"}},{"name":"Tip","in":"query","description":"optional - An amount taken up front for the API Partner if Donor decides to apply a tip. Added to the total amount to charge on the donor’s card . Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","schema":{"maxLength":7,"type":"string"}},{"name":"Tax","in":"query","description":"optional - A tax amount taken up front. Added to the total amount to charge on the donor’s card. Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","schema":{"maxLength":7,"type":"string"}},{"name":"PaymentMethodTypeId","in":"query","description":"For ACH Fees please set to \"7\" otherwise only set for an API Partner with different fees based on a particular card type for example:\r\nUsed for API Partner's per card type fee calculation based on contract, For example - $0.30 per transaction for Visa, MasterCard and Discover cards and $0.50 per transaction for American Express.\r\noptional - The payment method type used for fee calculation.\r\npossible values -\r\n 1 - AMEX,\r\n 2 - MASTERCARD,\r\n 3 - VISA,\r\n 4 - DISCOVER,\r\n 5 - DINERSCLUB,\r\n 7 - ACH","schema":{"type":"string"}},{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns the calculated fees","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeeResponse"}}}},"400":{"description":"If fees calculation throws exception","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}},"404":{"description":"If the fees are not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"FeeResponse":{"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","nullable":true},"PaymentAmount":{"type":"number","description":"This is the amount charged to the donor. Will be equal to the sum of the Amount parameters if payFee=false, but if payFee=true, then this will be the amount that will be charged to the donor in order to have the net post-disbursement donation be equal to the Amount parameters.","format":"double","nullable":true},"CardFeeRate":{"type":"number","description":"example 2.5% - applied to EVERY donation. This is the FrontStream card processing fee. The percentage of the PaymentAmount that will be taken for credit card fees. Expressed as a human-readable percentage rather than a decimal value, it is intended to be able to be displayed directly on a page without needing to be converted.","format":"double","nullable":true},"CardFeeAmount":{"type":"number","description":"This is the amount that is owed to the gateway for the example 2.5% that FrontStream collects from the transaction.\r\n 2.5% of transaction amount if donor is not paying the fee, otherwise 2.5% of the transaction + card fee.","format":"double","nullable":true},"CardTypeFeeAmount":{"type":"number","description":"A per transaction fee configured by card type (VI, MC, DI, AMEX, etc.) per API Partner's Contract other wise 0 (zero)","format":"double","nullable":true},"TotalCommissionRate":{"type":"number","description":"The Total percentage of Commissions that FrontStream takes from a given transaction.\r\nThis rate = Partner CommissionRate + FS CommissionRate","format":"double","nullable":true},"TotalCommissionAmount":{"type":"number","description":"The product of the transaction times the Total commission rate.","format":"double","nullable":true},"PartnerCommissionRate":{"type":"number","description":"The Partner Commission percentage taken on behalf of the Partner from a given transaction.","format":"double","nullable":true},"PartnerCommissionAmount":{"type":"number","description":"The product of the transaction times the Partner commission rate.","format":"double","nullable":true},"FsCommissionRate":{"type":"number","description":"The FrontStream Commission percentage that FrontStream takes from a given transaction.","format":"double","nullable":true},"FsCommissionAmount":{"type":"number","description":"The product of the transaction times the FrontStream commission rate.","format":"double","nullable":true},"TotalFees":{"type":"number","description":"The sum of all fees applied to a transaction amount. (TotalCommission + CardFee + FlatFee + CardFeeOnFee)","format":"double","nullable":true},"MaxOverridePartnerCommissionRate":{"type":"number","description":"The derived minimum partner override rate and maximum partner override rate\r\n\r\nMaxOverridePartnerCommissionRate = TotalFees = (PartnerCommission rate) + (Card Fee Rate) + (Fs Commission Rate)\r\nMinOverridePartnerCommissionRate = (Card Fee rate) + (Fs Commission rate)","format":"double"},"MinOverridePartnerCommissionRate":{"type":"number","format":"double"},"PerTransFee":{"type":"number","description":"The flat amount that will be taken from the PaymentAmount for any Per-Transaction Fees as configured in your contract.","format":"double","nullable":true},"Tip":{"type":"number","description":"The flat amount that will be paid out to the API Partner if Donor decides to add a tip regardless of payFee true or false.","format":"double"},"CardFeeOnFeeAmount":{"type":"number","format":"double","nullable":true},"Tax":{"type":"number","format":"double","nullable":true},"AchFeeRate":{"type":"number","description":"The ACH processing fee rate applied to this transaction.","format":"double","nullable":true},"AchFeeAmount":{"type":"number","description":"The ACH processing fee amount for this transaction.","format":"double","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}}} ``` ## Calculates Fees based on an array of Transaction Line items - Amount and Transaction Source Groupings > Used in our Non-Profit space to help cover any fees on Donations giving the option for all of a donation to go to a Charity. ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/fees":{"post":{"tags":["Fees"],"summary":"Calculates Fees based on an array of Transaction Line items - Amount and Transaction Source Groupings","description":"Used in our Non-Profit space to help cover any fees on Donations giving the option for all of a donation to go to a Charity.","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/FeeListRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/FeeListRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/FeeListRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/FeeListRequest"}}}},"responses":{"200":{"description":"Returns the calculated fees","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeeListResponse"}}}},"400":{"description":"If fees calculation throws exception","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}},"404":{"description":"If the fees are not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"FeeListRequest":{"required":["Transactions"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"IntegrationSourceGuid":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"TokenGuid":{"type":"string","description":"Payment API Token GUID. Card Type of Token will be used in Fee Calculation. If using TokenGuid then do not set CreditCardTypeId parameter","nullable":true},"PaymentMethodTypeId":{"type":"string","description":"For ACH Fees please set to \"7\" otherwise only set for an API Partner with different fees based on a particular card type for example:\r\nUsed for API Partner's per card type fee calculation based on contract, For example - $0.30 per transaction for Visa, MasterCard and Discover cards and $0.50 per transaction for American Express.\r\noptional - The payment method type used for fee calculation. Applies to all transactions in the list.\r\npossible values -\r\n 1 - AMEX, 2 - MASTERCARD, 3 - VISA, 4 - DISCOVER, 5 - DINERSCLUB,\r\n 7 - ACH","nullable":true},"Transactions":{"type":"array","items":{"$ref":"#/components/schemas/PaymentTransTypeRequest"},"description":"required - 1 to n transactions to break down transaction line items"}},"additionalProperties":false},"PaymentTransTypeRequest":{"required":["Amount","TransactionSourceGroupId"],"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","description":"required - For Direct Merchant (For Profit) Api Partners should set to PaymentNoFee (12), other values are for Non Profit transactions - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;\r\n 13 - EventDonationFee;\r\n 14 - SponsorshipFee\r\n 15 - MembershipFee"},"Amount":{"maxLength":7,"type":"string","description":"required - Amount of line item without the fees included, Payment api will calculate fees for you"},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction. Indicates if the donor intends to cover the processing fees for the donation (primary used for Non Profit transactions like a donation)"},"CommissionRateOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - The percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract.","nullable":true},"CardProcessingFeeOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - Overrides the default percentage processing fee","nullable":true},"ExternalLineId":{"maxLength":100,"type":"string","description":"optional (max: 100) - use this to track individual line item IDs if necessary.","nullable":true},"Tip":{"maxLength":7,"type":"string","description":"optional (max: 7) - An amount taken up front for the API Partner if Donor decides to apply a tip. Added to the total amount to charge on the donor’s card . Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true},"Tax":{"maxLength":7,"type":"string","description":"optional (max: 7) - A tax amount taken up front. Added to the total amount to charge on the donor’s card. Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true}},"additionalProperties":false,"description":""},"FeeListResponse":{"type":"object","properties":{"TotalPaymentAmount":{"type":"number","description":"The total payment amount processed toward the cardholder's account.","format":"double"},"TotalFeesAmount":{"type":"number","description":"The calculated total fees amount of the list of transactions.","format":"double"},"TotalTaxAmount":{"type":"number","description":"The calculated total tax amount of the list of transactions.","format":"double"},"TransactionFees":{"type":"array","items":{"$ref":"#/components/schemas/FeeResponse"},"description":"List of Transaction Fee Responses","nullable":true}},"additionalProperties":false},"FeeResponse":{"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","nullable":true},"PaymentAmount":{"type":"number","description":"This is the amount charged to the donor. Will be equal to the sum of the Amount parameters if payFee=false, but if payFee=true, then this will be the amount that will be charged to the donor in order to have the net post-disbursement donation be equal to the Amount parameters.","format":"double","nullable":true},"CardFeeRate":{"type":"number","description":"example 2.5% - applied to EVERY donation. This is the FrontStream card processing fee. The percentage of the PaymentAmount that will be taken for credit card fees. Expressed as a human-readable percentage rather than a decimal value, it is intended to be able to be displayed directly on a page without needing to be converted.","format":"double","nullable":true},"CardFeeAmount":{"type":"number","description":"This is the amount that is owed to the gateway for the example 2.5% that FrontStream collects from the transaction.\r\n 2.5% of transaction amount if donor is not paying the fee, otherwise 2.5% of the transaction + card fee.","format":"double","nullable":true},"CardTypeFeeAmount":{"type":"number","description":"A per transaction fee configured by card type (VI, MC, DI, AMEX, etc.) per API Partner's Contract other wise 0 (zero)","format":"double","nullable":true},"TotalCommissionRate":{"type":"number","description":"The Total percentage of Commissions that FrontStream takes from a given transaction.\r\nThis rate = Partner CommissionRate + FS CommissionRate","format":"double","nullable":true},"TotalCommissionAmount":{"type":"number","description":"The product of the transaction times the Total commission rate.","format":"double","nullable":true},"PartnerCommissionRate":{"type":"number","description":"The Partner Commission percentage taken on behalf of the Partner from a given transaction.","format":"double","nullable":true},"PartnerCommissionAmount":{"type":"number","description":"The product of the transaction times the Partner commission rate.","format":"double","nullable":true},"FsCommissionRate":{"type":"number","description":"The FrontStream Commission percentage that FrontStream takes from a given transaction.","format":"double","nullable":true},"FsCommissionAmount":{"type":"number","description":"The product of the transaction times the FrontStream commission rate.","format":"double","nullable":true},"TotalFees":{"type":"number","description":"The sum of all fees applied to a transaction amount. (TotalCommission + CardFee + FlatFee + CardFeeOnFee)","format":"double","nullable":true},"MaxOverridePartnerCommissionRate":{"type":"number","description":"The derived minimum partner override rate and maximum partner override rate\r\n\r\nMaxOverridePartnerCommissionRate = TotalFees = (PartnerCommission rate) + (Card Fee Rate) + (Fs Commission Rate)\r\nMinOverridePartnerCommissionRate = (Card Fee rate) + (Fs Commission rate)","format":"double"},"MinOverridePartnerCommissionRate":{"type":"number","format":"double"},"PerTransFee":{"type":"number","description":"The flat amount that will be taken from the PaymentAmount for any Per-Transaction Fees as configured in your contract.","format":"double","nullable":true},"Tip":{"type":"number","description":"The flat amount that will be paid out to the API Partner if Donor decides to add a tip regardless of payFee true or false.","format":"double"},"CardFeeOnFeeAmount":{"type":"number","format":"double","nullable":true},"Tax":{"type":"number","format":"double","nullable":true},"AchFeeRate":{"type":"number","description":"The ACH processing fee rate applied to this transaction.","format":"double","nullable":true},"AchFeeAmount":{"type":"number","description":"The ACH processing fee amount for this transaction.","format":"double","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}}} ``` # Response Codes Payment API Response Codes returned in the Payment Response object for ResponseCode, PaymentResult, and PaymentStatus codes described. ## Payment Response Codes (ResponseCode object) **ResponseCode** object - Approved = **0**, Not processed = **-100** with more possible values - [General Info & Utilities](/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes) ## Payment Result (PaymentResult object) codes | **Code** | **Value** | **Notes** | | -------- | ---------- | ---------------------------------------------------------- | | 1 | Pending | Not currently used | | 2 | Processing | Not currently used | | 3 | Successful | Transaction completed successfully | | 4 | Failed | Transaction was declined (or failed for some other reason) | | 5 | Refunded | Transaction has been refunded after settlement | | 6 | Cancelled | Transaction has been voided/reversed prior to settlement | ## Payment Process Status(ProcessStatus object) codes | **Code** | **Value** | **Reporting Value** | **Description** | | -------- | -------------- | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 1 | NotProcessed | Not Processed | The transaction was not processed. This can be due to internal errors, but also applies when a transaction fails for legitimate reasons prior to being sent to the credit card processor (such as passing in a duplicate tranId). | | 2 | Authorized | Awaiting Authorization | The transaction was approved by the credit card processor, but has yet to be settled (generally still shows as pending on the cardholder's bank/card account). | | 4 | Settled | Authorized | The transaction has been settled (due to differences in how banks handle things, the transaction may still show as pending on the cardholder's account at this point, but should clear soon). | | 5 | Rejected | Rejected | The transaction declined. | | 6 | RefundRequired | Refund Required | A refund request has been entered for this transaction, but it has yet to be processed. | | 7 | AwaitingRefund | Awaiting Refund | The refund request for this transaction has been approved, but is awaiting settlement. | | 8 | Refunded | Refunded | The refund request has been settled. Once a transaction enters this status, due to variances in how banks handle refunds, the cardholder should expect to see the funds credited to their account within 3-5 business days (although in some rare cases, this can take up to 21 days). Please note: Given that the settlement of the refund request with the card processor initiates the funds transfer back to the cardholder, the entire process is out of Frontstream's hands, and we have no ability to make a refund return to the cardholder faster as it is entirely in the hands of their bank at this point. | | 9 | Cancelled | Cancelled | When a refund request is entered for a transaction that has yet to be settled, the transaction will simply be voided (technically speaking, a reversal message is sent to the cardholder's bank, which cancels the pending authorization on their bank account) instead of going through the refund process, and will change to this status instead of status code 6. | | 10 | Chargeback | Chargeback | The cardholder has initiated a chargeback with their bank for the transaction. | | 11 | RefundRejected | Refund Rejected | The refund request was not approved. | | 12 | DistroOnly | Distro Only | Disto Only status is used for Express Payroll transactions | # Each API reference specifics! The following sections covers each **FrontStream Payment API** endpoint details. Please continue ahead. # Authenticate ## This will create an API AccessToken for an Application > Return HTTP Status Code 200 (OK) with AccessToken > \ > Returns HTTP Status Code 400 if could not authenticate ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/ClientSession":{"post":{"tags":["Authenticate"],"summary":"This will create an API AccessToken for an Application","description":"Return HTTP Status Code 200 (OK) with AccessToken\r\nReturns HTTP Status Code 400 if could not authenticate","requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/ClientSessionRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/ClientSessionRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/ClientSessionRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/ClientSessionRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthenticationClientSessionResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"ClientSessionRequest":{"required":["ClientId","ClientSecret"],"type":"object","properties":{"ClientId":{"type":"string","description":"Unique identifier for the API Partner; provided by FrontStream"},"ClientSecret":{"maxLength":500,"type":"string","description":"Key specifically paired to the clientId"}},"additionalProperties":false,"description":""},"AuthenticationClientSessionResponse":{"type":"object","properties":{"Token":{"type":"string","description":"This is the AccessToken you will use for any other API call","nullable":true},"ClientId":{"type":"string","description":"Unique identifier for the API Partner; provided by FrontStream","format":"uuid"},"ExpirationDate":{"type":"string","description":"The date and time at which the AccessToken will no longer be valid if not used first. Will always be 5 hours from when the response is sent.","format":"date-time"}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` # Fees ## Calculates Fees based on Amount and Transaction Source Grouping > Used in our Non-Profit space to help cover any fees on Donations giving the option for all of a donation to go to a Charity. ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/fee":{"get":{"tags":["Fees"],"summary":"Calculates Fees based on Amount and Transaction Source Grouping","description":"Used in our Non-Profit space to help cover any fees on Donations giving the option for all of a donation to go to a Charity.","parameters":[{"name":"ProcessorGuid","in":"query","description":"optional - Identifies Processor being used by an API Partner","schema":{"type":"string"}},{"name":"CharityId","in":"query","description":"optional - Valid CharityId from Charity Search","schema":{"type":"string"}},{"name":"OrganizationGuid","in":"query","description":"internal use - Valid Panorama Organization Guid","schema":{"type":"string"}},{"name":"IntegrationSourceGuid","in":"query","description":"internal use - Identifies integrated Product","schema":{"type":"string"}},{"name":"TokenGuid","in":"query","description":"Payment API Token GUID. Card Type of Token will be used in Fee Calculation. If using TokenGuid then do not set CreditCardTypeId parameter","schema":{"type":"string"}},{"name":"Amount","in":"query","description":"required - transaction amount","required":true,"schema":{"maxLength":7,"type":"string"}},{"name":"TransactionSourceGroupId","in":"query","description":"required - API Partners should set to 10 if API Partner fees configured - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;","required":true,"schema":{"type":"string"}},{"name":"PayFee","in":"query","description":"required - cover the fees flag for the transaction. Indicates if the donor intends to cover the processing fees for the donation","required":true,"schema":{"type":"boolean"}},{"name":"CommissionRateOverride","in":"query","description":"optional - The percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract.","schema":{"type":"number","format":"double"}},{"name":"CardProcessingFeeOverride","in":"query","description":"optional - Overrides the default percentage processing fee","schema":{"type":"number","format":"double"}},{"name":"Tip","in":"query","description":"optional - An amount taken up front for the API Partner if Donor decides to apply a tip. Added to the total amount to charge on the donor’s card . Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","schema":{"maxLength":7,"type":"string"}},{"name":"Tax","in":"query","description":"optional - A tax amount taken up front. Added to the total amount to charge on the donor’s card. Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","schema":{"maxLength":7,"type":"string"}},{"name":"PaymentMethodTypeId","in":"query","description":"For ACH Fees please set to \"7\" otherwise only set for an API Partner with different fees based on a particular card type for example:\r\nUsed for API Partner's per card type fee calculation based on contract, For example - $0.30 per transaction for Visa, MasterCard and Discover cards and $0.50 per transaction for American Express.\r\noptional - The payment method type used for fee calculation.\r\npossible values -\r\n 1 - AMEX,\r\n 2 - MASTERCARD,\r\n 3 - VISA,\r\n 4 - DISCOVER,\r\n 5 - DINERSCLUB,\r\n 7 - ACH","schema":{"type":"string"}},{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns the calculated fees","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeeResponse"}}}},"400":{"description":"If fees calculation throws exception","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}},"404":{"description":"If the fees are not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"FeeResponse":{"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","nullable":true},"PaymentAmount":{"type":"number","description":"This is the amount charged to the donor. Will be equal to the sum of the Amount parameters if payFee=false, but if payFee=true, then this will be the amount that will be charged to the donor in order to have the net post-disbursement donation be equal to the Amount parameters.","format":"double","nullable":true},"CardFeeRate":{"type":"number","description":"example 2.5% - applied to EVERY donation. This is the FrontStream card processing fee. The percentage of the PaymentAmount that will be taken for credit card fees. Expressed as a human-readable percentage rather than a decimal value, it is intended to be able to be displayed directly on a page without needing to be converted.","format":"double","nullable":true},"CardFeeAmount":{"type":"number","description":"This is the amount that is owed to the gateway for the example 2.5% that FrontStream collects from the transaction.\r\n 2.5% of transaction amount if donor is not paying the fee, otherwise 2.5% of the transaction + card fee.","format":"double","nullable":true},"CardTypeFeeAmount":{"type":"number","description":"A per transaction fee configured by card type (VI, MC, DI, AMEX, etc.) per API Partner's Contract other wise 0 (zero)","format":"double","nullable":true},"TotalCommissionRate":{"type":"number","description":"The Total percentage of Commissions that FrontStream takes from a given transaction.\r\nThis rate = Partner CommissionRate + FS CommissionRate","format":"double","nullable":true},"TotalCommissionAmount":{"type":"number","description":"The product of the transaction times the Total commission rate.","format":"double","nullable":true},"PartnerCommissionRate":{"type":"number","description":"The Partner Commission percentage taken on behalf of the Partner from a given transaction.","format":"double","nullable":true},"PartnerCommissionAmount":{"type":"number","description":"The product of the transaction times the Partner commission rate.","format":"double","nullable":true},"FsCommissionRate":{"type":"number","description":"The FrontStream Commission percentage that FrontStream takes from a given transaction.","format":"double","nullable":true},"FsCommissionAmount":{"type":"number","description":"The product of the transaction times the FrontStream commission rate.","format":"double","nullable":true},"TotalFees":{"type":"number","description":"The sum of all fees applied to a transaction amount. (TotalCommission + CardFee + FlatFee + CardFeeOnFee)","format":"double","nullable":true},"MaxOverridePartnerCommissionRate":{"type":"number","description":"The derived minimum partner override rate and maximum partner override rate\r\n\r\nMaxOverridePartnerCommissionRate = TotalFees = (PartnerCommission rate) + (Card Fee Rate) + (Fs Commission Rate)\r\nMinOverridePartnerCommissionRate = (Card Fee rate) + (Fs Commission rate)","format":"double"},"MinOverridePartnerCommissionRate":{"type":"number","format":"double"},"PerTransFee":{"type":"number","description":"The flat amount that will be taken from the PaymentAmount for any Per-Transaction Fees as configured in your contract.","format":"double","nullable":true},"Tip":{"type":"number","description":"The flat amount that will be paid out to the API Partner if Donor decides to add a tip regardless of payFee true or false.","format":"double"},"CardFeeOnFeeAmount":{"type":"number","format":"double","nullable":true},"Tax":{"type":"number","format":"double","nullable":true},"AchFeeRate":{"type":"number","description":"The ACH processing fee rate applied to this transaction.","format":"double","nullable":true},"AchFeeAmount":{"type":"number","description":"The ACH processing fee amount for this transaction.","format":"double","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}}} ``` ## Calculates Fees based on an array of Transaction Line items - Amount and Transaction Source Groupings > Used in our Non-Profit space to help cover any fees on Donations giving the option for all of a donation to go to a Charity. ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/fees":{"post":{"tags":["Fees"],"summary":"Calculates Fees based on an array of Transaction Line items - Amount and Transaction Source Groupings","description":"Used in our Non-Profit space to help cover any fees on Donations giving the option for all of a donation to go to a Charity.","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/FeeListRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/FeeListRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/FeeListRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/FeeListRequest"}}}},"responses":{"200":{"description":"Returns the calculated fees","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FeeListResponse"}}}},"400":{"description":"If fees calculation throws exception","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}},"404":{"description":"If the fees are not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"FeeListRequest":{"required":["Transactions"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"IntegrationSourceGuid":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"TokenGuid":{"type":"string","description":"Payment API Token GUID. Card Type of Token will be used in Fee Calculation. If using TokenGuid then do not set CreditCardTypeId parameter","nullable":true},"PaymentMethodTypeId":{"type":"string","description":"For ACH Fees please set to \"7\" otherwise only set for an API Partner with different fees based on a particular card type for example:\r\nUsed for API Partner's per card type fee calculation based on contract, For example - $0.30 per transaction for Visa, MasterCard and Discover cards and $0.50 per transaction for American Express.\r\noptional - The payment method type used for fee calculation. Applies to all transactions in the list.\r\npossible values -\r\n 1 - AMEX, 2 - MASTERCARD, 3 - VISA, 4 - DISCOVER, 5 - DINERSCLUB,\r\n 7 - ACH","nullable":true},"Transactions":{"type":"array","items":{"$ref":"#/components/schemas/PaymentTransTypeRequest"},"description":"required - 1 to n transactions to break down transaction line items"}},"additionalProperties":false},"PaymentTransTypeRequest":{"required":["Amount","TransactionSourceGroupId"],"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","description":"required - For Direct Merchant (For Profit) Api Partners should set to PaymentNoFee (12), other values are for Non Profit transactions - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;\r\n 13 - EventDonationFee;\r\n 14 - SponsorshipFee\r\n 15 - MembershipFee"},"Amount":{"maxLength":7,"type":"string","description":"required - Amount of line item without the fees included, Payment api will calculate fees for you"},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction. Indicates if the donor intends to cover the processing fees for the donation (primary used for Non Profit transactions like a donation)"},"CommissionRateOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - The percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract.","nullable":true},"CardProcessingFeeOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - Overrides the default percentage processing fee","nullable":true},"ExternalLineId":{"maxLength":100,"type":"string","description":"optional (max: 100) - use this to track individual line item IDs if necessary.","nullable":true},"Tip":{"maxLength":7,"type":"string","description":"optional (max: 7) - An amount taken up front for the API Partner if Donor decides to apply a tip. Added to the total amount to charge on the donor’s card . Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true},"Tax":{"maxLength":7,"type":"string","description":"optional (max: 7) - A tax amount taken up front. Added to the total amount to charge on the donor’s card. Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true}},"additionalProperties":false,"description":""},"FeeListResponse":{"type":"object","properties":{"TotalPaymentAmount":{"type":"number","description":"The total payment amount processed toward the cardholder's account.","format":"double"},"TotalFeesAmount":{"type":"number","description":"The calculated total fees amount of the list of transactions.","format":"double"},"TotalTaxAmount":{"type":"number","description":"The calculated total tax amount of the list of transactions.","format":"double"},"TransactionFees":{"type":"array","items":{"$ref":"#/components/schemas/FeeResponse"},"description":"List of Transaction Fee Responses","nullable":true}},"additionalProperties":false},"FeeResponse":{"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","nullable":true},"PaymentAmount":{"type":"number","description":"This is the amount charged to the donor. Will be equal to the sum of the Amount parameters if payFee=false, but if payFee=true, then this will be the amount that will be charged to the donor in order to have the net post-disbursement donation be equal to the Amount parameters.","format":"double","nullable":true},"CardFeeRate":{"type":"number","description":"example 2.5% - applied to EVERY donation. This is the FrontStream card processing fee. The percentage of the PaymentAmount that will be taken for credit card fees. Expressed as a human-readable percentage rather than a decimal value, it is intended to be able to be displayed directly on a page without needing to be converted.","format":"double","nullable":true},"CardFeeAmount":{"type":"number","description":"This is the amount that is owed to the gateway for the example 2.5% that FrontStream collects from the transaction.\r\n 2.5% of transaction amount if donor is not paying the fee, otherwise 2.5% of the transaction + card fee.","format":"double","nullable":true},"CardTypeFeeAmount":{"type":"number","description":"A per transaction fee configured by card type (VI, MC, DI, AMEX, etc.) per API Partner's Contract other wise 0 (zero)","format":"double","nullable":true},"TotalCommissionRate":{"type":"number","description":"The Total percentage of Commissions that FrontStream takes from a given transaction.\r\nThis rate = Partner CommissionRate + FS CommissionRate","format":"double","nullable":true},"TotalCommissionAmount":{"type":"number","description":"The product of the transaction times the Total commission rate.","format":"double","nullable":true},"PartnerCommissionRate":{"type":"number","description":"The Partner Commission percentage taken on behalf of the Partner from a given transaction.","format":"double","nullable":true},"PartnerCommissionAmount":{"type":"number","description":"The product of the transaction times the Partner commission rate.","format":"double","nullable":true},"FsCommissionRate":{"type":"number","description":"The FrontStream Commission percentage that FrontStream takes from a given transaction.","format":"double","nullable":true},"FsCommissionAmount":{"type":"number","description":"The product of the transaction times the FrontStream commission rate.","format":"double","nullable":true},"TotalFees":{"type":"number","description":"The sum of all fees applied to a transaction amount. (TotalCommission + CardFee + FlatFee + CardFeeOnFee)","format":"double","nullable":true},"MaxOverridePartnerCommissionRate":{"type":"number","description":"The derived minimum partner override rate and maximum partner override rate\r\n\r\nMaxOverridePartnerCommissionRate = TotalFees = (PartnerCommission rate) + (Card Fee Rate) + (Fs Commission Rate)\r\nMinOverridePartnerCommissionRate = (Card Fee rate) + (Fs Commission rate)","format":"double"},"MinOverridePartnerCommissionRate":{"type":"number","format":"double"},"PerTransFee":{"type":"number","description":"The flat amount that will be taken from the PaymentAmount for any Per-Transaction Fees as configured in your contract.","format":"double","nullable":true},"Tip":{"type":"number","description":"The flat amount that will be paid out to the API Partner if Donor decides to add a tip regardless of payFee true or false.","format":"double"},"CardFeeOnFeeAmount":{"type":"number","format":"double","nullable":true},"Tax":{"type":"number","format":"double","nullable":true},"AchFeeRate":{"type":"number","description":"The ACH processing fee rate applied to this transaction.","format":"double","nullable":true},"AchFeeAmount":{"type":"number","description":"The ACH processing fee amount for this transaction.","format":"double","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}}} ``` # Notifications ## GET /api/notifications > Get Notifications History per Integration Source by PaymentId or PaymentExternalId ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/notifications":{"get":{"tags":["Notifications"],"summary":"Get Notifications History per Integration Source by PaymentId or PaymentExternalId","description":"","parameters":[{"name":"paymentId","in":"query","schema":{"type":"integer","format":"int32"}},{"name":"paymentExternalId","in":"query","schema":{"type":"string"}},{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns all Notifications history by PaymentId or PaymentExternalId","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NotificationsResponse"}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}},"404":{"description":"If the Notifications are not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"NotificationsResponse":{"type":"object","properties":{"NotificationId":{"type":"integer","description":"Notification Id","format":"int32"},"NotificationGuid":{"type":"string","description":"Unique Notification identifier","format":"uuid"},"NotificationConfigId":{"type":"integer","description":"Notification Configuration Id set up per Integration Source","format":"int32"},"CreatedDate":{"type":"string","description":"Notification Created date","format":"date-time"},"ModifiedDate":{"type":"string","format":"date-time","nullable":true},"Payload":{"type":"string","description":"Notification payload sent out for transaction status","nullable":true},"RetryCount":{"type":"integer","description":"Number of retry attempts to send Notification payload to configured Notification URL","format":"int32","nullable":true},"Postdate":{"type":"string","description":"if available - the date the Notification was posted to configured Notification URL successfully","format":"date-time","nullable":true},"NotificationStatus":{"$ref":"#/components/schemas/NotificationStatus"},"NotificationUrl":{"type":"string","description":"Url configure to post notifications to. The Integration Source endpoint to post notification payload to.","nullable":true},"PaymentId":{"type":"integer","description":"Payment API PaymentId associated with the Notification","format":"int32","nullable":true},"PaymentExternalId":{"type":"string","description":"Payment API PaymentExternalId associated with the Notification","nullable":true}},"additionalProperties":false},"NotificationStatus":{"enum":[1,2,3,4,5],"type":"integer","format":"int32"},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}}} ``` ## Used to test sending over a transaction notification payload to the notification url endpoint configured per an Integration Source > Parameters: > \ > > \ > Url - Integration Source endpoint to post payload to. Example: https\://{yourenvironment.yourdomain}.com/api/yourNotification endpoint > \\ > > \ > AccessToken - optional if access token needed to hit notification url > \ > > \ > Payload - test payload posting over to Url > \\ > > \\ > > \ > Example notification test with payload sent out for transaction status: > \\ > > \ > POST /api/notificationTest > \ > { > \ > ?Url = "", // your URL to post notification to. > \ > AccessToken=testToken, // optional if required to hit notification URL. > \ > Payload = { > \ > "PaymentId": 55514, > \ > "PaymentGuid": "4f2835cb-1afe-482b-aea6-bf6ea7061828", > \ > "PaymentDate": "2026-01-20T15:20:07.948", > \ > "PaymentExternalId": "19498411", > \ > "OriginalExternalID": "19498411", > \ > "RecurringProfileId": null, > \ > "RecurringProfileGuid": null, > \ > "NextBillDate": null, > \ > "ProcessStatus": 2, // possible values: NotProcessed = 1 "Not Processed", Authorized = 2 "Awaiting Authorization", Settled = 4 "Authorized", Rejected = 5 "Rejected", RefundRequired = 6 "Refund Required", AwaitingRefund = 7 "Awaiting Refund", Refunded = 8 "Refunded", Cancelled = 9 "Cancelled", Chargeback = 10 "Chargeback", RefundRejected = 11 "Refund Rejected" > \ > "ProcessStatusValue": "Awaiting Authorization", > \ > "PaymentResult": 3, // possible values: Pending = 1, Processing = 2, Successful = 3, Failed = 4, Refunded = 5, Cancelled = 6 > \ > "PaymentResultValue": "Successful", > \ > "Amount": 105.53, > \ > "DistributionType": null, // possible values: null, or "Direct Deposit" or "Check" > \ > "DistributionTypeValue": null, // possible values: null, or 1 - Direct Deposit or 2 - Check > \ > "DistributionStatus": "Processing", possible values: null, or "Processing", "Settled", "Refunded", "Voided" > \ > "DistributionId": null, > \ > "SourceGuid": "12345678-9012-1234-5678-123456789012", > \ > "SourceName": "DonationForm", > \ > "CharityId": null, > \ > "OrganizationGuid": "12345678-9012-1234-5678-123456789012", > \ > "OrganizationName": "TEST SOCIETY", > \ > "Ein": "00-0000000", > \ > "SalesforceAccountId": null, > \ > "FgExternalId": null, > \ > "BfgExternalId": null, > \ > "ArtezExternalId": null, > \ > "ArtezInstanceGuid": null, > \ > "ExternalConstituentId": null, > \ > "FirstName": "TEST", > \ > "LastName": "NAME", > \ > "Email": "", > \ > "CardHolderName": "Test name", > \ > "CCLastDigits": "2222", > \ > "CCType": "Visa", > \ > "IpAddress": "127.0.0.1", > \ > "ExternalEventId": "9922", > \ > "ExternalEventGuid": null, > \ > "ExternalEventName": null, > \ > "ShippingFee": 0, > \ > "TaxableBenefit": 0, > \ > "TranId": "885ecade-735c-4b8c-9cfd-2870ebca049f", > \ > "Tip": 0, > \ > "VoidRequestDate": null, > \ > "VoidReason": null, > \ > "RefundRequestDate": null, > \ > "RefundReason": null, > \ > "ProcessorId": 1, > \ > "ProcessorGuid": "12345678-9012-1234-5678-123456789012", > \ > "PaymentMethodTypeId": 3, > \ > "Surcharge": null, > \ > "IsSurchargeEligible": false, > \ > "CheckLastDigits": null, > \ > "CheckNumber": null, > \ > "CheckTypeId": null, > \ > "CheckAccountTypeId": null, > \ > "FsApplicationFee": null, > \ > "EpfSessionId": "c2bdd62b-0f22-45fe-83f6-119a24e54f82", > \ > "PaymentLines": \[ > \ > { > \ > "PaymentLineId": 50256, > \ > "PaymentId": 55514, > \ > "CreatedDate": "2026-01-20T15:20:09.5520567Z", > \ > "ModifiedDate": "2026-01-20T15:20:09.45", > \ > "IsDeleted": false, > \ > "Amount": 100, > \ > "CardFeeAmount": 3.49, > \ > "CardTypeFeeAmount": 0, > \ > "CommissionAmount": 1.5, > \ > "PayFee": true, > \ > "TransactionSourceGroupId": 1, > \ > "CardFeeRate": 3.49, > \ > "TotalCommissionRate": 1.5, > \ > "TotalCommissionAmount": 1.5, > \ > "PartnerCommissionRate": 0, > \ > "PartnerCommissionAmount": 0, > \ > "FsCommissionRate": 1.5, > \ > "FsCommissionAmount": 1.5, > \ > "TotalFees": 5.53, > \ > "PerTransFee": 0.35, > \ > "ExternalLineId": null, > \ > "Tip": 0, > \ > "CommissionRateOverride": null, > \ > "CardFeeOnFeeAmount": 0.19, > \ > "Tax": 0 > \ > } > \ > ] > \ > } > \ > } ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/notificationTest":{"post":{"tags":["Notifications"],"summary":"Used to test sending over a transaction notification payload to the notification url endpoint configured per an Integration Source","description":" Parameters:\r\n \r\n Url - Integration Source endpoint to post payload to. Example: https://{yourenvironment.yourdomain}.com/api/yourNotification endpoint\r\n\r\n AccessToken - optional if access token needed to hit notification url\r\n \r\n Payload - test payload posting over to Url\r\n\r\n\r\n Example notification test with payload sent out for transaction status:\r\n\r\n\tPOST /api/notificationTest\r\n\t{\r\n\t ?Url = \"\", // your URL to post notification to.\r\n\t AccessToken=testToken, // optional if required to hit notification URL.\r\n\t Payload = {\r\n\t \"PaymentId\": 55514,\r\n\t \"PaymentGuid\": \"4f2835cb-1afe-482b-aea6-bf6ea7061828\",\r\n\t \"PaymentDate\": \"2026-01-20T15:20:07.948\",\r\n\t \"PaymentExternalId\": \"19498411\",\r\n\t \"OriginalExternalID\": \"19498411\",\r\n\t \"RecurringProfileId\": null,\r\n\t \"RecurringProfileGuid\": null,\r\n\t \"NextBillDate\": null,\r\n\t \"ProcessStatus\": 2, // possible values: NotProcessed = 1 \"Not Processed\", Authorized = 2 \"Awaiting Authorization\", Settled = 4 \"Authorized\", Rejected = 5 \"Rejected\", RefundRequired = 6 \"Refund Required\", AwaitingRefund = 7 \"Awaiting Refund\", Refunded = 8 \"Refunded\", Cancelled = 9 \"Cancelled\", Chargeback = 10 \"Chargeback\", RefundRejected = 11 \"Refund Rejected\"\r\n\t \"ProcessStatusValue\": \"Awaiting Authorization\",\r\n\t \"PaymentResult\": 3, // possible values: Pending = 1, Processing = 2, Successful = 3, Failed = 4, Refunded = 5, Cancelled = 6\r\n\t \"PaymentResultValue\": \"Successful\",\r\n\t \"Amount\": 105.53,\r\n\t \"DistributionType\": null, // possible values: null, or \"Direct Deposit\" or \"Check\"\r\n\t \"DistributionTypeValue\": null, // possible values: null, or 1 - Direct Deposit or 2 - Check\r\n\t \"DistributionStatus\": \"Processing\", possible values: null, or \"Processing\", \"Settled\", \"Refunded\", \"Voided\"\r\n\t \"DistributionId\": null,\r\n\t \"SourceGuid\": \"12345678-9012-1234-5678-123456789012\",\r\n\t \"SourceName\": \"DonationForm\",\r\n\t \"CharityId\": null,\r\n\t \"OrganizationGuid\": \"12345678-9012-1234-5678-123456789012\",\r\n\t \"OrganizationName\": \"TEST SOCIETY\",\r\n\t \"Ein\": \"00-0000000\",\r\n\t \"SalesforceAccountId\": null,\r\n\t \"FgExternalId\": null,\r\n\t \"BfgExternalId\": null,\r\n\t \"ArtezExternalId\": null,\r\n\t \"ArtezInstanceGuid\": null,\r\n\t \"ExternalConstituentId\": null,\r\n\t \"FirstName\": \"TEST\",\r\n\t \"LastName\": \"NAME\",\r\n\t \"Email\": \"test@testemail.com\",\r\n\t \"CardHolderName\": \"Test name\",\r\n\t \"CCLastDigits\": \"2222\",\r\n\t \"CCType\": \"Visa\",\r\n\t \"IpAddress\": \"127.0.0.1\",\r\n\t \"ExternalEventId\": \"9922\",\r\n\t \"ExternalEventGuid\": null,\r\n\t \"ExternalEventName\": null,\r\n\t \"ShippingFee\": 0,\r\n\t \"TaxableBenefit\": 0,\r\n\t \"TranId\": \"885ecade-735c-4b8c-9cfd-2870ebca049f\",\r\n\t \"Tip\": 0,\r\n\t \"VoidRequestDate\": null,\r\n\t \"VoidReason\": null,\r\n\t \"RefundRequestDate\": null,\r\n\t \"RefundReason\": null,\r\n\t \"ProcessorId\": 1,\r\n\t \"ProcessorGuid\": \"12345678-9012-1234-5678-123456789012\",\r\n\t \"PaymentMethodTypeId\": 3,\r\n\t \"Surcharge\": null,\r\n\t \"IsSurchargeEligible\": false,\r\n\t \"CheckLastDigits\": null,\r\n\t \"CheckNumber\": null,\r\n\t \"CheckTypeId\": null,\r\n\t \"CheckAccountTypeId\": null,\r\n\t \"FsApplicationFee\": null,\r\n\t \"EpfSessionId\": \"c2bdd62b-0f22-45fe-83f6-119a24e54f82\",\r\n\t \"PaymentLines\": [\r\n\t {\r\n\t \"PaymentLineId\": 50256,\r\n\t \"PaymentId\": 55514,\r\n\t \"CreatedDate\": \"2026-01-20T15:20:09.5520567Z\",\r\n\t \"ModifiedDate\": \"2026-01-20T15:20:09.45\",\r\n\t \"IsDeleted\": false,\r\n\t \"Amount\": 100,\r\n\t \"CardFeeAmount\": 3.49,\r\n\t \"CardTypeFeeAmount\": 0,\r\n\t \"CommissionAmount\": 1.5,\r\n\t \"PayFee\": true,\r\n\t \"TransactionSourceGroupId\": 1,\r\n\t \"CardFeeRate\": 3.49,\r\n\t \"TotalCommissionRate\": 1.5,\r\n\t \"TotalCommissionAmount\": 1.5,\r\n\t \"PartnerCommissionRate\": 0,\r\n\t \"PartnerCommissionAmount\": 0,\r\n\t \"FsCommissionRate\": 1.5,\r\n\t \"FsCommissionAmount\": 1.5,\r\n\t \"TotalFees\": 5.53,\r\n\t \"PerTransFee\": 0.35,\r\n\t \"ExternalLineId\": null,\r\n\t \"Tip\": 0,\r\n\t \"CommissionRateOverride\": null,\r\n\t \"CardFeeOnFeeAmount\": 0.19,\r\n\t \"Tax\": 0\r\n\t }\r\n\t ]\r\n\t}\r\n\t}","parameters":[{"name":"url","in":"query","description":"","schema":{"type":"string"}},{"name":"payload","in":"query","description":"","schema":{"type":"string"}},{"name":"accessToken","in":"query","description":"","schema":{"type":"string"}},{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success"},"400":{"description":"Failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}}} ``` ## PUT /api/notificationConfig > Save Notification Configurations per an Integration Source ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/notificationConfig":{"put":{"tags":["Notifications"],"summary":"Save Notification Configurations per an Integration Source","description":"","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/EditAllNotificationConfigSave"}},"application/json":{"schema":{"$ref":"#/components/schemas/EditAllNotificationConfigSave"}},"text/json":{"schema":{"$ref":"#/components/schemas/EditAllNotificationConfigSave"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/EditAllNotificationConfigSave"}}}},"responses":{"200":{"description":"Returns saved notification config","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/NotificationConfigurationDto"}}}}},"400":{"description":"If the notification config are not saved","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"EditAllNotificationConfigSave":{"required":["NotificationConfigs"],"type":"object","properties":{"IntegrationSourceGuid":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"NotificationConfigs":{"maxItems":20,"type":"array","items":{"$ref":"#/components/schemas/EditNotificationConfigSave"},"description":"NotificationConfigs: 1 - n notification configs for an Integration Source"}},"additionalProperties":false,"description":""},"EditNotificationConfigSave":{"required":["NotificationConfigurationTypeId","NotificationProtocolTypeId","NotificationUrl","Retries"],"type":"object","properties":{"NotificationConfigurationTypeId":{"type":"string","description":"required - NotificationConfigurationTypeId: possible values -\r\n 1 - General"},"NotificationProtocolTypeId":{"type":"string","description":"required - NotificationProtocolTypeId: possible values -\r\n 1 - Web,\r\n 2 - Email - (Email currently not in use)"},"NotificationUrl":{"maxLength":250,"type":"string","description":"required - NotificationUrl - Url to post notification to. Integration Source endpoint to post payload to. Example: https://{yourenvironment.yourdomain}.com/api/yourNotification endpoint. Make sure to include Https://"},"NotificationEmailFrom":{"maxLength":250,"type":"string","description":"Not in use - NotificationEmailFrom – optional Notification Email from","format":"email","nullable":true},"NotificationEmailTo":{"maxLength":250,"type":"string","description":"Not in use - NotificationEmailTo – optional Notification Email to","format":"email","nullable":true},"Retries":{"type":"integer","description":"required - number of retries to try again failed notifications - currently retries 10 times by default or set to 0","format":"int32"},"AccessToken":{"maxLength":250,"type":"string","description":"optional (max: 250) - if access token needed to hit notification url","nullable":true},"IsDeleted":{"type":"boolean","description":"set to true if you wish to deactivate configuration, otherwise set to false"}},"additionalProperties":false,"description":""},"NotificationConfigurationDto":{"type":"object","properties":{"NotificationConfigId":{"type":"integer","format":"int32"},"NotificationConfigType":{"$ref":"#/components/schemas/NotificationConfigurationTypeDto"},"NotificationProtocolType":{"$ref":"#/components/schemas/NotificationProtocolTypeDto"},"IntegrationSourceId":{"type":"integer","format":"int32"},"NotificationUrl":{"type":"string","nullable":true},"NotificationEmailTo":{"type":"string","nullable":true},"NotificationEmailFrom":{"type":"string","nullable":true},"AccessToken":{"type":"string","nullable":true},"Retries":{"type":"integer","format":"int32"},"CreatedDate":{"type":"string","format":"date-time"},"ModifiedDate":{"type":"string","format":"date-time","nullable":true},"IsDeleted":{"type":"boolean"}},"additionalProperties":false},"NotificationConfigurationTypeDto":{"enum":[1,2,3,4,5,6,7,8],"type":"integer","format":"int32"},"NotificationProtocolTypeDto":{"enum":[1,2],"type":"integer","format":"int32"},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}}} ``` # Tokenization ## Update an existing card or ACH token > Provide one of TokenGuid, ExternalCardToken, or ExternalCheckToken to identify the token. > \ > Only include the fields you want to update — all fields are optional. > \ > Card fields (CardNum, ExpMonth, ExpYear, CVNum, NameOnCard) are only valid for card tokens. > \ > ACH fields (CheckRoutingNumber, CheckAccountNumber, etc.) are only valid for ACH tokens. ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/token":{"put":{"tags":["Tokenization"],"summary":"Update an existing card or ACH token","description":"Provide one of TokenGuid, ExternalCardToken, or ExternalCheckToken to identify the token.\r\nOnly include the fields you want to update — all fields are optional.\r\nCard fields (CardNum, ExpMonth, ExpYear, CVNum, NameOnCard) are only valid for card tokens.\r\nACH fields (CheckRoutingNumber, CheckAccountNumber, etc.) are only valid for ACH tokens.","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/UpdateTokenRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTokenRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/UpdateTokenRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/UpdateTokenRequest"}}}},"responses":{"200":{"description":"Returns the updated token details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateTokenResponse"}}}},"400":{"description":"If the update fails","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"UpdateTokenRequest":{"type":"object","properties":{"TokenGuid":{"type":"string","description":"Token identifier - provide one of: TokenGuid, ExternalCardToken, or ExternalCheckToken","nullable":true},"ExternalCardToken":{"maxLength":200,"type":"string","description":"optional (max: 200) - 3rd party gateway card token","nullable":true},"ExternalCheckToken":{"maxLength":200,"type":"string","description":"optional (max: 200) - 3rd party gateway check/ACH token","nullable":true},"CardNum":{"maxLength":30,"type":"string","description":"optional (max: 30) - updated credit card number","nullable":true},"ExpMonth":{"maxLength":2,"minLength":2,"type":"string","description":"optional - example: \"01\" for January","nullable":true},"ExpYear":{"maxLength":2,"minLength":2,"type":"string","description":"optional - example: \"29\" for 2029","nullable":true},"CVNum":{"maxLength":4,"type":"string","description":"optional (max: 4) - CVV","nullable":true},"NameOnCard":{"maxLength":25,"type":"string","description":"optional (max: 25) - updated name on card","nullable":true},"CheckRoutingNumber":{"maxLength":9,"type":"string","description":"optional (max: 9) - updated bank routing number","nullable":true},"CheckAccountNumber":{"maxLength":20,"type":"string","description":"optional (max: 20) - updated bank account number","nullable":true},"CheckNumber":{"maxLength":10,"type":"string","description":"optional (max: 10) - check number","nullable":true},"CheckAccountTypeId":{"type":"string","description":"optional - 1=Checking, 2=Saving","nullable":true},"CheckTypeId":{"type":"string","description":"optional - 1=Personal, 2=Corporate, 3=Government","nullable":true},"NameOnCheck":{"maxLength":25,"type":"string","description":"optional (max: 25) - updated name on check","nullable":true},"Email":{"maxLength":100,"type":"string","description":"optional (max: 100) - updated billing email","format":"email","nullable":true},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing first name","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing last name","nullable":true},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - billing zip/postal code","nullable":true},"Street":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing street address","nullable":true},"City":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing city","nullable":true},"State":{"maxLength":50,"type":"string","description":"optional (max: 50) - 2 char US state code or non-US equivalent","nullable":true},"Country":{"maxLength":2,"type":"string","description":"optional - 2 char country code","nullable":true},"Currency":{"maxLength":3,"type":"string","description":"optional - 3 char currency code, e.g. \"USD\", \"CAD\"","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - constituent id from partner system","nullable":true},"IsDefault":{"type":"boolean","description":"optional - when true, designates this token as the default payment method for the constituent;\r\nclears IsDefault on all other tokens for the same constituent and processor","nullable":true},"IntegrationSource":{"type":"string","description":"optional - internal use - Identifies integrated Product; validated against the integration source that created the token","nullable":true}},"additionalProperties":false},"UpdateTokenResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"True if the token update was successful"},"Message":{"type":"string","description":"Update token response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Processor response message","nullable":true},"TokenGuid":{"type":"string","description":"The TokenGuid identifying this token","format":"uuid"},"ExternalCardToken":{"type":"string","description":"Updated ExternalCardToken - may differ from the original if the card number was changed on a processor that requires a new token (e.g. Stripe)","nullable":true},"ExternalCheckToken":{"type":"string","description":"Updated ExternalCheckToken - may differ from the original if the bank account was changed on a processor that requires a new token","nullable":true},"ExternalCustomerId":{"type":"string","description":"ExternalCustomerId - 3rd party gateway customer id tied to the token","nullable":true},"ExternalConstituentId":{"type":"string","description":"Partner's constituent/donor id stored on the token record","nullable":true},"ResponseCode":{"type":"string","description":"Response Code - \"0\" on success, any other value indicates an error","nullable":true}},"additionalProperties":false},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ## Cancel/delete a payment token by TokenGuid, ExternalCardToken, or ExternalCheckToken > Removes the token from the payment gateway and soft-deletes the token record. The IntegrationSource that created the token must match. ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/token":{"delete":{"tags":["Tokenization"],"summary":"Cancel/delete a payment token by TokenGuid, ExternalCardToken, or ExternalCheckToken","description":"Removes the token from the payment gateway and soft-deletes the token record. The IntegrationSource that created the token must match.","parameters":[{"name":"TokenGuid","in":"query","description":"Token identifier - provide one of: TokenGuid, ExternalCardToken, or ExternalCheckToken","schema":{"type":"string"}},{"name":"ExternalCardToken","in":"query","description":"optional (max: 200) - 3rd party gateway card token","schema":{"maxLength":200,"type":"string"}},{"name":"ExternalCheckToken","in":"query","description":"optional (max: 200) - 3rd party gateway check/ACH token","schema":{"maxLength":200,"type":"string"}},{"name":"IntegrationSource","in":"query","description":"optional - internal use - Identifies integrated Product; validated against the integration source that created the token","schema":{"type":"string"}},{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Token successfully deleted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeleteTokenResponse"}}}},"400":{"description":"If the delete fails","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"DeleteTokenResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"True if the token was successfully cancelled/deleted"},"TokenGuid":{"type":"string","description":"The TokenGuid that was deleted","format":"uuid"},"ExternalCardToken":{"type":"string","description":"3rd party gateway card token that was deleted (null for ACH tokens)","nullable":true},"ExternalCheckToken":{"type":"string","description":"3rd party gateway check/ACH token that was deleted (null for card tokens)","nullable":true},"ExternalCustomerId":{"type":"string","description":"3rd party gateway customer id associated with the deleted token","nullable":true},"ExternalConstituentId":{"type":"string","description":"Partner's constituent/donor id stored on the deleted token record","nullable":true},"Message":{"type":"string","description":"Response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Processor response message","nullable":true},"ResponseCode":{"type":"string","description":"Response code - \"0\" on success, any other value indicates an error","nullable":true}},"additionalProperties":false},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ## POST /api/tokenize > Tokenize a credit card ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/tokenize":{"post":{"tags":["Tokenization"],"summary":"Tokenize a credit card","description":"","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/GetTokenRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/GetTokenRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/GetTokenRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/GetTokenRequest"}}}},"responses":{"201":{"description":"Returns the newly created token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTokenResponse"}}}},"400":{"description":"If it fails to create a token","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"GetTokenRequest":{"required":["CardNum","City","Country","Email","ExpMonth","ExpYear","NameOnCard","Street"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"IntegrationSource":{"type":"string","description":"internal use","nullable":true},"CardNum":{"maxLength":30,"type":"string","description":"Valid Credit card number"},"CardType":{"maxLength":20,"type":"string","description":"optional (max: 20) - \"American Express\", \"Mastercard\", \"Visa\", \"Discover\", \"Diners Club\" - will be set internally based on cardNum","nullable":true},"ExpMonth":{"maxLength":2,"minLength":2,"type":"string","description":"example: \"01\" for January - required"},"ExpYear":{"maxLength":2,"minLength":2,"type":"string","description":"example: \"29\" for 2029 - required"},"CVNum":{"maxLength":4,"type":"string","description":"optional (max: 4) - valid CVV - please provide for CVV checks","nullable":true},"NameOnCard":{"maxLength":25,"type":"string","description":"required - Name on Card"},"Email":{"maxLength":100,"type":"string","description":"required - valid contact email","format":"email"},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - please provide for best interchange and avs checks - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000","nullable":true},"Street":{"maxLength":50,"type":"string","description":"required - please provide for best interchange and avs checks"},"City":{"maxLength":50,"type":"string","description":"required - please provide for best interchange and avs checks"},"State":{"maxLength":50,"type":"string","description":"optional - 2 char US state code, 3 char may be used for other non-US","nullable":true},"Country":{"maxLength":2,"type":"string","description":"required - 2 char country code"},"Currency":{"maxLength":3,"type":"string","description":"optional - 3 char currency code - Example for US - \"USD\", for CA - \"CAD\"","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ConstituentId per Product","nullable":true},"ExternalCustomerId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ArgoFire Gateway CustomerKey for pre-existing ArgoFire customers without a Payment API token record","nullable":true},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing First Name","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing Last Name","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"client ip address (max: 40) where transaction originates","nullable":true}},"additionalProperties":false,"description":""},"GetTokenResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"This is \"true\" tokenization process was successful, and \"false\" if unsuccessful."},"Message":{"type":"string","description":"Get Token response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Get Token Processor response message","nullable":true},"TransactionId":{"type":"string","description":"Not currently used and may be null","nullable":true},"TokenGuid":{"type":"string","description":"The unique GUID associated with the credit card or bank token you created that is used with the api/paymentToken endpoint","format":"uuid"},"ExternalCardToken":{"type":"string","description":"ExternalCardToken if available to return - represents 3rd party gateway card token","nullable":true},"ExternalCheckToken":{"type":"string","description":"ExternalCheckToken if available to return - represents 3rd party gateway check token","nullable":true},"ExternalCustomerId":{"type":"string","description":"ExternalCustomerId if available to return - represents 3rd party gateway customer id tied to gateway token","nullable":true},"ExternalConstituentId":{"type":"string","description":"Partner's constituent/donor id provided at tokenize time","nullable":true},"ResponseCode":{"type":"string","description":"Response Code - Successful = \"OK\" or \"0\", any other response code unsuccessful","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ## POST /api/tokenizeAch > Tokenize ACH/check account ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/tokenizeAch":{"post":{"tags":["Tokenization"],"summary":"Tokenize ACH/check account","description":"","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/GetTokenAchRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/GetTokenAchRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/GetTokenAchRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/GetTokenAchRequest"}}}},"responses":{"201":{"description":"Returns the newly created token","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GetTokenResponse"}}}},"400":{"description":"If it fails to create a token","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"GetTokenAchRequest":{"required":["CheckAccountNumber","CheckAccountTypeId","CheckRoutingNumber","CheckTypeId","City","Country","Email","NameOnCheck","Street"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"CheckRoutingNumber":{"maxLength":9,"type":"string","description":"required - Valid Check Bank Routing Number - formats -\r\nUS: Enter 9-digits,\r\nCA: Enter 9-digits (Format: 0YYYXXXXX: A mandatory leading zero. YYY: The 3-digit institution number. XXXXX: The 5-digit transit number),\r\nAU: Enter 6-digits - BSB Number (Bank State Branch) without hyphen"},"CheckAccountNumber":{"maxLength":20,"type":"string","description":"required - Valid Check Account Number - formats -\r\nUS: Enter 8-12 digits,\r\nCA: Enter 7-12 digits,\r\nAU: Enter 3-9 digits"},"CheckNumber":{"maxLength":10,"type":"string","description":"optional (max: 10) - Valid Check Number","nullable":true},"CheckAccountTypeId":{"type":"string","description":"required for Check ACH transactions - possible values -\r\n 1 - Checking,\r\n 2 - Saving"},"CheckTypeId":{"type":"string","description":"required for Check ACH transactions - possible values -\r\n 1 - Personal,\r\n 2 - Corporate,\r\n 3 - Government"},"NameOnCheck":{"maxLength":25,"type":"string","description":"required - Name on ACH Check Account"},"Email":{"maxLength":100,"type":"string","description":"required - valid contact email","format":"email"},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000","nullable":true},"Street":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing street"},"City":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing city"},"State":{"maxLength":50,"type":"string","description":"optional - 2 char US state code, 3 char may be used for other non-US","nullable":true},"Country":{"maxLength":2,"type":"string","description":"optional - 2 char country code"},"Currency":{"maxLength":3,"type":"string","description":"optional - 3 char currency code - Example for US - \"USD\", for CA - \"CAD\"","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ConstituentId per Product","nullable":true},"ExternalCustomerId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ArgoFire Gateway CustomerKey for pre-existing ArgoFire customers without a Payment API token record","nullable":true},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing First Name","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing Last Name","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"client ip address (max: 40) where transaction originates","nullable":true}},"additionalProperties":false},"GetTokenResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"This is \"true\" tokenization process was successful, and \"false\" if unsuccessful."},"Message":{"type":"string","description":"Get Token response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Get Token Processor response message","nullable":true},"TransactionId":{"type":"string","description":"Not currently used and may be null","nullable":true},"TokenGuid":{"type":"string","description":"The unique GUID associated with the credit card or bank token you created that is used with the api/paymentToken endpoint","format":"uuid"},"ExternalCardToken":{"type":"string","description":"ExternalCardToken if available to return - represents 3rd party gateway card token","nullable":true},"ExternalCheckToken":{"type":"string","description":"ExternalCheckToken if available to return - represents 3rd party gateway check token","nullable":true},"ExternalCustomerId":{"type":"string","description":"ExternalCustomerId if available to return - represents 3rd party gateway customer id tied to gateway token","nullable":true},"ExternalConstituentId":{"type":"string","description":"Partner's constituent/donor id provided at tokenize time","nullable":true},"ResponseCode":{"type":"string","description":"Response Code - Successful = \"OK\" or \"0\", any other response code unsuccessful","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` # Recurring Contracts ## POST /api/recurringProfile > Add a recurring profile ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/recurringProfile":{"post":{"tags":["Recurring Contracts"],"summary":"Add a recurring profile","description":"","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/AddRecurringProfileRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/AddRecurringProfileRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/AddRecurringProfileRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/AddRecurringProfileRequest"}}}},"responses":{"201":{"description":"Returns the newly created profile","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringProfileResponse"}}}},"400":{"description":"If it fails to create a profile","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"AddRecurringProfileRequest":{"required":["Amount","BillingFrequency","StartDate","TokenGuid"],"type":"object","properties":{"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"TokenGuid":{"type":"string","description":"required - Valid token guid of created tokenized account"},"Amount":{"maxLength":7,"type":"string","description":"required - Amount to be charged per billing frequency"},"StartDate":{"type":"string","description":"required - format yyyy-MM-dd - start date of contract"},"EndDate":{"type":"string","description":"optional - format yyyy-MM-dd - end date of contract (must be after StartDate) if you wish a contract to stop recurring at certain date","nullable":true},"NextBillDate":{"type":"string","description":"optional - format yyyy-MM-dd - We will calculate if not provided. The date when the first recurrence should begin charging the donor's card. Must be after StartDate. Use our GET api/nextBillDate API to help calculate.","nullable":true},"BillingFrequency":{"type":"string","description":"required - How often the recurrence should occur. Possible values:\r\n \"Daily\", (once per day)\r\n \"Weekly\", (once per week)\r\n \"Bi-Weekly\", (once per 2 weeks)\r\n \"Monthly\", (once per month)\r\n \"Bi-Monthly\", (Once every 2 months)\r\n \"Semi-Monthly\", (twice per month)\r\n \"Quarterly\", (four times per year)\r\n \"Semi-Annually\", (twice per year)\r\n \"Annually\" (once per year)"},"PreFeeAmount":{"maxLength":7,"type":"string","description":"optional - Pre Fee Amount with the fees not included if using PayFee flag (primary used for Non Profit transactions like Donations)","nullable":true},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction (primary used for Non Profit transactions like a donation), if used see Amount and PreFeeAmount info","nullable":true},"TransactionSourceGroupId":{"type":"string","description":"optional - For Direct Merchant (For Profit) Api Partners should set to PaymentNoFee (12), other values are for Non Profit transactions - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;","nullable":true},"ExternalEventId":{"maxLength":10,"type":"string","description":"optional - Event Id per Product","nullable":true},"ExternalEventGuid":{"type":"string","description":"optional - Event Guid per Product","nullable":true},"ExternalEventName":{"maxLength":500,"type":"string","description":"optional - Event Name per Product","nullable":true},"Surcharge":{"maxLength":7,"type":"string","description":"optional - calculated surcharge amount","nullable":true},"CommissionRateOverride":{"type":"string","description":"optional - The percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract. Primary used for Non Profit transactions.","nullable":true},"CardProcessingFeeOverride":{"type":"string","description":"optional - Overrides the default percentage processing fee. Primary used for Non Profit transactions.","nullable":true}},"additionalProperties":false,"description":""},"RecurringProfileResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"For all success responses, this will be True."},"Message":{"type":"string","description":"Recurring Profile response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Recurring Profile processor response message","nullable":true},"TransactionId":{"type":"string","description":"Not currently used and will be null","nullable":true},"RecurringProfileGuid":{"type":"string","description":"GUID that identifies this particular recurring billing contract. This value is used for both the Update Recurring Profile and Cancel Recurring Profile endpoints.","format":"uuid"},"RecurringProfileId":{"type":"integer","description":"An integer identifier for this particular recurring billing contract. Is not used elsewhere in the API.","format":"int32"},"ResponseCode":{"type":"string","description":"Response Code - Successful = \"OK\" or \"0\", any other response code unsuccessful","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ## PUT /api/recurringProfile > Update a recurring profile ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/recurringProfile":{"put":{"tags":["Recurring Contracts"],"summary":"Update a recurring profile","description":"","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/UpdateRecurringProfileRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/UpdateRecurringProfileRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/UpdateRecurringProfileRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/UpdateRecurringProfileRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringProfileResponse"}}}},"400":{"description":"Failure","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"UpdateRecurringProfileRequest":{"required":["RecurringProfileGuid"],"type":"object","properties":{"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"RecurringProfileGuid":{"type":"string","description":"required - Valid Recurring Profile Guid for update"},"Amount":{"maxLength":7,"type":"string","description":"optional if updating existing recurring profile - Amount to be charged per billing frequency","nullable":true},"StartDate":{"type":"string","description":"optional if updating existing recurring profile - format yyyy-MM-dd - start date of contract to update","nullable":true},"EndDate":{"type":"string","description":"optional if updating existing recurring profile - format yyyy-MM-dd - end date of contract (must be after StartDate) if you wish a contract to stop recurring at certain date","nullable":true},"NextBillDate":{"type":"string","description":"optional if updating existing recurring profile - format yyyy-MM-dd - The date when the first recurrence should begin charging the donor's card. Must be after StartDate.","nullable":true},"BillingFrequency":{"type":"string","description":"optional if updating existing recurring profile - How often the recurrence should occur. Possible values:\r\n \"Daily\", (once per day)\r\n \"Weekly\", (once per week)\r\n \"Bi-Weekly\", (once per 2 weeks)\r\n \"Monthly\", (once per month)\r\n \"Bi-Monthly\", (Once every 2 months)\r\n \"Semi-Monthly\", (twice per month)\r\n \"Quarterly\", (four times per year)\r\n \"Semi-Annually\", (twice per year)\r\n \"Annually\" (once per year)","nullable":true},"PreFeeAmount":{"maxLength":7,"type":"string","description":"optional if updating existing recurring profile - Pre Fee Amount with the fees not included if using fee (used for Non Profit transactions like a donation)","nullable":true},"PayFee":{"type":"boolean","description":"optional if updating existing recurring profile - cover the fees flag for the transaction (primary used for Non Profit transactions like a donation), if used see Amount and PreFeeAmount info","nullable":true},"TransactionSourceGroupId":{"type":"string","description":"optional if updating existing recurring profile - For Direct Merchant (For Profit) Api Partners should set to PaymentNoFee (12), other values are for Non Profit transactions - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;","nullable":true},"ExternalEventId":{"maxLength":10,"type":"string","description":"optional - Event Id per Product","nullable":true},"ExternalEventGuid":{"type":"string","description":"optional - Event Guid per Product","nullable":true},"ExternalEventName":{"maxLength":500,"type":"string","description":"optional - Event Name per Product","nullable":true},"UseOriginalFees":{"type":"boolean","description":"optional - if a Non Profit organization has changed fees then UseOriginalFee = false will update recurring profile to use updated organization fees. Primary used for Non Profit transactions.","nullable":true},"CommissionRateOverride":{"type":"string","description":"optional - update the percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract. Primary used for Non Profit transactions.","nullable":true},"CardProcessingFeeOverride":{"type":"string","description":"optional - update the CardProcessingFeeOverride that Overrides the default percentage processing fee. Primary used for Non Profit transactions.","nullable":true}},"additionalProperties":false,"description":""},"RecurringProfileResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"For all success responses, this will be True."},"Message":{"type":"string","description":"Recurring Profile response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Recurring Profile processor response message","nullable":true},"TransactionId":{"type":"string","description":"Not currently used and will be null","nullable":true},"RecurringProfileGuid":{"type":"string","description":"GUID that identifies this particular recurring billing contract. This value is used for both the Update Recurring Profile and Cancel Recurring Profile endpoints.","format":"uuid"},"RecurringProfileId":{"type":"integer","description":"An integer identifier for this particular recurring billing contract. Is not used elsewhere in the API.","format":"int32"},"ResponseCode":{"type":"string","description":"Response Code - Successful = \"OK\" or \"0\", any other response code unsuccessful","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ## DELETE /api/recurringProfile > Delete/Cancel a recurring profile ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/recurringProfile":{"delete":{"tags":["Recurring Contracts"],"summary":"Delete/Cancel a recurring profile","description":"","parameters":[{"name":"IntegrationSource","in":"query","description":"internal use - Identifies integrated Product","schema":{"type":"string"}},{"name":"RecurringProfileGuid","in":"query","description":"required - Valid Recurring Profile Guid for delete","required":true,"schema":{"type":"string"}},{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RecurringProfileResponse"}}}},"400":{"description":"Failure","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"RecurringProfileResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"For all success responses, this will be True."},"Message":{"type":"string","description":"Recurring Profile response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Recurring Profile processor response message","nullable":true},"TransactionId":{"type":"string","description":"Not currently used and will be null","nullable":true},"RecurringProfileGuid":{"type":"string","description":"GUID that identifies this particular recurring billing contract. This value is used for both the Update Recurring Profile and Cancel Recurring Profile endpoints.","format":"uuid"},"RecurringProfileId":{"type":"integer","description":"An integer identifier for this particular recurring billing contract. Is not used elsewhere in the API.","format":"int32"},"ResponseCode":{"type":"string","description":"Response Code - Successful = \"OK\" or \"0\", any other response code unsuccessful","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ## GET /api/nextBillDate > Get a next bill date calculated using Date and Billing Frequency from request for your recurring contract ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/nextBillDate":{"get":{"tags":["Recurring Contracts"],"summary":"Get a next bill date calculated using Date and Billing Frequency from request for your recurring contract","description":"","parameters":[{"name":"Date","in":"query","description":"required - format yyyy-MM-dd - Used to help calculate and return NextBillDate based on your Date provided.","required":true,"schema":{"type":"string"}},{"name":"BillingFrequency","in":"query","description":"required - How often the recurrence should occur. Used to help calculate NextBillDate based on billing frequency provided. Possible values:\r\n \"Daily\", (once per day)\r\n \"Weekly\", (once per week)\r\n \"Bi-Weekly\", (once per 2 weeks)\r\n \"Monthly\", (once per month)\r\n \"Bi-Monthly\", (Once every 2 months)\r\n \"Semi-Monthly\", (twice per month)\r\n \"Quarterly\", (four times per year)\r\n \"Semi-Annually\", (twice per year)\r\n \"Annually\" (once per year)","required":true,"schema":{"type":"string"}},{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns next bill date","content":{"application/json":{"schema":{"$ref":"#/components/schemas/NextBillDateResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}},"404":{"description":"If the next bill date not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"NextBillDateResponse":{"type":"object","properties":{"NextBillDate":{"type":"string","description":"Response Format Example:\r\n\"NextBillDate\": \"2029-07-23TT00:00:00\"","format":"date-time"}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}}} ``` # Pay Links ## POST /api/paylink > Returns a pay link - a unique URL that when clicked, directs users to our FrontStream secure online payment page ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/paylink":{"post":{"tags":["Pay Links"],"summary":"Returns a pay link - a unique URL that when clicked, directs users to our FrontStream secure online payment page","description":"","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/PayLinkRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/PayLinkRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/PayLinkRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/PayLinkRequest"}}}},"responses":{"200":{"description":"Returns a pay link","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayLinkResponse"}}}},"400":{"description":"If pay link creation throws exception","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}},"404":{"description":"If pay link data is not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"PayLinkRequest":{"required":["ApiKey","RedirectUrl"],"type":"object","properties":{"ApiKey":{"type":"string","description":"required - Your API key for pay link authentication."},"ProcessorGuid":{"type":"string","description":"optional - Identifies Processor being used by an API Partner","nullable":true},"IntegrationSource":{"type":"string","description":"optional and internal use - Identifies integrated Product","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"client ip address where transaction originates","nullable":true},"RedirectUrl":{"maxLength":500,"type":"string","description":"required - The URL to which the user will be redirected after payment."},"PaymentLines":{"type":"array","items":{"$ref":"#/components/schemas/PayLinkPaymentLine"},"description":"optional - An array of payment line objects specifying amounts and types. Required unless WorkflowType is \"UpdateToken\".","nullable":true},"TranId":{"maxLength":100,"type":"string","description":"optional (max: 100) for API Partner Reference or Invoice number and Dup Checking - unique id per Integration Source transaction (where integration source has DupCheckEnabled) that will be checked against successfully processed prior TranIds for Duplicates","nullable":true},"ShowTransactionId":{"type":"boolean","description":"optional - 'True' will display the TranId on the checkout form. If set 'True' and optional TranId is not set, our form will allow for input to set TranId in form UI","nullable":true},"TransactionIdText":{"maxLength":100,"type":"string","description":"optional (max: 100) - The text to display in front of the TranId. Example: Invoice#:","nullable":true},"PoweredByText":{"maxLength":100,"type":"string","description":"optional (max: 100) - Text to display for branding purposes (e.g., \"Powered by Your Company\"). If not provided, defaults to the Integration Source Application name configured that created the Pay link. Otherwise, defaults to \"FrontStream\"","nullable":true},"PoweredByUrl":{"maxLength":500,"type":"string","description":"optional (max: 500) - a valid URL users will be directed to when clicking the PoweredByText usually your Company URL. If not provided, defaults to https://www.frontstream.com","nullable":true},"DonateButtonText":{"maxLength":100,"type":"string","description":"optional (max: 100) - Text displayed on the submit payment button. Default is \"Submit Payment\".","nullable":true},"Language":{"maxLength":35,"type":"string","description":"optional (max: 35) - The language of the pay link session. Default is \"en\" for english.","nullable":true},"DefaultCountryCode":{"maxLength":2,"type":"string","description":"optional - 2 char country code. The default country code for user input. Example: \"US\".","nullable":true},"Theme":{"maxLength":5000,"type":"string","description":"optional (max: 5000) - CSS string for custom styling of the embedded session. Example: \".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)}\"","nullable":true},"ThemeFonts":{"maxItems":50,"type":"array","items":{"type":"string"},"description":"optional - Array of fonts to be used in the session. example: \"\"Open Sans:400,500,600,700 \",\"Montserrat:400, 700 \",\"Roboto:400, 700 \".","nullable":true},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - if set, this FirstName will display in payment form","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - if set, this LastName will display in payment form","nullable":true},"Email":{"maxLength":100,"type":"string","description":"option (max: 100) - valid contact email - - if set, this Email will display in payment form","format":"email","nullable":true},"Street":{"maxLength":50,"type":"string","description":"optional (max: 50) - if set, this Street will display in payment form","nullable":true},"City":{"maxLength":50,"type":"string","description":"optional (max: 50) - if set, this City will display in payment form","nullable":true},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000 - if set, this Zip will display in payment form","nullable":true},"State":{"maxLength":50,"type":"string","description":"optional - 2 char US state code, 3 char may be used for other non-US - if set, this State will display in payment form","nullable":true},"Country":{"maxLength":2,"type":"string","description":"optional - 2 char country code - if set, this Country will display in payment form","nullable":true},"Phone":{"maxLength":20,"type":"string","description":"optional (max: 20) - valid North America and AU patterns currently supported: 123-456-7890, (123) 456-7890, 123.456.7890, +12025550123, 1234567890, 0412345678, +61412345678","nullable":true},"TokenizeCard":{"type":"boolean","description":"optional - set to true to tokenize card or check at time of purchase","nullable":true},"TokenGuid":{"type":"string","description":"optional - TokenGuid to use to process transaction in payment form. If using ExternalCardToken or ExternalCheckToken instead of TokenGuid - Valid Token Guid from a Tokenized card through Embedded Payment Form/Payment API","nullable":true},"ExternalCardToken":{"maxLength":200,"type":"string","description":"optional (max: 200) - Customer credit card token generated outside the Embedded Form (e.g. ArgoFire). ExternalCardToken to use to process transaction in payment form.","nullable":true},"ExternalCheckToken":{"maxLength":200,"type":"string","description":"optional (max: 200) - Customer check token generated outside the Embedded Form (e.g. ArgoFire). ExternalCheckToken to use to process transaction in payment form.","nullable":true},"ExternalEventId":{"maxLength":10,"type":"string","description":"optional (max: 10) - Customer Event Id","nullable":true},"ExternalEventName":{"maxLength":500,"type":"string","description":"optional (max: 500) - Customer Event Name","nullable":true},"WorkflowType":{"type":"integer","description":"optional - future use - Workflow type for the session. Valid values: 3 (TokenPayment), 4 (ManageTokens).\r\nUse 3 to tokenize a card for an existing constituent without processing a payment.\r\nUse 4 for full card wallet management (list, add, delete).","format":"int32","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - The merchant's internal customer/client ID. When provided with WorkflowType=\"UpdateToken\", links the new card token to the customer/client's existing ArgoFire customer record.","nullable":true},"ExternalCustomerId":{"maxLength":200,"type":"string","description":"optional (max: 200) - The processor-generated CustomerKey for a pre-existing customer record. When provided with ExternalConstituentId, links the payment session to the existing processor customer record instead of creating a new one.","nullable":true}},"additionalProperties":false},"PayLinkPaymentLine":{"required":["Recurring","Type"],"type":"object","properties":{"Amount":{"maxLength":7,"type":"string","description":"optional - transaction amount. If amount is not provided and single payment line, the amount field will be editable for input on form (range $0.01 to $99,999.99)","nullable":true},"Type":{"type":"integer","description":"required - Payment type identifier - possible values -\r\n 1 - Donation Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 12 - PaymentNoFee;","format":"int32"},"Recurring":{"type":"integer","description":"required - Indicates if the payment is recurring and billing frequency - possible values -\r\n 0 - Not recurring,\r\n 1 - Daily,\r\n 2 - Weekly,\r\n 3 - Bi-Weekly,\r\n 4 - Monthly,\r\n 5 - Bi-Monthly,\r\n 6 - Quarterly,\r\n 7 - Semi-Annually,\r\n 8 - Annually\r\n 9 - Semi-Monthly","format":"int32"},"ExternalLineId":{"maxLength":100,"type":"string","description":"optional (max: 100) - use this to track individual line item IDs if necessary.","nullable":true}},"additionalProperties":false},"PayLinkResponse":{"type":"object","properties":{"PayLinkUrl":{"type":"string","description":"a unique URL that when clicked, direct users to our FrontStream secure online payment page","nullable":true}},"additionalProperties":false},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}}} ``` ## DELETE /api/paylink > Delete/Cancel a previous pay link url created from being used again ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/paylink":{"delete":{"tags":["Pay Links"],"summary":"Delete/Cancel a previous pay link url created from being used again","description":"","parameters":[{"name":"PayLinkId","in":"query","description":"required - Valid pay link identifier to be cancelled/deleted - the identifier is the last parameter of the pay link url returned in the original creation process","required":true,"schema":{"type":"string"}},{"name":"IntegrationSource","in":"query","description":"internal use - Identifies integrated Product","schema":{"type":"string"}},{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PayLinkResponse"}}}},"400":{"description":"Failure","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"PayLinkResponse":{"type":"object","properties":{"PayLinkUrl":{"type":"string","description":"a unique URL that when clicked, direct users to our FrontStream secure online payment page","nullable":true}},"additionalProperties":false},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` # Charity Search ## GET /api/CharitySearch > Nonprofit Charity Search ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/CharitySearch":{"get":{"tags":["Charity Search"],"summary":"Nonprofit Charity Search","description":"","parameters":[{"name":"Name","in":"query","description":"optional - Charity Name - partial or full name","schema":{"maxLength":70,"type":"string"}},{"name":"EIN","in":"query","description":"optional - Valid US/CA Nonprofit EIN/Tax ID. For US EINs, the dash proceeding the first two numbers is optional; the endpoint will handle it either way (i.e. 12-3456789 and 123456789 are both valid and will result in the same record being returned)","schema":{"maxLength":15,"minLength":9,"type":"string"}},{"name":"CharitySource","in":"query","description":"optional - This should be either 1 (US) or 2 (Canada) - Default to US","schema":{"type":"integer","format":"int32"}},{"name":"City","in":"query","description":"optional - Searches the city name of charity addresses","schema":{"maxLength":30,"type":"string"}},{"name":"State","in":"query","description":"optional - Searches the state code of charity addresses - ISO Standard two digit State code. (VA, NY)","schema":{"maxLength":2,"type":"string"}},{"name":"PageIndex","in":"query","description":"Defaults to 1 - The page of results to display (i.e. if there are 100 overall results to your search and you provide this as 3 with a PageSize=10, this will return results #21 through #30)","schema":{"type":"integer","format":"int32"}},{"name":"PageSize","in":"query","description":"Defaults to 10 - The number of results to display per page.","schema":{"type":"integer","format":"int32"}},{"name":"SortColumn","in":"query","description":"Default SortColumn NpoName - Indicates which SearchResults field to sort by (see response example for valid values). Only supports sorting by one column.","schema":{"type":"string"}},{"name":"SortDesc","in":"query","description":"true/false - Determine to order the results by descending values of the selected column (or NpoName if not selected).","schema":{"type":"boolean"}}],"responses":{"200":{"description":"Returns Charity Search Data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CharitySearchResults"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}},"404":{"description":"If Charity Search Data not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"CharitySearchResults":{"type":"object","properties":{"TotalResultCount":{"type":"integer","description":"How many total possible results there are for your search.","format":"int32"},"TotalPages":{"type":"integer","description":"How many pages of data exist based on your selected PageSize.","format":"int32"},"PageIndex":{"type":"integer","description":"Confirms what you passed in the querystring.","format":"int32"},"PageSize":{"type":"integer","description":"Confirms what you passed in the querystring.","format":"int32"},"SearchResults":{"type":"array","items":{"$ref":"#/components/schemas/CharitySearchResultsList"},"description":"Each record in the array represents a full Charity Record.","nullable":true}},"additionalProperties":false,"description":""},"CharitySearchResultsList":{"type":"object","properties":{"CharityId":{"type":"string","description":"Unique Identifier for the Charity in the Payment API.","nullable":true},"NpoName":{"type":"string","description":"Name of the Charity in the Payment API database.","nullable":true},"EIN":{"type":"string","description":"The United States EIN or Canadian Tax ID of the Charity.","nullable":true},"Address1":{"type":"string","description":"Address Line 1 of the Charity's address.","nullable":true},"Address2":{"type":"string","description":"Address Line 2 of the Charity's address.","nullable":true},"City":{"type":"string","description":"City of the Charity's address.","nullable":true},"State":{"type":"string","description":"State of the Charity's address.","nullable":true},"Zip":{"type":"string","description":"Postal Code of the Charity's address.","nullable":true},"Country":{"type":"string","description":"Country of the Charity's address.","nullable":true},"NpoEligibilityFlag":{"type":"boolean","description":"Indicates whether or not the organization is currently able to receive tax-deductible donations based on United States IRS filings."},"ParentOrgName":{"type":"string","description":"This will return the same value as NpoName if the Charity has no Parent organization, but if a particular organization has indicated that it is a child organization of a larger Charity (such as a regional chapter of a nationwide charity), the Parent Charity name will appear here.","nullable":true},"NTEEcode":{"type":"string","description":"The Charity's NTEE code as defined by United States IRS filings. This is not a required classification, and thus may not exist for all records (and will not exist for Canadian charity records).","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}}} ``` # Get Processor Payment Methods ## Get Active processor supported Payment Method Types by ProcessorGuid > GET /api/processorPaymentMethodTypes?processorGuid=12345678-9012-3456-7890-dc84772c0032 > \ > Response Example: > \ > \[ > \ > { > \ > "PaymentMethodTypeId": 1, > \ > "PaymentMethodTypeValue": "AMEX" > \ > }, > \ > { > \ > "PaymentMethodTypeId": 2, > \ > "PaymentMethodTypeValue": "MASTERCARD" > \ > }, > \ > { > \ > "PaymentMethodTypeId": 3, > \ > "PaymentMethodTypeValue": "VISA" > \ > }, > \ > { > \ > "PaymentMethodTypeId": 4, > \ > "PaymentMethodTypeValue": "DISCOVER" > \ > }, > \ > { > \ > "PaymentMethodTypeId": 5, > \ > "PaymentMethodTypeValue": "DINERSCLUB" > \ > }, > \ > { > \ > "PaymentMethodTypeId": 6, > \ > "PaymentMethodTypeValue": "JCB" > \ > }, > \ > { > \ > "PaymentMethodTypeId": 7, > \ > "PaymentMethodTypeValue": "ACH" > \ > }, > \ > { > \ > "PaymentMethodTypeId": 8, > \ > "PaymentMethodTypeValue": "GOOGLEPAY" > \ > }, > \ > { > \ > "PaymentMethodTypeId": 9, > \ > "PaymentMethodTypeValue": "APPLEPAY" > \ > }, > \ > { > \ > "PaymentMethodTypeId": 10, > \ > "PaymentMethodTypeValue": "STRIPE" > \ > } > \ > ] ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/processorPaymentMethodTypes":{"get":{"tags":["Get Processor Payment Methods"],"summary":"Get Active processor supported Payment Method Types by ProcessorGuid","description":" GET /api/processorPaymentMethodTypes?processorGuid=12345678-9012-3456-7890-dc84772c0032\r\n Response Example:\r\n\t\t[\r\n \t\t{\r\n \"PaymentMethodTypeId\": 1,\r\n \"PaymentMethodTypeValue\": \"AMEX\"\r\n },\r\n {\r\n \"PaymentMethodTypeId\": 2,\r\n \"PaymentMethodTypeValue\": \"MASTERCARD\"\r\n },\r\n {\r\n \"PaymentMethodTypeId\": 3,\r\n \"PaymentMethodTypeValue\": \"VISA\"\r\n },\r\n {\r\n \"PaymentMethodTypeId\": 4,\r\n \"PaymentMethodTypeValue\": \"DISCOVER\"\r\n },\r\n {\r\n \"PaymentMethodTypeId\": 5,\r\n \"PaymentMethodTypeValue\": \"DINERSCLUB\"\r\n },\r\n {\r\n \"PaymentMethodTypeId\": 6,\r\n \"PaymentMethodTypeValue\": \"JCB\"\r\n },\r\n {\r\n \"PaymentMethodTypeId\": 7,\r\n \"PaymentMethodTypeValue\": \"ACH\"\r\n },\r\n {\r\n \"PaymentMethodTypeId\": 8,\r\n \"PaymentMethodTypeValue\": \"GOOGLEPAY\"\r\n },\r\n {\r\n \"PaymentMethodTypeId\": 9,\r\n \"PaymentMethodTypeValue\": \"APPLEPAY\"\r\n },\r\n {\r\n \"PaymentMethodTypeId\": 10,\r\n \"PaymentMethodTypeValue\": \"STRIPE\"\r\n }\r\n\t\t]","parameters":[{"name":"processorGuid","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"mKey","in":"query","schema":{"type":"string"}},{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns processor supported Payment Method Types data","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/PaymentMethodTypeResponse"}}}}},"404":{"description":"If the processor payment method types not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"PaymentMethodTypeResponse":{"type":"object","properties":{"PaymentMethodTypeId":{"$ref":"#/components/schemas/PaymentMethodTypeEnum"},"PaymentMethodTypeValue":{"type":"string","description":"possible values :\r\n\"NONE\" = 0,\r\n\"AMEX\" = 1,\r\n\"MASTERCARD\" = 2,\r\n\"VISA\" = 3,\r\n\"DISCOVER\" = 4,\r\n\"DINERSCLUB\" = 5,\r\n\"JCB\" = 6,\r\n\"ACH\" = 7,\r\n\"GOOGLEPAY\" = 8,\r\n\"APPLEPAY\" = 9\r\n\"STRIPE\" = 10","nullable":true}},"additionalProperties":false},"PaymentMethodTypeEnum":{"enum":[0,1,2,3,4,5,6,7,8,9,10],"type":"integer","format":"int32"},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}}} ``` # Surcharge ## GET /api/surchargeConfig > Get Configured Surcharge Merchant data: Is Surcharge enabled, Surcharge percentage, and Surcharge StartDate ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/surchargeConfig":{"get":{"tags":["Surcharge"],"summary":"Get Configured Surcharge Merchant data: Is Surcharge enabled, Surcharge percentage, and Surcharge StartDate","description":"","parameters":[{"name":"processorGuid","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"organizationGuid","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"mKey","in":"query","schema":{"type":"string"}},{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns the Configured Surcharge Merchant data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurchargeConfigResponse"}}}},"400":{"description":"If surcharge config throws exception","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}},"404":{"description":"If the surcharge config is not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"SurchargeConfigResponse":{"type":"object","properties":{"SurchargeEnabled":{"type":"boolean","description":"Is Surcharging enabled - true/false returned based on configured Merchant Surcharge."},"SurchargeRate":{"type":"string","description":"example 2.9900 in d.dddd format - configured Merchant Surcharge Percentage Rate.","nullable":true},"SurchargeStartDate":{"type":"string","description":"Surcharge Start Date based on configured Merchant Surcharge.\r\nDate Format - yyyy-MM-dd\r\nResponse Example:\r\n\"SurchargeStartDate\": \"2025-01-31\"","nullable":true}},"additionalProperties":false},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}}} ``` ## GET /api/surcharge > Returns Calculated Surcharge based on Amount, Configured Surcharge Merchant percentage, and CREDIT only Card Bin ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/surcharge":{"get":{"tags":["Surcharge"],"summary":"Returns Calculated Surcharge based on Amount, Configured Surcharge Merchant percentage, and CREDIT only Card Bin","description":"","parameters":[{"name":"ProcessorGuid","in":"query","description":"required if API Partner - Identifies Processor being used by an API Partner","schema":{"type":"string"}},{"name":"OrganizationGuid","in":"query","description":"internal use - Valid Panorama Organization Guid","schema":{"type":"string"}},{"name":"MKey","in":"query","description":"internal use - Used by FrontStream only","schema":{"maxLength":500,"type":"string"}},{"name":"CardBin","in":"query","description":"optional if TokenGuid or ExternalCardToken used - Valid card bin - 1st 6 to 8 digits","schema":{"maxLength":8,"minLength":6,"type":"string"}},{"name":"TokenGuid","in":"query","description":"optional - Valid Token Guid from a Tokenized card through Payment API","schema":{"type":"string"}},{"name":"ExternalCardToken","in":"query","description":"internal use","schema":{"maxLength":200,"type":"string"}},{"name":"Amount","in":"query","description":"required - transaction amount used for surcharge calculation","required":true,"schema":{"maxLength":9,"type":"string"}},{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns the calculated surcharge","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SurchargeResponse"}}}},"400":{"description":"If surcharge calculation throws exception","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}},"404":{"description":"If the surcharge data is not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"SurchargeResponse":{"type":"object","properties":{"Amount":{"type":"string","description":"This is the original amount submitted for Surcharge calculation.","nullable":true},"SurchargeAmount":{"type":"string","description":"This is the calculated surcharge amount based on configured Merchant Surcharge Percentage Rate and submitted amount.\r\nd.dd format","nullable":true},"SurchargeRate":{"type":"string","description":"example 2.9900 in d.dddd format - configured Merchant Surcharge Percentage Rate.","nullable":true}},"additionalProperties":false},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}}} ``` # Payments ## GET /api/paymentResponse > Returns previous payment response data if available by a PaymentGuid or an EpfSessionId ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/paymentResponse":{"get":{"tags":["Payments"],"summary":"Returns previous payment response data if available by a PaymentGuid or an EpfSessionId","description":"","parameters":[{"name":"paymentGuid","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"epfSessionId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Returns payment response data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"If payment response data returns throws exception"},"404":{"description":"If payment response data not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProblemDetails"}}}}}}}},"components":{"schemas":{"PaymentResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"As one would guess, this is \"true\" if the transaction was processed successfully, and \"false\" if the transaction was not processed successfully."},"Message":{"type":"string","description":"Payment Gateway response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Response from the processing bank.","nullable":true},"AuthCode":{"type":"string","description":"AuthCode from the processor.","nullable":true},"TransactionId":{"type":"string","description":"Payment Gateway TransactionId","nullable":true},"PaymentGuid":{"type":"string","description":"Payment API Payment GUID","format":"uuid"},"PaymentId":{"type":"integer","description":"Payment API Payment Id","format":"int32"},"ResponseCode":{"type":"string","description":"Response Code - Approved = 0, Not processed = -100 with more possible values - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"PaymentResult":{"$ref":"#/components/schemas/PaymentResult"},"ProcessStatus":{"$ref":"#/components/schemas/ProcessStatus"},"TotalAmount":{"type":"number","description":"The total amount processed toward the cardholder's account.","format":"double"},"TotalSurcharge":{"type":"number","description":"The total surcharge amount if available.","format":"double","nullable":true},"AVSStreetStatus":{"type":"string","description":"Address Verification Street Status if available.","nullable":true},"AVSZipStatus":{"type":"string","description":"Address Verification Zip Status if available.","nullable":true},"AVSResponse":{"type":"string","description":"Address Verification Response if available. AVS and CVV response values covered more here - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"CVVResponse":{"type":"string","description":"Card Verification Response if available. AVS and CVV response values covered more here - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"ExternalCardToken":{"type":"string","description":"ExternalCardToken if available to return - represents 3rd party gateway card token","nullable":true},"ExternalCheckToken":{"type":"string","description":"ExternalCheckToken if available to return - represents 3rd party gateway check token","nullable":true},"ExternalCustomerId":{"type":"string","description":"ExternalCustomerId if available to return - represents 3rd party gateway customer id tied to gateway token","nullable":true},"ExternalConstituentId":{"type":"string","description":"ExternalConstituentId if available to return - merchant-supplied constituent/donor id linked to this token","nullable":true},"TokenGuid":{"type":"string","description":"Payment API Token GUID if available to return","format":"uuid","nullable":true},"TransactionFees":{"type":"array","items":{"$ref":"#/components/schemas/FeeResponse"},"description":"Fee Response","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use","format":"uuid"},"ProcessorGuid":{"type":"string","description":"ProcessorGuid used","format":"uuid","nullable":true},"FirstName":{"type":"string","nullable":true},"LastName":{"type":"string","nullable":true},"EmailAddress":{"type":"string","nullable":true},"PostalCode":{"type":"string","nullable":true},"AddressLine1":{"type":"string","nullable":true},"City":{"type":"string","nullable":true},"ProvinceCode":{"type":"string","nullable":true},"CountryCode":{"type":"string","nullable":true},"CardNum":{"type":"string","description":"last 4 digits of card","nullable":true},"CardType":{"type":"string","description":"possible values if available: American Express, Mastercard, Visa, Discover, Diners Club, Undefined","nullable":true},"ExpMonth":{"type":"string","nullable":true},"ExpYear":{"type":"string","nullable":true},"Currency":{"type":"string","nullable":true},"PaymentMethodTypeId":{"type":"integer","description":"possible values if available:\r\nNone = 0,\r\nAmericanExpress = 1,\r\nMasterCard = 2,\r\nVisa = 3,\r\nDiscover = 4,\r\nDinersClub = 5,\r\nACH = 7,\r\nGOOGLEPAY = 8,\r\nAPPLEPAY = 9","format":"int32","nullable":true},"IsSurchargeEligible":{"type":"boolean","description":"Was card used Surcharge eligible","nullable":true},"CheckAccountNum":{"type":"string","description":"last 4 digits of check account","nullable":true},"TranId":{"type":"string","description":"unique tran id per Integration Source if available","nullable":true},"EpfSessionId":{"type":"string","description":"FrontStream unique Embedded Payment Form Session Id if available","nullable":true},"PaymentDate":{"type":"string","description":"Payment Date of transaction","format":"date-time"}},"additionalProperties":false,"description":"See more response code definitions here: https://developers.frontstream.com/welcome-to-our-payment-api/api-references/test-payment-api-features/response-codes"},"PaymentResult":{"enum":[1,2,3,4,5,6],"type":"integer","format":"int32"},"ProcessStatus":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12],"type":"integer","format":"int32"},"FeeResponse":{"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","nullable":true},"PaymentAmount":{"type":"number","description":"This is the amount charged to the donor. Will be equal to the sum of the Amount parameters if payFee=false, but if payFee=true, then this will be the amount that will be charged to the donor in order to have the net post-disbursement donation be equal to the Amount parameters.","format":"double","nullable":true},"CardFeeRate":{"type":"number","description":"example 2.5% - applied to EVERY donation. This is the FrontStream card processing fee. The percentage of the PaymentAmount that will be taken for credit card fees. Expressed as a human-readable percentage rather than a decimal value, it is intended to be able to be displayed directly on a page without needing to be converted.","format":"double","nullable":true},"CardFeeAmount":{"type":"number","description":"This is the amount that is owed to the gateway for the example 2.5% that FrontStream collects from the transaction.\r\n 2.5% of transaction amount if donor is not paying the fee, otherwise 2.5% of the transaction + card fee.","format":"double","nullable":true},"CardTypeFeeAmount":{"type":"number","description":"A per transaction fee configured by card type (VI, MC, DI, AMEX, etc.) per API Partner's Contract other wise 0 (zero)","format":"double","nullable":true},"TotalCommissionRate":{"type":"number","description":"The Total percentage of Commissions that FrontStream takes from a given transaction.\r\nThis rate = Partner CommissionRate + FS CommissionRate","format":"double","nullable":true},"TotalCommissionAmount":{"type":"number","description":"The product of the transaction times the Total commission rate.","format":"double","nullable":true},"PartnerCommissionRate":{"type":"number","description":"The Partner Commission percentage taken on behalf of the Partner from a given transaction.","format":"double","nullable":true},"PartnerCommissionAmount":{"type":"number","description":"The product of the transaction times the Partner commission rate.","format":"double","nullable":true},"FsCommissionRate":{"type":"number","description":"The FrontStream Commission percentage that FrontStream takes from a given transaction.","format":"double","nullable":true},"FsCommissionAmount":{"type":"number","description":"The product of the transaction times the FrontStream commission rate.","format":"double","nullable":true},"TotalFees":{"type":"number","description":"The sum of all fees applied to a transaction amount. (TotalCommission + CardFee + FlatFee + CardFeeOnFee)","format":"double","nullable":true},"MaxOverridePartnerCommissionRate":{"type":"number","description":"The derived minimum partner override rate and maximum partner override rate\r\n\r\nMaxOverridePartnerCommissionRate = TotalFees = (PartnerCommission rate) + (Card Fee Rate) + (Fs Commission Rate)\r\nMinOverridePartnerCommissionRate = (Card Fee rate) + (Fs Commission rate)","format":"double"},"MinOverridePartnerCommissionRate":{"type":"number","format":"double"},"PerTransFee":{"type":"number","description":"The flat amount that will be taken from the PaymentAmount for any Per-Transaction Fees as configured in your contract.","format":"double","nullable":true},"Tip":{"type":"number","description":"The flat amount that will be paid out to the API Partner if Donor decides to add a tip regardless of payFee true or false.","format":"double"},"CardFeeOnFeeAmount":{"type":"number","format":"double","nullable":true},"Tax":{"type":"number","format":"double","nullable":true},"AchFeeRate":{"type":"number","description":"The ACH processing fee rate applied to this transaction.","format":"double","nullable":true},"AchFeeAmount":{"type":"number","description":"The ACH processing fee amount for this transaction.","format":"double","nullable":true}},"additionalProperties":false,"description":""},"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}}} ``` ## POST /api/payment > Make a payment ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/payment":{"post":{"tags":["Payments"],"summary":"Make a payment","description":"","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/PaymentRequest"}}}},"responses":{"201":{"description":"Returns the newly created payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"If it fails to create a payment","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"PaymentRequest":{"required":["Email","IpAddress","NameOnCard","Transactions"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"MKey":{"maxLength":500,"type":"string","description":"internal use - Used by FrontStream only","nullable":true},"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"CardNum":{"maxLength":30,"type":"string","description":"optional - Valid Credit card number - required for non-Wallet transaction","nullable":true},"CardType":{"maxLength":20,"type":"string","description":"optional (max: 20) - \"American Express\", \"Mastercard\", \"Visa\", \"Discover\", \"Diners Club\" - will be set internally based on cardNum","nullable":true},"ExpMonth":{"maxLength":2,"type":"string","description":"optional (max: 2) - example: \"01\" for January - required for non-Wallet transaction","nullable":true},"ExpYear":{"maxLength":2,"type":"string","description":"optional (max: 2) - example: \"29\" for 2029 - required for non-Wallet transaction","nullable":true},"CVNum":{"maxLength":4,"type":"string","description":"optional (max: 4) - valid CVV - please provide for CVV checks","nullable":true},"NameOnCard":{"maxLength":25,"type":"string","description":"required - Name on Card"},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - please provide for best interchange and avs checks - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000","nullable":true},"Street":{"maxLength":50,"type":"string","description":"optional (max: 50) - please provide for best interchange and avs checks","nullable":true},"Email":{"maxLength":100,"type":"string","description":"required - valid contact email","format":"email"},"City":{"maxLength":50,"type":"string","description":"optional (max: 50) - please provide for best interchange and avs checks","nullable":true},"State":{"maxLength":50,"type":"string","description":"optional - 2 char US state code, 3 char may be used for other non-US","nullable":true},"Country":{"maxLength":2,"type":"string","description":"optional (max: 2) - 2 char country code","nullable":true},"Currency":{"maxLength":3,"type":"string","description":"optional (max: 3) - 3 char currency code - Example for US - \"USD\", for CA - \"CAD\"","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - Donor Identifier per Product","nullable":true},"ExternalCustomerId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ArgoFire Gateway CustomerKey for pre-existing ArgoFire customers without a Payment API token record","nullable":true},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing First Name","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing Last Name","nullable":true},"BillingDescriptor":{"maxLength":22,"type":"string","description":"optional (max: 22) - descriptor to show on bank statement","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"required - client ip address where transaction originates"},"ExternalEventId":{"maxLength":10,"type":"string","description":"optional (max: 10) - Event Identifier per Product","nullable":true},"ExternalEventGuid":{"type":"string","description":"optional - Event Guid per Product","nullable":true},"ExternalEventName":{"maxLength":500,"type":"string","description":"optional (max: 500) - Event Name per Product","nullable":true},"ShippingFee":{"maxLength":7,"type":"string","description":"optional (max: 7) - fee for shipping that will be added to the total amount","nullable":true},"TaxableBenefit":{"maxLength":7,"type":"string","description":"optional (max: 7) - If part of the donation being passed in is taxable, include that amount here. No calculations are performed using this value, it is simply a placeholder to be used for your own reporting; all commission and credit card fees still apply as normal.","nullable":true},"TranId":{"maxLength":100,"type":"string","description":"optional (max: 100) - system unique id for Dup Checking per Integration Source transaction (where integration source has DupCheckEnabled) that will be checked against successfully processed prior TranIds for Duplicates","nullable":true},"EpfSessionId":{"type":"string","description":"internal use - FrontStream unique Embedded Payment Form Session Id if available","nullable":true},"Transactions":{"type":"array","items":{"$ref":"#/components/schemas/PaymentTransTypeRequest"},"description":"required - 1 to n transactions to break down transaction line items"},"AFShieldAdditional":{"$ref":"#/components/schemas/AFShieldPaymentRequest"},"PaymentMethodTypeId":{"type":"string","description":"internal use - GooglePay (8) or Apple Pay (9) - possible values -\r\n \"8\" - GOOGLEPAY,\r\n \"9\" - APPLEPAY","nullable":true},"ExternalPaymentData":{"maxLength":5000,"type":"string","description":"internal use for Wallet transactions","nullable":true},"Surcharge":{"maxLength":7,"type":"string","description":"optional (max: 7) - calculated surcharge amount that will be added to the total amount","nullable":true},"Tokenize":{"type":"boolean","description":"optional - set to true to tokenize card at time of purchase","nullable":true}},"additionalProperties":false,"description":""},"PaymentTransTypeRequest":{"required":["Amount","TransactionSourceGroupId"],"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","description":"required - For Direct Merchant (For Profit) Api Partners should set to PaymentNoFee (12), other values are for Non Profit transactions - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;\r\n 13 - EventDonationFee;\r\n 14 - SponsorshipFee\r\n 15 - MembershipFee"},"Amount":{"maxLength":7,"type":"string","description":"required - Amount of line item without the fees included, Payment api will calculate fees for you"},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction. Indicates if the donor intends to cover the processing fees for the donation (primary used for Non Profit transactions like a donation)"},"CommissionRateOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - The percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract.","nullable":true},"CardProcessingFeeOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - Overrides the default percentage processing fee","nullable":true},"ExternalLineId":{"maxLength":100,"type":"string","description":"optional (max: 100) - use this to track individual line item IDs if necessary.","nullable":true},"Tip":{"maxLength":7,"type":"string","description":"optional (max: 7) - An amount taken up front for the API Partner if Donor decides to apply a tip. Added to the total amount to charge on the donor’s card . Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true},"Tax":{"maxLength":7,"type":"string","description":"optional (max: 7) - A tax amount taken up front. Added to the total amount to charge on the donor’s card. Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true}},"additionalProperties":false,"description":""},"AFShieldPaymentRequest":{"type":"object","properties":{"ProductDescription":{"maxLength":256,"type":"string","nullable":true},"ProductItem":{"maxLength":256,"type":"string","nullable":true},"ProductType":{"maxLength":256,"type":"string","nullable":true},"ProductQuantity":{"maxLength":3,"type":"string","nullable":true},"SessionId":{"maxLength":32,"type":"string","nullable":true},"BillToPhoneNumber":{"maxLength":32,"type":"string","nullable":true},"ShippingAddressStreet1":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressStreet2":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressCountry":{"maxLength":2,"type":"string","nullable":true},"ShippingAddressCity":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressEmail":{"maxLength":64,"type":"string","format":"email","nullable":true},"ShippingAddressName":{"maxLength":64,"type":"string","nullable":true},"ShippingAddressZip":{"maxLength":10,"type":"string","nullable":true},"ShippingAddressState":{"maxLength":50,"type":"string","nullable":true},"ShipToPhoneNumber":{"maxLength":32,"type":"string","nullable":true},"ShipToPremiseForUK":{"maxLength":256,"type":"string","nullable":true},"ShipToStreetForUK":{"maxLength":256,"type":"string","nullable":true},"BillToPremiseForUK":{"maxLength":256,"type":"string","nullable":true},"BillToStreetForUK":{"maxLength":256,"type":"string","nullable":true}},"additionalProperties":false,"description":""},"PaymentResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"As one would guess, this is \"true\" if the transaction was processed successfully, and \"false\" if the transaction was not processed successfully."},"Message":{"type":"string","description":"Payment Gateway response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Response from the processing bank.","nullable":true},"AuthCode":{"type":"string","description":"AuthCode from the processor.","nullable":true},"TransactionId":{"type":"string","description":"Payment Gateway TransactionId","nullable":true},"PaymentGuid":{"type":"string","description":"Payment API Payment GUID","format":"uuid"},"PaymentId":{"type":"integer","description":"Payment API Payment Id","format":"int32"},"ResponseCode":{"type":"string","description":"Response Code - Approved = 0, Not processed = -100 with more possible values - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"PaymentResult":{"$ref":"#/components/schemas/PaymentResult"},"ProcessStatus":{"$ref":"#/components/schemas/ProcessStatus"},"TotalAmount":{"type":"number","description":"The total amount processed toward the cardholder's account.","format":"double"},"TotalSurcharge":{"type":"number","description":"The total surcharge amount if available.","format":"double","nullable":true},"AVSStreetStatus":{"type":"string","description":"Address Verification Street Status if available.","nullable":true},"AVSZipStatus":{"type":"string","description":"Address Verification Zip Status if available.","nullable":true},"AVSResponse":{"type":"string","description":"Address Verification Response if available. AVS and CVV response values covered more here - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"CVVResponse":{"type":"string","description":"Card Verification Response if available. AVS and CVV response values covered more here - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"ExternalCardToken":{"type":"string","description":"ExternalCardToken if available to return - represents 3rd party gateway card token","nullable":true},"ExternalCheckToken":{"type":"string","description":"ExternalCheckToken if available to return - represents 3rd party gateway check token","nullable":true},"ExternalCustomerId":{"type":"string","description":"ExternalCustomerId if available to return - represents 3rd party gateway customer id tied to gateway token","nullable":true},"ExternalConstituentId":{"type":"string","description":"ExternalConstituentId if available to return - merchant-supplied constituent/donor id linked to this token","nullable":true},"TokenGuid":{"type":"string","description":"Payment API Token GUID if available to return","format":"uuid","nullable":true},"TransactionFees":{"type":"array","items":{"$ref":"#/components/schemas/FeeResponse"},"description":"Fee Response","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use","format":"uuid"},"ProcessorGuid":{"type":"string","description":"ProcessorGuid used","format":"uuid","nullable":true},"FirstName":{"type":"string","nullable":true},"LastName":{"type":"string","nullable":true},"EmailAddress":{"type":"string","nullable":true},"PostalCode":{"type":"string","nullable":true},"AddressLine1":{"type":"string","nullable":true},"City":{"type":"string","nullable":true},"ProvinceCode":{"type":"string","nullable":true},"CountryCode":{"type":"string","nullable":true},"CardNum":{"type":"string","description":"last 4 digits of card","nullable":true},"CardType":{"type":"string","description":"possible values if available: American Express, Mastercard, Visa, Discover, Diners Club, Undefined","nullable":true},"ExpMonth":{"type":"string","nullable":true},"ExpYear":{"type":"string","nullable":true},"Currency":{"type":"string","nullable":true},"PaymentMethodTypeId":{"type":"integer","description":"possible values if available:\r\nNone = 0,\r\nAmericanExpress = 1,\r\nMasterCard = 2,\r\nVisa = 3,\r\nDiscover = 4,\r\nDinersClub = 5,\r\nACH = 7,\r\nGOOGLEPAY = 8,\r\nAPPLEPAY = 9","format":"int32","nullable":true},"IsSurchargeEligible":{"type":"boolean","description":"Was card used Surcharge eligible","nullable":true},"CheckAccountNum":{"type":"string","description":"last 4 digits of check account","nullable":true},"TranId":{"type":"string","description":"unique tran id per Integration Source if available","nullable":true},"EpfSessionId":{"type":"string","description":"FrontStream unique Embedded Payment Form Session Id if available","nullable":true},"PaymentDate":{"type":"string","description":"Payment Date of transaction","format":"date-time"}},"additionalProperties":false,"description":"See more response code definitions here: https://developers.frontstream.com/welcome-to-our-payment-api/api-references/test-payment-api-features/response-codes"},"PaymentResult":{"enum":[1,2,3,4,5,6],"type":"integer","format":"int32"},"ProcessStatus":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12],"type":"integer","format":"int32"},"FeeResponse":{"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","nullable":true},"PaymentAmount":{"type":"number","description":"This is the amount charged to the donor. Will be equal to the sum of the Amount parameters if payFee=false, but if payFee=true, then this will be the amount that will be charged to the donor in order to have the net post-disbursement donation be equal to the Amount parameters.","format":"double","nullable":true},"CardFeeRate":{"type":"number","description":"example 2.5% - applied to EVERY donation. This is the FrontStream card processing fee. The percentage of the PaymentAmount that will be taken for credit card fees. Expressed as a human-readable percentage rather than a decimal value, it is intended to be able to be displayed directly on a page without needing to be converted.","format":"double","nullable":true},"CardFeeAmount":{"type":"number","description":"This is the amount that is owed to the gateway for the example 2.5% that FrontStream collects from the transaction.\r\n 2.5% of transaction amount if donor is not paying the fee, otherwise 2.5% of the transaction + card fee.","format":"double","nullable":true},"CardTypeFeeAmount":{"type":"number","description":"A per transaction fee configured by card type (VI, MC, DI, AMEX, etc.) per API Partner's Contract other wise 0 (zero)","format":"double","nullable":true},"TotalCommissionRate":{"type":"number","description":"The Total percentage of Commissions that FrontStream takes from a given transaction.\r\nThis rate = Partner CommissionRate + FS CommissionRate","format":"double","nullable":true},"TotalCommissionAmount":{"type":"number","description":"The product of the transaction times the Total commission rate.","format":"double","nullable":true},"PartnerCommissionRate":{"type":"number","description":"The Partner Commission percentage taken on behalf of the Partner from a given transaction.","format":"double","nullable":true},"PartnerCommissionAmount":{"type":"number","description":"The product of the transaction times the Partner commission rate.","format":"double","nullable":true},"FsCommissionRate":{"type":"number","description":"The FrontStream Commission percentage that FrontStream takes from a given transaction.","format":"double","nullable":true},"FsCommissionAmount":{"type":"number","description":"The product of the transaction times the FrontStream commission rate.","format":"double","nullable":true},"TotalFees":{"type":"number","description":"The sum of all fees applied to a transaction amount. (TotalCommission + CardFee + FlatFee + CardFeeOnFee)","format":"double","nullable":true},"MaxOverridePartnerCommissionRate":{"type":"number","description":"The derived minimum partner override rate and maximum partner override rate\r\n\r\nMaxOverridePartnerCommissionRate = TotalFees = (PartnerCommission rate) + (Card Fee Rate) + (Fs Commission Rate)\r\nMinOverridePartnerCommissionRate = (Card Fee rate) + (Fs Commission rate)","format":"double"},"MinOverridePartnerCommissionRate":{"type":"number","format":"double"},"PerTransFee":{"type":"number","description":"The flat amount that will be taken from the PaymentAmount for any Per-Transaction Fees as configured in your contract.","format":"double","nullable":true},"Tip":{"type":"number","description":"The flat amount that will be paid out to the API Partner if Donor decides to add a tip regardless of payFee true or false.","format":"double"},"CardFeeOnFeeAmount":{"type":"number","format":"double","nullable":true},"Tax":{"type":"number","format":"double","nullable":true},"AchFeeRate":{"type":"number","description":"The ACH processing fee rate applied to this transaction.","format":"double","nullable":true},"AchFeeAmount":{"type":"number","description":"The ACH processing fee amount for this transaction.","format":"double","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ## Make a payment by credit card or ACH check token > Request example: > \ > POST /api/paymentToken > \ > { > \ > "ProcessorGuid": "12345678-9012-3456-7890-dc84772c0032", > \ > "TokenGuid": "87654321-9012-3456-7890-123456789012", > \ > "Transactions": > \ > \[ > \ > { > \ > "TransactionSourceGroupId": "12", > \ > "Amount": "1.00", > \ > } > \ > ] > \ > } ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/paymentToken":{"post":{"tags":["Payments"],"summary":"Make a payment by credit card or ACH check token","description":" Request example:\r\n POST /api/paymentToken\r\n\t{\r\n \t\t\"ProcessorGuid\": \"12345678-9012-3456-7890-dc84772c0032\",\r\n \"TokenGuid\": \"87654321-9012-3456-7890-123456789012\",\r\n \"Transactions\":\r\n [\r\n {\r\n \"TransactionSourceGroupId\": \"12\",\r\n \"Amount\": \"1.00\", \r\n }\r\n ]\r\n\t}","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/PaymentTokenRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/PaymentTokenRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/PaymentTokenRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/PaymentTokenRequest"}}}},"responses":{"201":{"description":"Returns the newly created payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"If it fails to create a payment","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"PaymentTokenRequest":{"required":["Transactions"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"TokenGuid":{"type":"string","description":"optional if using ExternalCardToken or ExternalCheckToken instead of TokenGuid - Valid Token Guid from a Tokenized card through Payment API","nullable":true},"ExternalCardToken":{"maxLength":200,"type":"string","description":"internal use","nullable":true},"ExternalCheckToken":{"maxLength":200,"type":"string","description":"internal use","nullable":true},"TranId":{"maxLength":100,"type":"string","description":"optional (max: 100) - system unique id for Dup Checking per Integration Source transaction (where integration source has DupCheckEnabled) that will be checked against successfully processed prior TranIds for Duplicates","nullable":true},"EpfSessionId":{"type":"string","description":"internal use - FrontStream unique Embedded Payment Form Session Id if available","nullable":true},"BillingDescriptor":{"maxLength":22,"type":"string","description":"optional (max: 22) - descriptor to show on bank statement","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"client ip address (max: 40) where transaction originates","nullable":true},"ShippingFee":{"maxLength":7,"type":"string","description":"optional (max: 7) - fee for shipping that will be added to the total amount","nullable":true},"TaxableBenefit":{"maxLength":7,"type":"string","description":"optional (max: 7) - If part of the donation being passed in is taxable, include that amount here. No calculations are performed using this value, it is simply a placeholder to be used for your own reporting; all commission and credit card fees still apply as normal.","nullable":true},"Transactions":{"type":"array","items":{"$ref":"#/components/schemas/PaymentTransTypeRequest"},"description":"required - 1 to n transactions to break down transaction line items"},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) to override zip created during token creation - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000","nullable":true},"Street":{"maxLength":50,"type":"string","description":"optional (max: 50) to override street created during token creation","nullable":true},"City":{"maxLength":50,"type":"string","description":"optional (max: 50) to override city created during token creation","nullable":true},"State":{"maxLength":50,"type":"string","description":"optional (max: 50) to override state created during token creation","nullable":true},"Country":{"maxLength":2,"type":"string","description":"optional (max: 2) to override country created during token creation","nullable":true},"Currency":{"maxLength":3,"type":"string","description":"optional (max: 3) to override currency created during token creation","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - Donor Identifier per Product","nullable":true},"ExternalEventId":{"maxLength":10,"type":"string","description":"optional (max: 10) - Event Identifier per Product","nullable":true},"ExternalEventGuid":{"type":"string","description":"optional - Event Guid per Product","nullable":true},"ExternalEventName":{"maxLength":500,"type":"string","description":"optional (max: 500) - Event Name per Product","nullable":true},"AFShieldAdditional":{"$ref":"#/components/schemas/AFShieldPaymentRequest"},"Surcharge":{"maxLength":7,"type":"string","description":"optional (max: 7) - calculated surcharge amount","nullable":true}},"additionalProperties":false,"description":""},"PaymentTransTypeRequest":{"required":["Amount","TransactionSourceGroupId"],"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","description":"required - For Direct Merchant (For Profit) Api Partners should set to PaymentNoFee (12), other values are for Non Profit transactions - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;\r\n 13 - EventDonationFee;\r\n 14 - SponsorshipFee\r\n 15 - MembershipFee"},"Amount":{"maxLength":7,"type":"string","description":"required - Amount of line item without the fees included, Payment api will calculate fees for you"},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction. Indicates if the donor intends to cover the processing fees for the donation (primary used for Non Profit transactions like a donation)"},"CommissionRateOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - The percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract.","nullable":true},"CardProcessingFeeOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - Overrides the default percentage processing fee","nullable":true},"ExternalLineId":{"maxLength":100,"type":"string","description":"optional (max: 100) - use this to track individual line item IDs if necessary.","nullable":true},"Tip":{"maxLength":7,"type":"string","description":"optional (max: 7) - An amount taken up front for the API Partner if Donor decides to apply a tip. Added to the total amount to charge on the donor’s card . Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true},"Tax":{"maxLength":7,"type":"string","description":"optional (max: 7) - A tax amount taken up front. Added to the total amount to charge on the donor’s card. Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true}},"additionalProperties":false,"description":""},"AFShieldPaymentRequest":{"type":"object","properties":{"ProductDescription":{"maxLength":256,"type":"string","nullable":true},"ProductItem":{"maxLength":256,"type":"string","nullable":true},"ProductType":{"maxLength":256,"type":"string","nullable":true},"ProductQuantity":{"maxLength":3,"type":"string","nullable":true},"SessionId":{"maxLength":32,"type":"string","nullable":true},"BillToPhoneNumber":{"maxLength":32,"type":"string","nullable":true},"ShippingAddressStreet1":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressStreet2":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressCountry":{"maxLength":2,"type":"string","nullable":true},"ShippingAddressCity":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressEmail":{"maxLength":64,"type":"string","format":"email","nullable":true},"ShippingAddressName":{"maxLength":64,"type":"string","nullable":true},"ShippingAddressZip":{"maxLength":10,"type":"string","nullable":true},"ShippingAddressState":{"maxLength":50,"type":"string","nullable":true},"ShipToPhoneNumber":{"maxLength":32,"type":"string","nullable":true},"ShipToPremiseForUK":{"maxLength":256,"type":"string","nullable":true},"ShipToStreetForUK":{"maxLength":256,"type":"string","nullable":true},"BillToPremiseForUK":{"maxLength":256,"type":"string","nullable":true},"BillToStreetForUK":{"maxLength":256,"type":"string","nullable":true}},"additionalProperties":false,"description":""},"PaymentResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"As one would guess, this is \"true\" if the transaction was processed successfully, and \"false\" if the transaction was not processed successfully."},"Message":{"type":"string","description":"Payment Gateway response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Response from the processing bank.","nullable":true},"AuthCode":{"type":"string","description":"AuthCode from the processor.","nullable":true},"TransactionId":{"type":"string","description":"Payment Gateway TransactionId","nullable":true},"PaymentGuid":{"type":"string","description":"Payment API Payment GUID","format":"uuid"},"PaymentId":{"type":"integer","description":"Payment API Payment Id","format":"int32"},"ResponseCode":{"type":"string","description":"Response Code - Approved = 0, Not processed = -100 with more possible values - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"PaymentResult":{"$ref":"#/components/schemas/PaymentResult"},"ProcessStatus":{"$ref":"#/components/schemas/ProcessStatus"},"TotalAmount":{"type":"number","description":"The total amount processed toward the cardholder's account.","format":"double"},"TotalSurcharge":{"type":"number","description":"The total surcharge amount if available.","format":"double","nullable":true},"AVSStreetStatus":{"type":"string","description":"Address Verification Street Status if available.","nullable":true},"AVSZipStatus":{"type":"string","description":"Address Verification Zip Status if available.","nullable":true},"AVSResponse":{"type":"string","description":"Address Verification Response if available. AVS and CVV response values covered more here - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"CVVResponse":{"type":"string","description":"Card Verification Response if available. AVS and CVV response values covered more here - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"ExternalCardToken":{"type":"string","description":"ExternalCardToken if available to return - represents 3rd party gateway card token","nullable":true},"ExternalCheckToken":{"type":"string","description":"ExternalCheckToken if available to return - represents 3rd party gateway check token","nullable":true},"ExternalCustomerId":{"type":"string","description":"ExternalCustomerId if available to return - represents 3rd party gateway customer id tied to gateway token","nullable":true},"ExternalConstituentId":{"type":"string","description":"ExternalConstituentId if available to return - merchant-supplied constituent/donor id linked to this token","nullable":true},"TokenGuid":{"type":"string","description":"Payment API Token GUID if available to return","format":"uuid","nullable":true},"TransactionFees":{"type":"array","items":{"$ref":"#/components/schemas/FeeResponse"},"description":"Fee Response","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use","format":"uuid"},"ProcessorGuid":{"type":"string","description":"ProcessorGuid used","format":"uuid","nullable":true},"FirstName":{"type":"string","nullable":true},"LastName":{"type":"string","nullable":true},"EmailAddress":{"type":"string","nullable":true},"PostalCode":{"type":"string","nullable":true},"AddressLine1":{"type":"string","nullable":true},"City":{"type":"string","nullable":true},"ProvinceCode":{"type":"string","nullable":true},"CountryCode":{"type":"string","nullable":true},"CardNum":{"type":"string","description":"last 4 digits of card","nullable":true},"CardType":{"type":"string","description":"possible values if available: American Express, Mastercard, Visa, Discover, Diners Club, Undefined","nullable":true},"ExpMonth":{"type":"string","nullable":true},"ExpYear":{"type":"string","nullable":true},"Currency":{"type":"string","nullable":true},"PaymentMethodTypeId":{"type":"integer","description":"possible values if available:\r\nNone = 0,\r\nAmericanExpress = 1,\r\nMasterCard = 2,\r\nVisa = 3,\r\nDiscover = 4,\r\nDinersClub = 5,\r\nACH = 7,\r\nGOOGLEPAY = 8,\r\nAPPLEPAY = 9","format":"int32","nullable":true},"IsSurchargeEligible":{"type":"boolean","description":"Was card used Surcharge eligible","nullable":true},"CheckAccountNum":{"type":"string","description":"last 4 digits of check account","nullable":true},"TranId":{"type":"string","description":"unique tran id per Integration Source if available","nullable":true},"EpfSessionId":{"type":"string","description":"FrontStream unique Embedded Payment Form Session Id if available","nullable":true},"PaymentDate":{"type":"string","description":"Payment Date of transaction","format":"date-time"}},"additionalProperties":false,"description":"See more response code definitions here: https://developers.frontstream.com/welcome-to-our-payment-api/api-references/test-payment-api-features/response-codes"},"PaymentResult":{"enum":[1,2,3,4,5,6],"type":"integer","format":"int32"},"ProcessStatus":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12],"type":"integer","format":"int32"},"FeeResponse":{"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","nullable":true},"PaymentAmount":{"type":"number","description":"This is the amount charged to the donor. Will be equal to the sum of the Amount parameters if payFee=false, but if payFee=true, then this will be the amount that will be charged to the donor in order to have the net post-disbursement donation be equal to the Amount parameters.","format":"double","nullable":true},"CardFeeRate":{"type":"number","description":"example 2.5% - applied to EVERY donation. This is the FrontStream card processing fee. The percentage of the PaymentAmount that will be taken for credit card fees. Expressed as a human-readable percentage rather than a decimal value, it is intended to be able to be displayed directly on a page without needing to be converted.","format":"double","nullable":true},"CardFeeAmount":{"type":"number","description":"This is the amount that is owed to the gateway for the example 2.5% that FrontStream collects from the transaction.\r\n 2.5% of transaction amount if donor is not paying the fee, otherwise 2.5% of the transaction + card fee.","format":"double","nullable":true},"CardTypeFeeAmount":{"type":"number","description":"A per transaction fee configured by card type (VI, MC, DI, AMEX, etc.) per API Partner's Contract other wise 0 (zero)","format":"double","nullable":true},"TotalCommissionRate":{"type":"number","description":"The Total percentage of Commissions that FrontStream takes from a given transaction.\r\nThis rate = Partner CommissionRate + FS CommissionRate","format":"double","nullable":true},"TotalCommissionAmount":{"type":"number","description":"The product of the transaction times the Total commission rate.","format":"double","nullable":true},"PartnerCommissionRate":{"type":"number","description":"The Partner Commission percentage taken on behalf of the Partner from a given transaction.","format":"double","nullable":true},"PartnerCommissionAmount":{"type":"number","description":"The product of the transaction times the Partner commission rate.","format":"double","nullable":true},"FsCommissionRate":{"type":"number","description":"The FrontStream Commission percentage that FrontStream takes from a given transaction.","format":"double","nullable":true},"FsCommissionAmount":{"type":"number","description":"The product of the transaction times the FrontStream commission rate.","format":"double","nullable":true},"TotalFees":{"type":"number","description":"The sum of all fees applied to a transaction amount. (TotalCommission + CardFee + FlatFee + CardFeeOnFee)","format":"double","nullable":true},"MaxOverridePartnerCommissionRate":{"type":"number","description":"The derived minimum partner override rate and maximum partner override rate\r\n\r\nMaxOverridePartnerCommissionRate = TotalFees = (PartnerCommission rate) + (Card Fee Rate) + (Fs Commission Rate)\r\nMinOverridePartnerCommissionRate = (Card Fee rate) + (Fs Commission rate)","format":"double"},"MinOverridePartnerCommissionRate":{"type":"number","format":"double"},"PerTransFee":{"type":"number","description":"The flat amount that will be taken from the PaymentAmount for any Per-Transaction Fees as configured in your contract.","format":"double","nullable":true},"Tip":{"type":"number","description":"The flat amount that will be paid out to the API Partner if Donor decides to add a tip regardless of payFee true or false.","format":"double"},"CardFeeOnFeeAmount":{"type":"number","format":"double","nullable":true},"Tax":{"type":"number","format":"double","nullable":true},"AchFeeRate":{"type":"number","description":"The ACH processing fee rate applied to this transaction.","format":"double","nullable":true},"AchFeeAmount":{"type":"number","description":"The ACH processing fee amount for this transaction.","format":"double","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ## POST /api/verifyCard > Verify a credit card ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/verifyCard":{"post":{"tags":["Payments"],"summary":"Verify a credit card","description":"","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/VerifyCardRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/VerifyCardRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/VerifyCardRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/VerifyCardRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyCardResponse"}}}},"400":{"description":"Failure","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"VerifyCardRequest":{"required":["CardNum","City","Country","Email","ExpMonth","ExpYear","IpAddress","NameOnCard","Street"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"required if API Partner - Identifies Processor being used by an API Partner","nullable":true},"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"CardNum":{"maxLength":30,"type":"string","description":"required - Valid Credit card number"},"ExpMonth":{"maxLength":2,"minLength":2,"type":"string","description":"required - example: \"01\" for January"},"ExpYear":{"maxLength":2,"minLength":2,"type":"string","description":"required - example: \"29\" for 2029"},"CVNum":{"maxLength":4,"type":"string","description":"optional (max: 4) - valid CVV - please provide for CVV checks","nullable":true},"NameOnCard":{"maxLength":25,"type":"string","description":"required - Name on Card"},"Email":{"maxLength":100,"type":"string","description":"required - valid contact email","format":"email"},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - please provide for best interchange and avs checks - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000","nullable":true},"Street":{"maxLength":50,"type":"string","description":"required - please provide for best interchange and avs checks"},"City":{"maxLength":50,"type":"string","description":"required - please provide for best interchange and avs checks"},"State":{"maxLength":50,"type":"string","description":"optional - 2 char US state code, 3 char may be used for other non-US","nullable":true},"Country":{"maxLength":2,"type":"string","description":"required - 2 char country code"},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing First Name","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing Last Name","nullable":true},"Currency":{"maxLength":3,"type":"string","description":"optional - 3 char currency code - Example for US - \"USD\", for CA - \"CAD\"","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"required - client ip address where transaction originates"},"AFShieldAdditional":{"$ref":"#/components/schemas/AFShieldPaymentRequest"}},"additionalProperties":false,"description":""},"AFShieldPaymentRequest":{"type":"object","properties":{"ProductDescription":{"maxLength":256,"type":"string","nullable":true},"ProductItem":{"maxLength":256,"type":"string","nullable":true},"ProductType":{"maxLength":256,"type":"string","nullable":true},"ProductQuantity":{"maxLength":3,"type":"string","nullable":true},"SessionId":{"maxLength":32,"type":"string","nullable":true},"BillToPhoneNumber":{"maxLength":32,"type":"string","nullable":true},"ShippingAddressStreet1":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressStreet2":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressCountry":{"maxLength":2,"type":"string","nullable":true},"ShippingAddressCity":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressEmail":{"maxLength":64,"type":"string","format":"email","nullable":true},"ShippingAddressName":{"maxLength":64,"type":"string","nullable":true},"ShippingAddressZip":{"maxLength":10,"type":"string","nullable":true},"ShippingAddressState":{"maxLength":50,"type":"string","nullable":true},"ShipToPhoneNumber":{"maxLength":32,"type":"string","nullable":true},"ShipToPremiseForUK":{"maxLength":256,"type":"string","nullable":true},"ShipToStreetForUK":{"maxLength":256,"type":"string","nullable":true},"BillToPremiseForUK":{"maxLength":256,"type":"string","nullable":true},"BillToStreetForUK":{"maxLength":256,"type":"string","nullable":true}},"additionalProperties":false,"description":""},"VerifyCardResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"As one would guess, this is \"true\" if the transaction was processed successfully, and \"false\" if the transaction was not processed successfully."},"Message":{"type":"string","description":"Payment Gateway response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Response from the processing bank.","nullable":true},"ResponseCode":{"type":"string","description":"Response Code - Approved = 0, Not processed = -100 with more possible values - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"AVSStreetStatus":{"type":"string","description":"Address Verification Street Status","nullable":true},"AVSZipStatus":{"type":"string","description":"Address Verification Zip Status","nullable":true},"AVSResponse":{"type":"string","description":"Address Verification Response","nullable":true},"CVVResponse":{"type":"string","description":"Card Verification Response","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ## POST /api/paymentAch > Make an ach payment ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/paymentAch":{"post":{"tags":["Payments"],"summary":"Make an ach payment","description":"","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/PaymentAchRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/PaymentAchRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/PaymentAchRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/PaymentAchRequest"}}}},"responses":{"201":{"description":"Returns the newly created payment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaymentResponse"}}}},"400":{"description":"If it fails to create a payment","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"PaymentAchRequest":{"required":["CheckAccountNumber","CheckAccountTypeId","CheckRoutingNumber","CheckTypeId","Email","IpAddress","NameOnCheck","State","Transactions"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"MKey":{"maxLength":500,"type":"string","description":"internal use - Used by FrontStream only","nullable":true},"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"CheckRoutingNumber":{"maxLength":9,"type":"string","description":"required - Valid Check Bank Routing Number - formats -\r\nUS: Enter 9-digits,\r\nCA: Enter 9-digits (Format: 0YYYXXXXX: A mandatory leading zero. YYY: The 3-digit institution number. XXXXX: The 5-digit transit number),\r\nAU: Enter 6-digits - BSB Number (Bank State Branch) without hyphen"},"CheckAccountNumber":{"maxLength":20,"type":"string","description":"required - Valid Check Account Number - formats -\r\nUS: Enter 8-12 digits,\r\nCA: Enter 7-12 digits,\r\nAU: Enter 3-9 digits"},"CheckNumber":{"maxLength":10,"type":"string","description":"optional (max: 10) - Valid Check Number","nullable":true},"CheckAccountTypeId":{"type":"string","description":"required for Check ACH transactions - possible values -\r\n 1 - Checking,\r\n 2 - Savings"},"CheckTypeId":{"type":"string","description":"required for Check ACH transactions - possible values -\r\n 1 - Personal,\r\n 2 - Corporate,\r\n 3 - Government"},"NameOnCheck":{"maxLength":25,"type":"string","description":"required - Name on ACH Check Account"},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000","nullable":true},"Street":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing street","nullable":true},"Email":{"maxLength":100,"type":"string","description":"required - valid contact email","format":"email"},"City":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing city","nullable":true},"State":{"maxLength":50,"type":"string","description":"required - 2 char US state code, 3 char may be used for other non-US"},"Country":{"maxLength":2,"type":"string","description":"optional - 2 char country code","nullable":true},"Currency":{"maxLength":3,"type":"string","description":"optional - 3 char currency code - Example for US - \"USD\", for CA - \"CAD\"","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - Donor Identifier per Product","nullable":true},"ExternalCustomerId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ArgoFire Gateway CustomerKey for pre-existing ArgoFire customers without a Payment API token record","nullable":true},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing First Name","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing Last Name","nullable":true},"BillingDescriptor":{"maxLength":22,"type":"string","description":"optional (max: 22) - descriptor to show on bank statement","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"required - client ip address where transaction originates"},"ExternalEventId":{"maxLength":10,"type":"string","description":"optional (max: 10) - Event Identifier per Product","nullable":true},"ExternalEventGuid":{"type":"string","description":"optional - Event Guid per Product","nullable":true},"ExternalEventName":{"maxLength":500,"type":"string","description":"optional (max: 500) - Event Name per Product","nullable":true},"ShippingFee":{"maxLength":7,"type":"string","description":"optional (max: 7) - fee for shipping that will be added to the total amount","nullable":true},"TaxableBenefit":{"maxLength":7,"type":"string","description":"optional (max: 7) - If part of the donation being passed in is taxable, include that amount here. No calculations are performed using this value, it is simply a placeholder to be used for your own reporting; all commission and credit card fees still apply as normal.","nullable":true},"TranId":{"maxLength":100,"type":"string","description":"optional (max: 100) - system unique id for Dup Checking per Integration Source transaction (where integration source has DupCheckEnabled) that will be checked against successfully processed prior TranIds for Duplicates","nullable":true},"EpfSessionId":{"type":"string","description":"internal use - FrontStream unique Embedded Payment Form Session Id if available","nullable":true},"Transactions":{"type":"array","items":{"$ref":"#/components/schemas/PaymentTransTypeRequest"},"description":"required - 1 to n transactions to break down transaction line items"},"PaymentMethodTypeId":{"type":"string","description":"optional - if used please set to 7 for ACH or will be set internally","nullable":true},"Tokenize":{"type":"boolean","description":"optional - set to true to tokenize check at time of purchase","nullable":true}},"additionalProperties":false},"PaymentTransTypeRequest":{"required":["Amount","TransactionSourceGroupId"],"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","description":"required - For Direct Merchant (For Profit) Api Partners should set to PaymentNoFee (12), other values are for Non Profit transactions - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;\r\n 13 - EventDonationFee;\r\n 14 - SponsorshipFee\r\n 15 - MembershipFee"},"Amount":{"maxLength":7,"type":"string","description":"required - Amount of line item without the fees included, Payment api will calculate fees for you"},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction. Indicates if the donor intends to cover the processing fees for the donation (primary used for Non Profit transactions like a donation)"},"CommissionRateOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - The percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract.","nullable":true},"CardProcessingFeeOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - Overrides the default percentage processing fee","nullable":true},"ExternalLineId":{"maxLength":100,"type":"string","description":"optional (max: 100) - use this to track individual line item IDs if necessary.","nullable":true},"Tip":{"maxLength":7,"type":"string","description":"optional (max: 7) - An amount taken up front for the API Partner if Donor decides to apply a tip. Added to the total amount to charge on the donor’s card . Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true},"Tax":{"maxLength":7,"type":"string","description":"optional (max: 7) - A tax amount taken up front. Added to the total amount to charge on the donor’s card. Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true}},"additionalProperties":false,"description":""},"PaymentResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"As one would guess, this is \"true\" if the transaction was processed successfully, and \"false\" if the transaction was not processed successfully."},"Message":{"type":"string","description":"Payment Gateway response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Response from the processing bank.","nullable":true},"AuthCode":{"type":"string","description":"AuthCode from the processor.","nullable":true},"TransactionId":{"type":"string","description":"Payment Gateway TransactionId","nullable":true},"PaymentGuid":{"type":"string","description":"Payment API Payment GUID","format":"uuid"},"PaymentId":{"type":"integer","description":"Payment API Payment Id","format":"int32"},"ResponseCode":{"type":"string","description":"Response Code - Approved = 0, Not processed = -100 with more possible values - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"PaymentResult":{"$ref":"#/components/schemas/PaymentResult"},"ProcessStatus":{"$ref":"#/components/schemas/ProcessStatus"},"TotalAmount":{"type":"number","description":"The total amount processed toward the cardholder's account.","format":"double"},"TotalSurcharge":{"type":"number","description":"The total surcharge amount if available.","format":"double","nullable":true},"AVSStreetStatus":{"type":"string","description":"Address Verification Street Status if available.","nullable":true},"AVSZipStatus":{"type":"string","description":"Address Verification Zip Status if available.","nullable":true},"AVSResponse":{"type":"string","description":"Address Verification Response if available. AVS and CVV response values covered more here - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"CVVResponse":{"type":"string","description":"Card Verification Response if available. AVS and CVV response values covered more here - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"ExternalCardToken":{"type":"string","description":"ExternalCardToken if available to return - represents 3rd party gateway card token","nullable":true},"ExternalCheckToken":{"type":"string","description":"ExternalCheckToken if available to return - represents 3rd party gateway check token","nullable":true},"ExternalCustomerId":{"type":"string","description":"ExternalCustomerId if available to return - represents 3rd party gateway customer id tied to gateway token","nullable":true},"ExternalConstituentId":{"type":"string","description":"ExternalConstituentId if available to return - merchant-supplied constituent/donor id linked to this token","nullable":true},"TokenGuid":{"type":"string","description":"Payment API Token GUID if available to return","format":"uuid","nullable":true},"TransactionFees":{"type":"array","items":{"$ref":"#/components/schemas/FeeResponse"},"description":"Fee Response","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use","format":"uuid"},"ProcessorGuid":{"type":"string","description":"ProcessorGuid used","format":"uuid","nullable":true},"FirstName":{"type":"string","nullable":true},"LastName":{"type":"string","nullable":true},"EmailAddress":{"type":"string","nullable":true},"PostalCode":{"type":"string","nullable":true},"AddressLine1":{"type":"string","nullable":true},"City":{"type":"string","nullable":true},"ProvinceCode":{"type":"string","nullable":true},"CountryCode":{"type":"string","nullable":true},"CardNum":{"type":"string","description":"last 4 digits of card","nullable":true},"CardType":{"type":"string","description":"possible values if available: American Express, Mastercard, Visa, Discover, Diners Club, Undefined","nullable":true},"ExpMonth":{"type":"string","nullable":true},"ExpYear":{"type":"string","nullable":true},"Currency":{"type":"string","nullable":true},"PaymentMethodTypeId":{"type":"integer","description":"possible values if available:\r\nNone = 0,\r\nAmericanExpress = 1,\r\nMasterCard = 2,\r\nVisa = 3,\r\nDiscover = 4,\r\nDinersClub = 5,\r\nACH = 7,\r\nGOOGLEPAY = 8,\r\nAPPLEPAY = 9","format":"int32","nullable":true},"IsSurchargeEligible":{"type":"boolean","description":"Was card used Surcharge eligible","nullable":true},"CheckAccountNum":{"type":"string","description":"last 4 digits of check account","nullable":true},"TranId":{"type":"string","description":"unique tran id per Integration Source if available","nullable":true},"EpfSessionId":{"type":"string","description":"FrontStream unique Embedded Payment Form Session Id if available","nullable":true},"PaymentDate":{"type":"string","description":"Payment Date of transaction","format":"date-time"}},"additionalProperties":false,"description":"See more response code definitions here: https://developers.frontstream.com/welcome-to-our-payment-api/api-references/test-payment-api-features/response-codes"},"PaymentResult":{"enum":[1,2,3,4,5,6],"type":"integer","format":"int32"},"ProcessStatus":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12],"type":"integer","format":"int32"},"FeeResponse":{"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","nullable":true},"PaymentAmount":{"type":"number","description":"This is the amount charged to the donor. Will be equal to the sum of the Amount parameters if payFee=false, but if payFee=true, then this will be the amount that will be charged to the donor in order to have the net post-disbursement donation be equal to the Amount parameters.","format":"double","nullable":true},"CardFeeRate":{"type":"number","description":"example 2.5% - applied to EVERY donation. This is the FrontStream card processing fee. The percentage of the PaymentAmount that will be taken for credit card fees. Expressed as a human-readable percentage rather than a decimal value, it is intended to be able to be displayed directly on a page without needing to be converted.","format":"double","nullable":true},"CardFeeAmount":{"type":"number","description":"This is the amount that is owed to the gateway for the example 2.5% that FrontStream collects from the transaction.\r\n 2.5% of transaction amount if donor is not paying the fee, otherwise 2.5% of the transaction + card fee.","format":"double","nullable":true},"CardTypeFeeAmount":{"type":"number","description":"A per transaction fee configured by card type (VI, MC, DI, AMEX, etc.) per API Partner's Contract other wise 0 (zero)","format":"double","nullable":true},"TotalCommissionRate":{"type":"number","description":"The Total percentage of Commissions that FrontStream takes from a given transaction.\r\nThis rate = Partner CommissionRate + FS CommissionRate","format":"double","nullable":true},"TotalCommissionAmount":{"type":"number","description":"The product of the transaction times the Total commission rate.","format":"double","nullable":true},"PartnerCommissionRate":{"type":"number","description":"The Partner Commission percentage taken on behalf of the Partner from a given transaction.","format":"double","nullable":true},"PartnerCommissionAmount":{"type":"number","description":"The product of the transaction times the Partner commission rate.","format":"double","nullable":true},"FsCommissionRate":{"type":"number","description":"The FrontStream Commission percentage that FrontStream takes from a given transaction.","format":"double","nullable":true},"FsCommissionAmount":{"type":"number","description":"The product of the transaction times the FrontStream commission rate.","format":"double","nullable":true},"TotalFees":{"type":"number","description":"The sum of all fees applied to a transaction amount. (TotalCommission + CardFee + FlatFee + CardFeeOnFee)","format":"double","nullable":true},"MaxOverridePartnerCommissionRate":{"type":"number","description":"The derived minimum partner override rate and maximum partner override rate\r\n\r\nMaxOverridePartnerCommissionRate = TotalFees = (PartnerCommission rate) + (Card Fee Rate) + (Fs Commission Rate)\r\nMinOverridePartnerCommissionRate = (Card Fee rate) + (Fs Commission rate)","format":"double"},"MinOverridePartnerCommissionRate":{"type":"number","format":"double"},"PerTransFee":{"type":"number","description":"The flat amount that will be taken from the PaymentAmount for any Per-Transaction Fees as configured in your contract.","format":"double","nullable":true},"Tip":{"type":"number","description":"The flat amount that will be paid out to the API Partner if Donor decides to add a tip regardless of payFee true or false.","format":"double"},"CardFeeOnFeeAmount":{"type":"number","format":"double","nullable":true},"Tax":{"type":"number","format":"double","nullable":true},"AchFeeRate":{"type":"number","description":"The ACH processing fee rate applied to this transaction.","format":"double","nullable":true},"AchFeeAmount":{"type":"number","description":"The ACH processing fee amount for this transaction.","format":"double","nullable":true}},"additionalProperties":false,"description":""},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` # Returns ## POST /api/refund > Make a refund ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/refund":{"post":{"tags":["Returns"],"summary":"Make a refund","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/RefundRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/RefundRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/RefundRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/RefundRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RefundResponse"}}}},"400":{"description":"Failure","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"RefundRequest":{"required":["Reason"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"PaymentGuid":{"type":"string","description":"optional if not using PaymentExternalId - Payment API PaymentGuid to be refunded","nullable":true},"PaymentExternalId":{"maxLength":200,"type":"string","description":"optional (max: 200) if not using PaymentGuid - 3rd Party Payment External Id to be refunded","nullable":true},"Reason":{"maxLength":500,"type":"string","description":"required - reason for refund request"}},"additionalProperties":false,"description":""},"RefundResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"\"true\" if the transaction was processed successfully, and \"false\" if the transaction was not processed successfully."},"Message":{"type":"string","nullable":true},"ProcessorMessage":{"type":"string","nullable":true},"TransactionId":{"type":"string","nullable":true},"OriginalTransactionId":{"type":"string","nullable":true},"PaymentGuid":{"type":"string","format":"uuid"},"PaymentId":{"type":"integer","format":"int32"},"ResponseCode":{"type":"string","nullable":true},"PaymentResult":{"$ref":"#/components/schemas/PaymentResult"},"ProcessStatus":{"$ref":"#/components/schemas/ProcessStatus"}},"additionalProperties":false,"description":""},"PaymentResult":{"enum":[1,2,3,4,5,6],"type":"integer","format":"int32"},"ProcessStatus":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12],"type":"integer","format":"int32"},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ## POST /api/void > Make a void ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/void":{"post":{"tags":["Returns"],"summary":"Make a void","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/VoidRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/VoidRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/VoidRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/VoidRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VoidResponse"}}}},"400":{"description":"Failure","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"VoidRequest":{"required":["Reason"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"PaymentGuid":{"type":"string","description":"optional - if not using PaymentExternalId - Payment API PaymentGuid to be refunded","nullable":true},"PaymentExternalId":{"maxLength":200,"type":"string","description":"optional (max: 200) - if not using PaymentGuid - 3rd Party Payment External Id to be refunded","nullable":true},"Reason":{"maxLength":500,"type":"string","description":"required - reason for void request"}},"additionalProperties":false,"description":""},"VoidResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"\"true\" if the transaction was processed successfully, and \"false\" if the transaction was not processed successfully."},"Message":{"type":"string","nullable":true},"ProcessorMessage":{"type":"string","nullable":true},"TransactionId":{"type":"string","nullable":true},"OriginalTransactionId":{"type":"string","nullable":true},"PaymentGuid":{"type":"string","format":"uuid"},"PaymentId":{"type":"integer","format":"int32"},"ResponseCode":{"type":"string","nullable":true},"PaymentResult":{"$ref":"#/components/schemas/PaymentResult"},"ProcessStatus":{"$ref":"#/components/schemas/ProcessStatus"}},"additionalProperties":false,"description":""},"PaymentResult":{"enum":[1,2,3,4,5,6],"type":"integer","format":"int32"},"ProcessStatus":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12],"type":"integer","format":"int32"},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` # Reports ## Generate Organization Transactions Report by valid organizationGuid > Sample request to get transactions report filters by PaymentDate after (operation 7 = After) > \ > January 1st 2026 (2026-01-01) sorted by PaymentDate column desc, returning page index 1 > \ > and page size 1000 records. > \\ > > \ > Please see Filters and Operation parameters defined here for requests: > \\ > > \ > POST /api/organizationTransactionsReport?organizationGuid=87654321-9012-3456-7890-123456789012 > \ > { > \ > "Filters": \[ > \ > { > \ > "Name": "PaymentDate", > \ > "Operation": 7, > \ > "Values": \[ > \ > "2026-01-01" > \ > ] > \ > } > \ > ], > \ > "SortColumns": \[ > \ > { > \ > "Name": "PaymentDate", > \ > "Descending": true, > \ > "Order": 0 > \ > } > \ > ], > \ > "PageSize": 1000, > \ > "PageIndex": 1 > \ > } ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/organizationTransactionsReport":{"post":{"tags":["Reports"],"summary":"Generate Organization Transactions Report by valid organizationGuid","description":" Sample request to get transactions report filters by PaymentDate after (operation 7 = After)\r\n January 1st 2026 (2026-01-01) sorted by PaymentDate column desc, returning page index 1\r\n and page size 1000 records.\r\n\r\n Please see Filters and Operation parameters defined here for requests: https://developers.frontstream.com/welcome-to-our-payment-api/api-references/retrieve-transactions-report#body-parameter-definitions\r\n\r\n POST /api/organizationTransactionsReport?organizationGuid=87654321-9012-3456-7890-123456789012\r\n\t\t{\r\n \t\t\"Filters\": [\r\n \t\t{\r\n \t\t\"Name\": \"PaymentDate\",\r\n \t\t\"Operation\": 7,\r\n \t\t\"Values\": [\r\n \t\t \"2026-01-01\"\r\n \t\t]\r\n \t\t}\r\n \t\t],\r\n \t\t\"SortColumns\": [\r\n \t\t{\r\n \t\t\"Name\": \"PaymentDate\",\r\n \t\t\"Descending\": true,\r\n \t\t\"Order\": 0\r\n \t\t}\r\n \t\t],\r\n \t\t\"PageSize\": 1000,\r\n \t\t\"PageIndex\": 1\r\n\t\t}","parameters":[{"name":"organizationGuid","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/PaymentReportRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/PaymentReportRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/PaymentReportRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/PaymentReportRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionReportDetailPagedResults"}}}},"400":{"description":"Failure","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"PaymentReportRequest":{"type":"object","properties":{"Filters":{"type":"array","items":{"$ref":"#/components/schemas/SelectedConstraintDto"},"description":"Report Filters","nullable":true},"SortColumns":{"type":"array","items":{"$ref":"#/components/schemas/SortColumnDto"},"description":"Sort Columns","nullable":true},"PageSize":{"type":"integer","description":"How many records to return per page.","format":"int32"},"PageIndex":{"type":"integer","description":"Which page of results to return. Starts at 1 (0 will also return the first page)","format":"int32"}},"additionalProperties":false,"description":""},"SelectedConstraintDto":{"type":"object","properties":{"Name":{"type":"string","nullable":true},"Operation":{"$ref":"#/components/schemas/ConstraintOperation"},"Values":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false},"ConstraintOperation":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23],"type":"integer","format":"int32"},"SortColumnDto":{"type":"object","properties":{"Name":{"type":"string","nullable":true},"Descending":{"type":"boolean"},"Order":{"type":"integer","format":"int32"}},"additionalProperties":false},"TransactionReportDetailPagedResults":{"type":"object","properties":{"CurrentPage":{"type":"integer","format":"int32"},"PageSize":{"type":"integer","format":"int32"},"Results":{"type":"array","items":{"$ref":"#/components/schemas/TransactionReportDetail"},"nullable":true},"TotalPages":{"type":"integer","format":"int32"},"TotalRows":{"type":"integer","format":"int32"}},"additionalProperties":false},"TransactionReportDetail":{"type":"object","properties":{"PaymentDate":{"type":"string","description":"Payment Date of transaction","format":"date-time"},"PaymentGuid":{"type":"string","description":"Payment API Payment GUID","format":"uuid"},"PaymentId":{"type":"integer","description":"Payment API Payment Id","format":"int32"},"PaymentExternalId":{"type":"string","description":"Payment Gateway TransactionId - is the TransactionId of a Payment Response object","nullable":true},"OriginalExternalID":{"type":"string","description":"Original Payment Gateway TransactionId - is the Original TransactionId of a Payment Response object","nullable":true},"ProcessStatus":{"$ref":"#/components/schemas/ProcessStatus"},"ProcessStatusValue":{"type":"string","description":"Process Status value - possible values: NotProcessed = 1 \"Not Processed\", Authorized = 2 \"Awaiting Authorization\", Settled = 4 \"Authorized\", Rejected = 5 \"Rejected\", RefundRequired = 6 \"Refund Required\", AwaitingRefund = 7 \"Awaiting Refund\", Refunded = 8 \"Refunded\", Cancelled = 9 \"Cancelled\", Chargeback = 10 \"Chargeback\", RefundRejected = 11 \"Refund Rejected\"","nullable":true},"PaymentResult":{"$ref":"#/components/schemas/PaymentResult"},"PaymentResultValue":{"type":"string","description":"Payment Result value - possible values: \"Pending\" = 1, \"Processing\" = 2, \"Successful\" = 3, \"Failed\" = 4, \"Refunded\" = 5, \"Cancelled\" = 6","nullable":true},"ExternalConstituentId":{"type":"string","description":"Donor Identifier","nullable":true},"FirstName":{"type":"string","description":"billing First Name","nullable":true},"LastName":{"type":"string","description":"billing Last Name","nullable":true},"Email":{"type":"string","description":"contact email","nullable":true},"CardHolderName":{"type":"string","description":"Name on Card","nullable":true},"CCLastDigits":{"type":"string","description":"if available - last 4 digits of card","nullable":true},"ExpirationDate":{"type":"string","description":"MM/YY format","nullable":true},"CCType":{"type":"string","description":"possible values if available: \"American Express\", \"Mastercard\", \"Visa\", \"Discover\", \"Diners Club\", Undefined","nullable":true},"CoverTheFee":{"type":"string","description":"YES/NO - did donor Cover the Fees on Donation.","nullable":true},"DonationAmount":{"type":"number","description":"The total donation amount requested.","format":"double"},"CoverTheFeeAmount":{"type":"number","description":"The total donation amount requested.","format":"double"},"TransactionAmount":{"type":"number","description":"The total transaction amount processed toward the cardholder's account.","format":"double"},"ServiceFees":{"type":"number","description":"The calculated total fees amount of the list of transaction lines.","format":"double"},"PerformanceFees":{"type":"number","description":"The sum of CommissionAmount across all transaction lines.","format":"double"},"ProcessingFees":{"type":"number","description":"The sum of CardFeeAmount, PerTransFee, and CardFeeOnFeeAmount across all transaction lines.","format":"double"},"AmountPaid":{"type":"number","description":"The total transaction amount minus processing Fees","format":"double"},"Taxes":{"type":"number","description":"The calculated total tax amount of the list of transaction lines if any.","format":"double"},"Recurring":{"type":"string","description":"if available - YES/NO - if recurring billing contract used for transaction","nullable":true},"RecurringFrequency":{"type":"string","description":"if available - if recurring billing contract used for transaction\r\nPossible values:\r\n \"Daily\", (once per day)\r\n \"Weekly\", (once per week)\r\n \"Bi-Weekly\", (once per 2 weeks)\r\n \"Monthly\", (once per month)\r\n \"Bi-Monthly\", (Once every 2 months)\r\n \"Semi-Monthly\", (twice per month)\r\n \"Quarterly\", (four times per year)\r\n \"Semi-Annually\", (twice per year)\r\n \"Annually\" (once per year)","nullable":true},"RecurringProfileGuid":{"type":"string","description":"if available - GUID that identifies the recurring billing contract used for transaction","format":"uuid","nullable":true},"NextBillDate":{"type":"string","description":"if available - Next Billing date of the recurring billing contract used for transaction","format":"date-time","nullable":true},"DistributionType":{"$ref":"#/components/schemas/DistributionType"},"DistributionTypeValue":{"type":"string","description":"if available for Non-Profit Charity data - Distribution Type value - possible values: \"Direct Deposit\" = 1, \"Check\" = 2. Indicates the payment method that was used to disburse the funds to the Charity.","nullable":true},"DistributionStatus":{"type":"string","description":"if available for Non-Profit Charity data - possible values: \"Processing\", \"Settled\", \"Refunded\", \"Voided\"","nullable":true},"DistributionId":{"type":"integer","description":"if available for Non-Profit Charity data - Unique identifier for the distribution.","format":"int32","nullable":true},"DisbursementDate":{"type":"string","description":"if available for Non-Profit Charity data - Date funds were distributed to the organization.","format":"date-time","nullable":true},"SourceGuid":{"type":"string","description":"Source used","format":"uuid"},"SourceName":{"type":"string","nullable":true},"CharityId":{"type":"string","description":"if available for Non-Profit Charity data - CharityId used","nullable":true},"OrganizationName":{"type":"string","description":"if available Non-Profit Charity data - Organization Name","nullable":true},"Ein":{"type":"string","description":"if available for Non-Profit Charity data - Charity EIN","nullable":true},"ExternalEventId":{"type":"string","description":"Event Identifier per Product","nullable":true},"ExternalEventGuid":{"type":"string","description":"Event Guid per Product","format":"uuid"},"ExternalEventName":{"type":"string","description":"Event Name per Product","nullable":true},"TaxableBenefit":{"type":"number","description":"optional - If part of the original donation transaction, amount passed in that was taxable. No calculations were performed using this value, it is simply a placeholder to be used for your own reporting;","format":"double"},"TranId":{"type":"string","description":"unique tran id per Integration Source if available","nullable":true},"VoidRequestDate":{"type":"string","description":"Date of Void Request if available","format":"date-time","nullable":true},"VoidReason":{"type":"string","description":"Void Reason submitted if available","nullable":true},"RefundRequestDate":{"type":"string","description":"Date of Refund Request if available","format":"date-time","nullable":true},"RefundReason":{"type":"string","description":"Refund Reason submitted if available","nullable":true},"ProcessorId":{"type":"integer","description":"ProcessorId used","format":"int32","nullable":true},"ProcessorGuid":{"type":"string","description":"ProcessorGuid used","format":"uuid","nullable":true},"PaymentMethodTypeId":{"type":"integer","description":"possible values if available:\r\nNONE = 0,\r\nAMEX = 1,\r\nMASTERCARD = 2,\r\nVISA = 3,\r\nDISCOVER = 4,\r\nDINERSCLUB = 5,\r\nACH = 7,\r\nGOOGLEPAY = 8,\r\nAPPLEPAY = 9","format":"int32","nullable":true},"PaymentMethodTypeIdValue":{"type":"string","description":"\"NONE\" = 0,\r\n\"AMEX\" = 1,\r\n\"MASTERCARD\" = 2,\r\n\"VISA\" = 3,\r\n\"DISCOVER\" = 4,\r\n\"DINERSCLUB\" = 5,\r\n\"ACH\" = 7,\r\n\"GOOGLEPAY\" = 8,\r\n\"APPLEPAY\" = 9","nullable":true},"Surcharge":{"type":"number","description":"if available - The total surcharge amount.","format":"double","nullable":true},"IsSurchargeEligible":{"type":"boolean","description":"if available - Was card used Surcharge eligible","nullable":true},"CheckLastDigits":{"type":"string","description":"if available - last 4 digits of check account used","nullable":true},"CheckNumber":{"type":"string","description":"if available - Valid Check Number used","nullable":true},"CheckTypeId":{"type":"integer","description":"if available for Check transactions - possible values -\r\n 1 = Personal,\r\n 2 = Corporate,\r\n 3 = Government","format":"int32","nullable":true},"CheckTypeIdValue":{"type":"string","description":"if available for Check transactions - possible values -\r\n \"Personal\" = 1,\r\n \"Corporate\" = 2,\r\n \"Government\" = 3","nullable":true},"CheckAccountTypeId":{"type":"integer","description":"if available for Check transactions - possible values -\r\n 1 = Checking,\r\n 2 = Savings","format":"int32","nullable":true},"CheckAccountTypeIdValue":{"type":"string","description":"if available for Check transactions - possible values -\r\n \"Checking\" = 1,\r\n \"Savings\" = 2","nullable":true},"EpfSessionId":{"type":"string","description":"FrontStream unique Embedded Payment Form Session Id if available","format":"uuid","nullable":true},"TransactionLines":{"type":"array","items":{"$ref":"#/components/schemas/TransactionLinesDetail"},"nullable":true}},"additionalProperties":false,"description":"Transaction Report Details"},"ProcessStatus":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12],"type":"integer","format":"int32"},"PaymentResult":{"enum":[1,2,3,4,5,6],"type":"integer","format":"int32"},"DistributionType":{"enum":[1,2],"type":"integer","format":"int32"},"TransactionLinesDetail":{"type":"object","properties":{"PaymentGuid":{"type":"string","description":"Payment API Payment GUID for reference","format":"uuid"},"PaymentLineId":{"type":"integer","description":"Payment API Payment Line Identifier for reference","format":"int32"},"PaymentId":{"type":"integer","description":"Payment API Payment Identifier for reference","format":"int32"},"CreatedDate":{"type":"string","format":"date-time"},"ModifiedDate":{"type":"string","format":"date-time","nullable":true},"Amount":{"type":"number","description":"Transaction Line Amount","format":"double"},"CommissionAmount":{"type":"number","format":"double","nullable":true},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction. Indicates if the donor intended to cover the processing fees for the donation (primary used for Non Profit transactions like a donation)","nullable":true},"TransactionSourceGroupId":{"type":"integer","format":"int32","nullable":true},"CardFeeRate":{"type":"number","description":"example 2.5% - applied to EVERY donation. This is the FrontStream card processing fee. The percentage of the PaymentAmount that will be taken for credit card fees. Expressed as a human-readable percentage rather than a decimal value, it is intended to be able to be displayed directly on a page without needing to be converted.","format":"double","nullable":true},"CardFeeAmount":{"type":"number","description":"This is the amount that is owed to the gateway for the example 2.5% that FrontStream collects from the transaction.\r\n 2.5% of transaction amount if donor is not paying the fee, otherwise 2.5% of the transaction + card fee.","format":"double","nullable":true},"CardTypeFeeAmount":{"type":"number","description":"A per-transaction fee configured by card type (VI, MC, DI, AMEX, etc.) per API Partner's Contract other wise 0 (zero)","format":"double","nullable":true},"TotalCommissionRate":{"type":"number","description":"The Total percentage of Commissions that FrontStream takes from a given transaction.\r\nThis rate = Partner CommissionRate + FS CommissionRate","format":"double","nullable":true},"TotalCommissionAmount":{"type":"number","description":"The product of the transaction times the Total commission rate.","format":"double","nullable":true},"PartnerCommissionRate":{"type":"number","description":"The Partner Commission percentage taken on behalf of the Partner from a given transaction.","format":"double","nullable":true},"PartnerCommissionAmount":{"type":"number","description":"The product of the transaction times the Partner commission rate.","format":"double","nullable":true},"FsCommissionRate":{"type":"number","description":"The FrontStream Commission percentage that FrontStream takes from a given transaction.","format":"double","nullable":true},"FsCommissionAmount":{"type":"number","description":"The product of the transaction times the FrontStream commission rate.","format":"double","nullable":true},"TotalFees":{"type":"number","description":"The sum of all fees applied to a transaction amount. (TotalCommission + CardFee + FlatFee + CardFeeOnFee)","format":"double","nullable":true},"PerTransFee":{"type":"number","description":"The flat amount that will be taken from the PaymentAmount for any Per-Transaction Fees as configured in your contract.","format":"double","nullable":true},"ExternalLineId":{"type":"string","description":"optional - used to track individual line item IDs if necessary.","nullable":true},"Tip":{"type":"number","format":"double","nullable":true},"CommissionRateOverride":{"type":"number","format":"double","nullable":true},"Tax":{"type":"number","description":"Transaction Line Tax","format":"double","nullable":true},"CardFeeOnFeeAmount":{"type":"number","format":"double","nullable":true},"PerformanceFee":{"type":"number","description":"The performance fee (CommissionAmount) for this transaction line.","format":"double","nullable":true},"ProcessingFee":{"type":"number","description":"The processing fee (CardFeeAmount + PerTransFee + CardFeeOnFeeAmount) for this transaction line.","format":"double","nullable":true},"ShippingFee":{"type":"number","description":"The shipping fee applied to this transaction line (populated on the first line only).","format":"double","nullable":true},"AchFeeRate":{"type":"number","description":"The ACH processing fee rate applied to this transaction line.","format":"double","nullable":true},"AchFeeAmount":{"type":"number","description":"The ACH processing fee amount for this transaction line.","format":"double","nullable":true}},"additionalProperties":false,"description":"Transaction Line Details"},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ## POST /api/exportOrganizationTransactionsReport > Export Organization Transactions Report by valid organizationGuid in specified format "csv" or "excel". Defaults to "csv" if not provided ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/exportOrganizationTransactionsReport":{"post":{"tags":["Reports"],"summary":"Export Organization Transactions Report by valid organizationGuid in specified format \"csv\" or \"excel\". Defaults to \"csv\" if not provided","parameters":[{"name":"organizationGuid","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/PaymentExportReportRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/PaymentExportReportRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/PaymentExportReportRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/PaymentExportReportRequest"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Failure","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"PaymentExportReportRequest":{"type":"object","properties":{"Filters":{"type":"array","items":{"$ref":"#/components/schemas/SelectedConstraintDto"},"description":"Report Filters","nullable":true},"SortColumns":{"type":"array","items":{"$ref":"#/components/schemas/SortColumnDto"},"description":"Sort Columns","nullable":true},"PageSize":{"type":"integer","description":"How many records to return per page.","format":"int32"},"PageIndex":{"type":"integer","description":"Which page of results to return. Starts at 1 (0 will also return the first page)","format":"int32"},"Format":{"type":"string","description":"Determines which file type the report will be exported to. Valid values: \"csv\" or \"excel\"","nullable":true}},"additionalProperties":false,"description":""},"SelectedConstraintDto":{"type":"object","properties":{"Name":{"type":"string","nullable":true},"Operation":{"$ref":"#/components/schemas/ConstraintOperation"},"Values":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false},"ConstraintOperation":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23],"type":"integer","format":"int32"},"SortColumnDto":{"type":"object","properties":{"Name":{"type":"string","nullable":true},"Descending":{"type":"boolean"},"Order":{"type":"integer","format":"int32"}},"additionalProperties":false},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ## Generate Source Transactions Report > Sample request to get transactions report filters by PaymentDate after (operation 7 = After) > \ > January 1st 2026 (2026-01-01) sorted by PaymentDate column desc, returning page index 1 > \ > and page size 1000 records. > \\ > > \ > Please see Filters and Operation parameters defined here for requests: > \\ > > \ > POST /api/sourceTransactionsReport > \ > { > \ > "Filters": \[ > \ > { > \ > "Name": "PaymentDate", > \ > "Operation": 7, > \ > "Values": \[ > \ > "2026-01-01" > \ > ] > \ > } > \ > ], > \ > "SortColumns": \[ > \ > { > \ > "Name": "PaymentDate", > \ > "Descending": true, > \ > "Order": 0 > \ > } > \ > ], > \ > "PageSize": 1000, > \ > "PageIndex": 1 > \ > } ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/sourceTransactionsReport":{"post":{"tags":["Reports"],"summary":"Generate Source Transactions Report","description":" Sample request to get transactions report filters by PaymentDate after (operation 7 = After)\r\n January 1st 2026 (2026-01-01) sorted by PaymentDate column desc, returning page index 1\r\n and page size 1000 records.\r\n\r\n Please see Filters and Operation parameters defined here for requests: https://developers.frontstream.com/welcome-to-our-payment-api/api-references/retrieve-transactions-report#body-parameter-definitions\r\n\r\n POST /api/sourceTransactionsReport\r\n\t\t{\r\n \t\t\"Filters\": [\r\n \t\t{\r\n \t\t\"Name\": \"PaymentDate\",\r\n \t\t\"Operation\": 7,\r\n \t\t\"Values\": [\r\n \t\t \"2026-01-01\"\r\n \t\t]\r\n \t\t}\r\n \t\t],\r\n \t\t\"SortColumns\": [\r\n \t\t{\r\n \t\t\"Name\": \"PaymentDate\",\r\n \t\t\"Descending\": true,\r\n \t\t\"Order\": 0\r\n \t\t}\r\n \t\t],\r\n \t\t\"PageSize\": 1000,\r\n \t\t\"PageIndex\": 1\r\n\t\t}","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/PaymentReportRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/PaymentReportRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/PaymentReportRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/PaymentReportRequest"}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TransactionReportDetailPagedResults"}}}},"400":{"description":"Failure","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"PaymentReportRequest":{"type":"object","properties":{"Filters":{"type":"array","items":{"$ref":"#/components/schemas/SelectedConstraintDto"},"description":"Report Filters","nullable":true},"SortColumns":{"type":"array","items":{"$ref":"#/components/schemas/SortColumnDto"},"description":"Sort Columns","nullable":true},"PageSize":{"type":"integer","description":"How many records to return per page.","format":"int32"},"PageIndex":{"type":"integer","description":"Which page of results to return. Starts at 1 (0 will also return the first page)","format":"int32"}},"additionalProperties":false,"description":""},"SelectedConstraintDto":{"type":"object","properties":{"Name":{"type":"string","nullable":true},"Operation":{"$ref":"#/components/schemas/ConstraintOperation"},"Values":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false},"ConstraintOperation":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23],"type":"integer","format":"int32"},"SortColumnDto":{"type":"object","properties":{"Name":{"type":"string","nullable":true},"Descending":{"type":"boolean"},"Order":{"type":"integer","format":"int32"}},"additionalProperties":false},"TransactionReportDetailPagedResults":{"type":"object","properties":{"CurrentPage":{"type":"integer","format":"int32"},"PageSize":{"type":"integer","format":"int32"},"Results":{"type":"array","items":{"$ref":"#/components/schemas/TransactionReportDetail"},"nullable":true},"TotalPages":{"type":"integer","format":"int32"},"TotalRows":{"type":"integer","format":"int32"}},"additionalProperties":false},"TransactionReportDetail":{"type":"object","properties":{"PaymentDate":{"type":"string","description":"Payment Date of transaction","format":"date-time"},"PaymentGuid":{"type":"string","description":"Payment API Payment GUID","format":"uuid"},"PaymentId":{"type":"integer","description":"Payment API Payment Id","format":"int32"},"PaymentExternalId":{"type":"string","description":"Payment Gateway TransactionId - is the TransactionId of a Payment Response object","nullable":true},"OriginalExternalID":{"type":"string","description":"Original Payment Gateway TransactionId - is the Original TransactionId of a Payment Response object","nullable":true},"ProcessStatus":{"$ref":"#/components/schemas/ProcessStatus"},"ProcessStatusValue":{"type":"string","description":"Process Status value - possible values: NotProcessed = 1 \"Not Processed\", Authorized = 2 \"Awaiting Authorization\", Settled = 4 \"Authorized\", Rejected = 5 \"Rejected\", RefundRequired = 6 \"Refund Required\", AwaitingRefund = 7 \"Awaiting Refund\", Refunded = 8 \"Refunded\", Cancelled = 9 \"Cancelled\", Chargeback = 10 \"Chargeback\", RefundRejected = 11 \"Refund Rejected\"","nullable":true},"PaymentResult":{"$ref":"#/components/schemas/PaymentResult"},"PaymentResultValue":{"type":"string","description":"Payment Result value - possible values: \"Pending\" = 1, \"Processing\" = 2, \"Successful\" = 3, \"Failed\" = 4, \"Refunded\" = 5, \"Cancelled\" = 6","nullable":true},"ExternalConstituentId":{"type":"string","description":"Donor Identifier","nullable":true},"FirstName":{"type":"string","description":"billing First Name","nullable":true},"LastName":{"type":"string","description":"billing Last Name","nullable":true},"Email":{"type":"string","description":"contact email","nullable":true},"CardHolderName":{"type":"string","description":"Name on Card","nullable":true},"CCLastDigits":{"type":"string","description":"if available - last 4 digits of card","nullable":true},"ExpirationDate":{"type":"string","description":"MM/YY format","nullable":true},"CCType":{"type":"string","description":"possible values if available: \"American Express\", \"Mastercard\", \"Visa\", \"Discover\", \"Diners Club\", Undefined","nullable":true},"CoverTheFee":{"type":"string","description":"YES/NO - did donor Cover the Fees on Donation.","nullable":true},"DonationAmount":{"type":"number","description":"The total donation amount requested.","format":"double"},"CoverTheFeeAmount":{"type":"number","description":"The total donation amount requested.","format":"double"},"TransactionAmount":{"type":"number","description":"The total transaction amount processed toward the cardholder's account.","format":"double"},"ServiceFees":{"type":"number","description":"The calculated total fees amount of the list of transaction lines.","format":"double"},"PerformanceFees":{"type":"number","description":"The sum of CommissionAmount across all transaction lines.","format":"double"},"ProcessingFees":{"type":"number","description":"The sum of CardFeeAmount, PerTransFee, and CardFeeOnFeeAmount across all transaction lines.","format":"double"},"AmountPaid":{"type":"number","description":"The total transaction amount minus processing Fees","format":"double"},"Taxes":{"type":"number","description":"The calculated total tax amount of the list of transaction lines if any.","format":"double"},"Recurring":{"type":"string","description":"if available - YES/NO - if recurring billing contract used for transaction","nullable":true},"RecurringFrequency":{"type":"string","description":"if available - if recurring billing contract used for transaction\r\nPossible values:\r\n \"Daily\", (once per day)\r\n \"Weekly\", (once per week)\r\n \"Bi-Weekly\", (once per 2 weeks)\r\n \"Monthly\", (once per month)\r\n \"Bi-Monthly\", (Once every 2 months)\r\n \"Semi-Monthly\", (twice per month)\r\n \"Quarterly\", (four times per year)\r\n \"Semi-Annually\", (twice per year)\r\n \"Annually\" (once per year)","nullable":true},"RecurringProfileGuid":{"type":"string","description":"if available - GUID that identifies the recurring billing contract used for transaction","format":"uuid","nullable":true},"NextBillDate":{"type":"string","description":"if available - Next Billing date of the recurring billing contract used for transaction","format":"date-time","nullable":true},"DistributionType":{"$ref":"#/components/schemas/DistributionType"},"DistributionTypeValue":{"type":"string","description":"if available for Non-Profit Charity data - Distribution Type value - possible values: \"Direct Deposit\" = 1, \"Check\" = 2. Indicates the payment method that was used to disburse the funds to the Charity.","nullable":true},"DistributionStatus":{"type":"string","description":"if available for Non-Profit Charity data - possible values: \"Processing\", \"Settled\", \"Refunded\", \"Voided\"","nullable":true},"DistributionId":{"type":"integer","description":"if available for Non-Profit Charity data - Unique identifier for the distribution.","format":"int32","nullable":true},"DisbursementDate":{"type":"string","description":"if available for Non-Profit Charity data - Date funds were distributed to the organization.","format":"date-time","nullable":true},"SourceGuid":{"type":"string","description":"Source used","format":"uuid"},"SourceName":{"type":"string","nullable":true},"CharityId":{"type":"string","description":"if available for Non-Profit Charity data - CharityId used","nullable":true},"OrganizationName":{"type":"string","description":"if available Non-Profit Charity data - Organization Name","nullable":true},"Ein":{"type":"string","description":"if available for Non-Profit Charity data - Charity EIN","nullable":true},"ExternalEventId":{"type":"string","description":"Event Identifier per Product","nullable":true},"ExternalEventGuid":{"type":"string","description":"Event Guid per Product","format":"uuid"},"ExternalEventName":{"type":"string","description":"Event Name per Product","nullable":true},"TaxableBenefit":{"type":"number","description":"optional - If part of the original donation transaction, amount passed in that was taxable. No calculations were performed using this value, it is simply a placeholder to be used for your own reporting;","format":"double"},"TranId":{"type":"string","description":"unique tran id per Integration Source if available","nullable":true},"VoidRequestDate":{"type":"string","description":"Date of Void Request if available","format":"date-time","nullable":true},"VoidReason":{"type":"string","description":"Void Reason submitted if available","nullable":true},"RefundRequestDate":{"type":"string","description":"Date of Refund Request if available","format":"date-time","nullable":true},"RefundReason":{"type":"string","description":"Refund Reason submitted if available","nullable":true},"ProcessorId":{"type":"integer","description":"ProcessorId used","format":"int32","nullable":true},"ProcessorGuid":{"type":"string","description":"ProcessorGuid used","format":"uuid","nullable":true},"PaymentMethodTypeId":{"type":"integer","description":"possible values if available:\r\nNONE = 0,\r\nAMEX = 1,\r\nMASTERCARD = 2,\r\nVISA = 3,\r\nDISCOVER = 4,\r\nDINERSCLUB = 5,\r\nACH = 7,\r\nGOOGLEPAY = 8,\r\nAPPLEPAY = 9","format":"int32","nullable":true},"PaymentMethodTypeIdValue":{"type":"string","description":"\"NONE\" = 0,\r\n\"AMEX\" = 1,\r\n\"MASTERCARD\" = 2,\r\n\"VISA\" = 3,\r\n\"DISCOVER\" = 4,\r\n\"DINERSCLUB\" = 5,\r\n\"ACH\" = 7,\r\n\"GOOGLEPAY\" = 8,\r\n\"APPLEPAY\" = 9","nullable":true},"Surcharge":{"type":"number","description":"if available - The total surcharge amount.","format":"double","nullable":true},"IsSurchargeEligible":{"type":"boolean","description":"if available - Was card used Surcharge eligible","nullable":true},"CheckLastDigits":{"type":"string","description":"if available - last 4 digits of check account used","nullable":true},"CheckNumber":{"type":"string","description":"if available - Valid Check Number used","nullable":true},"CheckTypeId":{"type":"integer","description":"if available for Check transactions - possible values -\r\n 1 = Personal,\r\n 2 = Corporate,\r\n 3 = Government","format":"int32","nullable":true},"CheckTypeIdValue":{"type":"string","description":"if available for Check transactions - possible values -\r\n \"Personal\" = 1,\r\n \"Corporate\" = 2,\r\n \"Government\" = 3","nullable":true},"CheckAccountTypeId":{"type":"integer","description":"if available for Check transactions - possible values -\r\n 1 = Checking,\r\n 2 = Savings","format":"int32","nullable":true},"CheckAccountTypeIdValue":{"type":"string","description":"if available for Check transactions - possible values -\r\n \"Checking\" = 1,\r\n \"Savings\" = 2","nullable":true},"EpfSessionId":{"type":"string","description":"FrontStream unique Embedded Payment Form Session Id if available","format":"uuid","nullable":true},"TransactionLines":{"type":"array","items":{"$ref":"#/components/schemas/TransactionLinesDetail"},"nullable":true}},"additionalProperties":false,"description":"Transaction Report Details"},"ProcessStatus":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12],"type":"integer","format":"int32"},"PaymentResult":{"enum":[1,2,3,4,5,6],"type":"integer","format":"int32"},"DistributionType":{"enum":[1,2],"type":"integer","format":"int32"},"TransactionLinesDetail":{"type":"object","properties":{"PaymentGuid":{"type":"string","description":"Payment API Payment GUID for reference","format":"uuid"},"PaymentLineId":{"type":"integer","description":"Payment API Payment Line Identifier for reference","format":"int32"},"PaymentId":{"type":"integer","description":"Payment API Payment Identifier for reference","format":"int32"},"CreatedDate":{"type":"string","format":"date-time"},"ModifiedDate":{"type":"string","format":"date-time","nullable":true},"Amount":{"type":"number","description":"Transaction Line Amount","format":"double"},"CommissionAmount":{"type":"number","format":"double","nullable":true},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction. Indicates if the donor intended to cover the processing fees for the donation (primary used for Non Profit transactions like a donation)","nullable":true},"TransactionSourceGroupId":{"type":"integer","format":"int32","nullable":true},"CardFeeRate":{"type":"number","description":"example 2.5% - applied to EVERY donation. This is the FrontStream card processing fee. The percentage of the PaymentAmount that will be taken for credit card fees. Expressed as a human-readable percentage rather than a decimal value, it is intended to be able to be displayed directly on a page without needing to be converted.","format":"double","nullable":true},"CardFeeAmount":{"type":"number","description":"This is the amount that is owed to the gateway for the example 2.5% that FrontStream collects from the transaction.\r\n 2.5% of transaction amount if donor is not paying the fee, otherwise 2.5% of the transaction + card fee.","format":"double","nullable":true},"CardTypeFeeAmount":{"type":"number","description":"A per-transaction fee configured by card type (VI, MC, DI, AMEX, etc.) per API Partner's Contract other wise 0 (zero)","format":"double","nullable":true},"TotalCommissionRate":{"type":"number","description":"The Total percentage of Commissions that FrontStream takes from a given transaction.\r\nThis rate = Partner CommissionRate + FS CommissionRate","format":"double","nullable":true},"TotalCommissionAmount":{"type":"number","description":"The product of the transaction times the Total commission rate.","format":"double","nullable":true},"PartnerCommissionRate":{"type":"number","description":"The Partner Commission percentage taken on behalf of the Partner from a given transaction.","format":"double","nullable":true},"PartnerCommissionAmount":{"type":"number","description":"The product of the transaction times the Partner commission rate.","format":"double","nullable":true},"FsCommissionRate":{"type":"number","description":"The FrontStream Commission percentage that FrontStream takes from a given transaction.","format":"double","nullable":true},"FsCommissionAmount":{"type":"number","description":"The product of the transaction times the FrontStream commission rate.","format":"double","nullable":true},"TotalFees":{"type":"number","description":"The sum of all fees applied to a transaction amount. (TotalCommission + CardFee + FlatFee + CardFeeOnFee)","format":"double","nullable":true},"PerTransFee":{"type":"number","description":"The flat amount that will be taken from the PaymentAmount for any Per-Transaction Fees as configured in your contract.","format":"double","nullable":true},"ExternalLineId":{"type":"string","description":"optional - used to track individual line item IDs if necessary.","nullable":true},"Tip":{"type":"number","format":"double","nullable":true},"CommissionRateOverride":{"type":"number","format":"double","nullable":true},"Tax":{"type":"number","description":"Transaction Line Tax","format":"double","nullable":true},"CardFeeOnFeeAmount":{"type":"number","format":"double","nullable":true},"PerformanceFee":{"type":"number","description":"The performance fee (CommissionAmount) for this transaction line.","format":"double","nullable":true},"ProcessingFee":{"type":"number","description":"The processing fee (CardFeeAmount + PerTransFee + CardFeeOnFeeAmount) for this transaction line.","format":"double","nullable":true},"ShippingFee":{"type":"number","description":"The shipping fee applied to this transaction line (populated on the first line only).","format":"double","nullable":true},"AchFeeRate":{"type":"number","description":"The ACH processing fee rate applied to this transaction line.","format":"double","nullable":true},"AchFeeAmount":{"type":"number","description":"The ACH processing fee amount for this transaction line.","format":"double","nullable":true}},"additionalProperties":false,"description":"Transaction Line Details"},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ## POST /api/exportSourceTransactionsReport > Export Source Transactions Report in specified format "csv" or "excel". Defaults to "csv" if not provided ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"paths":{"/api/exportSourceTransactionsReport":{"post":{"tags":["Reports"],"summary":"Export Source Transactions Report in specified format \"csv\" or \"excel\". Defaults to \"csv\" if not provided","parameters":[{"name":"AccessToken","in":"header","description":"access token","required":true,"schema":{"type":"string"}}],"requestBody":{"description":"","content":{"application/json-patch+json":{"schema":{"$ref":"#/components/schemas/PaymentExportReportRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/PaymentExportReportRequest"}},"text/json":{"schema":{"$ref":"#/components/schemas/PaymentExportReportRequest"}},"application/*+json":{"schema":{"$ref":"#/components/schemas/PaymentExportReportRequest"}}}},"responses":{"200":{"description":"Success"},"400":{"description":"Failure","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/BrokenRule"}}}}}}}}},"components":{"schemas":{"PaymentExportReportRequest":{"type":"object","properties":{"Filters":{"type":"array","items":{"$ref":"#/components/schemas/SelectedConstraintDto"},"description":"Report Filters","nullable":true},"SortColumns":{"type":"array","items":{"$ref":"#/components/schemas/SortColumnDto"},"description":"Sort Columns","nullable":true},"PageSize":{"type":"integer","description":"How many records to return per page.","format":"int32"},"PageIndex":{"type":"integer","description":"Which page of results to return. Starts at 1 (0 will also return the first page)","format":"int32"},"Format":{"type":"string","description":"Determines which file type the report will be exported to. Valid values: \"csv\" or \"excel\"","nullable":true}},"additionalProperties":false,"description":""},"SelectedConstraintDto":{"type":"object","properties":{"Name":{"type":"string","nullable":true},"Operation":{"$ref":"#/components/schemas/ConstraintOperation"},"Values":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false},"ConstraintOperation":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23],"type":"integer","format":"int32"},"SortColumnDto":{"type":"object","properties":{"Name":{"type":"string","nullable":true},"Descending":{"type":"boolean"},"Order":{"type":"integer","format":"int32"}},"additionalProperties":false},"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` # Models ## The AddRecurringProfileRequest object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"AddRecurringProfileRequest":{"required":["Amount","BillingFrequency","StartDate","TokenGuid"],"type":"object","properties":{"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"TokenGuid":{"type":"string","description":"required - Valid token guid of created tokenized account"},"Amount":{"maxLength":7,"type":"string","description":"required - Amount to be charged per billing frequency"},"StartDate":{"type":"string","description":"required - format yyyy-MM-dd - start date of contract"},"EndDate":{"type":"string","description":"optional - format yyyy-MM-dd - end date of contract (must be after StartDate) if you wish a contract to stop recurring at certain date","nullable":true},"NextBillDate":{"type":"string","description":"optional - format yyyy-MM-dd - We will calculate if not provided. The date when the first recurrence should begin charging the donor's card. Must be after StartDate. Use our GET api/nextBillDate API to help calculate.","nullable":true},"BillingFrequency":{"type":"string","description":"required - How often the recurrence should occur. Possible values:\r\n \"Daily\", (once per day)\r\n \"Weekly\", (once per week)\r\n \"Bi-Weekly\", (once per 2 weeks)\r\n \"Monthly\", (once per month)\r\n \"Bi-Monthly\", (Once every 2 months)\r\n \"Semi-Monthly\", (twice per month)\r\n \"Quarterly\", (four times per year)\r\n \"Semi-Annually\", (twice per year)\r\n \"Annually\" (once per year)"},"PreFeeAmount":{"maxLength":7,"type":"string","description":"optional - Pre Fee Amount with the fees not included if using PayFee flag (primary used for Non Profit transactions like Donations)","nullable":true},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction (primary used for Non Profit transactions like a donation), if used see Amount and PreFeeAmount info","nullable":true},"TransactionSourceGroupId":{"type":"string","description":"optional - For Direct Merchant (For Profit) Api Partners should set to PaymentNoFee (12), other values are for Non Profit transactions - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;","nullable":true},"ExternalEventId":{"maxLength":10,"type":"string","description":"optional - Event Id per Product","nullable":true},"ExternalEventGuid":{"type":"string","description":"optional - Event Guid per Product","nullable":true},"ExternalEventName":{"maxLength":500,"type":"string","description":"optional - Event Name per Product","nullable":true},"Surcharge":{"maxLength":7,"type":"string","description":"optional - calculated surcharge amount","nullable":true},"CommissionRateOverride":{"type":"string","description":"optional - The percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract. Primary used for Non Profit transactions.","nullable":true},"CardProcessingFeeOverride":{"type":"string","description":"optional - Overrides the default percentage processing fee. Primary used for Non Profit transactions.","nullable":true}},"additionalProperties":false,"description":""}}}} ``` ## The AFShieldPaymentRequest object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"AFShieldPaymentRequest":{"type":"object","properties":{"ProductDescription":{"maxLength":256,"type":"string","nullable":true},"ProductItem":{"maxLength":256,"type":"string","nullable":true},"ProductType":{"maxLength":256,"type":"string","nullable":true},"ProductQuantity":{"maxLength":3,"type":"string","nullable":true},"SessionId":{"maxLength":32,"type":"string","nullable":true},"BillToPhoneNumber":{"maxLength":32,"type":"string","nullable":true},"ShippingAddressStreet1":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressStreet2":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressCountry":{"maxLength":2,"type":"string","nullable":true},"ShippingAddressCity":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressEmail":{"maxLength":64,"type":"string","format":"email","nullable":true},"ShippingAddressName":{"maxLength":64,"type":"string","nullable":true},"ShippingAddressZip":{"maxLength":10,"type":"string","nullable":true},"ShippingAddressState":{"maxLength":50,"type":"string","nullable":true},"ShipToPhoneNumber":{"maxLength":32,"type":"string","nullable":true},"ShipToPremiseForUK":{"maxLength":256,"type":"string","nullable":true},"ShipToStreetForUK":{"maxLength":256,"type":"string","nullable":true},"BillToPremiseForUK":{"maxLength":256,"type":"string","nullable":true},"BillToStreetForUK":{"maxLength":256,"type":"string","nullable":true}},"additionalProperties":false,"description":""}}}} ``` ## The AuthenticationClientSessionResponse object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"AuthenticationClientSessionResponse":{"type":"object","properties":{"Token":{"type":"string","description":"This is the AccessToken you will use for any other API call","nullable":true},"ClientId":{"type":"string","description":"Unique identifier for the API Partner; provided by FrontStream","format":"uuid"},"ExpirationDate":{"type":"string","description":"The date and time at which the AccessToken will no longer be valid if not used first. Will always be 5 hours from when the response is sent.","format":"date-time"}},"additionalProperties":false,"description":""}}}} ``` ## The BrokenRule object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"BrokenRule":{"type":"object","properties":{"ErrorCode":{"type":"integer","format":"int32"},"Message":{"type":"string","nullable":true},"LoggerMessage":{"type":"string","nullable":true}},"additionalProperties":false}}}} ``` ## The CharitySearchResults object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"CharitySearchResults":{"type":"object","properties":{"TotalResultCount":{"type":"integer","description":"How many total possible results there are for your search.","format":"int32"},"TotalPages":{"type":"integer","description":"How many pages of data exist based on your selected PageSize.","format":"int32"},"PageIndex":{"type":"integer","description":"Confirms what you passed in the querystring.","format":"int32"},"PageSize":{"type":"integer","description":"Confirms what you passed in the querystring.","format":"int32"},"SearchResults":{"type":"array","items":{"$ref":"#/components/schemas/CharitySearchResultsList"},"description":"Each record in the array represents a full Charity Record.","nullable":true}},"additionalProperties":false,"description":""},"CharitySearchResultsList":{"type":"object","properties":{"CharityId":{"type":"string","description":"Unique Identifier for the Charity in the Payment API.","nullable":true},"NpoName":{"type":"string","description":"Name of the Charity in the Payment API database.","nullable":true},"EIN":{"type":"string","description":"The United States EIN or Canadian Tax ID of the Charity.","nullable":true},"Address1":{"type":"string","description":"Address Line 1 of the Charity's address.","nullable":true},"Address2":{"type":"string","description":"Address Line 2 of the Charity's address.","nullable":true},"City":{"type":"string","description":"City of the Charity's address.","nullable":true},"State":{"type":"string","description":"State of the Charity's address.","nullable":true},"Zip":{"type":"string","description":"Postal Code of the Charity's address.","nullable":true},"Country":{"type":"string","description":"Country of the Charity's address.","nullable":true},"NpoEligibilityFlag":{"type":"boolean","description":"Indicates whether or not the organization is currently able to receive tax-deductible donations based on United States IRS filings."},"ParentOrgName":{"type":"string","description":"This will return the same value as NpoName if the Charity has no Parent organization, but if a particular organization has indicated that it is a child organization of a larger Charity (such as a regional chapter of a nationwide charity), the Parent Charity name will appear here.","nullable":true},"NTEEcode":{"type":"string","description":"The Charity's NTEE code as defined by United States IRS filings. This is not a required classification, and thus may not exist for all records (and will not exist for Canadian charity records).","nullable":true}},"additionalProperties":false,"description":""}}}} ``` ## The CharitySearchResultsList object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"CharitySearchResultsList":{"type":"object","properties":{"CharityId":{"type":"string","description":"Unique Identifier for the Charity in the Payment API.","nullable":true},"NpoName":{"type":"string","description":"Name of the Charity in the Payment API database.","nullable":true},"EIN":{"type":"string","description":"The United States EIN or Canadian Tax ID of the Charity.","nullable":true},"Address1":{"type":"string","description":"Address Line 1 of the Charity's address.","nullable":true},"Address2":{"type":"string","description":"Address Line 2 of the Charity's address.","nullable":true},"City":{"type":"string","description":"City of the Charity's address.","nullable":true},"State":{"type":"string","description":"State of the Charity's address.","nullable":true},"Zip":{"type":"string","description":"Postal Code of the Charity's address.","nullable":true},"Country":{"type":"string","description":"Country of the Charity's address.","nullable":true},"NpoEligibilityFlag":{"type":"boolean","description":"Indicates whether or not the organization is currently able to receive tax-deductible donations based on United States IRS filings."},"ParentOrgName":{"type":"string","description":"This will return the same value as NpoName if the Charity has no Parent organization, but if a particular organization has indicated that it is a child organization of a larger Charity (such as a regional chapter of a nationwide charity), the Parent Charity name will appear here.","nullable":true},"NTEEcode":{"type":"string","description":"The Charity's NTEE code as defined by United States IRS filings. This is not a required classification, and thus may not exist for all records (and will not exist for Canadian charity records).","nullable":true}},"additionalProperties":false,"description":""}}}} ``` ## The ClientSessionRequest object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"ClientSessionRequest":{"required":["ClientId","ClientSecret"],"type":"object","properties":{"ClientId":{"type":"string","description":"Unique identifier for the API Partner; provided by FrontStream"},"ClientSecret":{"maxLength":500,"type":"string","description":"Key specifically paired to the clientId"}},"additionalProperties":false,"description":""}}}} ``` ## The ConstraintOperation object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"ConstraintOperation":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23],"type":"integer","format":"int32"}}}} ``` ## The DeleteTokenResponse object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"DeleteTokenResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"True if the token was successfully cancelled/deleted"},"TokenGuid":{"type":"string","description":"The TokenGuid that was deleted","format":"uuid"},"ExternalCardToken":{"type":"string","description":"3rd party gateway card token that was deleted (null for ACH tokens)","nullable":true},"ExternalCheckToken":{"type":"string","description":"3rd party gateway check/ACH token that was deleted (null for card tokens)","nullable":true},"ExternalCustomerId":{"type":"string","description":"3rd party gateway customer id associated with the deleted token","nullable":true},"ExternalConstituentId":{"type":"string","description":"Partner's constituent/donor id stored on the deleted token record","nullable":true},"Message":{"type":"string","description":"Response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Processor response message","nullable":true},"ResponseCode":{"type":"string","description":"Response code - \"0\" on success, any other value indicates an error","nullable":true}},"additionalProperties":false}}}} ``` ## The DistributionType object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"DistributionType":{"enum":[1,2],"type":"integer","format":"int32"}}}} ``` ## The EditAllNotificationConfigSave object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"EditAllNotificationConfigSave":{"required":["NotificationConfigs"],"type":"object","properties":{"IntegrationSourceGuid":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"NotificationConfigs":{"maxItems":20,"type":"array","items":{"$ref":"#/components/schemas/EditNotificationConfigSave"},"description":"NotificationConfigs: 1 - n notification configs for an Integration Source"}},"additionalProperties":false,"description":""},"EditNotificationConfigSave":{"required":["NotificationConfigurationTypeId","NotificationProtocolTypeId","NotificationUrl","Retries"],"type":"object","properties":{"NotificationConfigurationTypeId":{"type":"string","description":"required - NotificationConfigurationTypeId: possible values -\r\n 1 - General"},"NotificationProtocolTypeId":{"type":"string","description":"required - NotificationProtocolTypeId: possible values -\r\n 1 - Web,\r\n 2 - Email - (Email currently not in use)"},"NotificationUrl":{"maxLength":250,"type":"string","description":"required - NotificationUrl - Url to post notification to. Integration Source endpoint to post payload to. Example: https://{yourenvironment.yourdomain}.com/api/yourNotification endpoint. Make sure to include Https://"},"NotificationEmailFrom":{"maxLength":250,"type":"string","description":"Not in use - NotificationEmailFrom – optional Notification Email from","format":"email","nullable":true},"NotificationEmailTo":{"maxLength":250,"type":"string","description":"Not in use - NotificationEmailTo – optional Notification Email to","format":"email","nullable":true},"Retries":{"type":"integer","description":"required - number of retries to try again failed notifications - currently retries 10 times by default or set to 0","format":"int32"},"AccessToken":{"maxLength":250,"type":"string","description":"optional (max: 250) - if access token needed to hit notification url","nullable":true},"IsDeleted":{"type":"boolean","description":"set to true if you wish to deactivate configuration, otherwise set to false"}},"additionalProperties":false,"description":""}}}} ``` ## The EditNotificationConfigSave object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"EditNotificationConfigSave":{"required":["NotificationConfigurationTypeId","NotificationProtocolTypeId","NotificationUrl","Retries"],"type":"object","properties":{"NotificationConfigurationTypeId":{"type":"string","description":"required - NotificationConfigurationTypeId: possible values -\r\n 1 - General"},"NotificationProtocolTypeId":{"type":"string","description":"required - NotificationProtocolTypeId: possible values -\r\n 1 - Web,\r\n 2 - Email - (Email currently not in use)"},"NotificationUrl":{"maxLength":250,"type":"string","description":"required - NotificationUrl - Url to post notification to. Integration Source endpoint to post payload to. Example: https://{yourenvironment.yourdomain}.com/api/yourNotification endpoint. Make sure to include Https://"},"NotificationEmailFrom":{"maxLength":250,"type":"string","description":"Not in use - NotificationEmailFrom – optional Notification Email from","format":"email","nullable":true},"NotificationEmailTo":{"maxLength":250,"type":"string","description":"Not in use - NotificationEmailTo – optional Notification Email to","format":"email","nullable":true},"Retries":{"type":"integer","description":"required - number of retries to try again failed notifications - currently retries 10 times by default or set to 0","format":"int32"},"AccessToken":{"maxLength":250,"type":"string","description":"optional (max: 250) - if access token needed to hit notification url","nullable":true},"IsDeleted":{"type":"boolean","description":"set to true if you wish to deactivate configuration, otherwise set to false"}},"additionalProperties":false,"description":""}}}} ``` ## The FeeListRequest object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"FeeListRequest":{"required":["Transactions"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"IntegrationSourceGuid":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"TokenGuid":{"type":"string","description":"Payment API Token GUID. Card Type of Token will be used in Fee Calculation. If using TokenGuid then do not set CreditCardTypeId parameter","nullable":true},"PaymentMethodTypeId":{"type":"string","description":"For ACH Fees please set to \"7\" otherwise only set for an API Partner with different fees based on a particular card type for example:\r\nUsed for API Partner's per card type fee calculation based on contract, For example - $0.30 per transaction for Visa, MasterCard and Discover cards and $0.50 per transaction for American Express.\r\noptional - The payment method type used for fee calculation. Applies to all transactions in the list.\r\npossible values -\r\n 1 - AMEX, 2 - MASTERCARD, 3 - VISA, 4 - DISCOVER, 5 - DINERSCLUB,\r\n 7 - ACH","nullable":true},"Transactions":{"type":"array","items":{"$ref":"#/components/schemas/PaymentTransTypeRequest"},"description":"required - 1 to n transactions to break down transaction line items"}},"additionalProperties":false},"PaymentTransTypeRequest":{"required":["Amount","TransactionSourceGroupId"],"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","description":"required - For Direct Merchant (For Profit) Api Partners should set to PaymentNoFee (12), other values are for Non Profit transactions - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;\r\n 13 - EventDonationFee;\r\n 14 - SponsorshipFee\r\n 15 - MembershipFee"},"Amount":{"maxLength":7,"type":"string","description":"required - Amount of line item without the fees included, Payment api will calculate fees for you"},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction. Indicates if the donor intends to cover the processing fees for the donation (primary used for Non Profit transactions like a donation)"},"CommissionRateOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - The percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract.","nullable":true},"CardProcessingFeeOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - Overrides the default percentage processing fee","nullable":true},"ExternalLineId":{"maxLength":100,"type":"string","description":"optional (max: 100) - use this to track individual line item IDs if necessary.","nullable":true},"Tip":{"maxLength":7,"type":"string","description":"optional (max: 7) - An amount taken up front for the API Partner if Donor decides to apply a tip. Added to the total amount to charge on the donor’s card . Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true},"Tax":{"maxLength":7,"type":"string","description":"optional (max: 7) - A tax amount taken up front. Added to the total amount to charge on the donor’s card. Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true}},"additionalProperties":false,"description":""}}}} ``` ## The FeeListResponse object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"FeeListResponse":{"type":"object","properties":{"TotalPaymentAmount":{"type":"number","description":"The total payment amount processed toward the cardholder's account.","format":"double"},"TotalFeesAmount":{"type":"number","description":"The calculated total fees amount of the list of transactions.","format":"double"},"TotalTaxAmount":{"type":"number","description":"The calculated total tax amount of the list of transactions.","format":"double"},"TransactionFees":{"type":"array","items":{"$ref":"#/components/schemas/FeeResponse"},"description":"List of Transaction Fee Responses","nullable":true}},"additionalProperties":false},"FeeResponse":{"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","nullable":true},"PaymentAmount":{"type":"number","description":"This is the amount charged to the donor. Will be equal to the sum of the Amount parameters if payFee=false, but if payFee=true, then this will be the amount that will be charged to the donor in order to have the net post-disbursement donation be equal to the Amount parameters.","format":"double","nullable":true},"CardFeeRate":{"type":"number","description":"example 2.5% - applied to EVERY donation. This is the FrontStream card processing fee. The percentage of the PaymentAmount that will be taken for credit card fees. Expressed as a human-readable percentage rather than a decimal value, it is intended to be able to be displayed directly on a page without needing to be converted.","format":"double","nullable":true},"CardFeeAmount":{"type":"number","description":"This is the amount that is owed to the gateway for the example 2.5% that FrontStream collects from the transaction.\r\n 2.5% of transaction amount if donor is not paying the fee, otherwise 2.5% of the transaction + card fee.","format":"double","nullable":true},"CardTypeFeeAmount":{"type":"number","description":"A per transaction fee configured by card type (VI, MC, DI, AMEX, etc.) per API Partner's Contract other wise 0 (zero)","format":"double","nullable":true},"TotalCommissionRate":{"type":"number","description":"The Total percentage of Commissions that FrontStream takes from a given transaction.\r\nThis rate = Partner CommissionRate + FS CommissionRate","format":"double","nullable":true},"TotalCommissionAmount":{"type":"number","description":"The product of the transaction times the Total commission rate.","format":"double","nullable":true},"PartnerCommissionRate":{"type":"number","description":"The Partner Commission percentage taken on behalf of the Partner from a given transaction.","format":"double","nullable":true},"PartnerCommissionAmount":{"type":"number","description":"The product of the transaction times the Partner commission rate.","format":"double","nullable":true},"FsCommissionRate":{"type":"number","description":"The FrontStream Commission percentage that FrontStream takes from a given transaction.","format":"double","nullable":true},"FsCommissionAmount":{"type":"number","description":"The product of the transaction times the FrontStream commission rate.","format":"double","nullable":true},"TotalFees":{"type":"number","description":"The sum of all fees applied to a transaction amount. (TotalCommission + CardFee + FlatFee + CardFeeOnFee)","format":"double","nullable":true},"MaxOverridePartnerCommissionRate":{"type":"number","description":"The derived minimum partner override rate and maximum partner override rate\r\n\r\nMaxOverridePartnerCommissionRate = TotalFees = (PartnerCommission rate) + (Card Fee Rate) + (Fs Commission Rate)\r\nMinOverridePartnerCommissionRate = (Card Fee rate) + (Fs Commission rate)","format":"double"},"MinOverridePartnerCommissionRate":{"type":"number","format":"double"},"PerTransFee":{"type":"number","description":"The flat amount that will be taken from the PaymentAmount for any Per-Transaction Fees as configured in your contract.","format":"double","nullable":true},"Tip":{"type":"number","description":"The flat amount that will be paid out to the API Partner if Donor decides to add a tip regardless of payFee true or false.","format":"double"},"CardFeeOnFeeAmount":{"type":"number","format":"double","nullable":true},"Tax":{"type":"number","format":"double","nullable":true},"AchFeeRate":{"type":"number","description":"The ACH processing fee rate applied to this transaction.","format":"double","nullable":true},"AchFeeAmount":{"type":"number","description":"The ACH processing fee amount for this transaction.","format":"double","nullable":true}},"additionalProperties":false,"description":""}}}} ``` ## The FeeResponse object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"FeeResponse":{"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","nullable":true},"PaymentAmount":{"type":"number","description":"This is the amount charged to the donor. Will be equal to the sum of the Amount parameters if payFee=false, but if payFee=true, then this will be the amount that will be charged to the donor in order to have the net post-disbursement donation be equal to the Amount parameters.","format":"double","nullable":true},"CardFeeRate":{"type":"number","description":"example 2.5% - applied to EVERY donation. This is the FrontStream card processing fee. The percentage of the PaymentAmount that will be taken for credit card fees. Expressed as a human-readable percentage rather than a decimal value, it is intended to be able to be displayed directly on a page without needing to be converted.","format":"double","nullable":true},"CardFeeAmount":{"type":"number","description":"This is the amount that is owed to the gateway for the example 2.5% that FrontStream collects from the transaction.\r\n 2.5% of transaction amount if donor is not paying the fee, otherwise 2.5% of the transaction + card fee.","format":"double","nullable":true},"CardTypeFeeAmount":{"type":"number","description":"A per transaction fee configured by card type (VI, MC, DI, AMEX, etc.) per API Partner's Contract other wise 0 (zero)","format":"double","nullable":true},"TotalCommissionRate":{"type":"number","description":"The Total percentage of Commissions that FrontStream takes from a given transaction.\r\nThis rate = Partner CommissionRate + FS CommissionRate","format":"double","nullable":true},"TotalCommissionAmount":{"type":"number","description":"The product of the transaction times the Total commission rate.","format":"double","nullable":true},"PartnerCommissionRate":{"type":"number","description":"The Partner Commission percentage taken on behalf of the Partner from a given transaction.","format":"double","nullable":true},"PartnerCommissionAmount":{"type":"number","description":"The product of the transaction times the Partner commission rate.","format":"double","nullable":true},"FsCommissionRate":{"type":"number","description":"The FrontStream Commission percentage that FrontStream takes from a given transaction.","format":"double","nullable":true},"FsCommissionAmount":{"type":"number","description":"The product of the transaction times the FrontStream commission rate.","format":"double","nullable":true},"TotalFees":{"type":"number","description":"The sum of all fees applied to a transaction amount. (TotalCommission + CardFee + FlatFee + CardFeeOnFee)","format":"double","nullable":true},"MaxOverridePartnerCommissionRate":{"type":"number","description":"The derived minimum partner override rate and maximum partner override rate\r\n\r\nMaxOverridePartnerCommissionRate = TotalFees = (PartnerCommission rate) + (Card Fee Rate) + (Fs Commission Rate)\r\nMinOverridePartnerCommissionRate = (Card Fee rate) + (Fs Commission rate)","format":"double"},"MinOverridePartnerCommissionRate":{"type":"number","format":"double"},"PerTransFee":{"type":"number","description":"The flat amount that will be taken from the PaymentAmount for any Per-Transaction Fees as configured in your contract.","format":"double","nullable":true},"Tip":{"type":"number","description":"The flat amount that will be paid out to the API Partner if Donor decides to add a tip regardless of payFee true or false.","format":"double"},"CardFeeOnFeeAmount":{"type":"number","format":"double","nullable":true},"Tax":{"type":"number","format":"double","nullable":true},"AchFeeRate":{"type":"number","description":"The ACH processing fee rate applied to this transaction.","format":"double","nullable":true},"AchFeeAmount":{"type":"number","description":"The ACH processing fee amount for this transaction.","format":"double","nullable":true}},"additionalProperties":false,"description":""}}}} ``` ## The GetTokenAchRequest object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"GetTokenAchRequest":{"required":["CheckAccountNumber","CheckAccountTypeId","CheckRoutingNumber","CheckTypeId","City","Country","Email","NameOnCheck","Street"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"CheckRoutingNumber":{"maxLength":9,"type":"string","description":"required - Valid Check Bank Routing Number - formats -\r\nUS: Enter 9-digits,\r\nCA: Enter 9-digits (Format: 0YYYXXXXX: A mandatory leading zero. YYY: The 3-digit institution number. XXXXX: The 5-digit transit number),\r\nAU: Enter 6-digits - BSB Number (Bank State Branch) without hyphen"},"CheckAccountNumber":{"maxLength":20,"type":"string","description":"required - Valid Check Account Number - formats -\r\nUS: Enter 8-12 digits,\r\nCA: Enter 7-12 digits,\r\nAU: Enter 3-9 digits"},"CheckNumber":{"maxLength":10,"type":"string","description":"optional (max: 10) - Valid Check Number","nullable":true},"CheckAccountTypeId":{"type":"string","description":"required for Check ACH transactions - possible values -\r\n 1 - Checking,\r\n 2 - Saving"},"CheckTypeId":{"type":"string","description":"required for Check ACH transactions - possible values -\r\n 1 - Personal,\r\n 2 - Corporate,\r\n 3 - Government"},"NameOnCheck":{"maxLength":25,"type":"string","description":"required - Name on ACH Check Account"},"Email":{"maxLength":100,"type":"string","description":"required - valid contact email","format":"email"},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000","nullable":true},"Street":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing street"},"City":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing city"},"State":{"maxLength":50,"type":"string","description":"optional - 2 char US state code, 3 char may be used for other non-US","nullable":true},"Country":{"maxLength":2,"type":"string","description":"optional - 2 char country code"},"Currency":{"maxLength":3,"type":"string","description":"optional - 3 char currency code - Example for US - \"USD\", for CA - \"CAD\"","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ConstituentId per Product","nullable":true},"ExternalCustomerId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ArgoFire Gateway CustomerKey for pre-existing ArgoFire customers without a Payment API token record","nullable":true},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing First Name","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing Last Name","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"client ip address (max: 40) where transaction originates","nullable":true}},"additionalProperties":false}}}} ``` ## The GetTokenRequest object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"GetTokenRequest":{"required":["CardNum","City","Country","Email","ExpMonth","ExpYear","NameOnCard","Street"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"IntegrationSource":{"type":"string","description":"internal use","nullable":true},"CardNum":{"maxLength":30,"type":"string","description":"Valid Credit card number"},"CardType":{"maxLength":20,"type":"string","description":"optional (max: 20) - \"American Express\", \"Mastercard\", \"Visa\", \"Discover\", \"Diners Club\" - will be set internally based on cardNum","nullable":true},"ExpMonth":{"maxLength":2,"minLength":2,"type":"string","description":"example: \"01\" for January - required"},"ExpYear":{"maxLength":2,"minLength":2,"type":"string","description":"example: \"29\" for 2029 - required"},"CVNum":{"maxLength":4,"type":"string","description":"optional (max: 4) - valid CVV - please provide for CVV checks","nullable":true},"NameOnCard":{"maxLength":25,"type":"string","description":"required - Name on Card"},"Email":{"maxLength":100,"type":"string","description":"required - valid contact email","format":"email"},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - please provide for best interchange and avs checks - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000","nullable":true},"Street":{"maxLength":50,"type":"string","description":"required - please provide for best interchange and avs checks"},"City":{"maxLength":50,"type":"string","description":"required - please provide for best interchange and avs checks"},"State":{"maxLength":50,"type":"string","description":"optional - 2 char US state code, 3 char may be used for other non-US","nullable":true},"Country":{"maxLength":2,"type":"string","description":"required - 2 char country code"},"Currency":{"maxLength":3,"type":"string","description":"optional - 3 char currency code - Example for US - \"USD\", for CA - \"CAD\"","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ConstituentId per Product","nullable":true},"ExternalCustomerId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ArgoFire Gateway CustomerKey for pre-existing ArgoFire customers without a Payment API token record","nullable":true},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing First Name","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing Last Name","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"client ip address (max: 40) where transaction originates","nullable":true}},"additionalProperties":false,"description":""}}}} ``` ## The GetTokenResponse object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"GetTokenResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"This is \"true\" tokenization process was successful, and \"false\" if unsuccessful."},"Message":{"type":"string","description":"Get Token response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Get Token Processor response message","nullable":true},"TransactionId":{"type":"string","description":"Not currently used and may be null","nullable":true},"TokenGuid":{"type":"string","description":"The unique GUID associated with the credit card or bank token you created that is used with the api/paymentToken endpoint","format":"uuid"},"ExternalCardToken":{"type":"string","description":"ExternalCardToken if available to return - represents 3rd party gateway card token","nullable":true},"ExternalCheckToken":{"type":"string","description":"ExternalCheckToken if available to return - represents 3rd party gateway check token","nullable":true},"ExternalCustomerId":{"type":"string","description":"ExternalCustomerId if available to return - represents 3rd party gateway customer id tied to gateway token","nullable":true},"ExternalConstituentId":{"type":"string","description":"Partner's constituent/donor id provided at tokenize time","nullable":true},"ResponseCode":{"type":"string","description":"Response Code - Successful = \"OK\" or \"0\", any other response code unsuccessful","nullable":true}},"additionalProperties":false,"description":""}}}} ``` ## The NextBillDateResponse object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"NextBillDateResponse":{"type":"object","properties":{"NextBillDate":{"type":"string","description":"Response Format Example:\r\n\"NextBillDate\": \"2029-07-23TT00:00:00\"","format":"date-time"}},"additionalProperties":false,"description":""}}}} ``` ## The NotificationConfigurationDto object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"NotificationConfigurationDto":{"type":"object","properties":{"NotificationConfigId":{"type":"integer","format":"int32"},"NotificationConfigType":{"$ref":"#/components/schemas/NotificationConfigurationTypeDto"},"NotificationProtocolType":{"$ref":"#/components/schemas/NotificationProtocolTypeDto"},"IntegrationSourceId":{"type":"integer","format":"int32"},"NotificationUrl":{"type":"string","nullable":true},"NotificationEmailTo":{"type":"string","nullable":true},"NotificationEmailFrom":{"type":"string","nullable":true},"AccessToken":{"type":"string","nullable":true},"Retries":{"type":"integer","format":"int32"},"CreatedDate":{"type":"string","format":"date-time"},"ModifiedDate":{"type":"string","format":"date-time","nullable":true},"IsDeleted":{"type":"boolean"}},"additionalProperties":false},"NotificationConfigurationTypeDto":{"enum":[1,2,3,4,5,6,7,8],"type":"integer","format":"int32"},"NotificationProtocolTypeDto":{"enum":[1,2],"type":"integer","format":"int32"}}}} ``` ## The NotificationConfigurationTypeDto object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"NotificationConfigurationTypeDto":{"enum":[1,2,3,4,5,6,7,8],"type":"integer","format":"int32"}}}} ``` ## The NotificationProtocolTypeDto object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"NotificationProtocolTypeDto":{"enum":[1,2],"type":"integer","format":"int32"}}}} ``` ## The NotificationsResponse object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"NotificationsResponse":{"type":"object","properties":{"NotificationId":{"type":"integer","description":"Notification Id","format":"int32"},"NotificationGuid":{"type":"string","description":"Unique Notification identifier","format":"uuid"},"NotificationConfigId":{"type":"integer","description":"Notification Configuration Id set up per Integration Source","format":"int32"},"CreatedDate":{"type":"string","description":"Notification Created date","format":"date-time"},"ModifiedDate":{"type":"string","format":"date-time","nullable":true},"Payload":{"type":"string","description":"Notification payload sent out for transaction status","nullable":true},"RetryCount":{"type":"integer","description":"Number of retry attempts to send Notification payload to configured Notification URL","format":"int32","nullable":true},"Postdate":{"type":"string","description":"if available - the date the Notification was posted to configured Notification URL successfully","format":"date-time","nullable":true},"NotificationStatus":{"$ref":"#/components/schemas/NotificationStatus"},"NotificationUrl":{"type":"string","description":"Url configure to post notifications to. The Integration Source endpoint to post notification payload to.","nullable":true},"PaymentId":{"type":"integer","description":"Payment API PaymentId associated with the Notification","format":"int32","nullable":true},"PaymentExternalId":{"type":"string","description":"Payment API PaymentExternalId associated with the Notification","nullable":true}},"additionalProperties":false},"NotificationStatus":{"enum":[1,2,3,4,5],"type":"integer","format":"int32"}}}} ``` ## The NotificationStatus object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"NotificationStatus":{"enum":[1,2,3,4,5],"type":"integer","format":"int32"}}}} ``` ## The PayLinkPaymentLine object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"PayLinkPaymentLine":{"required":["Recurring","Type"],"type":"object","properties":{"Amount":{"maxLength":7,"type":"string","description":"optional - transaction amount. If amount is not provided and single payment line, the amount field will be editable for input on form (range $0.01 to $99,999.99)","nullable":true},"Type":{"type":"integer","description":"required - Payment type identifier - possible values -\r\n 1 - Donation Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 12 - PaymentNoFee;","format":"int32"},"Recurring":{"type":"integer","description":"required - Indicates if the payment is recurring and billing frequency - possible values -\r\n 0 - Not recurring,\r\n 1 - Daily,\r\n 2 - Weekly,\r\n 3 - Bi-Weekly,\r\n 4 - Monthly,\r\n 5 - Bi-Monthly,\r\n 6 - Quarterly,\r\n 7 - Semi-Annually,\r\n 8 - Annually\r\n 9 - Semi-Monthly","format":"int32"},"ExternalLineId":{"maxLength":100,"type":"string","description":"optional (max: 100) - use this to track individual line item IDs if necessary.","nullable":true}},"additionalProperties":false}}}} ``` ## The PayLinkRequest object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"PayLinkRequest":{"required":["ApiKey","RedirectUrl"],"type":"object","properties":{"ApiKey":{"type":"string","description":"required - Your API key for pay link authentication."},"ProcessorGuid":{"type":"string","description":"optional - Identifies Processor being used by an API Partner","nullable":true},"IntegrationSource":{"type":"string","description":"optional and internal use - Identifies integrated Product","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"client ip address where transaction originates","nullable":true},"RedirectUrl":{"maxLength":500,"type":"string","description":"required - The URL to which the user will be redirected after payment."},"PaymentLines":{"type":"array","items":{"$ref":"#/components/schemas/PayLinkPaymentLine"},"description":"optional - An array of payment line objects specifying amounts and types. Required unless WorkflowType is \"UpdateToken\".","nullable":true},"TranId":{"maxLength":100,"type":"string","description":"optional (max: 100) for API Partner Reference or Invoice number and Dup Checking - unique id per Integration Source transaction (where integration source has DupCheckEnabled) that will be checked against successfully processed prior TranIds for Duplicates","nullable":true},"ShowTransactionId":{"type":"boolean","description":"optional - 'True' will display the TranId on the checkout form. If set 'True' and optional TranId is not set, our form will allow for input to set TranId in form UI","nullable":true},"TransactionIdText":{"maxLength":100,"type":"string","description":"optional (max: 100) - The text to display in front of the TranId. Example: Invoice#:","nullable":true},"PoweredByText":{"maxLength":100,"type":"string","description":"optional (max: 100) - Text to display for branding purposes (e.g., \"Powered by Your Company\"). If not provided, defaults to the Integration Source Application name configured that created the Pay link. Otherwise, defaults to \"FrontStream\"","nullable":true},"PoweredByUrl":{"maxLength":500,"type":"string","description":"optional (max: 500) - a valid URL users will be directed to when clicking the PoweredByText usually your Company URL. If not provided, defaults to https://www.frontstream.com","nullable":true},"DonateButtonText":{"maxLength":100,"type":"string","description":"optional (max: 100) - Text displayed on the submit payment button. Default is \"Submit Payment\".","nullable":true},"Language":{"maxLength":35,"type":"string","description":"optional (max: 35) - The language of the pay link session. Default is \"en\" for english.","nullable":true},"DefaultCountryCode":{"maxLength":2,"type":"string","description":"optional - 2 char country code. The default country code for user input. Example: \"US\".","nullable":true},"Theme":{"maxLength":5000,"type":"string","description":"optional (max: 5000) - CSS string for custom styling of the embedded session. Example: \".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)}\"","nullable":true},"ThemeFonts":{"maxItems":50,"type":"array","items":{"type":"string"},"description":"optional - Array of fonts to be used in the session. example: \"\"Open Sans:400,500,600,700 \",\"Montserrat:400, 700 \",\"Roboto:400, 700 \".","nullable":true},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - if set, this FirstName will display in payment form","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - if set, this LastName will display in payment form","nullable":true},"Email":{"maxLength":100,"type":"string","description":"option (max: 100) - valid contact email - - if set, this Email will display in payment form","format":"email","nullable":true},"Street":{"maxLength":50,"type":"string","description":"optional (max: 50) - if set, this Street will display in payment form","nullable":true},"City":{"maxLength":50,"type":"string","description":"optional (max: 50) - if set, this City will display in payment form","nullable":true},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000 - if set, this Zip will display in payment form","nullable":true},"State":{"maxLength":50,"type":"string","description":"optional - 2 char US state code, 3 char may be used for other non-US - if set, this State will display in payment form","nullable":true},"Country":{"maxLength":2,"type":"string","description":"optional - 2 char country code - if set, this Country will display in payment form","nullable":true},"Phone":{"maxLength":20,"type":"string","description":"optional (max: 20) - valid North America and AU patterns currently supported: 123-456-7890, (123) 456-7890, 123.456.7890, +12025550123, 1234567890, 0412345678, +61412345678","nullable":true},"TokenizeCard":{"type":"boolean","description":"optional - set to true to tokenize card or check at time of purchase","nullable":true},"TokenGuid":{"type":"string","description":"optional - TokenGuid to use to process transaction in payment form. If using ExternalCardToken or ExternalCheckToken instead of TokenGuid - Valid Token Guid from a Tokenized card through Embedded Payment Form/Payment API","nullable":true},"ExternalCardToken":{"maxLength":200,"type":"string","description":"optional (max: 200) - Customer credit card token generated outside the Embedded Form (e.g. ArgoFire). ExternalCardToken to use to process transaction in payment form.","nullable":true},"ExternalCheckToken":{"maxLength":200,"type":"string","description":"optional (max: 200) - Customer check token generated outside the Embedded Form (e.g. ArgoFire). ExternalCheckToken to use to process transaction in payment form.","nullable":true},"ExternalEventId":{"maxLength":10,"type":"string","description":"optional (max: 10) - Customer Event Id","nullable":true},"ExternalEventName":{"maxLength":500,"type":"string","description":"optional (max: 500) - Customer Event Name","nullable":true},"WorkflowType":{"type":"integer","description":"optional - future use - Workflow type for the session. Valid values: 3 (TokenPayment), 4 (ManageTokens).\r\nUse 3 to tokenize a card for an existing constituent without processing a payment.\r\nUse 4 for full card wallet management (list, add, delete).","format":"int32","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - The merchant's internal customer/client ID. When provided with WorkflowType=\"UpdateToken\", links the new card token to the customer/client's existing ArgoFire customer record.","nullable":true},"ExternalCustomerId":{"maxLength":200,"type":"string","description":"optional (max: 200) - The processor-generated CustomerKey for a pre-existing customer record. When provided with ExternalConstituentId, links the payment session to the existing processor customer record instead of creating a new one.","nullable":true}},"additionalProperties":false},"PayLinkPaymentLine":{"required":["Recurring","Type"],"type":"object","properties":{"Amount":{"maxLength":7,"type":"string","description":"optional - transaction amount. If amount is not provided and single payment line, the amount field will be editable for input on form (range $0.01 to $99,999.99)","nullable":true},"Type":{"type":"integer","description":"required - Payment type identifier - possible values -\r\n 1 - Donation Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 12 - PaymentNoFee;","format":"int32"},"Recurring":{"type":"integer","description":"required - Indicates if the payment is recurring and billing frequency - possible values -\r\n 0 - Not recurring,\r\n 1 - Daily,\r\n 2 - Weekly,\r\n 3 - Bi-Weekly,\r\n 4 - Monthly,\r\n 5 - Bi-Monthly,\r\n 6 - Quarterly,\r\n 7 - Semi-Annually,\r\n 8 - Annually\r\n 9 - Semi-Monthly","format":"int32"},"ExternalLineId":{"maxLength":100,"type":"string","description":"optional (max: 100) - use this to track individual line item IDs if necessary.","nullable":true}},"additionalProperties":false}}}} ``` ## The PayLinkResponse object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"PayLinkResponse":{"type":"object","properties":{"PayLinkUrl":{"type":"string","description":"a unique URL that when clicked, direct users to our FrontStream secure online payment page","nullable":true}},"additionalProperties":false}}}} ``` ## The PaymentAchRequest object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"PaymentAchRequest":{"required":["CheckAccountNumber","CheckAccountTypeId","CheckRoutingNumber","CheckTypeId","Email","IpAddress","NameOnCheck","State","Transactions"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"MKey":{"maxLength":500,"type":"string","description":"internal use - Used by FrontStream only","nullable":true},"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"CheckRoutingNumber":{"maxLength":9,"type":"string","description":"required - Valid Check Bank Routing Number - formats -\r\nUS: Enter 9-digits,\r\nCA: Enter 9-digits (Format: 0YYYXXXXX: A mandatory leading zero. YYY: The 3-digit institution number. XXXXX: The 5-digit transit number),\r\nAU: Enter 6-digits - BSB Number (Bank State Branch) without hyphen"},"CheckAccountNumber":{"maxLength":20,"type":"string","description":"required - Valid Check Account Number - formats -\r\nUS: Enter 8-12 digits,\r\nCA: Enter 7-12 digits,\r\nAU: Enter 3-9 digits"},"CheckNumber":{"maxLength":10,"type":"string","description":"optional (max: 10) - Valid Check Number","nullable":true},"CheckAccountTypeId":{"type":"string","description":"required for Check ACH transactions - possible values -\r\n 1 - Checking,\r\n 2 - Savings"},"CheckTypeId":{"type":"string","description":"required for Check ACH transactions - possible values -\r\n 1 - Personal,\r\n 2 - Corporate,\r\n 3 - Government"},"NameOnCheck":{"maxLength":25,"type":"string","description":"required - Name on ACH Check Account"},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000","nullable":true},"Street":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing street","nullable":true},"Email":{"maxLength":100,"type":"string","description":"required - valid contact email","format":"email"},"City":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing city","nullable":true},"State":{"maxLength":50,"type":"string","description":"required - 2 char US state code, 3 char may be used for other non-US"},"Country":{"maxLength":2,"type":"string","description":"optional - 2 char country code","nullable":true},"Currency":{"maxLength":3,"type":"string","description":"optional - 3 char currency code - Example for US - \"USD\", for CA - \"CAD\"","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - Donor Identifier per Product","nullable":true},"ExternalCustomerId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ArgoFire Gateway CustomerKey for pre-existing ArgoFire customers without a Payment API token record","nullable":true},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing First Name","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing Last Name","nullable":true},"BillingDescriptor":{"maxLength":22,"type":"string","description":"optional (max: 22) - descriptor to show on bank statement","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"required - client ip address where transaction originates"},"ExternalEventId":{"maxLength":10,"type":"string","description":"optional (max: 10) - Event Identifier per Product","nullable":true},"ExternalEventGuid":{"type":"string","description":"optional - Event Guid per Product","nullable":true},"ExternalEventName":{"maxLength":500,"type":"string","description":"optional (max: 500) - Event Name per Product","nullable":true},"ShippingFee":{"maxLength":7,"type":"string","description":"optional (max: 7) - fee for shipping that will be added to the total amount","nullable":true},"TaxableBenefit":{"maxLength":7,"type":"string","description":"optional (max: 7) - If part of the donation being passed in is taxable, include that amount here. No calculations are performed using this value, it is simply a placeholder to be used for your own reporting; all commission and credit card fees still apply as normal.","nullable":true},"TranId":{"maxLength":100,"type":"string","description":"optional (max: 100) - system unique id for Dup Checking per Integration Source transaction (where integration source has DupCheckEnabled) that will be checked against successfully processed prior TranIds for Duplicates","nullable":true},"EpfSessionId":{"type":"string","description":"internal use - FrontStream unique Embedded Payment Form Session Id if available","nullable":true},"Transactions":{"type":"array","items":{"$ref":"#/components/schemas/PaymentTransTypeRequest"},"description":"required - 1 to n transactions to break down transaction line items"},"PaymentMethodTypeId":{"type":"string","description":"optional - if used please set to 7 for ACH or will be set internally","nullable":true},"Tokenize":{"type":"boolean","description":"optional - set to true to tokenize check at time of purchase","nullable":true}},"additionalProperties":false},"PaymentTransTypeRequest":{"required":["Amount","TransactionSourceGroupId"],"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","description":"required - For Direct Merchant (For Profit) Api Partners should set to PaymentNoFee (12), other values are for Non Profit transactions - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;\r\n 13 - EventDonationFee;\r\n 14 - SponsorshipFee\r\n 15 - MembershipFee"},"Amount":{"maxLength":7,"type":"string","description":"required - Amount of line item without the fees included, Payment api will calculate fees for you"},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction. Indicates if the donor intends to cover the processing fees for the donation (primary used for Non Profit transactions like a donation)"},"CommissionRateOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - The percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract.","nullable":true},"CardProcessingFeeOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - Overrides the default percentage processing fee","nullable":true},"ExternalLineId":{"maxLength":100,"type":"string","description":"optional (max: 100) - use this to track individual line item IDs if necessary.","nullable":true},"Tip":{"maxLength":7,"type":"string","description":"optional (max: 7) - An amount taken up front for the API Partner if Donor decides to apply a tip. Added to the total amount to charge on the donor’s card . Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true},"Tax":{"maxLength":7,"type":"string","description":"optional (max: 7) - A tax amount taken up front. Added to the total amount to charge on the donor’s card. Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true}},"additionalProperties":false,"description":""}}}} ``` ## The PaymentExportReportRequest object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"PaymentExportReportRequest":{"type":"object","properties":{"Filters":{"type":"array","items":{"$ref":"#/components/schemas/SelectedConstraintDto"},"description":"Report Filters","nullable":true},"SortColumns":{"type":"array","items":{"$ref":"#/components/schemas/SortColumnDto"},"description":"Sort Columns","nullable":true},"PageSize":{"type":"integer","description":"How many records to return per page.","format":"int32"},"PageIndex":{"type":"integer","description":"Which page of results to return. Starts at 1 (0 will also return the first page)","format":"int32"},"Format":{"type":"string","description":"Determines which file type the report will be exported to. Valid values: \"csv\" or \"excel\"","nullable":true}},"additionalProperties":false,"description":""},"SelectedConstraintDto":{"type":"object","properties":{"Name":{"type":"string","nullable":true},"Operation":{"$ref":"#/components/schemas/ConstraintOperation"},"Values":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false},"ConstraintOperation":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23],"type":"integer","format":"int32"},"SortColumnDto":{"type":"object","properties":{"Name":{"type":"string","nullable":true},"Descending":{"type":"boolean"},"Order":{"type":"integer","format":"int32"}},"additionalProperties":false}}}} ``` ## The PaymentMethodTypeEnum object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"PaymentMethodTypeEnum":{"enum":[0,1,2,3,4,5,6,7,8,9,10],"type":"integer","format":"int32"}}}} ``` ## The PaymentMethodTypeResponse object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"PaymentMethodTypeResponse":{"type":"object","properties":{"PaymentMethodTypeId":{"$ref":"#/components/schemas/PaymentMethodTypeEnum"},"PaymentMethodTypeValue":{"type":"string","description":"possible values :\r\n\"NONE\" = 0,\r\n\"AMEX\" = 1,\r\n\"MASTERCARD\" = 2,\r\n\"VISA\" = 3,\r\n\"DISCOVER\" = 4,\r\n\"DINERSCLUB\" = 5,\r\n\"JCB\" = 6,\r\n\"ACH\" = 7,\r\n\"GOOGLEPAY\" = 8,\r\n\"APPLEPAY\" = 9\r\n\"STRIPE\" = 10","nullable":true}},"additionalProperties":false},"PaymentMethodTypeEnum":{"enum":[0,1,2,3,4,5,6,7,8,9,10],"type":"integer","format":"int32"}}}} ``` ## The PaymentReportRequest object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"PaymentReportRequest":{"type":"object","properties":{"Filters":{"type":"array","items":{"$ref":"#/components/schemas/SelectedConstraintDto"},"description":"Report Filters","nullable":true},"SortColumns":{"type":"array","items":{"$ref":"#/components/schemas/SortColumnDto"},"description":"Sort Columns","nullable":true},"PageSize":{"type":"integer","description":"How many records to return per page.","format":"int32"},"PageIndex":{"type":"integer","description":"Which page of results to return. Starts at 1 (0 will also return the first page)","format":"int32"}},"additionalProperties":false,"description":""},"SelectedConstraintDto":{"type":"object","properties":{"Name":{"type":"string","nullable":true},"Operation":{"$ref":"#/components/schemas/ConstraintOperation"},"Values":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false},"ConstraintOperation":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23],"type":"integer","format":"int32"},"SortColumnDto":{"type":"object","properties":{"Name":{"type":"string","nullable":true},"Descending":{"type":"boolean"},"Order":{"type":"integer","format":"int32"}},"additionalProperties":false}}}} ``` ## The PaymentRequest object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"PaymentRequest":{"required":["Email","IpAddress","NameOnCard","Transactions"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"MKey":{"maxLength":500,"type":"string","description":"internal use - Used by FrontStream only","nullable":true},"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"CardNum":{"maxLength":30,"type":"string","description":"optional - Valid Credit card number - required for non-Wallet transaction","nullable":true},"CardType":{"maxLength":20,"type":"string","description":"optional (max: 20) - \"American Express\", \"Mastercard\", \"Visa\", \"Discover\", \"Diners Club\" - will be set internally based on cardNum","nullable":true},"ExpMonth":{"maxLength":2,"type":"string","description":"optional (max: 2) - example: \"01\" for January - required for non-Wallet transaction","nullable":true},"ExpYear":{"maxLength":2,"type":"string","description":"optional (max: 2) - example: \"29\" for 2029 - required for non-Wallet transaction","nullable":true},"CVNum":{"maxLength":4,"type":"string","description":"optional (max: 4) - valid CVV - please provide for CVV checks","nullable":true},"NameOnCard":{"maxLength":25,"type":"string","description":"required - Name on Card"},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - please provide for best interchange and avs checks - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000","nullable":true},"Street":{"maxLength":50,"type":"string","description":"optional (max: 50) - please provide for best interchange and avs checks","nullable":true},"Email":{"maxLength":100,"type":"string","description":"required - valid contact email","format":"email"},"City":{"maxLength":50,"type":"string","description":"optional (max: 50) - please provide for best interchange and avs checks","nullable":true},"State":{"maxLength":50,"type":"string","description":"optional - 2 char US state code, 3 char may be used for other non-US","nullable":true},"Country":{"maxLength":2,"type":"string","description":"optional (max: 2) - 2 char country code","nullable":true},"Currency":{"maxLength":3,"type":"string","description":"optional (max: 3) - 3 char currency code - Example for US - \"USD\", for CA - \"CAD\"","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - Donor Identifier per Product","nullable":true},"ExternalCustomerId":{"maxLength":200,"type":"string","description":"optional (max: 200) - ArgoFire Gateway CustomerKey for pre-existing ArgoFire customers without a Payment API token record","nullable":true},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing First Name","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing Last Name","nullable":true},"BillingDescriptor":{"maxLength":22,"type":"string","description":"optional (max: 22) - descriptor to show on bank statement","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"required - client ip address where transaction originates"},"ExternalEventId":{"maxLength":10,"type":"string","description":"optional (max: 10) - Event Identifier per Product","nullable":true},"ExternalEventGuid":{"type":"string","description":"optional - Event Guid per Product","nullable":true},"ExternalEventName":{"maxLength":500,"type":"string","description":"optional (max: 500) - Event Name per Product","nullable":true},"ShippingFee":{"maxLength":7,"type":"string","description":"optional (max: 7) - fee for shipping that will be added to the total amount","nullable":true},"TaxableBenefit":{"maxLength":7,"type":"string","description":"optional (max: 7) - If part of the donation being passed in is taxable, include that amount here. No calculations are performed using this value, it is simply a placeholder to be used for your own reporting; all commission and credit card fees still apply as normal.","nullable":true},"TranId":{"maxLength":100,"type":"string","description":"optional (max: 100) - system unique id for Dup Checking per Integration Source transaction (where integration source has DupCheckEnabled) that will be checked against successfully processed prior TranIds for Duplicates","nullable":true},"EpfSessionId":{"type":"string","description":"internal use - FrontStream unique Embedded Payment Form Session Id if available","nullable":true},"Transactions":{"type":"array","items":{"$ref":"#/components/schemas/PaymentTransTypeRequest"},"description":"required - 1 to n transactions to break down transaction line items"},"AFShieldAdditional":{"$ref":"#/components/schemas/AFShieldPaymentRequest"},"PaymentMethodTypeId":{"type":"string","description":"internal use - GooglePay (8) or Apple Pay (9) - possible values -\r\n \"8\" - GOOGLEPAY,\r\n \"9\" - APPLEPAY","nullable":true},"ExternalPaymentData":{"maxLength":5000,"type":"string","description":"internal use for Wallet transactions","nullable":true},"Surcharge":{"maxLength":7,"type":"string","description":"optional (max: 7) - calculated surcharge amount that will be added to the total amount","nullable":true},"Tokenize":{"type":"boolean","description":"optional - set to true to tokenize card at time of purchase","nullable":true}},"additionalProperties":false,"description":""},"PaymentTransTypeRequest":{"required":["Amount","TransactionSourceGroupId"],"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","description":"required - For Direct Merchant (For Profit) Api Partners should set to PaymentNoFee (12), other values are for Non Profit transactions - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;\r\n 13 - EventDonationFee;\r\n 14 - SponsorshipFee\r\n 15 - MembershipFee"},"Amount":{"maxLength":7,"type":"string","description":"required - Amount of line item without the fees included, Payment api will calculate fees for you"},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction. Indicates if the donor intends to cover the processing fees for the donation (primary used for Non Profit transactions like a donation)"},"CommissionRateOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - The percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract.","nullable":true},"CardProcessingFeeOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - Overrides the default percentage processing fee","nullable":true},"ExternalLineId":{"maxLength":100,"type":"string","description":"optional (max: 100) - use this to track individual line item IDs if necessary.","nullable":true},"Tip":{"maxLength":7,"type":"string","description":"optional (max: 7) - An amount taken up front for the API Partner if Donor decides to apply a tip. Added to the total amount to charge on the donor’s card . Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true},"Tax":{"maxLength":7,"type":"string","description":"optional (max: 7) - A tax amount taken up front. Added to the total amount to charge on the donor’s card. Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true}},"additionalProperties":false,"description":""},"AFShieldPaymentRequest":{"type":"object","properties":{"ProductDescription":{"maxLength":256,"type":"string","nullable":true},"ProductItem":{"maxLength":256,"type":"string","nullable":true},"ProductType":{"maxLength":256,"type":"string","nullable":true},"ProductQuantity":{"maxLength":3,"type":"string","nullable":true},"SessionId":{"maxLength":32,"type":"string","nullable":true},"BillToPhoneNumber":{"maxLength":32,"type":"string","nullable":true},"ShippingAddressStreet1":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressStreet2":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressCountry":{"maxLength":2,"type":"string","nullable":true},"ShippingAddressCity":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressEmail":{"maxLength":64,"type":"string","format":"email","nullable":true},"ShippingAddressName":{"maxLength":64,"type":"string","nullable":true},"ShippingAddressZip":{"maxLength":10,"type":"string","nullable":true},"ShippingAddressState":{"maxLength":50,"type":"string","nullable":true},"ShipToPhoneNumber":{"maxLength":32,"type":"string","nullable":true},"ShipToPremiseForUK":{"maxLength":256,"type":"string","nullable":true},"ShipToStreetForUK":{"maxLength":256,"type":"string","nullable":true},"BillToPremiseForUK":{"maxLength":256,"type":"string","nullable":true},"BillToStreetForUK":{"maxLength":256,"type":"string","nullable":true}},"additionalProperties":false,"description":""}}}} ``` ## The PaymentResponse object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"PaymentResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"As one would guess, this is \"true\" if the transaction was processed successfully, and \"false\" if the transaction was not processed successfully."},"Message":{"type":"string","description":"Payment Gateway response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Response from the processing bank.","nullable":true},"AuthCode":{"type":"string","description":"AuthCode from the processor.","nullable":true},"TransactionId":{"type":"string","description":"Payment Gateway TransactionId","nullable":true},"PaymentGuid":{"type":"string","description":"Payment API Payment GUID","format":"uuid"},"PaymentId":{"type":"integer","description":"Payment API Payment Id","format":"int32"},"ResponseCode":{"type":"string","description":"Response Code - Approved = 0, Not processed = -100 with more possible values - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"PaymentResult":{"$ref":"#/components/schemas/PaymentResult"},"ProcessStatus":{"$ref":"#/components/schemas/ProcessStatus"},"TotalAmount":{"type":"number","description":"The total amount processed toward the cardholder's account.","format":"double"},"TotalSurcharge":{"type":"number","description":"The total surcharge amount if available.","format":"double","nullable":true},"AVSStreetStatus":{"type":"string","description":"Address Verification Street Status if available.","nullable":true},"AVSZipStatus":{"type":"string","description":"Address Verification Zip Status if available.","nullable":true},"AVSResponse":{"type":"string","description":"Address Verification Response if available. AVS and CVV response values covered more here - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"CVVResponse":{"type":"string","description":"Card Verification Response if available. AVS and CVV response values covered more here - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"ExternalCardToken":{"type":"string","description":"ExternalCardToken if available to return - represents 3rd party gateway card token","nullable":true},"ExternalCheckToken":{"type":"string","description":"ExternalCheckToken if available to return - represents 3rd party gateway check token","nullable":true},"ExternalCustomerId":{"type":"string","description":"ExternalCustomerId if available to return - represents 3rd party gateway customer id tied to gateway token","nullable":true},"ExternalConstituentId":{"type":"string","description":"ExternalConstituentId if available to return - merchant-supplied constituent/donor id linked to this token","nullable":true},"TokenGuid":{"type":"string","description":"Payment API Token GUID if available to return","format":"uuid","nullable":true},"TransactionFees":{"type":"array","items":{"$ref":"#/components/schemas/FeeResponse"},"description":"Fee Response","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use","format":"uuid"},"ProcessorGuid":{"type":"string","description":"ProcessorGuid used","format":"uuid","nullable":true},"FirstName":{"type":"string","nullable":true},"LastName":{"type":"string","nullable":true},"EmailAddress":{"type":"string","nullable":true},"PostalCode":{"type":"string","nullable":true},"AddressLine1":{"type":"string","nullable":true},"City":{"type":"string","nullable":true},"ProvinceCode":{"type":"string","nullable":true},"CountryCode":{"type":"string","nullable":true},"CardNum":{"type":"string","description":"last 4 digits of card","nullable":true},"CardType":{"type":"string","description":"possible values if available: American Express, Mastercard, Visa, Discover, Diners Club, Undefined","nullable":true},"ExpMonth":{"type":"string","nullable":true},"ExpYear":{"type":"string","nullable":true},"Currency":{"type":"string","nullable":true},"PaymentMethodTypeId":{"type":"integer","description":"possible values if available:\r\nNone = 0,\r\nAmericanExpress = 1,\r\nMasterCard = 2,\r\nVisa = 3,\r\nDiscover = 4,\r\nDinersClub = 5,\r\nACH = 7,\r\nGOOGLEPAY = 8,\r\nAPPLEPAY = 9","format":"int32","nullable":true},"IsSurchargeEligible":{"type":"boolean","description":"Was card used Surcharge eligible","nullable":true},"CheckAccountNum":{"type":"string","description":"last 4 digits of check account","nullable":true},"TranId":{"type":"string","description":"unique tran id per Integration Source if available","nullable":true},"EpfSessionId":{"type":"string","description":"FrontStream unique Embedded Payment Form Session Id if available","nullable":true},"PaymentDate":{"type":"string","description":"Payment Date of transaction","format":"date-time"}},"additionalProperties":false,"description":"See more response code definitions here: https://developers.frontstream.com/welcome-to-our-payment-api/api-references/test-payment-api-features/response-codes"},"PaymentResult":{"enum":[1,2,3,4,5,6],"type":"integer","format":"int32"},"ProcessStatus":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12],"type":"integer","format":"int32"},"FeeResponse":{"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","nullable":true},"PaymentAmount":{"type":"number","description":"This is the amount charged to the donor. Will be equal to the sum of the Amount parameters if payFee=false, but if payFee=true, then this will be the amount that will be charged to the donor in order to have the net post-disbursement donation be equal to the Amount parameters.","format":"double","nullable":true},"CardFeeRate":{"type":"number","description":"example 2.5% - applied to EVERY donation. This is the FrontStream card processing fee. The percentage of the PaymentAmount that will be taken for credit card fees. Expressed as a human-readable percentage rather than a decimal value, it is intended to be able to be displayed directly on a page without needing to be converted.","format":"double","nullable":true},"CardFeeAmount":{"type":"number","description":"This is the amount that is owed to the gateway for the example 2.5% that FrontStream collects from the transaction.\r\n 2.5% of transaction amount if donor is not paying the fee, otherwise 2.5% of the transaction + card fee.","format":"double","nullable":true},"CardTypeFeeAmount":{"type":"number","description":"A per transaction fee configured by card type (VI, MC, DI, AMEX, etc.) per API Partner's Contract other wise 0 (zero)","format":"double","nullable":true},"TotalCommissionRate":{"type":"number","description":"The Total percentage of Commissions that FrontStream takes from a given transaction.\r\nThis rate = Partner CommissionRate + FS CommissionRate","format":"double","nullable":true},"TotalCommissionAmount":{"type":"number","description":"The product of the transaction times the Total commission rate.","format":"double","nullable":true},"PartnerCommissionRate":{"type":"number","description":"The Partner Commission percentage taken on behalf of the Partner from a given transaction.","format":"double","nullable":true},"PartnerCommissionAmount":{"type":"number","description":"The product of the transaction times the Partner commission rate.","format":"double","nullable":true},"FsCommissionRate":{"type":"number","description":"The FrontStream Commission percentage that FrontStream takes from a given transaction.","format":"double","nullable":true},"FsCommissionAmount":{"type":"number","description":"The product of the transaction times the FrontStream commission rate.","format":"double","nullable":true},"TotalFees":{"type":"number","description":"The sum of all fees applied to a transaction amount. (TotalCommission + CardFee + FlatFee + CardFeeOnFee)","format":"double","nullable":true},"MaxOverridePartnerCommissionRate":{"type":"number","description":"The derived minimum partner override rate and maximum partner override rate\r\n\r\nMaxOverridePartnerCommissionRate = TotalFees = (PartnerCommission rate) + (Card Fee Rate) + (Fs Commission Rate)\r\nMinOverridePartnerCommissionRate = (Card Fee rate) + (Fs Commission rate)","format":"double"},"MinOverridePartnerCommissionRate":{"type":"number","format":"double"},"PerTransFee":{"type":"number","description":"The flat amount that will be taken from the PaymentAmount for any Per-Transaction Fees as configured in your contract.","format":"double","nullable":true},"Tip":{"type":"number","description":"The flat amount that will be paid out to the API Partner if Donor decides to add a tip regardless of payFee true or false.","format":"double"},"CardFeeOnFeeAmount":{"type":"number","format":"double","nullable":true},"Tax":{"type":"number","format":"double","nullable":true},"AchFeeRate":{"type":"number","description":"The ACH processing fee rate applied to this transaction.","format":"double","nullable":true},"AchFeeAmount":{"type":"number","description":"The ACH processing fee amount for this transaction.","format":"double","nullable":true}},"additionalProperties":false,"description":""}}}} ``` ## The PaymentResult object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"PaymentResult":{"enum":[1,2,3,4,5,6],"type":"integer","format":"int32"}}}} ``` ## The PaymentTokenRequest object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"PaymentTokenRequest":{"required":["Transactions"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"TokenGuid":{"type":"string","description":"optional if using ExternalCardToken or ExternalCheckToken instead of TokenGuid - Valid Token Guid from a Tokenized card through Payment API","nullable":true},"ExternalCardToken":{"maxLength":200,"type":"string","description":"internal use","nullable":true},"ExternalCheckToken":{"maxLength":200,"type":"string","description":"internal use","nullable":true},"TranId":{"maxLength":100,"type":"string","description":"optional (max: 100) - system unique id for Dup Checking per Integration Source transaction (where integration source has DupCheckEnabled) that will be checked against successfully processed prior TranIds for Duplicates","nullable":true},"EpfSessionId":{"type":"string","description":"internal use - FrontStream unique Embedded Payment Form Session Id if available","nullable":true},"BillingDescriptor":{"maxLength":22,"type":"string","description":"optional (max: 22) - descriptor to show on bank statement","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"client ip address (max: 40) where transaction originates","nullable":true},"ShippingFee":{"maxLength":7,"type":"string","description":"optional (max: 7) - fee for shipping that will be added to the total amount","nullable":true},"TaxableBenefit":{"maxLength":7,"type":"string","description":"optional (max: 7) - If part of the donation being passed in is taxable, include that amount here. No calculations are performed using this value, it is simply a placeholder to be used for your own reporting; all commission and credit card fees still apply as normal.","nullable":true},"Transactions":{"type":"array","items":{"$ref":"#/components/schemas/PaymentTransTypeRequest"},"description":"required - 1 to n transactions to break down transaction line items"},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) to override zip created during token creation - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000","nullable":true},"Street":{"maxLength":50,"type":"string","description":"optional (max: 50) to override street created during token creation","nullable":true},"City":{"maxLength":50,"type":"string","description":"optional (max: 50) to override city created during token creation","nullable":true},"State":{"maxLength":50,"type":"string","description":"optional (max: 50) to override state created during token creation","nullable":true},"Country":{"maxLength":2,"type":"string","description":"optional (max: 2) to override country created during token creation","nullable":true},"Currency":{"maxLength":3,"type":"string","description":"optional (max: 3) to override currency created during token creation","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - Donor Identifier per Product","nullable":true},"ExternalEventId":{"maxLength":10,"type":"string","description":"optional (max: 10) - Event Identifier per Product","nullable":true},"ExternalEventGuid":{"type":"string","description":"optional - Event Guid per Product","nullable":true},"ExternalEventName":{"maxLength":500,"type":"string","description":"optional (max: 500) - Event Name per Product","nullable":true},"AFShieldAdditional":{"$ref":"#/components/schemas/AFShieldPaymentRequest"},"Surcharge":{"maxLength":7,"type":"string","description":"optional (max: 7) - calculated surcharge amount","nullable":true}},"additionalProperties":false,"description":""},"PaymentTransTypeRequest":{"required":["Amount","TransactionSourceGroupId"],"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","description":"required - For Direct Merchant (For Profit) Api Partners should set to PaymentNoFee (12), other values are for Non Profit transactions - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;\r\n 13 - EventDonationFee;\r\n 14 - SponsorshipFee\r\n 15 - MembershipFee"},"Amount":{"maxLength":7,"type":"string","description":"required - Amount of line item without the fees included, Payment api will calculate fees for you"},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction. Indicates if the donor intends to cover the processing fees for the donation (primary used for Non Profit transactions like a donation)"},"CommissionRateOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - The percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract.","nullable":true},"CardProcessingFeeOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - Overrides the default percentage processing fee","nullable":true},"ExternalLineId":{"maxLength":100,"type":"string","description":"optional (max: 100) - use this to track individual line item IDs if necessary.","nullable":true},"Tip":{"maxLength":7,"type":"string","description":"optional (max: 7) - An amount taken up front for the API Partner if Donor decides to apply a tip. Added to the total amount to charge on the donor’s card . Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true},"Tax":{"maxLength":7,"type":"string","description":"optional (max: 7) - A tax amount taken up front. Added to the total amount to charge on the donor’s card. Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true}},"additionalProperties":false,"description":""},"AFShieldPaymentRequest":{"type":"object","properties":{"ProductDescription":{"maxLength":256,"type":"string","nullable":true},"ProductItem":{"maxLength":256,"type":"string","nullable":true},"ProductType":{"maxLength":256,"type":"string","nullable":true},"ProductQuantity":{"maxLength":3,"type":"string","nullable":true},"SessionId":{"maxLength":32,"type":"string","nullable":true},"BillToPhoneNumber":{"maxLength":32,"type":"string","nullable":true},"ShippingAddressStreet1":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressStreet2":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressCountry":{"maxLength":2,"type":"string","nullable":true},"ShippingAddressCity":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressEmail":{"maxLength":64,"type":"string","format":"email","nullable":true},"ShippingAddressName":{"maxLength":64,"type":"string","nullable":true},"ShippingAddressZip":{"maxLength":10,"type":"string","nullable":true},"ShippingAddressState":{"maxLength":50,"type":"string","nullable":true},"ShipToPhoneNumber":{"maxLength":32,"type":"string","nullable":true},"ShipToPremiseForUK":{"maxLength":256,"type":"string","nullable":true},"ShipToStreetForUK":{"maxLength":256,"type":"string","nullable":true},"BillToPremiseForUK":{"maxLength":256,"type":"string","nullable":true},"BillToStreetForUK":{"maxLength":256,"type":"string","nullable":true}},"additionalProperties":false,"description":""}}}} ``` ## The PaymentTransTypeRequest object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"PaymentTransTypeRequest":{"required":["Amount","TransactionSourceGroupId"],"type":"object","properties":{"TransactionSourceGroupId":{"type":"string","description":"required - For Direct Merchant (For Profit) Api Partners should set to PaymentNoFee (12), other values are for Non Profit transactions - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;\r\n 13 - EventDonationFee;\r\n 14 - SponsorshipFee\r\n 15 - MembershipFee"},"Amount":{"maxLength":7,"type":"string","description":"required - Amount of line item without the fees included, Payment api will calculate fees for you"},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction. Indicates if the donor intends to cover the processing fees for the donation (primary used for Non Profit transactions like a donation)"},"CommissionRateOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - The percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract.","nullable":true},"CardProcessingFeeOverride":{"maxLength":7,"type":"string","description":"optional (max: 7) - Overrides the default percentage processing fee","nullable":true},"ExternalLineId":{"maxLength":100,"type":"string","description":"optional (max: 100) - use this to track individual line item IDs if necessary.","nullable":true},"Tip":{"maxLength":7,"type":"string","description":"optional (max: 7) - An amount taken up front for the API Partner if Donor decides to apply a tip. Added to the total amount to charge on the donor’s card . Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true},"Tax":{"maxLength":7,"type":"string","description":"optional (max: 7) - A tax amount taken up front. Added to the total amount to charge on the donor’s card. Card fee calculations are performed using this value; all commission and credit card fees still apply as normal.","nullable":true}},"additionalProperties":false,"description":""}}}} ``` ## The ProblemDetails object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"ProblemDetails":{"type":"object","properties":{"type":{"type":"string","nullable":true},"title":{"type":"string","nullable":true},"status":{"type":"integer","format":"int32","nullable":true},"detail":{"type":"string","nullable":true},"instance":{"type":"string","nullable":true}},"additionalProperties":{}}}}} ``` ## The ProcessStatus object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"ProcessStatus":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12],"type":"integer","format":"int32"}}}} ``` ## The RecurringProfileResponse object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"RecurringProfileResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"For all success responses, this will be True."},"Message":{"type":"string","description":"Recurring Profile response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Recurring Profile processor response message","nullable":true},"TransactionId":{"type":"string","description":"Not currently used and will be null","nullable":true},"RecurringProfileGuid":{"type":"string","description":"GUID that identifies this particular recurring billing contract. This value is used for both the Update Recurring Profile and Cancel Recurring Profile endpoints.","format":"uuid"},"RecurringProfileId":{"type":"integer","description":"An integer identifier for this particular recurring billing contract. Is not used elsewhere in the API.","format":"int32"},"ResponseCode":{"type":"string","description":"Response Code - Successful = \"OK\" or \"0\", any other response code unsuccessful","nullable":true}},"additionalProperties":false,"description":""}}}} ``` ## The RefundRequest object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"RefundRequest":{"required":["Reason"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"PaymentGuid":{"type":"string","description":"optional if not using PaymentExternalId - Payment API PaymentGuid to be refunded","nullable":true},"PaymentExternalId":{"maxLength":200,"type":"string","description":"optional (max: 200) if not using PaymentGuid - 3rd Party Payment External Id to be refunded","nullable":true},"Reason":{"maxLength":500,"type":"string","description":"required - reason for refund request"}},"additionalProperties":false,"description":""}}}} ``` ## The RefundResponse object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"RefundResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"\"true\" if the transaction was processed successfully, and \"false\" if the transaction was not processed successfully."},"Message":{"type":"string","nullable":true},"ProcessorMessage":{"type":"string","nullable":true},"TransactionId":{"type":"string","nullable":true},"OriginalTransactionId":{"type":"string","nullable":true},"PaymentGuid":{"type":"string","format":"uuid"},"PaymentId":{"type":"integer","format":"int32"},"ResponseCode":{"type":"string","nullable":true},"PaymentResult":{"$ref":"#/components/schemas/PaymentResult"},"ProcessStatus":{"$ref":"#/components/schemas/ProcessStatus"}},"additionalProperties":false,"description":""},"PaymentResult":{"enum":[1,2,3,4,5,6],"type":"integer","format":"int32"},"ProcessStatus":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12],"type":"integer","format":"int32"}}}} ``` ## The SelectedConstraintDto object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"SelectedConstraintDto":{"type":"object","properties":{"Name":{"type":"string","nullable":true},"Operation":{"$ref":"#/components/schemas/ConstraintOperation"},"Values":{"type":"array","items":{"type":"string"},"nullable":true}},"additionalProperties":false},"ConstraintOperation":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23],"type":"integer","format":"int32"}}}} ``` ## The SortColumnDto object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"SortColumnDto":{"type":"object","properties":{"Name":{"type":"string","nullable":true},"Descending":{"type":"boolean"},"Order":{"type":"integer","format":"int32"}},"additionalProperties":false}}}} ``` ## The SurchargeConfigResponse object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"SurchargeConfigResponse":{"type":"object","properties":{"SurchargeEnabled":{"type":"boolean","description":"Is Surcharging enabled - true/false returned based on configured Merchant Surcharge."},"SurchargeRate":{"type":"string","description":"example 2.9900 in d.dddd format - configured Merchant Surcharge Percentage Rate.","nullable":true},"SurchargeStartDate":{"type":"string","description":"Surcharge Start Date based on configured Merchant Surcharge.\r\nDate Format - yyyy-MM-dd\r\nResponse Example:\r\n\"SurchargeStartDate\": \"2025-01-31\"","nullable":true}},"additionalProperties":false}}}} ``` ## The SurchargeResponse object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"SurchargeResponse":{"type":"object","properties":{"Amount":{"type":"string","description":"This is the original amount submitted for Surcharge calculation.","nullable":true},"SurchargeAmount":{"type":"string","description":"This is the calculated surcharge amount based on configured Merchant Surcharge Percentage Rate and submitted amount.\r\nd.dd format","nullable":true},"SurchargeRate":{"type":"string","description":"example 2.9900 in d.dddd format - configured Merchant Surcharge Percentage Rate.","nullable":true}},"additionalProperties":false}}}} ``` ## The TransactionLinesDetail object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"TransactionLinesDetail":{"type":"object","properties":{"PaymentGuid":{"type":"string","description":"Payment API Payment GUID for reference","format":"uuid"},"PaymentLineId":{"type":"integer","description":"Payment API Payment Line Identifier for reference","format":"int32"},"PaymentId":{"type":"integer","description":"Payment API Payment Identifier for reference","format":"int32"},"CreatedDate":{"type":"string","format":"date-time"},"ModifiedDate":{"type":"string","format":"date-time","nullable":true},"Amount":{"type":"number","description":"Transaction Line Amount","format":"double"},"CommissionAmount":{"type":"number","format":"double","nullable":true},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction. Indicates if the donor intended to cover the processing fees for the donation (primary used for Non Profit transactions like a donation)","nullable":true},"TransactionSourceGroupId":{"type":"integer","format":"int32","nullable":true},"CardFeeRate":{"type":"number","description":"example 2.5% - applied to EVERY donation. This is the FrontStream card processing fee. The percentage of the PaymentAmount that will be taken for credit card fees. Expressed as a human-readable percentage rather than a decimal value, it is intended to be able to be displayed directly on a page without needing to be converted.","format":"double","nullable":true},"CardFeeAmount":{"type":"number","description":"This is the amount that is owed to the gateway for the example 2.5% that FrontStream collects from the transaction.\r\n 2.5% of transaction amount if donor is not paying the fee, otherwise 2.5% of the transaction + card fee.","format":"double","nullable":true},"CardTypeFeeAmount":{"type":"number","description":"A per-transaction fee configured by card type (VI, MC, DI, AMEX, etc.) per API Partner's Contract other wise 0 (zero)","format":"double","nullable":true},"TotalCommissionRate":{"type":"number","description":"The Total percentage of Commissions that FrontStream takes from a given transaction.\r\nThis rate = Partner CommissionRate + FS CommissionRate","format":"double","nullable":true},"TotalCommissionAmount":{"type":"number","description":"The product of the transaction times the Total commission rate.","format":"double","nullable":true},"PartnerCommissionRate":{"type":"number","description":"The Partner Commission percentage taken on behalf of the Partner from a given transaction.","format":"double","nullable":true},"PartnerCommissionAmount":{"type":"number","description":"The product of the transaction times the Partner commission rate.","format":"double","nullable":true},"FsCommissionRate":{"type":"number","description":"The FrontStream Commission percentage that FrontStream takes from a given transaction.","format":"double","nullable":true},"FsCommissionAmount":{"type":"number","description":"The product of the transaction times the FrontStream commission rate.","format":"double","nullable":true},"TotalFees":{"type":"number","description":"The sum of all fees applied to a transaction amount. (TotalCommission + CardFee + FlatFee + CardFeeOnFee)","format":"double","nullable":true},"PerTransFee":{"type":"number","description":"The flat amount that will be taken from the PaymentAmount for any Per-Transaction Fees as configured in your contract.","format":"double","nullable":true},"ExternalLineId":{"type":"string","description":"optional - used to track individual line item IDs if necessary.","nullable":true},"Tip":{"type":"number","format":"double","nullable":true},"CommissionRateOverride":{"type":"number","format":"double","nullable":true},"Tax":{"type":"number","description":"Transaction Line Tax","format":"double","nullable":true},"CardFeeOnFeeAmount":{"type":"number","format":"double","nullable":true},"PerformanceFee":{"type":"number","description":"The performance fee (CommissionAmount) for this transaction line.","format":"double","nullable":true},"ProcessingFee":{"type":"number","description":"The processing fee (CardFeeAmount + PerTransFee + CardFeeOnFeeAmount) for this transaction line.","format":"double","nullable":true},"ShippingFee":{"type":"number","description":"The shipping fee applied to this transaction line (populated on the first line only).","format":"double","nullable":true},"AchFeeRate":{"type":"number","description":"The ACH processing fee rate applied to this transaction line.","format":"double","nullable":true},"AchFeeAmount":{"type":"number","description":"The ACH processing fee amount for this transaction line.","format":"double","nullable":true}},"additionalProperties":false,"description":"Transaction Line Details"}}}} ``` ## The TransactionReportDetail object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"TransactionReportDetail":{"type":"object","properties":{"PaymentDate":{"type":"string","description":"Payment Date of transaction","format":"date-time"},"PaymentGuid":{"type":"string","description":"Payment API Payment GUID","format":"uuid"},"PaymentId":{"type":"integer","description":"Payment API Payment Id","format":"int32"},"PaymentExternalId":{"type":"string","description":"Payment Gateway TransactionId - is the TransactionId of a Payment Response object","nullable":true},"OriginalExternalID":{"type":"string","description":"Original Payment Gateway TransactionId - is the Original TransactionId of a Payment Response object","nullable":true},"ProcessStatus":{"$ref":"#/components/schemas/ProcessStatus"},"ProcessStatusValue":{"type":"string","description":"Process Status value - possible values: NotProcessed = 1 \"Not Processed\", Authorized = 2 \"Awaiting Authorization\", Settled = 4 \"Authorized\", Rejected = 5 \"Rejected\", RefundRequired = 6 \"Refund Required\", AwaitingRefund = 7 \"Awaiting Refund\", Refunded = 8 \"Refunded\", Cancelled = 9 \"Cancelled\", Chargeback = 10 \"Chargeback\", RefundRejected = 11 \"Refund Rejected\"","nullable":true},"PaymentResult":{"$ref":"#/components/schemas/PaymentResult"},"PaymentResultValue":{"type":"string","description":"Payment Result value - possible values: \"Pending\" = 1, \"Processing\" = 2, \"Successful\" = 3, \"Failed\" = 4, \"Refunded\" = 5, \"Cancelled\" = 6","nullable":true},"ExternalConstituentId":{"type":"string","description":"Donor Identifier","nullable":true},"FirstName":{"type":"string","description":"billing First Name","nullable":true},"LastName":{"type":"string","description":"billing Last Name","nullable":true},"Email":{"type":"string","description":"contact email","nullable":true},"CardHolderName":{"type":"string","description":"Name on Card","nullable":true},"CCLastDigits":{"type":"string","description":"if available - last 4 digits of card","nullable":true},"ExpirationDate":{"type":"string","description":"MM/YY format","nullable":true},"CCType":{"type":"string","description":"possible values if available: \"American Express\", \"Mastercard\", \"Visa\", \"Discover\", \"Diners Club\", Undefined","nullable":true},"CoverTheFee":{"type":"string","description":"YES/NO - did donor Cover the Fees on Donation.","nullable":true},"DonationAmount":{"type":"number","description":"The total donation amount requested.","format":"double"},"CoverTheFeeAmount":{"type":"number","description":"The total donation amount requested.","format":"double"},"TransactionAmount":{"type":"number","description":"The total transaction amount processed toward the cardholder's account.","format":"double"},"ServiceFees":{"type":"number","description":"The calculated total fees amount of the list of transaction lines.","format":"double"},"PerformanceFees":{"type":"number","description":"The sum of CommissionAmount across all transaction lines.","format":"double"},"ProcessingFees":{"type":"number","description":"The sum of CardFeeAmount, PerTransFee, and CardFeeOnFeeAmount across all transaction lines.","format":"double"},"AmountPaid":{"type":"number","description":"The total transaction amount minus processing Fees","format":"double"},"Taxes":{"type":"number","description":"The calculated total tax amount of the list of transaction lines if any.","format":"double"},"Recurring":{"type":"string","description":"if available - YES/NO - if recurring billing contract used for transaction","nullable":true},"RecurringFrequency":{"type":"string","description":"if available - if recurring billing contract used for transaction\r\nPossible values:\r\n \"Daily\", (once per day)\r\n \"Weekly\", (once per week)\r\n \"Bi-Weekly\", (once per 2 weeks)\r\n \"Monthly\", (once per month)\r\n \"Bi-Monthly\", (Once every 2 months)\r\n \"Semi-Monthly\", (twice per month)\r\n \"Quarterly\", (four times per year)\r\n \"Semi-Annually\", (twice per year)\r\n \"Annually\" (once per year)","nullable":true},"RecurringProfileGuid":{"type":"string","description":"if available - GUID that identifies the recurring billing contract used for transaction","format":"uuid","nullable":true},"NextBillDate":{"type":"string","description":"if available - Next Billing date of the recurring billing contract used for transaction","format":"date-time","nullable":true},"DistributionType":{"$ref":"#/components/schemas/DistributionType"},"DistributionTypeValue":{"type":"string","description":"if available for Non-Profit Charity data - Distribution Type value - possible values: \"Direct Deposit\" = 1, \"Check\" = 2. Indicates the payment method that was used to disburse the funds to the Charity.","nullable":true},"DistributionStatus":{"type":"string","description":"if available for Non-Profit Charity data - possible values: \"Processing\", \"Settled\", \"Refunded\", \"Voided\"","nullable":true},"DistributionId":{"type":"integer","description":"if available for Non-Profit Charity data - Unique identifier for the distribution.","format":"int32","nullable":true},"DisbursementDate":{"type":"string","description":"if available for Non-Profit Charity data - Date funds were distributed to the organization.","format":"date-time","nullable":true},"SourceGuid":{"type":"string","description":"Source used","format":"uuid"},"SourceName":{"type":"string","nullable":true},"CharityId":{"type":"string","description":"if available for Non-Profit Charity data - CharityId used","nullable":true},"OrganizationName":{"type":"string","description":"if available Non-Profit Charity data - Organization Name","nullable":true},"Ein":{"type":"string","description":"if available for Non-Profit Charity data - Charity EIN","nullable":true},"ExternalEventId":{"type":"string","description":"Event Identifier per Product","nullable":true},"ExternalEventGuid":{"type":"string","description":"Event Guid per Product","format":"uuid"},"ExternalEventName":{"type":"string","description":"Event Name per Product","nullable":true},"TaxableBenefit":{"type":"number","description":"optional - If part of the original donation transaction, amount passed in that was taxable. No calculations were performed using this value, it is simply a placeholder to be used for your own reporting;","format":"double"},"TranId":{"type":"string","description":"unique tran id per Integration Source if available","nullable":true},"VoidRequestDate":{"type":"string","description":"Date of Void Request if available","format":"date-time","nullable":true},"VoidReason":{"type":"string","description":"Void Reason submitted if available","nullable":true},"RefundRequestDate":{"type":"string","description":"Date of Refund Request if available","format":"date-time","nullable":true},"RefundReason":{"type":"string","description":"Refund Reason submitted if available","nullable":true},"ProcessorId":{"type":"integer","description":"ProcessorId used","format":"int32","nullable":true},"ProcessorGuid":{"type":"string","description":"ProcessorGuid used","format":"uuid","nullable":true},"PaymentMethodTypeId":{"type":"integer","description":"possible values if available:\r\nNONE = 0,\r\nAMEX = 1,\r\nMASTERCARD = 2,\r\nVISA = 3,\r\nDISCOVER = 4,\r\nDINERSCLUB = 5,\r\nACH = 7,\r\nGOOGLEPAY = 8,\r\nAPPLEPAY = 9","format":"int32","nullable":true},"PaymentMethodTypeIdValue":{"type":"string","description":"\"NONE\" = 0,\r\n\"AMEX\" = 1,\r\n\"MASTERCARD\" = 2,\r\n\"VISA\" = 3,\r\n\"DISCOVER\" = 4,\r\n\"DINERSCLUB\" = 5,\r\n\"ACH\" = 7,\r\n\"GOOGLEPAY\" = 8,\r\n\"APPLEPAY\" = 9","nullable":true},"Surcharge":{"type":"number","description":"if available - The total surcharge amount.","format":"double","nullable":true},"IsSurchargeEligible":{"type":"boolean","description":"if available - Was card used Surcharge eligible","nullable":true},"CheckLastDigits":{"type":"string","description":"if available - last 4 digits of check account used","nullable":true},"CheckNumber":{"type":"string","description":"if available - Valid Check Number used","nullable":true},"CheckTypeId":{"type":"integer","description":"if available for Check transactions - possible values -\r\n 1 = Personal,\r\n 2 = Corporate,\r\n 3 = Government","format":"int32","nullable":true},"CheckTypeIdValue":{"type":"string","description":"if available for Check transactions - possible values -\r\n \"Personal\" = 1,\r\n \"Corporate\" = 2,\r\n \"Government\" = 3","nullable":true},"CheckAccountTypeId":{"type":"integer","description":"if available for Check transactions - possible values -\r\n 1 = Checking,\r\n 2 = Savings","format":"int32","nullable":true},"CheckAccountTypeIdValue":{"type":"string","description":"if available for Check transactions - possible values -\r\n \"Checking\" = 1,\r\n \"Savings\" = 2","nullable":true},"EpfSessionId":{"type":"string","description":"FrontStream unique Embedded Payment Form Session Id if available","format":"uuid","nullable":true},"TransactionLines":{"type":"array","items":{"$ref":"#/components/schemas/TransactionLinesDetail"},"nullable":true}},"additionalProperties":false,"description":"Transaction Report Details"},"ProcessStatus":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12],"type":"integer","format":"int32"},"PaymentResult":{"enum":[1,2,3,4,5,6],"type":"integer","format":"int32"},"DistributionType":{"enum":[1,2],"type":"integer","format":"int32"},"TransactionLinesDetail":{"type":"object","properties":{"PaymentGuid":{"type":"string","description":"Payment API Payment GUID for reference","format":"uuid"},"PaymentLineId":{"type":"integer","description":"Payment API Payment Line Identifier for reference","format":"int32"},"PaymentId":{"type":"integer","description":"Payment API Payment Identifier for reference","format":"int32"},"CreatedDate":{"type":"string","format":"date-time"},"ModifiedDate":{"type":"string","format":"date-time","nullable":true},"Amount":{"type":"number","description":"Transaction Line Amount","format":"double"},"CommissionAmount":{"type":"number","format":"double","nullable":true},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction. Indicates if the donor intended to cover the processing fees for the donation (primary used for Non Profit transactions like a donation)","nullable":true},"TransactionSourceGroupId":{"type":"integer","format":"int32","nullable":true},"CardFeeRate":{"type":"number","description":"example 2.5% - applied to EVERY donation. This is the FrontStream card processing fee. The percentage of the PaymentAmount that will be taken for credit card fees. Expressed as a human-readable percentage rather than a decimal value, it is intended to be able to be displayed directly on a page without needing to be converted.","format":"double","nullable":true},"CardFeeAmount":{"type":"number","description":"This is the amount that is owed to the gateway for the example 2.5% that FrontStream collects from the transaction.\r\n 2.5% of transaction amount if donor is not paying the fee, otherwise 2.5% of the transaction + card fee.","format":"double","nullable":true},"CardTypeFeeAmount":{"type":"number","description":"A per-transaction fee configured by card type (VI, MC, DI, AMEX, etc.) per API Partner's Contract other wise 0 (zero)","format":"double","nullable":true},"TotalCommissionRate":{"type":"number","description":"The Total percentage of Commissions that FrontStream takes from a given transaction.\r\nThis rate = Partner CommissionRate + FS CommissionRate","format":"double","nullable":true},"TotalCommissionAmount":{"type":"number","description":"The product of the transaction times the Total commission rate.","format":"double","nullable":true},"PartnerCommissionRate":{"type":"number","description":"The Partner Commission percentage taken on behalf of the Partner from a given transaction.","format":"double","nullable":true},"PartnerCommissionAmount":{"type":"number","description":"The product of the transaction times the Partner commission rate.","format":"double","nullable":true},"FsCommissionRate":{"type":"number","description":"The FrontStream Commission percentage that FrontStream takes from a given transaction.","format":"double","nullable":true},"FsCommissionAmount":{"type":"number","description":"The product of the transaction times the FrontStream commission rate.","format":"double","nullable":true},"TotalFees":{"type":"number","description":"The sum of all fees applied to a transaction amount. (TotalCommission + CardFee + FlatFee + CardFeeOnFee)","format":"double","nullable":true},"PerTransFee":{"type":"number","description":"The flat amount that will be taken from the PaymentAmount for any Per-Transaction Fees as configured in your contract.","format":"double","nullable":true},"ExternalLineId":{"type":"string","description":"optional - used to track individual line item IDs if necessary.","nullable":true},"Tip":{"type":"number","format":"double","nullable":true},"CommissionRateOverride":{"type":"number","format":"double","nullable":true},"Tax":{"type":"number","description":"Transaction Line Tax","format":"double","nullable":true},"CardFeeOnFeeAmount":{"type":"number","format":"double","nullable":true},"PerformanceFee":{"type":"number","description":"The performance fee (CommissionAmount) for this transaction line.","format":"double","nullable":true},"ProcessingFee":{"type":"number","description":"The processing fee (CardFeeAmount + PerTransFee + CardFeeOnFeeAmount) for this transaction line.","format":"double","nullable":true},"ShippingFee":{"type":"number","description":"The shipping fee applied to this transaction line (populated on the first line only).","format":"double","nullable":true},"AchFeeRate":{"type":"number","description":"The ACH processing fee rate applied to this transaction line.","format":"double","nullable":true},"AchFeeAmount":{"type":"number","description":"The ACH processing fee amount for this transaction line.","format":"double","nullable":true}},"additionalProperties":false,"description":"Transaction Line Details"}}}} ``` ## The TransactionReportDetailPagedResults object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"TransactionReportDetailPagedResults":{"type":"object","properties":{"CurrentPage":{"type":"integer","format":"int32"},"PageSize":{"type":"integer","format":"int32"},"Results":{"type":"array","items":{"$ref":"#/components/schemas/TransactionReportDetail"},"nullable":true},"TotalPages":{"type":"integer","format":"int32"},"TotalRows":{"type":"integer","format":"int32"}},"additionalProperties":false},"TransactionReportDetail":{"type":"object","properties":{"PaymentDate":{"type":"string","description":"Payment Date of transaction","format":"date-time"},"PaymentGuid":{"type":"string","description":"Payment API Payment GUID","format":"uuid"},"PaymentId":{"type":"integer","description":"Payment API Payment Id","format":"int32"},"PaymentExternalId":{"type":"string","description":"Payment Gateway TransactionId - is the TransactionId of a Payment Response object","nullable":true},"OriginalExternalID":{"type":"string","description":"Original Payment Gateway TransactionId - is the Original TransactionId of a Payment Response object","nullable":true},"ProcessStatus":{"$ref":"#/components/schemas/ProcessStatus"},"ProcessStatusValue":{"type":"string","description":"Process Status value - possible values: NotProcessed = 1 \"Not Processed\", Authorized = 2 \"Awaiting Authorization\", Settled = 4 \"Authorized\", Rejected = 5 \"Rejected\", RefundRequired = 6 \"Refund Required\", AwaitingRefund = 7 \"Awaiting Refund\", Refunded = 8 \"Refunded\", Cancelled = 9 \"Cancelled\", Chargeback = 10 \"Chargeback\", RefundRejected = 11 \"Refund Rejected\"","nullable":true},"PaymentResult":{"$ref":"#/components/schemas/PaymentResult"},"PaymentResultValue":{"type":"string","description":"Payment Result value - possible values: \"Pending\" = 1, \"Processing\" = 2, \"Successful\" = 3, \"Failed\" = 4, \"Refunded\" = 5, \"Cancelled\" = 6","nullable":true},"ExternalConstituentId":{"type":"string","description":"Donor Identifier","nullable":true},"FirstName":{"type":"string","description":"billing First Name","nullable":true},"LastName":{"type":"string","description":"billing Last Name","nullable":true},"Email":{"type":"string","description":"contact email","nullable":true},"CardHolderName":{"type":"string","description":"Name on Card","nullable":true},"CCLastDigits":{"type":"string","description":"if available - last 4 digits of card","nullable":true},"ExpirationDate":{"type":"string","description":"MM/YY format","nullable":true},"CCType":{"type":"string","description":"possible values if available: \"American Express\", \"Mastercard\", \"Visa\", \"Discover\", \"Diners Club\", Undefined","nullable":true},"CoverTheFee":{"type":"string","description":"YES/NO - did donor Cover the Fees on Donation.","nullable":true},"DonationAmount":{"type":"number","description":"The total donation amount requested.","format":"double"},"CoverTheFeeAmount":{"type":"number","description":"The total donation amount requested.","format":"double"},"TransactionAmount":{"type":"number","description":"The total transaction amount processed toward the cardholder's account.","format":"double"},"ServiceFees":{"type":"number","description":"The calculated total fees amount of the list of transaction lines.","format":"double"},"PerformanceFees":{"type":"number","description":"The sum of CommissionAmount across all transaction lines.","format":"double"},"ProcessingFees":{"type":"number","description":"The sum of CardFeeAmount, PerTransFee, and CardFeeOnFeeAmount across all transaction lines.","format":"double"},"AmountPaid":{"type":"number","description":"The total transaction amount minus processing Fees","format":"double"},"Taxes":{"type":"number","description":"The calculated total tax amount of the list of transaction lines if any.","format":"double"},"Recurring":{"type":"string","description":"if available - YES/NO - if recurring billing contract used for transaction","nullable":true},"RecurringFrequency":{"type":"string","description":"if available - if recurring billing contract used for transaction\r\nPossible values:\r\n \"Daily\", (once per day)\r\n \"Weekly\", (once per week)\r\n \"Bi-Weekly\", (once per 2 weeks)\r\n \"Monthly\", (once per month)\r\n \"Bi-Monthly\", (Once every 2 months)\r\n \"Semi-Monthly\", (twice per month)\r\n \"Quarterly\", (four times per year)\r\n \"Semi-Annually\", (twice per year)\r\n \"Annually\" (once per year)","nullable":true},"RecurringProfileGuid":{"type":"string","description":"if available - GUID that identifies the recurring billing contract used for transaction","format":"uuid","nullable":true},"NextBillDate":{"type":"string","description":"if available - Next Billing date of the recurring billing contract used for transaction","format":"date-time","nullable":true},"DistributionType":{"$ref":"#/components/schemas/DistributionType"},"DistributionTypeValue":{"type":"string","description":"if available for Non-Profit Charity data - Distribution Type value - possible values: \"Direct Deposit\" = 1, \"Check\" = 2. Indicates the payment method that was used to disburse the funds to the Charity.","nullable":true},"DistributionStatus":{"type":"string","description":"if available for Non-Profit Charity data - possible values: \"Processing\", \"Settled\", \"Refunded\", \"Voided\"","nullable":true},"DistributionId":{"type":"integer","description":"if available for Non-Profit Charity data - Unique identifier for the distribution.","format":"int32","nullable":true},"DisbursementDate":{"type":"string","description":"if available for Non-Profit Charity data - Date funds were distributed to the organization.","format":"date-time","nullable":true},"SourceGuid":{"type":"string","description":"Source used","format":"uuid"},"SourceName":{"type":"string","nullable":true},"CharityId":{"type":"string","description":"if available for Non-Profit Charity data - CharityId used","nullable":true},"OrganizationName":{"type":"string","description":"if available Non-Profit Charity data - Organization Name","nullable":true},"Ein":{"type":"string","description":"if available for Non-Profit Charity data - Charity EIN","nullable":true},"ExternalEventId":{"type":"string","description":"Event Identifier per Product","nullable":true},"ExternalEventGuid":{"type":"string","description":"Event Guid per Product","format":"uuid"},"ExternalEventName":{"type":"string","description":"Event Name per Product","nullable":true},"TaxableBenefit":{"type":"number","description":"optional - If part of the original donation transaction, amount passed in that was taxable. No calculations were performed using this value, it is simply a placeholder to be used for your own reporting;","format":"double"},"TranId":{"type":"string","description":"unique tran id per Integration Source if available","nullable":true},"VoidRequestDate":{"type":"string","description":"Date of Void Request if available","format":"date-time","nullable":true},"VoidReason":{"type":"string","description":"Void Reason submitted if available","nullable":true},"RefundRequestDate":{"type":"string","description":"Date of Refund Request if available","format":"date-time","nullable":true},"RefundReason":{"type":"string","description":"Refund Reason submitted if available","nullable":true},"ProcessorId":{"type":"integer","description":"ProcessorId used","format":"int32","nullable":true},"ProcessorGuid":{"type":"string","description":"ProcessorGuid used","format":"uuid","nullable":true},"PaymentMethodTypeId":{"type":"integer","description":"possible values if available:\r\nNONE = 0,\r\nAMEX = 1,\r\nMASTERCARD = 2,\r\nVISA = 3,\r\nDISCOVER = 4,\r\nDINERSCLUB = 5,\r\nACH = 7,\r\nGOOGLEPAY = 8,\r\nAPPLEPAY = 9","format":"int32","nullable":true},"PaymentMethodTypeIdValue":{"type":"string","description":"\"NONE\" = 0,\r\n\"AMEX\" = 1,\r\n\"MASTERCARD\" = 2,\r\n\"VISA\" = 3,\r\n\"DISCOVER\" = 4,\r\n\"DINERSCLUB\" = 5,\r\n\"ACH\" = 7,\r\n\"GOOGLEPAY\" = 8,\r\n\"APPLEPAY\" = 9","nullable":true},"Surcharge":{"type":"number","description":"if available - The total surcharge amount.","format":"double","nullable":true},"IsSurchargeEligible":{"type":"boolean","description":"if available - Was card used Surcharge eligible","nullable":true},"CheckLastDigits":{"type":"string","description":"if available - last 4 digits of check account used","nullable":true},"CheckNumber":{"type":"string","description":"if available - Valid Check Number used","nullable":true},"CheckTypeId":{"type":"integer","description":"if available for Check transactions - possible values -\r\n 1 = Personal,\r\n 2 = Corporate,\r\n 3 = Government","format":"int32","nullable":true},"CheckTypeIdValue":{"type":"string","description":"if available for Check transactions - possible values -\r\n \"Personal\" = 1,\r\n \"Corporate\" = 2,\r\n \"Government\" = 3","nullable":true},"CheckAccountTypeId":{"type":"integer","description":"if available for Check transactions - possible values -\r\n 1 = Checking,\r\n 2 = Savings","format":"int32","nullable":true},"CheckAccountTypeIdValue":{"type":"string","description":"if available for Check transactions - possible values -\r\n \"Checking\" = 1,\r\n \"Savings\" = 2","nullable":true},"EpfSessionId":{"type":"string","description":"FrontStream unique Embedded Payment Form Session Id if available","format":"uuid","nullable":true},"TransactionLines":{"type":"array","items":{"$ref":"#/components/schemas/TransactionLinesDetail"},"nullable":true}},"additionalProperties":false,"description":"Transaction Report Details"},"ProcessStatus":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12],"type":"integer","format":"int32"},"PaymentResult":{"enum":[1,2,3,4,5,6],"type":"integer","format":"int32"},"DistributionType":{"enum":[1,2],"type":"integer","format":"int32"},"TransactionLinesDetail":{"type":"object","properties":{"PaymentGuid":{"type":"string","description":"Payment API Payment GUID for reference","format":"uuid"},"PaymentLineId":{"type":"integer","description":"Payment API Payment Line Identifier for reference","format":"int32"},"PaymentId":{"type":"integer","description":"Payment API Payment Identifier for reference","format":"int32"},"CreatedDate":{"type":"string","format":"date-time"},"ModifiedDate":{"type":"string","format":"date-time","nullable":true},"Amount":{"type":"number","description":"Transaction Line Amount","format":"double"},"CommissionAmount":{"type":"number","format":"double","nullable":true},"PayFee":{"type":"boolean","description":"optional - cover the fees flag for the transaction. Indicates if the donor intended to cover the processing fees for the donation (primary used for Non Profit transactions like a donation)","nullable":true},"TransactionSourceGroupId":{"type":"integer","format":"int32","nullable":true},"CardFeeRate":{"type":"number","description":"example 2.5% - applied to EVERY donation. This is the FrontStream card processing fee. The percentage of the PaymentAmount that will be taken for credit card fees. Expressed as a human-readable percentage rather than a decimal value, it is intended to be able to be displayed directly on a page without needing to be converted.","format":"double","nullable":true},"CardFeeAmount":{"type":"number","description":"This is the amount that is owed to the gateway for the example 2.5% that FrontStream collects from the transaction.\r\n 2.5% of transaction amount if donor is not paying the fee, otherwise 2.5% of the transaction + card fee.","format":"double","nullable":true},"CardTypeFeeAmount":{"type":"number","description":"A per-transaction fee configured by card type (VI, MC, DI, AMEX, etc.) per API Partner's Contract other wise 0 (zero)","format":"double","nullable":true},"TotalCommissionRate":{"type":"number","description":"The Total percentage of Commissions that FrontStream takes from a given transaction.\r\nThis rate = Partner CommissionRate + FS CommissionRate","format":"double","nullable":true},"TotalCommissionAmount":{"type":"number","description":"The product of the transaction times the Total commission rate.","format":"double","nullable":true},"PartnerCommissionRate":{"type":"number","description":"The Partner Commission percentage taken on behalf of the Partner from a given transaction.","format":"double","nullable":true},"PartnerCommissionAmount":{"type":"number","description":"The product of the transaction times the Partner commission rate.","format":"double","nullable":true},"FsCommissionRate":{"type":"number","description":"The FrontStream Commission percentage that FrontStream takes from a given transaction.","format":"double","nullable":true},"FsCommissionAmount":{"type":"number","description":"The product of the transaction times the FrontStream commission rate.","format":"double","nullable":true},"TotalFees":{"type":"number","description":"The sum of all fees applied to a transaction amount. (TotalCommission + CardFee + FlatFee + CardFeeOnFee)","format":"double","nullable":true},"PerTransFee":{"type":"number","description":"The flat amount that will be taken from the PaymentAmount for any Per-Transaction Fees as configured in your contract.","format":"double","nullable":true},"ExternalLineId":{"type":"string","description":"optional - used to track individual line item IDs if necessary.","nullable":true},"Tip":{"type":"number","format":"double","nullable":true},"CommissionRateOverride":{"type":"number","format":"double","nullable":true},"Tax":{"type":"number","description":"Transaction Line Tax","format":"double","nullable":true},"CardFeeOnFeeAmount":{"type":"number","format":"double","nullable":true},"PerformanceFee":{"type":"number","description":"The performance fee (CommissionAmount) for this transaction line.","format":"double","nullable":true},"ProcessingFee":{"type":"number","description":"The processing fee (CardFeeAmount + PerTransFee + CardFeeOnFeeAmount) for this transaction line.","format":"double","nullable":true},"ShippingFee":{"type":"number","description":"The shipping fee applied to this transaction line (populated on the first line only).","format":"double","nullable":true},"AchFeeRate":{"type":"number","description":"The ACH processing fee rate applied to this transaction line.","format":"double","nullable":true},"AchFeeAmount":{"type":"number","description":"The ACH processing fee amount for this transaction line.","format":"double","nullable":true}},"additionalProperties":false,"description":"Transaction Line Details"}}}} ``` ## The UpdateRecurringProfileRequest object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"UpdateRecurringProfileRequest":{"required":["RecurringProfileGuid"],"type":"object","properties":{"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"RecurringProfileGuid":{"type":"string","description":"required - Valid Recurring Profile Guid for update"},"Amount":{"maxLength":7,"type":"string","description":"optional if updating existing recurring profile - Amount to be charged per billing frequency","nullable":true},"StartDate":{"type":"string","description":"optional if updating existing recurring profile - format yyyy-MM-dd - start date of contract to update","nullable":true},"EndDate":{"type":"string","description":"optional if updating existing recurring profile - format yyyy-MM-dd - end date of contract (must be after StartDate) if you wish a contract to stop recurring at certain date","nullable":true},"NextBillDate":{"type":"string","description":"optional if updating existing recurring profile - format yyyy-MM-dd - The date when the first recurrence should begin charging the donor's card. Must be after StartDate.","nullable":true},"BillingFrequency":{"type":"string","description":"optional if updating existing recurring profile - How often the recurrence should occur. Possible values:\r\n \"Daily\", (once per day)\r\n \"Weekly\", (once per week)\r\n \"Bi-Weekly\", (once per 2 weeks)\r\n \"Monthly\", (once per month)\r\n \"Bi-Monthly\", (Once every 2 months)\r\n \"Semi-Monthly\", (twice per month)\r\n \"Quarterly\", (four times per year)\r\n \"Semi-Annually\", (twice per year)\r\n \"Annually\" (once per year)","nullable":true},"PreFeeAmount":{"maxLength":7,"type":"string","description":"optional if updating existing recurring profile - Pre Fee Amount with the fees not included if using fee (used for Non Profit transactions like a donation)","nullable":true},"PayFee":{"type":"boolean","description":"optional if updating existing recurring profile - cover the fees flag for the transaction (primary used for Non Profit transactions like a donation), if used see Amount and PreFeeAmount info","nullable":true},"TransactionSourceGroupId":{"type":"string","description":"optional if updating existing recurring profile - For Direct Merchant (For Profit) Api Partners should set to PaymentNoFee (12), other values are for Non Profit transactions - possible values -\r\n 1 - Donation Fee,\r\n 2 - Peer-to-Peer Fee,\r\n 3 - Auction Performance Fee,\r\n 4 - Ticket Fee,\r\n 5 - Registration Fee,\r\n 6 - Quick Sales Fee,\r\n 7 - Online Store Fee,\r\n 8 - Campaign Fee,\r\n 9 - 0% Auction Performance Fee,\r\n 10 - ApiPartnerFee,\r\n 11 - ExpressPayrollFee;\r\n 12 - PaymentNoFee;","nullable":true},"ExternalEventId":{"maxLength":10,"type":"string","description":"optional - Event Id per Product","nullable":true},"ExternalEventGuid":{"type":"string","description":"optional - Event Guid per Product","nullable":true},"ExternalEventName":{"maxLength":500,"type":"string","description":"optional - Event Name per Product","nullable":true},"UseOriginalFees":{"type":"boolean","description":"optional - if a Non Profit organization has changed fees then UseOriginalFee = false will update recurring profile to use updated organization fees. Primary used for Non Profit transactions.","nullable":true},"CommissionRateOverride":{"type":"string","description":"optional - update the percentage value that you want to set for your commission on the transaction. Minimum value that will be used is the FrontStream Commission Rate as set in your contract, maximum value is the maximum commission rate set in your contract. Passing values outside of the min/max range will not result in a validation error, but will instead default to the min/max value (i.e. if your maximum commission rate in your contract is 10%, and you pass \"15.0\" for this value, the Payment API will simply use 10%). Not including this field or passing null also defaults to using the maximum commission rate from your contract. Primary used for Non Profit transactions.","nullable":true},"CardProcessingFeeOverride":{"type":"string","description":"optional - update the CardProcessingFeeOverride that Overrides the default percentage processing fee. Primary used for Non Profit transactions.","nullable":true}},"additionalProperties":false,"description":""}}}} ``` ## The UpdateTokenRequest object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"UpdateTokenRequest":{"type":"object","properties":{"TokenGuid":{"type":"string","description":"Token identifier - provide one of: TokenGuid, ExternalCardToken, or ExternalCheckToken","nullable":true},"ExternalCardToken":{"maxLength":200,"type":"string","description":"optional (max: 200) - 3rd party gateway card token","nullable":true},"ExternalCheckToken":{"maxLength":200,"type":"string","description":"optional (max: 200) - 3rd party gateway check/ACH token","nullable":true},"CardNum":{"maxLength":30,"type":"string","description":"optional (max: 30) - updated credit card number","nullable":true},"ExpMonth":{"maxLength":2,"minLength":2,"type":"string","description":"optional - example: \"01\" for January","nullable":true},"ExpYear":{"maxLength":2,"minLength":2,"type":"string","description":"optional - example: \"29\" for 2029","nullable":true},"CVNum":{"maxLength":4,"type":"string","description":"optional (max: 4) - CVV","nullable":true},"NameOnCard":{"maxLength":25,"type":"string","description":"optional (max: 25) - updated name on card","nullable":true},"CheckRoutingNumber":{"maxLength":9,"type":"string","description":"optional (max: 9) - updated bank routing number","nullable":true},"CheckAccountNumber":{"maxLength":20,"type":"string","description":"optional (max: 20) - updated bank account number","nullable":true},"CheckNumber":{"maxLength":10,"type":"string","description":"optional (max: 10) - check number","nullable":true},"CheckAccountTypeId":{"type":"string","description":"optional - 1=Checking, 2=Saving","nullable":true},"CheckTypeId":{"type":"string","description":"optional - 1=Personal, 2=Corporate, 3=Government","nullable":true},"NameOnCheck":{"maxLength":25,"type":"string","description":"optional (max: 25) - updated name on check","nullable":true},"Email":{"maxLength":100,"type":"string","description":"optional (max: 100) - updated billing email","format":"email","nullable":true},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing first name","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing last name","nullable":true},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - billing zip/postal code","nullable":true},"Street":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing street address","nullable":true},"City":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing city","nullable":true},"State":{"maxLength":50,"type":"string","description":"optional (max: 50) - 2 char US state code or non-US equivalent","nullable":true},"Country":{"maxLength":2,"type":"string","description":"optional - 2 char country code","nullable":true},"Currency":{"maxLength":3,"type":"string","description":"optional - 3 char currency code, e.g. \"USD\", \"CAD\"","nullable":true},"ExternalConstituentId":{"maxLength":200,"type":"string","description":"optional (max: 200) - constituent id from partner system","nullable":true},"IsDefault":{"type":"boolean","description":"optional - when true, designates this token as the default payment method for the constituent;\r\nclears IsDefault on all other tokens for the same constituent and processor","nullable":true},"IntegrationSource":{"type":"string","description":"optional - internal use - Identifies integrated Product; validated against the integration source that created the token","nullable":true}},"additionalProperties":false}}}} ``` ## The UpdateTokenResponse object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"UpdateTokenResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"True if the token update was successful"},"Message":{"type":"string","description":"Update token response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Processor response message","nullable":true},"TokenGuid":{"type":"string","description":"The TokenGuid identifying this token","format":"uuid"},"ExternalCardToken":{"type":"string","description":"Updated ExternalCardToken - may differ from the original if the card number was changed on a processor that requires a new token (e.g. Stripe)","nullable":true},"ExternalCheckToken":{"type":"string","description":"Updated ExternalCheckToken - may differ from the original if the bank account was changed on a processor that requires a new token","nullable":true},"ExternalCustomerId":{"type":"string","description":"ExternalCustomerId - 3rd party gateway customer id tied to the token","nullable":true},"ExternalConstituentId":{"type":"string","description":"Partner's constituent/donor id stored on the token record","nullable":true},"ResponseCode":{"type":"string","description":"Response Code - \"0\" on success, any other value indicates an error","nullable":true}},"additionalProperties":false}}}} ``` ## The VerifyCardRequest object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"VerifyCardRequest":{"required":["CardNum","City","Country","Email","ExpMonth","ExpYear","IpAddress","NameOnCard","Street"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"required if API Partner - Identifies Processor being used by an API Partner","nullable":true},"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"CardNum":{"maxLength":30,"type":"string","description":"required - Valid Credit card number"},"ExpMonth":{"maxLength":2,"minLength":2,"type":"string","description":"required - example: \"01\" for January"},"ExpYear":{"maxLength":2,"minLength":2,"type":"string","description":"required - example: \"29\" for 2029"},"CVNum":{"maxLength":4,"type":"string","description":"optional (max: 4) - valid CVV - please provide for CVV checks","nullable":true},"NameOnCard":{"maxLength":25,"type":"string","description":"required - Name on Card"},"Email":{"maxLength":100,"type":"string","description":"required - valid contact email","format":"email"},"Zip":{"maxLength":10,"type":"string","description":"optional (max: 10) - please provide for best interchange and avs checks - US, CA, AU formats are validated (example formats - US: 12345 or 12345-1234, CA: A1A 1A1, AU: 3000","nullable":true},"Street":{"maxLength":50,"type":"string","description":"required - please provide for best interchange and avs checks"},"City":{"maxLength":50,"type":"string","description":"required - please provide for best interchange and avs checks"},"State":{"maxLength":50,"type":"string","description":"optional - 2 char US state code, 3 char may be used for other non-US","nullable":true},"Country":{"maxLength":2,"type":"string","description":"required - 2 char country code"},"FirstName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing First Name","nullable":true},"LastName":{"maxLength":50,"type":"string","description":"optional (max: 50) - billing Last Name","nullable":true},"Currency":{"maxLength":3,"type":"string","description":"optional - 3 char currency code - Example for US - \"USD\", for CA - \"CAD\"","nullable":true},"IpAddress":{"maxLength":40,"type":"string","description":"required - client ip address where transaction originates"},"AFShieldAdditional":{"$ref":"#/components/schemas/AFShieldPaymentRequest"}},"additionalProperties":false,"description":""},"AFShieldPaymentRequest":{"type":"object","properties":{"ProductDescription":{"maxLength":256,"type":"string","nullable":true},"ProductItem":{"maxLength":256,"type":"string","nullable":true},"ProductType":{"maxLength":256,"type":"string","nullable":true},"ProductQuantity":{"maxLength":3,"type":"string","nullable":true},"SessionId":{"maxLength":32,"type":"string","nullable":true},"BillToPhoneNumber":{"maxLength":32,"type":"string","nullable":true},"ShippingAddressStreet1":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressStreet2":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressCountry":{"maxLength":2,"type":"string","nullable":true},"ShippingAddressCity":{"maxLength":256,"type":"string","nullable":true},"ShippingAddressEmail":{"maxLength":64,"type":"string","format":"email","nullable":true},"ShippingAddressName":{"maxLength":64,"type":"string","nullable":true},"ShippingAddressZip":{"maxLength":10,"type":"string","nullable":true},"ShippingAddressState":{"maxLength":50,"type":"string","nullable":true},"ShipToPhoneNumber":{"maxLength":32,"type":"string","nullable":true},"ShipToPremiseForUK":{"maxLength":256,"type":"string","nullable":true},"ShipToStreetForUK":{"maxLength":256,"type":"string","nullable":true},"BillToPremiseForUK":{"maxLength":256,"type":"string","nullable":true},"BillToStreetForUK":{"maxLength":256,"type":"string","nullable":true}},"additionalProperties":false,"description":""}}}} ``` ## The VerifyCardResponse object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"VerifyCardResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"As one would guess, this is \"true\" if the transaction was processed successfully, and \"false\" if the transaction was not processed successfully."},"Message":{"type":"string","description":"Payment Gateway response message","nullable":true},"ProcessorMessage":{"type":"string","description":"Response from the processing bank.","nullable":true},"ResponseCode":{"type":"string","description":"Response Code - Approved = 0, Not processed = -100 with more possible values - https://developers.frontstream.com/argofire/full-endpoint-reference-and-tools/general-info-and-utilities#argofire-response-codes","nullable":true},"AVSStreetStatus":{"type":"string","description":"Address Verification Street Status","nullable":true},"AVSZipStatus":{"type":"string","description":"Address Verification Zip Status","nullable":true},"AVSResponse":{"type":"string","description":"Address Verification Response","nullable":true},"CVVResponse":{"type":"string","description":"Card Verification Response","nullable":true}},"additionalProperties":false,"description":""}}}} ``` ## The VoidRequest object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"VoidRequest":{"required":["Reason"],"type":"object","properties":{"ProcessorGuid":{"type":"string","description":"optional for Non-Profit transactions like donations but required if For-Profit API Partner - Identifies Processor being used by an API Partner","nullable":true},"CharityId":{"type":"string","description":"optional - Valid CharityId Guid from Charity Search","nullable":true},"OrganizationGuid":{"type":"string","description":"internal use - Valid Panorama Organization Guid","nullable":true},"IntegrationSource":{"type":"string","description":"internal use - Identifies integrated Product","nullable":true},"PaymentGuid":{"type":"string","description":"optional - if not using PaymentExternalId - Payment API PaymentGuid to be refunded","nullable":true},"PaymentExternalId":{"maxLength":200,"type":"string","description":"optional (max: 200) - if not using PaymentGuid - 3rd Party Payment External Id to be refunded","nullable":true},"Reason":{"maxLength":500,"type":"string","description":"required - reason for void request"}},"additionalProperties":false,"description":""}}}} ``` ## The VoidResponse object ```json {"openapi":"3.0.1","info":{"title":"The Payment API","version":"v1"},"components":{"schemas":{"VoidResponse":{"type":"object","properties":{"Successful":{"type":"boolean","description":"\"true\" if the transaction was processed successfully, and \"false\" if the transaction was not processed successfully."},"Message":{"type":"string","nullable":true},"ProcessorMessage":{"type":"string","nullable":true},"TransactionId":{"type":"string","nullable":true},"OriginalTransactionId":{"type":"string","nullable":true},"PaymentGuid":{"type":"string","format":"uuid"},"PaymentId":{"type":"integer","format":"int32"},"ResponseCode":{"type":"string","nullable":true},"PaymentResult":{"$ref":"#/components/schemas/PaymentResult"},"ProcessStatus":{"$ref":"#/components/schemas/ProcessStatus"}},"additionalProperties":false,"description":""},"PaymentResult":{"enum":[1,2,3,4,5,6],"type":"integer","format":"int32"},"ProcessStatus":{"enum":[1,2,3,4,5,6,7,8,9,10,11,12],"type":"integer","format":"int32"}}}} ``` # ArgoFire HOME PAGE - INTRODUCTION
**ArgoFire** is FrontStream’s secure payment gateway built for businesses of all sizes. It supports a wide range of payment methods—including credit cards, debit cards, and ACH—and offers flexible integration options for web, mobile, and server-side applications. ArgoFire enables seamless payment processing for one-time sales, recurring billing, tokenized repeat transactions, and more, serving merchants across the U.S. and Canada. #### Key Features: **Flexible Integration Options:**\ ArgoFire offers a SOAP API, as well as virtual terminals, and tokenization tools—allowing developers to choose the approach that best fits their application. **Recurring Payments:**\ Built-in support for scheduled and flexible recurring billing, with tools to manage, update, and report on ongoing customer subscriptions. **Tokenization & Repeat Transactions:**\ Securely tokenize card and bank data for future use. Enables one-click repeat payments and safer storage of customer payment details. **eCheck & ACH Support:**\ Support for electronic checks and ACH transactions, with built-in verification tools to reduce risk and improve acceptance rates. **Settlement & Reconciliation Tools:**\ Comprehensive transaction reporting, batch settlement, and funding reconciliation designed to streamline business accounting and financial operations. **Security & Compliance:**\ ArgoFire is PCI DSS Level 1 certified. All sensitive data is encrypted and tokenized, reducing customer PCI scope and risk. #### Common Use Cases: * Payment forms hosted on business websites * Recurring customer subscriptions or installment billing * Integration with CRMs or e-commerce platforms * In-person payments via virtual terminal * Event or point-of-sale transactions * Back-office entry for mail or phone donations #### Benefits: **Built for Merchants:**\ ArgoFire is designed to meet the operational needs of modern businesses, with support for flexible payment flows, surcharges, and detailed transaction reporting. **Developer-Friendly:**\ Comprehensive documentation, SOAP endpoints, and flexible authentication make integration straightforward for technical teams. **Reliable & Scalable:**\ Designed to support high volumes of donations and transactions with enterprise-grade reliability. # Payment Flows & User Experience
### How ArgoFire Handles Payment Flows & Use Cases **ArgoFire** delivers flexible and secure payment processing through a powerful API and web-based virtual terminal, built to meet the needs of merchants and commerce platforms. From recurring billing to secure token reuse, ArgoFire provides a dependable backend for a wide range of real-world payment scenarios. *** #### Use Case: One-Time Payment via Direct API Integration 1. **Frontend Collection**\ Your platform collects payment data from the user using a secure, PCI-compliant input method. 2. **API Submission**\ Payment details are passed to ArgoFire's API for immediate processing. 3. **Authorization & Settlement**\ ArgoFire authorizes the transaction and routes it to the appropriate payment processor for settlement. See how One-Time Payment API looks: {% content-ref url="/pages/BiSh52nhhp5VYx1eTKHE" %} [Payment Processing – Credit, Check, Debit](/argofire/full-endpoint-reference-and-tools/payment-processing-credit-check-debit) {% endcontent-ref %} Use Case: Recurring Payment Setup via API 1. **Customer Enrollment**\ A customer signs up for a recurring payment plan on your site, providing payment details and selecting a billing frequency (e.g., monthly, annually). 2. **Token Generation**\ ArgoFire tokenizes the payment credentials and securely stores them for future transactions. 3. **Schedule Configuration**\ A recurring billing schedule is created and linked to the token, with parameters such as start date, amount, and frequency. 4. **Automated Billing**\ ArgoFire processes the payment automatically at the defined interval. 5. **Profile Management**\ Recurring payment profiles can be updated or canceled via API or ArgoFire’s admin interface. See how a Recurring Payment API looks: {% content-ref url="/pages/BALA2QJwJGuePOQbSsTj" %} [Recurring Billing & Customer Info](/argofire/recurring-billing-and-customer-info) {% endcontent-ref %} Use Case: One-Click Repeat Payment with Stored Token 1. **Initial Tokenization**\ After a successful payment, ArgoFire returns a token representing the customer's payment method. 2. **Stored Credentials**\ Your system securely stores the token for future use, never handling raw card or bank data. 3. **Initiate Repeat Charge**\ When the customer returns, your system uses the stored token to initiate a new charge through the API—eliminating the need to re-enter payment details. 4. **Response Handling**\ You receive confirmation details, including transaction ID, status, and receipt metadata. More about our Tokenization processing: {% content-ref url="/pages/rS5OteIyDWawYZdh4Gmv" %} [Tokenization & Repeat Transactions](/argofire/key-concepts-and-features/tokenization-and-repeat-transactions) {% endcontent-ref %} *** Use Case: Manual Payment Entry via Virtual Terminal 1. **Merchant Login**\ Staff access ArgoFire’s secure virtual terminal interface via browser. 2. **Manual Entry**\ A user inputs customer information and enters card or bank payment details—commonly used for mail order, phone orders, or in-house payments. 3. **Secure Processing**\ ArgoFire processes the payment immediately, ensuring compliance with PCI requirements. 4. **Confirmation & Receipt**\ A confirmation screen is displayed, and a receipt can be emailed directly to the customer. More about our Virtual Terminal processing: {% content-ref url="/pages/azaqdboda3fQ3rffgobu" %} [Virtual Terminal](/argofire/virtual-terminal) {% endcontent-ref %} *** #### Why These Flows Matter * **API-First Approach:** Build fully customized checkout and payment experiences using ArgoFire’s secure, developer-friendly endpoints. * **Built-In Recurring Support:** Schedule and manage automated billing without relying on a separate subscription service. * **Tokenization for Reuse:** Make repeat purchases fast and secure using ArgoFire-generated tokens. * **Virtual Terminal for Admins:** Enable staff to handle back-office donations securely and efficiently. * **Secure & Compliant:** ArgoFire ensures PCI-compliant handling of payment data through tokenization, encryption, and secure infrastructure. # Supported Payment Methods
**ArgoFire** supports multiple secure, tokenizable payment methods for processing purchases, one-time payments, and recurring sales. All methods integrate seamlessly with ArgoFire’s PCI-compliant tokenization, repeat payment, and recurring billing infrastructure. *** #### 1. Credit Cards ArgoFire supports all major credit card brands: * Visa * Mastercard * American Express * Discover **Usage** * Tokenized via `GetToken()` * Processed via `ProcessCreditCard` * Can be used for one-time or recurring sales * Stored securely for repeat sales using `ManageCreditCardInfo` *** #### 2. Debit Cards **Usage**\ Most branded debit cards (e.g., Visa Debit, Mastercard Debit) are processed as credit card transactions—commonly referred to as **offline debit**. These transactions follow the same flows as credit card sales, including tokenization, authorization, and settlement. In contrast, **PIN-based (online) debit cards** are also supported, but their availability and processing behavior vary by processor. PIN debit may require additional configuration and does not follow the standard credit card transaction flow. *** #### 3. ACH / eChecks (Bank Transfers) ArgoFire supports ACH direct debit from U.S. bank accounts. **Usage** * Tokenized via `GetCheckToken()` * Processed via `ProcessCheck` * Can be used for one-time or recurring sales * Stored securely using `ManageCheckInfo` Please see more details of these **ProcessCredit, ProcessCheck, and ProcessDebitCard** APIs here: {% content-ref url="/pages/BiSh52nhhp5VYx1eTKHE" %} [Payment Processing – Credit, Check, Debit](/argofire/full-endpoint-reference-and-tools/payment-processing-credit-check-debit) {% endcontent-ref %} Please find more information about our Tokenization Services here: {% content-ref url="/pages/y20bxK0h6FsOYuiXkxRg" %} [Tokenization Services](/argofire/full-endpoint-reference-and-tools/tokenization-services) {% endcontent-ref %} *** **4. Digital Wallets (Apple Pay & Google Pay)** Apple Pay and Google Pay are supported in specific integration contexts within **ArgoFire**.\ These payment methods can be used by partners whose implementations pass transactions to the `ProcessCreditCard` endpoint, provided the wallet payload is formatted and submitted correctly. * Repeat sales and recurring billing using digital wallets (Apple Pay, Google Pay) are **not currently supported in ArgoFire** but are planned for future updates. * For **ECOMM transactions**, any follow-on transaction (Repeat Sale or Recurring) must also be processed as ECOMM since digital wallet cryptograms are acquired through a web-based flow. * **MOTO transactions** generally do not support digital wallets due to authentication requirements. * Processor-specific availability may vary and should be confirmed prior to launch. For **Digital Wallet** support we recommend implementing our **Embedded Payment Form** versus direct integration. Please see our Embedded Payment Form implementation guide: {% embed url="" %} *** #### Unsupported Payment Types (via API) The following are **not supported** through the ArgoFire Secure Electronic Payments API: * PayPal * Buy Now, Pay Later services (e.g., Klarna, Afterpay) * Cryptocurrency #### Summary Table | Payment Method | API Tokenization | Repeat Sales | Recurring Billing | Endpoint(s) | | ---------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------- | | Credit Card | ✅ | ✅ | ✅ | `GetToken`, `ProcessCreditCard` | | Debit Card | ✅ (as credit) | ✅ | ✅ | `GetToken`, `ProcessCreditCard` | | ACH / eCheck | ✅ | ✅ | ✅ | `GetCheckToken`, `ProcessCheck` | | Apple Pay / Google Pay | ✅ | 🚧 *(future)* | 🚧 *(future)* | `ProcessCreditCar` | *** # Tokenization & Repeat Transactions
**ArgoFire** enables secure, PCI-compliant tokenization of both credit card and ACH payment methods. Tokens allow merchants to process repeat sales without storing or re-collecting sensitive payment data. This is especially useful for returning customers, recurring subscriptions, and virtual terminal users who need to charge saved payment methods. *** Tokenization replaces sensitive payment credentials with secure reference keys that can be safely stored and reused for future transactions. This lets merchants avoid handling raw credit card or bank account data directly, supporting PCI compliance. FrontStream supports two token types: * **CcInfoKey** — A token representing a credit card. * **CheckInfoKey** — A token representing an ACH (bank account). These tokens are returned by the **GetToken** (credit card) and **GetCheckToken** (ACH) Web services and can be used in place of card or account numbers for subsequent transactions like RepeatSale, Return, or Void. Tokens are stored securely on FrontStream’s PCI-certified infrastructure. Your system references the token — not the original payment data — when processing follow-up payments, reducing risk and exposure. *** #### Tokenization Flow **1. Generate ClientSessionID** Call the **GetClientSession** Web service to begin a secure session. **2. Tokenize the Payment Method** * Use **GetToken** to tokenize a credit card (returns a CcInfoKey). * Use **GetCheckToken** to tokenize an ACH account (returns a CheckInfoKey). **3. Store Customer & Token**\ Associate the returned token with a customer record in your system for future use. **4. Future Use**\ Use the stored token to run repeat sale transactions without re-entering payment data. Please see more details of the **GetClientSession, GetToken**, and **GetCheckToken** APIs here: {% content-ref url="/pages/y20bxK0h6FsOYuiXkxRg" %} [Tokenization Services](/argofire/full-endpoint-reference-and-tools/tokenization-services) {% endcontent-ref %} *** #### Use Case: One-Click Repeat Sale **Initial Payment & Tokenization**\ A customer completes a purchase. ArgoFire returns a token, which is stored in your system. **Initiate Repeat Sale**\ When the customer returns, your system submits the stored token via the relevant payment Web service to process a new sale — no re-entry of payment data required. **Secure Processing & Receipt**\ ArgoFire processes the repeat sale and returns a response with full transaction details, including transaction ID, status, and receipt information. *** #### Use Case: Scheduled Recurring Sales **Initial Tokenization**\ A payment method is tokenized using **GetToken** or **GetCheckToken**. **Recurring Schedule Setup**\ Use **ManageContract** to create a recurring schedule tied to the token (e.g., monthly or annually). **Automatic Billing**\ ArgoFire charges the customer automatically according to the configured schedule, using the stored token. **Contract Management**\ Use **ManageContract** to update billing frequency, change amounts, or cancel the schedule as needed. *** #### Key Web Services for Tokenization & Repeat Sales * **GetClientSession** – Begins a secure client session for tokenization. * **GetToken** – Tokenizes a credit card and returns a **CcInfoKey**.\ `https://secure.ftipgw.com/admin/ws/recurring.asmx?op=GetToken` * **GetCheckToken** – Tokenizes an ACH account and returns a **CheckInfoKey**.\ `https://secure.ftipgw.com/admin/ws/recurring.asmx?op=GetCheckToken` * **ManageContract** – Creates, updates, or cancels recurring billing schedules. * **ProcessCreditCard / ProcessCheck** – Submits a transaction using a stored token. Please see more details of these **GetClientSession, GetToken, and GetCheckToken** APIs here: {% content-ref url="/pages/y20bxK0h6FsOYuiXkxRg" %} [Tokenization Services](/argofire/full-endpoint-reference-and-tools/tokenization-services) {% endcontent-ref %} Please see more details of these **ProcessCreditCard / ProcessCheck** APIs here: {% content-ref url="/pages/BiSh52nhhp5VYx1eTKHE" %} [Payment Processing – Credit, Check, Debit](/argofire/full-endpoint-reference-and-tools/payment-processing-credit-check-debit) {% endcontent-ref %} Please see more details on **ManageContract** API here: {% content-ref url="/pages/BALA2QJwJGuePOQbSsTj" %} [Recurring Billing & Customer Info](/argofire/recurring-billing-and-customer-info) {% endcontent-ref %} #### Security & Compliance * **PCI Scope Reduction**: Tokenization keeps sensitive data off your servers. * **Encrypted End-to-End**: All communications are encrypted; tokens are stored securely. * **Merchant-Scoped Tokens**: Tokens can only be used by your merchant account. # Recurring Payments with ArgoFire
**ArgoFire** supports fully automated recurring payments using a customer’s securely tokenized credit card or ACH account. By creating a recurring billing contract tied to a tokenized payment method, you can set up scheduled payments or subscription charges with minimal development effort and no need to store sensitive payment data. *** #### Key Capabilities * **Flexible Scheduling**: Bill customers weekly, monthly, annually, or on custom intervals. * **Auto-Payment Processing**: ArgoFire handles billing automatically based on your schedule. * **Credit Card & ACH Support**: Recurring contracts can use either `CcInfoKey` or `CheckInfoKey` tokens. * **Contract Management**: Update or cancel active schedules via the API. *** #### Recurring Payment Flow #### 1. Create Customer Call the appropriate Web service to create a customer record in ArgoFire. The response includes a **CustomerKey** that identifies this customer for future operations. #### 2. Add Recurring Credit Card Use **GetToken** to tokenize a customer’s credit card. The response returns a **CcInfoKey** along with the **CustomerKey** and optionally a **ContractKey**. Store these keys in your system to reference the customer and their payment method in subsequent transactions. #### 3. Add Recurring Check Use **GetCheckToken** to tokenize a customer’s ACH account. The response returns a **CheckInfoKey** along with the **CustomerKey** and optionally a **ContractKey**. Store these keys for future recurring billing. #### 4. Manage Contract Use **ManageContract** to create, update, or cancel recurring billing schedules. The **ContractKey** returned from prior steps identifies the specific recurring schedule tied to the tokenized payment method. This allows automatic billing on configured intervals (e.g., monthly, annually) without re-entering payment information. *** #### API Operations for Recurring Payments | Operation | Description | | ------------------------------------------ | ---------------------------------------------------------------------------- | | `ManageContract` | Add, update, or cancel recurring billing contracts. | | `ManageCustomer` | Create or update the customer record associated with the recurring contract. | | `ManageCreditCardInfo` / `ManageCheckInfo` | Update the token tied to a customer if payment details change. | For more details of **ManageContract, ManageCustomer, and ManageCredit/CheckInfo** APIs please see: {% content-ref url="/pages/BALA2QJwJGuePOQbSsTj" %} [Recurring Billing & Customer Info](/argofire/recurring-billing-and-customer-info) {% endcontent-ref %} *** #### Important Notes * **Billing Failures**: Failed transactions (e.g., declined cards) are reported in the response. Merchants are responsible for handling follow-ups or retries. * **Customer Notifications**: ArgoFire does not automatically send renewal reminders or receipts. You can use the transaction response data to trigger custom messaging. * **Token Security**: Tokens used in recurring contracts are merchant-scoped and cannot be reused across unrelated merchant accounts. # Surcharging
**ArgoFire** provides support for transaction surcharging, enabling merchants to transparently pass processing fees to payers in compliance with applicable laws and card network rules. This section outlines how surcharges are applied, calculated, and processed through **ArgoFire**. *** #### Overview Surcharging allows merchants to offset processing fees by adding a fee to the total transaction amount when a credit card is used. This feature must be enabled at the account level by FrontStream and is subject to compliance requirements. **Important:** Enabling surcharging requires additional review and approval of your organization by FrontStream to ensure compliance. To simplify surcharging payment processing, we strongly encourage merchants to make full use of surcharge support via our **Embedded Payment Form**, which lessens the compliance review process. Once our **Compliance** team approves your surcharge implementation, surcharge is configured at the account level and applied automatically according to your specified parameters. Please see our **FrontStream Embedded Payment Form** for our surcharge payment method support and implementation steps: {% embed url="" %} *** #### Supported Payment Methods for Surcharging | Payment Method | Surcharging Supported | | -------------- | --------------------- | | Credit Card | ✅ | | Debit Card | ❌ (not permitted) | | ACH / eCheck | ❌ | > ⚠️ Surcharges **must not** be applied to debit card or ACH transactions per network and regulatory guidelines. *** #### How It Works **When surcharging is enabled for a merchant account:** 1. Using our **Embedded Payment Form** implementation the original amount, surcharge amount, and payment methods are handled for you. 2. If eligible for surcharging (e.g., credit card), our Embedded Payment Form automatically calculates, displays, and applies the surcharge. 3. The total charged amount (including surcharge) is reflected in the API response. 4. The surcharge is visible in the transaction metadata and on the customer receipt. *** #### API Behavior * **Surcharges are not submitted by the merchant via API.**\ The calculation and application are handled entirely by our Embedded Payment Form and ArgoFire at the time of processing. * Please contact our FrontStream implementation team for direct API surcharge support as it requires a more strenuous compliance review if implementing versus using our **Embedded Payment Form.** * **The surcharge amount appears in the `TransactionResult.SurchargeAmount` field** in the response, along with the final `TotalAmount`. *** #### Example Response Snippet ```xml xmlCopyEdit 0 Approved 103.50 3.50 CreditCard ``` *** #### Notes and Limitations * **Must be enabled by FrontStream Support**—there is no self-service surcharge toggle. * **Merchant is responsible** for compliance with state laws and card brand rules regarding surcharge disclosures. * **A Merchant Compliance review** is **required** by our **FrontStream Compliance** team before surcharge can be enabled. * Surcharges cannot be configured via API parameters or adjusted per transaction. # Virtual Terminal
The **ArgoFire** Virtual Terminal is a secure, browser-based interface that allows authorized users to manually enter and process payments without needing to build or integrate through the API. It is ideal for back-office staff, support teams, or nonprofits processing donations over the phone. *** #### Overview While ArgoFire’s Secure Electronic Payments API is designed for developers building integrated donation forms or eCommerce workflows, the **Virtual Terminal** provides a ready-made interface for directly entering payment data, including: * One-time credit card and ACH payments * Processing sale, pre-authorization, return, and force authorization transactions * Accessing stored customer payment methods * Issuing refunds or voids on previous transactions * Viewing basic reporting and transaction search *** #### Key Features | Feature | Supported | | -------------------------------- | -------------------------------- | | One-time credit card payments | ✅ | | One-time ACH / eCheck payments | ✅ | | Recurring billing setup | ❌ | | Use of stored payment tokens | ✅ | | Refunds and voids | ✅ | | PCI-compliant entry | ✅ (browser-based, secure) | | User role and permission control | ✅ (via Admin Console) | | Supported transaction types | SALE, PREAUTH, RETURN, FORCEAUTH | *** #### Use Cases * Phone-in donations or purchases * Staff-assisted payments * Refunds without developer involvement * Quick resolution of failed or rejected transactions * Manual processing of force authorizations and pre-authorizations *** #### Access and Permissions Access to the Virtual Terminal is granted through the **FrontStream Admin Console**. All users with admin credentials have full access to all terminal features. Permissions are not role-based at this time. Key functional notes: * **Full access for admins:** Any user with Admin Console access can process payments, issue refunds, and manage transactions. * **Activity visibility:** Transactions processed via the Virtual Terminal are visible in Admin Console reports and associated with the user account used for entry. *** #### Relationship to API While the Virtual Terminal does **not** use your custom API integration, it operates on the **same ArgoFire gateway and account**. This means: * Transactions appear in the same reporting and export tools * Stored tokens created via the Virtual Terminal are accessible via API * API-created records (e.g., customer tokens) can be used in the Virtual Terminal *** #### Important Notes * **No development required.** The Virtual Terminal is fully managed and hosted by FrontStream. * **Great for testing:** You can use the Virtual Terminal to test payment credentials, card behavior, or even failure scenarios without needing to write code. * **Useful fallback:** In case of downtime or integration delays, the Virtual Terminal provides a manual backup for critical payment flows. # Transaction Lifecycle & Status Codes
*** #### Supported Transaction Types The API supports the following transaction types: | Transaction Type | Description | | ----------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | **Sale** | A combined authorization and capture of funds in a single step. | | **Pre-Authorization** | Authorization only, holds funds without capture. | | **Force Authorization** | Capture with an authorization code. Used in exceptional cases. | | **Return** | Refund or credit applied to a settled transaction. | | **Repeat Sale** | A repeat sale transaction that uses a previously stored token to charge the customer again without re-entering payment data. | *Note:* Recurring payment processing is handled via a separate recurring payments API and is not part of these transaction types. *** #### Transaction Status Values The **transactionStatus** field in API responses can hold the following documented values: | Status | Description | | ------------ | ------------------------------------------------------------- | | **Approved** | Transaction successfully authorized or captured. | | **Declined** | Transaction declined by card issuer or processor. | | **Error** | Processing error due to invalid data or system failure. | | **Void** | Authorization canceled before capture/settlement. | | **Refunded** | Amount refunded to the cardholder from a settled transaction. | | **Pending** | Transaction awaiting further processing or settlement. | *** #### HTTP Response Status Codes The API uses standard HTTP status codes. The documented ones include: | Code | Meaning | | ---- | --------------------------------------------------------- | | 200 | Request processed successfully. | | 201 | Resource created successfully (e.g., transaction logged). | | 400 | Bad request due to invalid or missing parameters. | | 401 | Unauthorized: invalid or missing API credentials. | | 403 | Forbidden: insufficient permissions. | | 404 | Resource not found. | | 409 | Conflict, such as duplicate transactions. | | 500 | Internal server error. | *** #### Key Response Fields The following fields are included in the API transaction responses relevant to lifecycle and status: * **transactionId:** Unique identifier for the transaction. * **transactionType:** One of the documented transaction types above (Sale, Pre-Authorization, etc.). * **transactionStatus:** Status value from the documented set (Approved, Declined, etc.). * **responseCode:** Numeric processor or gateway result code. * **responseText:** Human-readable description of the transaction outcome. * **authCode:** Issuer authorization code, when applicable. * **timestamp:** Date and time of the transaction or last status update. *** #### Best Practices * Rely primarily on **transactionStatus** and **responseCode** to drive your business logic. * Log declined and error transactions for troubleshooting and customer support. * Implement retries only for transient server or network failures, not for declined or error responses caused by invalid payment data or issuer decisions. * Use **responseText** for user-facing messaging or logging. # Payment Processing – Credit, Check, Debit
## ProcessCreditCard **Endpoint URL:**\ `https://secure.ftipgw.com/ArgoFire/transact.asmx?op=ProcessCreditCard` **Method:**\ SOAP (Action: `ProcessCreditCard`) **Description:**\ Submits a real-time credit card transaction for authorization and optional capture. This is the core processing endpoint for credit card payments, supporting both one-time and token-based transactions. **Request Parameters:** | Name | Type | Required | Description | | ------------- | ------- | ----------- | ---------------------------------------------------------------- | | Username | string | Yes | API credential username | | Password | string | Yes | API credential password | | TransType | string | Yes | Transaction type: `Sale`, `Auth`, `Return`, or `PostAuth` | | Amount | decimal | Yes | Amount to charge in dollars (e.g., `10.00`) | | NameOnCard | string | No | Cardholder's name | | CcAccountNum | string | Conditional | Raw credit card number — required if no token is used | | CcExpDate | string | Conditional | Expiration date (MMYY) — required if using raw card data | | InvoiceNumber | string | No | Optional invoice number for reconciliation | | Street | string | No | Optional AVS field: billing address street | | Zip | string | No | Optional AVS field: billing ZIP code | | ExtData | string | No | Optional XML-formatted metadata for advanced options (see Notes) | **Notes:** * Either `CcAccountNum` + `CcExpDate` **or** `CcInfoKey` must be provided — both are not required. * `TransType` values: * `Sale` – Authorizes and captures funds * `Auth` – Authorization only (for later capture via `PostAuth`) * `Return` – Issues a refund for a previous sale * `PostAuth` – Captures funds from a previous `Auth` * `ExtData` can be used to pass flags like `12345T]]>` * CVV is not stored and must be passed each time (if required). * This endpoint returns a response object that includes: * `Result` (0 = success) * `RespMSG` (e.g., "Approved") * `AuthCode` * `TransRefID` (used for lookups and reporting) #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/transact.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://TPISoft.com/SmartPayments/ProcessCreditCard" string string string string string string string string string string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length int string string string string string string string string string string string string string string string string string string string string ``` #### SOAP 1.2 The following is a sample SOAP 1.2 request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/transact.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/soap+xml; charset=utf-8 Content-Length: length string string string string string string string string string string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: application/soap+xml; charset=utf-8 Content-Length: length int string string string string string string string string string string string string string string string string string string string string ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/transact.asmx/ProcessCreditCard HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length UserName=string&Password=string&TransType=string&CardNum=string&ExpDate=string&MagData=string&NameOnCard=string&Amount=string&InvNum=string&PNRef=string&Zip=string&Street=string&CVNum=string&ExtData=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length int string string string string string string string string string string string string string string string string string string string string ``` ## Valid Input Reference Characters #### Table 1. Valid Data Characters | DEC | HEX | Character | DEC | HEX | Character | DEC | HEX | Character | | --- | --- | --------- | ---- | --- | --------- | --- | --- | ----------------------- | | 32 | 20 | (space) | 63 | 3F | `?` | 96 | 60 | \\`\ | | 33 | 21 | `!` | 64 | 40 | `@` | 97 | 61 | `a` | | 34 | 22 | `“` | 65 | 42 | `A` | 98 | 62 | `b` | | 35 | 23 | `#` | 66 | 42 | `B` | 99 | 63 | `c` | | 36 | 24 | `$` | 67 | 43 | `C` | 100 | 64 | `d` | | 37 | 25 | `%` | 68 | 44 | `D` | 101 | 65 | `e` | | 38 | 26 | `&` | 69 | 45 | `E` | 102 | 66 | `f` | | 39 | 27 | `‘` | 70 | 46 | `F` | 103 | 67 | `g` | | 40 | 28 | `(` | 71 | 47 | `G` | 104 | 68 | `h` | | 41 | 29 | `)` | 72 | 48 | `H` | 105 | 69 | `i` *(typo note below)* | | 42 | 2A | `*` | 73 | 49 | `I` | 106 | 6A | `j` | | 43 | 2B | `+` | 74 | 4A | `J` | 107 | 6B | `k` | | 44 | 2C | `,` | 75 | 4B | `K` | 108 | 6C | `l` | | 45 | 2D | `–` | 76 | 4C | `L` | 109 | 6D | `m` | | 46 | 2E | `.` | 77 | 4D | `M` | 110 | 6E | `n` | | 47 | 2F | `/` | 78 | 4E | `N` | 111 | 6F | `o` | | 48 | 30 | `0` | 79 | 4F | `O` | 112 | 70 | `p` | | 49 | 31 | `1` | 80 | 50 | `P` | 113 | 71 | `q` | | 50 | 32 | `2` | 81 | 51 | `Q` | 114 | 72 | `r` | | 51 | 33 | `3` | 82 | 52 | `R` | 115 | 73 | `s` | | 52 | 34 | `4` | 83 | 53 | `S` | 116 | 74 | `t` | | 53 | 35 | `5` | 84 | 54 | `T` | 117 | 75 | `u` | | 54 | 36 | `6` | 85 | 55 | `U` | 118 | 76 | `v` | | 55 | 37 | `7` | 86 | 56 | `V` | 119 | 77 | `w` | | 56 | 38 | `8` | 87 | 57 | `W` | 120 | 78 | `x` | | 57 | 39 | `9` | 88 | 58 | `X` | 121 | 79 | `y` | | 58 | 3A | `:` | 89 | 59 | `Y` | 122 | 7A | `z` | | 59 | 3B | `;` | 90 | 5A | `Z` | 123 | 7B | `{` | | 60 | 3C | `<` | 91\* | — | | 124 | 7C | `\|` | | 61 | 3D | `=` | 94 | 5E | `^` | 125 | 7D | `}` | | 62 | 3E | `>` | 95 | 5F | `_` | 126 | 7E | `~` | #### Table 2. XML Character Removal These characters must be stripped by the Payment Server before submitting data to Web Service operations, to ensure correct XML parsing. | Character | XML Parser Encoding | | --------- | ------------------- | | `<` | `<` | | `>` | `>` | | `&` | `&` | | `‘` | `'` | | `“` | `"` | #### Example: Character Removal in Action If you submit: * `NameOnCard = "John & James"` → The `&` is stripped → processed as `John James` * `NameOnCard = "John & James"` → Processed as `John amp; James` ## RepeatSale #### **Description** Creates a new charge by repeating billing information used by a previous sale using its `PNRef`. Ideal for processing payments without re-entering full card details. #### **Endpoint** ``` https://secure.ftipgw.com/ArgoFire/transact.asmx?op=ProcessCreditCard ``` #### **Required Parameters** | Parameter | Required | Description | | ----------- | -------- | ----------------------------------------------------- | | `UserName` | Yes | Merchant’s API username. | | `Password` | Yes | Merchant’s API password. | | `TransType` | Yes | Must be set to `Repeat Sale`. | | `PNRef` | Yes | Reference number of the original sale to be repeated. | #### **Sample Request** ``` test 123 Repeat Sale 2329 ``` #### **Sample Response** ``` 0 Approved APPROVAL VITAL2 VITAL2 2332 False ``` **Response Field Notes** * **Result = 0** → indicates success * **RespMSG** → human-readable status (`Approved`) * **Message** → detailed response message (`APPROVAL VITAL2`) * **AuthCode** → authorization reference for this RepeatSale transaction * **PNRef** → new reference number assigned to the RepeatSale * **GetCommercialCard** → `False` indicates the card is not a commercial card ## Reversal #### Description Reverses a previously authorized but unsettled credit card transaction. Unlike a Void, which cancels the transaction before settlement, a Reversal is used to cancel an authorization that has not yet been captured. #### Endpoint ``` https://secure.ftipgw.com/ArgoFire/transact.asmx?op=ProcessCreditCard ``` *(Same endpoint used for all `ProcessCreditCard` operations.)* #### Required Parameters | Parameter | Required | Description | | ----------- | -------- | ---------------------------------------------------------- | | `UserName` | Yes | Merchant’s API username. | | `Password` | Yes | Merchant’s API password. | | `TransType` | Yes | Must be set to `Reversal`. | | `PNRef` | Yes | Reference number of the original authorization to reverse. | #### Sample Request ``` test 123 Reversal 2327 ``` #### Sample Response ``` 0 Approved REVERSAL ACCEPTED GB00029 ACCEPTED Net_Count=1,Net_Amount=1,Settle_DT=2004-04-13 15:36:26 ``` **Response Field Notes:** * **Result = 0** → indicates successful reversal * **RespMSG** → human-readable status (`Approved`) * **Message** → confirmation message (`REVERSAL ACCEPTED`) * **AuthCode** → authorization reference for the reversal * **ExtData** → contains batch settlement details: count, total amount, settlement timestamp ## Void **Endpoint URL:**\ `https://secure.ftipgw.com/ArgoFire/transact.asmx?op=ProcessCreditCard` **Description:**\ Reverses (voids) a previously authorized yet unsettled credit card transaction. **Required Parameters:**
| Parameter | Required | Description | | ----------- | -------- | ------------------------------------------------------------------------ | | `UserName` | Yes | The merchant’s API username. | | `Password` | Yes | The merchant’s API password. | | `TransType` | Yes | Must be set to `Void`. | | `PNRef` | Yes | The reference number of the original transaction to be voided. | | `CardNum` | No | Must be passed as **null** (not required, but must not contain a value). | | `ExpDate` | No | Must be passed as **null** (not required, but must not contain a value). | **Sample Response** ``` 0 Approved VITAL4 2309 ``` **Response Field Notes** * **Result = 0** → indicates the void was successful * **RespMSG** → human-readable status (`Approved`) * **AuthCode** → approval reference code for the void * **PNRef** → new reference number created for the void transaction ## ProcessCheck **Endpoint URL:**\ `https://secure.ftipgw.com/ArgoFire/transact.asmx?op=ProcessCheck` **Method:**\ SOAP (Action: `ProcessCheck`) **Description:**\ Submits an electronic check (ACH) transaction using either raw bank account information or a previously generated `CheckInfoKey` token. Supports both `Sale` (debit) and `Return` (credit/refund) transactions. **Request Parameters:** | Name | Type | Required | Description | | ------------------- | ------- | ----------- | ---------------------------------------------------------------------- | | Username | string | Yes | API credential username | | Password | string | Yes | API credential password | | TransType | string | Yes | Transaction type: `Sale` or `Return` | | Amount | decimal | Yes | Dollar amount of the transaction (e.g., `50.00`) | | NameOnCheck | string | No | Optional name on the checking account | | CheckNum | string | No | Optional check number (for reference only) | | BankRoutingNum | string | Conditional | Required if not using `CheckInfoKey` | | BankAccountNum | string | Conditional | Required if not using `CheckInfoKey` | | BankAcctType | string | Conditional | `"C"` for Checking, `"S"` for Savings — required with raw account info | | CheckInfoKey | string | Conditional | Tokenized bank account key — use instead of raw routing/account info | | ClientTransactionID | string | No | Optional merchant-defined transaction reference | | InvoiceNumber | string | No | Optional invoice number | | Street | string | No | Optional billing street address (for validation/risk scoring) | | Zip | string | No | Optional ZIP code (for validation/risk scoring) | | Email | string | No | Optional email address for receipt | | ExtData | string | No | Optional XML string for advanced configuration (see Notes) | **Notes:** * You must provide either `BankRoutingNum` + `BankAccountNum` **or** a valid `CheckInfoKey`. * `TransType` must be either: * `Sale` — Debit the account (standard ACH pull) * `Return` — Credit the account (ACH refund) * `ExtData` can carry optional XML metadata like: ``` TSubscription Payment]]> ``` * Funds are not moved in real-time; ACH processing follows standard banking timelines (typically 1–3 business days). * The response includes fields such as: * `Result` (0 = success) * `RespMSG` (e.g., "Approved", "Invalid Routing Number") * `TransRefID` for future lookups #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/transact.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://TPISoft.com/SmartPayments/ProcessCheck" string string string string string string string string string
string
string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length int string string string string string string string string string string string string string string string string string string string string ``` #### SOAP 1.2 The following is a sample SOAP 1.2 request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/transact.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/soap+xml; charset=utf-8 Content-Length: length string string string string string string string string string
string
string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: application/soap+xml; charset=utf-8 Content-Length: length int string string string string string string string string string string string string string string string string string string string string ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/transact.asmx/ProcessCheck HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length UserName=string&Password=string&TransType=string&CheckNum=string&TransitNum=string&AccountNum=string&Amount=string&MICR=string&NameOnCheck=string&DL=string&SS=string&DOB=string&StateCode=string&CheckType=string&ExtData=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length int string string string string string string string string string string string string string string string string string string string string ``` ## Auth Capture #### **Description** Performs both an authorization and a capture in one step—approving and settling a credit card transaction within the current batch (often used in terminal-based or dedicated flows). #### **Endpoint** ``` https://secure.ftipgw.com/ArgoFire/transact.asmx?op=ProcessCreditCard ``` #### **Required Parameters** | Parameter | Required | Description | | ----------- | -------- | ----------------------------------------------- | | `UserName` | Yes | Merchant’s API username. | | `Password` | Yes | Merchant’s API password. | | `TransType` | Yes | Must be set to `Capture`. | | `PNRef` | Yes | Reference number of the previous authorization. | #### **Sample Request** ``` test 123 Capture 2327 ``` #### **Sample Response** ``` 0 Approved ACCEPTED GB00029 ACCEPTED Net_Count=1,Net_Amount=1,Settle_DT=2004-04-13 15:36:26 ``` **Response Field Notes:** * **Result = 0** → indicates successful authorization and capture * **RespMSG** → human-readable status (e.g., `Approved`) * **Message** → additional confirmation (e.g., `ACCEPTED`) * **AuthCode** → reference code confirming the transaction * **ExtData** → contains batch settlement details: count, total amount, settlement timestamp ## ProcessDebitCard **Endpoint URL:**\ `https://secure.ftipgw.com/ArgoFire/transact.asmx?op=ProcessDebitCard` **Method:**\ SOAP (Action: `ProcessDebitCard`) **Description:**\ Processes real-time debit card transactions. This endpoint is used when merchants are configured for debit card routing separate from standard credit card processing. It supports `Sale`, `Auth`, `Return`, and `PostAuth` transaction types, similar to `ProcessCreditCard`. **Request Parameters:** | Name | Type | Required | Description | | ------------------- | ------- | ----------- | --------------------------------------------------------- | | Username | string | Yes | API credential username | | Password | string | Yes | API credential password | | TransType | string | Yes | Transaction type: `Sale`, `Auth`, `Return`, or `PostAuth` | | Amount | decimal | Yes | Amount to charge in dollars (e.g., `25.00`) | | NameOnCard | string | No | Cardholder’s name | | CcAccountNum | string | Conditional | Debit card number — required if not using `CcInfoKey` | | CcExpDate | string | Conditional | Expiration date (MMYY) — required if using raw card data | | CcInfoKey | string | Conditional | Tokenized card key — used instead of card number | | Cvv2 | string | Optional | 3- or 4-digit security code | | ClientTransactionID | string | No | Optional merchant-defined reference ID | | InvoiceNumber | string | No | Optional invoice number | | Street | string | No | Optional AVS field: billing street address | | Zip | string | No | Optional AVS field: billing ZIP code | | Email | string | No | Optional email address for confirmation or metadata | | ExtData | string | No | Optional XML metadata for advanced settings (see Notes) | **Notes:** * Similar in structure to `ProcessCreditCard`, but uses debit routing and settlement channels. * Either `CcAccountNum` + `CcExpDate` **or** `CcInfoKey` must be provided. * `TransType` options: * `Sale`: Authorizes and settles the debit * `Auth`: Authorization only (for delayed capture) * `PostAuth`: Capture of a previously authorized transaction * `Return`: Refund back to the original debit card * Response includes: * `Result` (0 = success) * `RespMSG` (e.g., “Approved”) * `AuthCode` * `TransRefID` (used for future queries and reconciliation) * `ExtData` can include optional XML such as: ``` xmlCopyEdit ``` ``` 7890T]]> ``` #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/transact.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://TPISoft.com/SmartPayments/ProcessDebitCard" string string string string string string string string string string string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length int string string string string string string string string string string string string string string string string string string string string ``` #### SOAP 1.2 The following is a sample SOAP 1.2 request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/transact.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/soap+xml; charset=utf-8 Content-Length: length string string string string string string string string string string string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: application/soap+xml; charset=utf-8 Content-Length: length int string string string string string string string string string string string string string string string string string string string string ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/transact.asmx/ProcessDebitCard HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length UserName=string&Password=string&TransType=string&CardNum=string&ExpDate=string&MagData=string&NameOnCard=string&Amount=string&InvNum=string&PNRef=string&Pin=string&RegisterNum=string&SureChargeAmt=string&CashBackAmt=string&ExtData=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length int string string string string string string string string string string string string string string string string string string string string ``` ### ExtData `ExtData` is an XML-formatted field used to pass **processor-specific, optional, or extended transaction data** in a `ProcessCreditCard` request. It serves as a flexible container for: * Processor-required fields (e.g., Wells Fargo host-based processing) * Transaction behavior modifiers (e.g., partial auth, duplicate handling) * Enhanced data (commercial cards, recurring transactions, invoice detail) > Some processors require `ExtData` for all transactions. `ExtData` must contain **well-formed XML**. #### Basic Structure ``` 123 T ``` #### Nested Structure (Supported) ``` 123
8320 85284
10.00 T ``` *** **Structural Rules (Critical)** * Multiple **top-level elements are allowed** * Nested elements must be **properly contained** * XML must be **well-formed and valid** #### Invalid Example (Broken Nesting) ``` 123 10.00 T ``` **Issue:** Mixing structured and unstructured data creates an invalid hierarchy. *** **Field Categories** #### Behavior Modifiers Fields that **change how the transaction is processed**. | Field | Description | Values | | -------------- | ------------------------------------- | --------------------- | | `Force` | Allow duplicate transactions | `T`, `F` | | `Partial` | Allow partial authorization (FSA/HSA) | `T`, `F` | | `TrainingMode` | Enable training/test mode | `T`, `F` | | `Timeout` | Timeout in seconds | Numeric (default: 40) | *** #### Card & Entry Data | Field | Description | Values | | ------------ | ---------------------- | -------------------------------------------------------------- | | `EntryMode` | Card entry method | `Manual`, `MagneticStripe`, `ICC`, `Proximity` | | `CVPresence` | CVV presence indicator | `None`, `NotSubmitted`, `Submitted`, `Illegible`, `NotPresent` | *** #### Transaction & Reference Data | Field | Description | | -------------------- | --------------------------- | | `CustomerID` | Customer identifier | | `CustomerIDAuthCode` | Original authorization code | | `RegisterNum` | Register number | | `ServerID` | Server identifier | | `PONum` | Purchase order number | | `City` | Billing city | *** Amount & Commercial Data | Field | Description | | ---------- | -------------------------------- | | `TipAmt` | Tip amount | | `TaxAmt` | Tax amount (commercial cards) | | `CustCode` | Customer code (commercial cards) | *** Recurring Transactions | Field | Description | | --------------- | ---------------------------- | | `SequenceNum` | Current transaction number | | `SequenceCount` | Total number of transactions | *** Other | Field | Description | Values | | ------------- | ---------------------- | -------- | | `BillPayment` | Bill payment indicator | `T`, `F` | *** `ExtData` must contain **well-formed XML**. **Basic Structure** ``` 123 T ``` **Nested Structure (Supported)** ``` 123
8320 85284
10.00 T ``` *** **Structural Rules (Critical)** * Multiple **top-level elements are allowed** * Nested elements must be **properly contained** * XML must be **well-formed and valid** **Invalid Example (Broken Nesting)** ``` 123 10.00 T ``` **Issue:** Mixing structured and unstructured data creates an invalid hierarchy. *** **Field Categories** **Behavior Modifiers** Fields that **change how the transaction is processed**. | Field | Description | Values | | -------------- | ------------------------------------- | --------------------- | | `Force` | Allow duplicate transactions | `T`, `F` | | `Partial` | Allow partial authorization (FSA/HSA) | `T`, `F` | | `TrainingMode` | Enable training/test mode | `T`, `F` | | `Timeout` | Timeout in seconds | Numeric (default: 40) | *** **Card & Entry Data** | Field | Description | Values | | ------------ | ---------------------- | -------------------------------------------------------------- | | `EntryMode` | Card entry method | `Manual`, `MagneticStripe`, `ICC`, `Proximity` | | `CVPresence` | CVV presence indicator | `None`, `NotSubmitted`, `Submitted`, `Illegible`, `NotPresent` | *** **Transaction & Reference Data** | Field | Description | | -------------------- | --------------------------- | | `CustomerID` | Customer identifier | | `CustomerIDAuthCode` | Original authorization code | | `RegisterNum` | Register number | | `ServerID` | Server identifier | | `PONum` | Purchase order number | | `City` | Billing city | *** #### Amount & Commercial Data | Field | Description | | ---------- | -------------------------------- | | `TipAmt` | Tip amount | | `TaxAmt` | Tax amount (commercial cards) | | `CustCode` | Customer code (commercial cards) | *** **Recurring Transactions** | Field | Description | | --------------- | ---------------------------- | | `SequenceNum` | Current transaction number | | `SequenceCount` | Total number of transactions | *** **Other** | Field | Description | Values | | ------------- | ---------------------- | -------- | | `BillPayment` | Bill payment indicator | `T`, `F` | *** Usage Guidelines Use `ExtData` when: * Required by the processor * Implementing advanced features (recurring, Level 2/3, invoice data) * Passing fields not available in the standard request *** Behavior Notes * `ExtData` is **not strictly validated** at the platform level * Validation and requirements are often **processor-specific** * Unsupported fields may be ignored or cause failure Partial Authorization If `Partial = T`, the processor may approve **less than the requested amount**.\ Integrations must handle partial approvals accordingly. Use `ExtData` when: * Required by the processor * Implementing advanced features (recurring, Level 2/3, invoice data) * Passing fields not available in the standard request *** # Tokenization Services
## GetClientSession **Endpoint URL:**\ `https://secure.ftipgw.com/admin/ws/recurring.asmx?op=GetClientSessionID` **Method:**\ SOAP (Action: `GetClientSessionID`) **Description:**\ Generates a `ClientSessionID`, which is a temporary token used to associate a cardholder or payer with subsequent tokenization requests (e.g., `GetToken`, `GetCheckToken`). This session ID must be passed in with any tokenization call. **Request Parameters:** | Name | Type | Required | Description | | --------- | ------ | -------- | ------------------------------------------------- | | Username | string | Yes | API credential username | | Password | string | Yes | API credential password | | ClientIP | string | Yes | IP address of the end user initiating the session | | UserAgent | string | No | Optional browser or client User-Agent string | **Notes:** * `ClientSessionID` is **required** in all tokenization calls and is valid for a short time only. * `Username` and `Password` are SOAP-level credentials, not tied to merchant accounts. * `ClientIP` should reflect the actual end user's IP — using a server IP may affect fraud tools. * Including the `UserAgent` may assist with device fingerprinting or risk analysis, if enabled. * Be sure to secure and store this session ID only temporarily. #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/recurring.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://www.tpisoft.com/Admin/ws/GetClientSessionID" string string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string string string string string string OK or Unknown_Error or Access_Denied or Invalid_Login or Invalid_User_Status or Invalid_User or User_Not_Found or Username_Already_In_Use or Username_Has_Invalid_Characters or Not_Enough_Privilege or Invalid_PartnerID or Invalid_VendorID or Invalid_Argument or Invalid_Record or Transaction_Type_Not_Supported_By_Host or Internal_Error or Invalid_ProcessorID or Processor_Not_Found or InValidPassword string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/recurring.asmx/GetClientSessionID HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length Username=string&Password=string&Vendor=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string string string string string string OK or Unknown_Error or Access_Denied or Invalid_Login or Invalid_User_Status or Invalid_User or User_Not_Found or Username_Already_In_Use or Username_Has_Invalid_Characters or Not_Enough_Privilege or Invalid_PartnerID or Invalid_VendorID or Invalid_Argument or Invalid_Record or Transaction_Type_Not_Supported_By_Host or Internal_Error or Invalid_ProcessorID or Processor_Not_Found or InValidPassword string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` ## GetToken **Endpoint URL:**\ `https://secure.ftipgw.com/admin/ws/recurring.asmx?op=GetToken` **Method:**\ SOAP (Action: `GetToken`) **Description:**\ Retrieves a `CcInfoKey` for a user, which represents a tokenized version of the credit card. This key can be reused for future transactions without resubmitting raw card data. **Request Parameters:** | Name | Type | Required | Description | | --------------- | ------ | -------- | ---------------------------------- | | ClientSessionID | string | Yes | Identifies the user session | | CcAccountNum | string | Yes | Raw credit card number to tokenize | | CcExpDate | string | Yes | Expiration date in MMYY format | | CcNameOnCard | string | No | Name on the card, as it appears | **Notes:** * This is a sensitive operation and must be called over HTTPS with appropriate security controls in place. * The resulting `CcInfoKey` is used in place of card data for subsequent transactions. * This call does **not** authorize a payment or validate the card beyond formatting. * `ClientSessionID` must be retrieved via a prior call to `GetClientSession`. * The `CcNameOnCard` field is optional and not validated or persisted. #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/recurring.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://www.tpisoft.com/Admin/ws/GetToken" string string string string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string string string string string string OK or Unknown_Error or Access_Denied or Invalid_Login or Invalid_User_Status or Invalid_User or User_Not_Found or Username_Already_In_Use or Username_Has_Invalid_Characters or Not_Enough_Privilege or Invalid_PartnerID or Invalid_VendorID or Invalid_Argument or Invalid_Record or Transaction_Type_Not_Supported_By_Host or Internal_Error or Invalid_ProcessorID or Processor_Not_Found or InValidPassword string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/recurring.asmx/GetToken HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length ClientSessionID=string&CcAccountNum=string&CcExpDate=string&CcNameOnCard=string&CcStreet=string&CcZip=string&FirstName=string&LastName=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string string string string string string OK or Unknown_Error or Access_Denied or Invalid_Login or Invalid_User_Status or Invalid_User or User_Not_Found or Username_Already_In_Use or Username_Has_Invalid_Characters or Not_Enough_Privilege or Invalid_PartnerID or Invalid_VendorID or Invalid_Argument or Invalid_Record or Transaction_Type_Not_Supported_By_Host or Internal_Error or Invalid_ProcessorID or Processor_Not_Found or InValidPassword string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` ## GetCheckToken **Endpoint URL:**\ `https://secure.ftipgw.com/admin/ws/recurring.asmx?op=GetCheckToken` **Method:**\ SOAP (Action: `GetCheckToken`) **Description:**\ Retrieves a `CheckInfoKey` for a user, which represents a tokenized version of their bank account information. This key can be used to initiate ACH or eCheck transactions without resubmitting raw bank data. **Request Parameters:** | Name | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------------ | | ClientSessionID | string | Yes | Identifies the user session | | BankRoutingNum | string | Yes | The bank routing number (9 digits) | | BankAccountNum | string | Yes | The bank account number | | BankAcctType | string | Yes | Type of account: `"C"` for Checking, `"S"` for Savings | | BankName | string | No | Optional bank name | **Notes:** * The returned `CheckInfoKey` can be stored and reused for initiating future ACH transactions. * This call does **not** validate the bank account or perform any micro-deposits. * `ClientSessionID` must be created via `GetClientSession` beforehand. * The `BankAcctType` is typically `"C"` or `"S"` — this field must be correctly set or the request will fail. * Always use HTTPS, and do not log or persist raw account/routing numbers. #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/recurring.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://www.tpisoft.com/Admin/ws/GetCheckToken" string string string string string string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string string string string string string OK or Unknown_Error or Access_Denied or Invalid_Login or Invalid_User_Status or Invalid_User or User_Not_Found or Username_Already_In_Use or Username_Has_Invalid_Characters or Not_Enough_Privilege or Invalid_PartnerID or Invalid_VendorID or Invalid_Argument or Invalid_Record or Transaction_Type_Not_Supported_By_Host or Internal_Error or Invalid_ProcessorID or Processor_Not_Found or InValidPassword string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/recurring.asmx/GetCheckToken HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length ClientSessionID=string&CkAccountNum=string&CkTransitNum=string&CkNameOnAccount=string&CheckType=string&AccountType=string&CkStreet=string&CkZip=string&FirstName=string&LastName=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string string string string string string OK or Unknown_Error or Access_Denied or Invalid_Login or Invalid_User_Status or Invalid_User or User_Not_Found or Username_Already_In_Use or Username_Has_Invalid_Characters or Not_Enough_Privilege or Invalid_PartnerID or Invalid_VendorID or Invalid_Argument or Invalid_Record or Transaction_Type_Not_Supported_By_Host or Internal_Error or Invalid_ProcessorID or Processor_Not_Found or InValidPassword string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` ##
# General Info & Utilities
## GetCardUpdates **Endpoint URL:**\ [**https://secure.ftipgw.com/Admin/ws/TrxDetail.asmx?op=GetCardUpdates**]()\ \ **Method:**\ Supports both **SOAP POST** and **HTTP GET/POST** (form‑encoded)\ \ **Description**\ Retrieves details of all card updates processed for a merchant within a specified date range, including updates like expiration date or account number changes reported by card updater services\ \ **Request Parameters**
| Parameter | Type | Required | Description | | --------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | **UserName** | string | Yes | User name assigned by the payment gateway [frontstream.com+1secure.ftipgw.com+1](https://www.frontstream.com/developers/secure-electronics-payments-api/documentation/getcardupdates?utm_source=chatgpt.com) | | **Password** | string | Yes | Corresponding password | | **MerchantKey** | string | Yes | Merchant’s key; the query runs against this merchant account | | **BeginDt** | string | Yes | Start of date range (`MM/DD/YYYY`); auto‑converted to `T00:00:00.0000AM` | | **EndDt** | string | Yes | End of date range (`MM/DD/YYYY`); auto‑converted to `T12:59:59.9999PM` | | **ExtData** | string | No | Optional XML string for extended data | \ **Notes**
* **Response Format:** * Returns an XML payload containing one `` node per card update event [secure.ftipgw.com+2frontstream.com+2secure.ftipgw.com+2](https://www.frontstream.com/developers/secure-electronics-payments-api/documentation/getcardupdates?utm_source=chatgpt.com). * **Response Fields:** * Includes fields like ``, ``, `` (boolean), ``, ``, and ``, among others [frontstream.com](https://www.frontstream.com/developers/secure-electronics-payments-api/documentation/getcardupdates?utm_source=chatgpt.com). * **Response Codes:** * Codes such as `000` (New Card), `201` (Expiration Updated), `202` (Account Number Updated), `203` (Account Closed), etc. A complete code‑to‑text mapping is available in the documentation [frontstream.com](https://www.frontstream.com/developers/secure-electronics-payments-api/documentation/getcardupdates?utm_source=chatgpt.com). * **Date Handling:** * Input dates are normalized with explicit AM/PM boundaries (`BeginDt` at midnight start, `EndDt` just before midnight end). * **Multiple Records:** * You may receive multiple `
` entries—make sure parsing logic handles arrays of updates. * **ExtData Usage:** * While optional, `ExtData` can be used to filter or enhance the request/response. Its exact format is provider‑specific XML. * **Protocol Flexibility:** * This endpoint can be invoked via SOAP or simple HTTP GET/POST — choose based on your integration context **SOAP 1.1**\ The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /Admin/ws/TrxDetail.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://demo.tpisoft.com/Admin/ws/GetCardUpdates" string string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string ``` **HTTP POST**\ The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /Admin/ws/TrxDetail.asmx/GetCardUpdates HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length username=string&password=string&merchantKey=string&beginDt=string&endDt=string&extData=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string ``` ## GetCardType **Endpoint URL:**\ `https://secure.ftipgw.com/ArgoFire/validate.asmx?op=GetCardType` **Method:**\ SOAP (Action: `GetCardType`) **Description:**\ Determines the type of a credit card (e.g., Visa, MasterCard, Discover, Amex) based on the card number provided. Intended for validation or routing decisions within ArgoFire-integrated flows. **Request Parameters:** | Name | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------ | | CcAccountNum | string | Yes | Credit card number to evaluate | **Notes:** * Returns a string indicating the card brand (e.g., `"Visa"`, `"MC"`, `"Amex"`). * No transaction or tokenization is performed — this is strictly a metadata lookup. * Often used for UI display or to conditionally apply rules before submission. * Ensure the card number is never logged or stored during this request. * This endpoint is part of the **ArgoFire validation suite**, and may differ slightly in behavior from the legacy version under `/recurring.asmx`. #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/validate.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://localhost/SmartPayments/GetCardType" string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string ``` #### SOAP 1.2 The following is a sample SOAP 1.2 request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/validate.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/soap+xml; charset=utf-8 Content-Length: length string ``` ``` HTTP/1.1 200 OK Content-Type: application/soap+xml; charset=utf-8 Content-Length: length string ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/validate.asmx/GetCardType HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length CardNumber=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string ``` ## GetInfo **Endpoint URL:**\ `https://secure.ftipgw.com/ArgoFire/transact.asmx?op=GetInfo` **Method:**\ SOAP (Action: `GetInfo`) **Description:**\ Retrieves full details about a previously submitted transaction using its `TransRefID`. This is often used for reconciliation, auditing, or checking the status and metadata of a payment after the fact. **Request Parameters:** | Name | Type | Required | Description | | ---------- | ------ | -------- | ------------------------------------------ | | Username | string | Yes | API credential username | | Password | string | Yes | API credential password | | TransRefID | string | Yes | Unique transaction reference ID to look up | **Notes:** * Returns a full record of the transaction, including status, amounts, timestamps, card type, and custom fields. * The `TransRefID` is returned by most ArgoFire transaction calls (e.g., `ProcessCreditCard`, `ProcessCheck`). * This endpoint does **not** return sensitive card data (e.g., PAN or CVV). * Commonly used by backend systems to confirm success, capture metadata, or display results to admins. * Must be called with valid API credentials — not tied to a session or tokenization flow. #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/transact.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://TPISoft.com/SmartPayments/GetInfo" string string string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length int string string string string string string string string string string string string string string string string string string string string ``` #### SOAP 1.2 The following is a sample SOAP 1.2 request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/transact.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/soap+xml; charset=utf-8 Content-Length: length string string string string ``` ``` HTTP/1.1 200 OK Content-Type: application/soap+xml; charset=utf-8 Content-Length: length int string string string string string string string string string string string string string string string string string string string string ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/transact.asmx/GetInfo HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length UserName=string&Password=string&TransType=string&ExtData=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length int string string string string string string string string string string string string string string string string string string string string ``` ## CaptureAll **Endpoint URL:**\ `https://secure.ftipgw.com/SmartPayments/transact.asmx?op=ProcessCreditCard` (Same as other `ProcessCreditCard` operations.) **Description:**\ The **CaptureAll** operation closes and settles all approved credit card transactions in the merchant’s current open batch. It is used to submit the entire batch for settlement with a single call, rather than capturing individual transactions one by one. #### Request Parameters | Parameter | Required | Description | | ----------- | -------- | ---------------------------- | | `UserName` | Yes | The merchant’s API username. | | `Password` | Yes | The merchant’s API password. | | `TransType` | Yes | Must be set to `CaptureAll`. | #### Sample Request ``` test 123 CaptureAll ``` #### Sample Response ``` 0 Approved ACCEPTED GB00029 ACCEPTED Net_Count=5,Net_Amount=275.00,Settle_DT=2004-04-13 15:36:26 ``` * **Result** `0` = successful batch settlement * **RespMSG / Message** = confirmation that batch was closed and accepted * **AuthCode** = settlement confirmation reference * **ExtData** = provides batch statistics: total transaction count, total settled amount, and settlement date/time ## ArgoFire Response Codes The list below contains result codes returned in the Result response field of the API or GUI AuthCode field. A decline returned by the payment processor for the API response field is value twelve (12) or thirteen (13). An approval is value zero (0). Any other value is an error code, which is returned by ArgoFire and not by the payment processor. Please note that when programmatically validating a transaction’s result, from the API, this value should be used instead of any response message describing the result. I.e. do *not* use RespMSG or Message response fields, as these values may vary. Please note that this list is subject to change without prior notice. | Value | Description | | ----- | ---------------------------------------------------------------------------------------- | | -100 | Transaction NOT Processed; Generic Host Error | | 0 | Approved | | 1 | User Authentication Failed | | 2 | Invalid Transaction | | 3 | Invalid Transaction Type | | 4 | Invalid Amount | | 5 | Invalid Merchant Information | | 7 | Field Format Error | | 8 | Not a Transaction Server | | 9 | Invalid Parameter Stream | | 10 | Too Many Line Items | | 11 | Client Timeout Waiting for Response | | 12 | Decline | | 13 | Referral | | 14 | Transaction Type Not Supported In This Version | | 19 | Original Transaction ID Not Found | | 20 | Customer Reference Number Not Found | | 22 | Invalid ABA Number | | 23 | Invalid Account Number | | 24 | Invalid Expiration Date | | 25 | Transaction Type Not Supported by Host | | 26 | Invalid Reference Number | | 27 | Invalid Receipt Information | | 28 | Invalid Check Holder Name | | 29 | Invalid Check Number | | 30 | Check DL Verification Requires DL State | | 40 | Transaction did not connect (to NCN because SecureNCIS is not running on the web server) | | 50 | Insufficient Funds Available | | 99 | General Error | | 100 | Invalid Transaction Returned from Host | | 101 | Timeout Value too Small or Invalid Time Out Value | | 102 | Processor Not Available | | 103 | Error Reading Response from Host | | 104 | Timeout waiting for Processor Response | | 105 | Credit Error | | 106 | Host Not Available | | 107 | Duplicate Suppression Timeout | | 108 | Void Error | | 109 | Timeout Waiting for Host Response | | 110 | Duplicate Transaction | | 111 | Capture Error | | 112 | Failed AVS Check | | 113 | Cannot Exceed Sales Cap | | 201 | FPRejected\_Floor | | 202 | FPRejected\_Ceiling | | 203 | FPRejected\_IP | | 204 | FPRejected\_BIN | | 205 | FPRejected\_Velocity | | 1000 | Generic Host Error | | 1001 | Invalid Login | | 1002 | Insufficient Privilege or Invalid Amount | | 1003 | Invalid Login Blocked | | 1004 | Invalid Login Deactivated | | 1005 | Transaction Type Not Allowed | | 1006 | Unsupported Processor | | 1007 | Invalid Request Message | | 1008 | Invalid Version | | 1010 | Payment Type Not Supported | | 1011 | Error Starting Transaction | | 1012 | Error Finishing Transaction | | 1013 | Error Checking Duplicate | | 1014 | No Records To Settle (in the current batch) | | 1015 | No Records To Process (in the current batch) | *AVS Response Codes* The following table contains the possible response values returned for address verification (AVS). | Value | Description | | ----- | ------------------------------------------------------------------------------------------------------------------- | | X | Exact: Address and nine-digit Zip match | | Y | Yes: Address and five-digit Zip match | | A | Address: Address matches, Zip does not | | Z | 5-digit Zip: 5-digit Zip matches, address doesn’t | | W | Whole Zip: 9-digit Zip matches, address doesn’t | | N | No: Neither address nor Zip matches | | U | Unavailable: Address information not available | | G | Unavailable: Address information not available for international transaction | | R | Retry: System unavailable or time-out | | E | Error: Transaction unintelligible for AVS or edit error found in the message that prevents AVS from being performed | | S | Not Supported: Issuer doesn’t support AVS service | | B | \* Street Match: Street addresses match for international transaction, but postal code doesn’t | | C | \* Street Address: Street addresses and postal code not verified for international transaction | | D | \* Match: Street addresses and postal codes match for international transaction | | I | \* Not Verified: Address Information not verified for International transaction | | M | \* Match: Street addresses and postal codes match for international transaction | | P | \* Postal Match: Postal codes match for international transaction, but street address doesn’t | | 0 | \*\* No response sent | | 5 | Invalid AVS response | \* These values are Visa specific. \*\* These values are returned by ArgoFire and not the processor. *CV Response Codes* The following table contains the possible response values returned for a CVV2/CVC2/CID check. | Value | Description | | ----- | -------------------------------------------------------------------------------------------------------------------------------------------- | | M | CVV2/CVC2/CID Match | | N | CVV2/CVC2/CID No Match | | P | Not Processed | | S | Issuer indicates that the CV data should be present on the card, but the merchant has indicated that the CV data is not present on the card. | | U | Unknown / Issuer has not certified for CV or issuer has not provided Visa/MasterCard with the CV encryption keys. | | X | Server Provider did not respond | # Transaction Types and Behaviors
## Transaction Types & Behaviors This reference explains the transaction types and behaviors available through ArgoFire. It outlines how `TransType` values map to different endpoints and what actions they trigger in the transaction lifecycle. Use this guide when developing against endpoints like `ProcessCreditCard`, `ProcessCheck`, or `ProcessDebitCard`, or when implementing features such as `Void`, `PostAuth`, `Repeat Sale`, or `Capture All`. ## Transaction Types These are core `TransType` values passed into transaction endpoints to define the behavior of a payment operation. | Name | Description | | ------------ | ----------------------------------------------------------------------------------------------- | | **Sale** | Standard payment. Funds are authorized and captured immediately. | | **Auth** | Authorization only. Holds funds without capturing. Captured later via `PostAuth`. | | **PostAuth** | Captures a previously authorized transaction. | | **Return** | Refunds a settled `Sale` or captured `Auth`. | | **Void** | Cancels a `Sale` or `Auth` before it is settled. | | **Reversal** | Attempts to cancel a transaction immediately after submission. Rare; depends on issuer support. | ## Transaction Workflows These are compound or operational workflows that build on the basic transaction types, often referencing prior transactions or using stored payment data. | Name | Description | | --------------- | --------------------------------------------------------------------------------- | | **Capture All** | Captures all unsettled `Auth` transactions for the merchant in a batch operation. | | **Repeat Sale** | Submits a new `Sale` using stored payment data from a previous transaction. | ## Transaction Usage Details **Sale** * **TransType:** `Sale` * **Used With:** `ProcessCreditCard`, `ProcessCheck`, `ProcessDebitCard` * **Behavior:** Charges the payment method and settles normally. **Auth** * **TransType:** `Auth` * **Used With:** `ProcessCreditCard`, `ProcessDebitCard` * **Behavior:** Places a hold on funds. Use `PostAuth` to settle later. **PostAuth** * **TransType:** `PostAuth` * **Used With:** `ProcessCreditCard`, `ProcessDebitCard` * **Behavior:** Captures funds from a prior `Auth`. **Return** * **TransType:** `Return` * **Used With:** `ProcessCreditCard`, `ProcessCheck`, `ProcessDebitCard` * **Behavior:** Refunds funds to the original payment method. **Void** * **TransType:** `Void` * **Used With:** `ProcessCreditCard`, `ProcessCheck`, `ProcessDebitCard` * **Behavior:** Cancels a transaction before it settles. * **Limitation:** Must be used on the same day before the transaction is batched for settlement. **Reversal** * **TransType:** `Reversal` *(or configured via `ExtData`)* * **Used With:** `ProcessCreditCard` * **Behavior:** Attempts to cancel a transaction immediately after submission. May not be supported by all issuers. ## Workflow Behaviors **Capture All** * **Endpoint:** `CaptureAll` * **Behavior:** Captures all currently authorized, unsettled transactions for the merchant. * **Use Case:** End-of-day batch capture for all prior `Auth` transactions. **Repeat Sale** * **Endpoint:** `ProcessCreditCard` or `ProcessCheck` * **Input:** Requires a previously stored `CcInfoKey`, `CheckInfoKey`, or `TransRefID` passed via `ExtData` * **Behavior:** Submits a new `Sale` using stored payment credentials from a prior transaction. \ \


# Recurring Billing & Customer Info
## AddRecurringCreditCard **Endpoint URL:**\ `https://secure.ftipgw.com/admin/ws/recurring.asmx?op=AddRecurringCreditCard` **Method:**\ Supports both **SOAP POST** and **HTTP POST** (form-encoded) **Description:**\ Creates a new recurring credit card billing contract by adding a customer profile, a recurring contract, and a payment method in a single API call. This endpoint simplifies recurring billing setup by consolidating multiple setup steps into a single request. *** ### Request Parameters | Parameter | Type | Required | Description | | -------------------- | ------ | -------- | ---------------------------------------------------------------- | | UserName | string | Yes | Admin user name for authentication | | Password | string | Yes | Admin user password | | Vendor | string | Yes | Merchant identifier (numeric key) | | CustomerID | string | Yes | Unique customer identifier provided by the merchant | | CustomerName | string | Yes | Full name of the customer | | FirstName | string | No | Customer’s first name | | LastName | string | No | Customer’s last name | | Title | string | No | Customer’s title | | Department | string | No | Customer’s department | | Street1 | string | No | Address line 1 | | Street2 | string | No | Address line 2 | | Street3 | string | No | Address line 3 | | City | string | No | City | | StateID | string | No | 2-character U.S. state abbreviation | | Province | string | No | Province (used for international addresses) | | Zip | string | No | Postal/ZIP code | | CountryID | string | No | 3-character country code (default is "USA") | | Email | string | No | Email address | | Mobile | string | No | Mobile phone number | | DayPhone | string | No | Daytime phone number | | Fax | string | No | Fax number | | ContractID | string | Yes | Unique contract ID assigned by the merchant | | ContractName | string | No | Descriptive name for the billing contract | | BillAmt | string | Yes | Billing amount per cycle | | TaxAmt | string | No | Tax amount | | TotalAmt | string | Yes | Total amount to bill (must equal BillAmt + TaxAmt) | | StartDate | string | Yes | Contract start date (must be at least one day in the future) | | EndDate | string | No | Optional end date; omit for indefinite billing | | BillingPeriod | string | Yes | One of: DAY, WEEK, MONTH, or YEAR | | BillingInterval | string | Yes | Frequency for the selected billing period (e.g., every 2 months) | | MaxFailures | string | No | Number of allowed consecutive failures before suspension | | FailureInterval | string | No | Days between retry attempts after failure | | EmailCustomer | string | No | TRUE/FALSE – send customer email confirmation | | EmailMerchant | string | No | TRUE/FALSE – send merchant email confirmation | | EmailCustomerFailure | string | No | TRUE/FALSE – notify customer on failure | | EmailMerchantFailure | string | No | TRUE/FALSE – notify merchant on failure | | CcAccountNum | string | Yes | Credit card number (digits only) | | CcExpDate | string | Yes | Expiration date (MMYY format) | | CcNameOnCard | string | No | Name as it appears on the card | | CcStreet | string | No | Billing address street line | | CcZip | string | No | Billing ZIP/postal code | | ExtData | string | No | Optional extended data (XML string for custom fields) | *** ### Notes * This endpoint is designed for **quick setup** of a full recurring billing profile in one request. It simultaneously creates the customer, the billing contract, and the associated payment method. * The **StartDate must be at least one day in the future**. Attempts to use today's date will result in a validation error. * **BillingPeriod** and **BillingInterval** determine the recurrence schedule. For example, `BillingPeriod=MONTH` and `BillingInterval=1` means monthly billing. * The **CcAccountNum** and **CcExpDate** fields are required for creating the credit card payment method. If you instead want to use a tokenized payment method, a different endpoint should be used. * If **TotalAmt ≠ BillAmt + TaxAmt**, the request will fail. * Optional fields such as **EmailCustomer**, **EmailMerchant**, and their failure variants provide control over automated email notifications. * The **ExtData** field supports gateway- or partner-specific extensions via embedded XML. For most merchants, this can be left blank. #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/recurring.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://www.tpisoft.com/Admin/ws/AddRecurringCreditCard" string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string string string string string string OK or Unknown_Error or Access_Denied or Invalid_Login or Invalid_User_Status or Invalid_User or User_Not_Found or Username_Already_In_Use or Username_Has_Invalid_Characters or Not_Enough_Privilege or Invalid_PartnerID or Invalid_VendorID or Invalid_Argument or Invalid_Record or Transaction_Type_Not_Supported_By_Host or Internal_Error or Invalid_ProcessorID or Processor_Not_Found or InValidPassword string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/recurring.asmx/AddRecurringCreditCard HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length Username=string&Password=string&Vendor=string&CustomerID=string&CustomerName=string&FirstName=string&LastName=string&Title=string&Department=string&Street1=string&Street2=string&Street3=string&City=string&StateID=string&Province=string&Zip=string&CountryID=string&Email=string&DayPhone=string&NightPhone=string&Fax=string&Mobile=string&ContractID=string&ContractName=string&BillAmt=string&TaxAmt=string&TotalAmt=string&StartDate=string&EndDate=string&BillingPeriod=string&BillingInterval=string&MaxFailures=string&FailureInterval=string&EmailCustomer=string&EmailMerchant=string&EmailCustomerFailure=string&EmailMerchantFailure=string&CcAccountNum=string&CcExpDate=string&CcNameOnCard=string&CcStreet=string&CcZip=string&ExtData=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string string string string string string OK or Unknown_Error or Access_Denied or Invalid_Login or Invalid_User_Status or Invalid_User or User_Not_Found or Username_Already_In_Use or Username_Has_Invalid_Characters or Not_Enough_Privilege or Invalid_PartnerID or Invalid_VendorID or Invalid_Argument or Invalid_Record or Transaction_Type_Not_Supported_By_Host or Internal_Error or Invalid_ProcessorID or Processor_Not_Found or InValidPassword string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` ## AddRecurringCheck **Endpoint URL:**\ `https://secure.ftipgw.com/admin/ws/recurring.asmx?op=AddRecurringCheck` **Method:**\ Supports **SOAP POST** and **HTTP POST** (form-encoded) **Description:**\ Adds a new recurring check-based billing contract by creating a customer profile, a billing contract, and a check payment method in one call. Useful for recurring ACH billing setups. ### Request Parameters | Parameter | Type | Required | Description | | -------------------- | ------ | -------- | ------------------------------------------------- | | UserName | string | Yes | Admin username | | Password | string | Yes | Admin password | | Vendor | string | Yes | Merchant/Vendor key | | CustomerID | string | Yes | Merchant-supplied unique customer ID | | CustomerName | string | Yes | Full customer name | | FirstName | string | No | Customer first name | | LastName | string | No | Customer last name | | Title | string | No | Title | | Department | string | No | Department | | Street1 | string | No | Address line 1 | | Street2 | string | No | Address line 2 | | Street3 | string | No | Address line 3 | | City | string | No | City | | StateID | string | No | 2-character state code | | Province | string | No | Province (for non-US) | | Zip | string | No | Postal code | | CountryID | string | No | 3-character country code | | Email | string | No | Email address | | DayPhone | string | No | Daytime phone | | Fax | string | No | Fax number | | Mobile | string | No | Mobile phone | | ContractID | string | Yes | Merchant-supplied contract ID | | ContractName | string | No | Billing contract name | | BillAmt | string | Yes | Billing amount per cycle | | TaxAmt | string | No | Tax amount | | TotalAmt | string | Yes | Must equal BillAmt + TaxAmt | | StartDate | string | Yes | Contract start date | | EndDate | string | No | Optional end date; omit for indefinite schedule | | BillingPeriod | string | Yes | DAY, WEEK, MONTH, or YEAR | | BillingInterval | string | Yes | Frequency for billing period | | MaxFailures | string | No | Max retries before suspension | | FailureInterval | string | No | Days between failure retries | | EmailCustomer | string | No | TRUE/FALSE – notify customer on success | | EmailMerchant | string | No | TRUE/FALSE – notify merchant on success | | EmailCustomerFailure | string | No | TRUE/FALSE – notify customer on failure | | EmailMerchantFailure | string | No | TRUE/FALSE – notify merchant on failure | | CheckType | string | Yes | PERSONAL or BUSINESS | | AccountType | string | Yes | CHECKING or SAVINGS | | CheckNum | string | No | Check number | | MICR | string | No | MICR line (optional when account info is present) | | AccountNum | string | Yes | Bank account number | | TransitNum | string | Yes | Bank routing number | | SS | string | No | SSN of the check holder | | DOB | string | No | Date of birth | | BranchCity | string | No | Bank branch city | | DL | string | No | Driver’s license number | | StateCode | string | No | State code on the license | | NameOnCheck | string | No | Name printed on the check | | ExtData | string | No | Optional XML string for additional metadata | *** ### Notes * Combines creation of a customer, billing contract, and ACH/check payment method into a single request. * StartDate is required and must be a valid future date. * Omitting EndDate results in an indefinite billing contract. * CheckType must be either `PERSONAL` or `BUSINESS`; AccountType must be `CHECKING` or `SAVINGS`. * TotalAmt must match the sum of BillAmt and TaxAmt, or the request will be rejected. * MICR input is optional if CheckNum, AccountNum, and TransitNum are provided. * Notifications can be configured for both customer and merchant on success and failure. * Response includes RecurringResult with elements such as `CustomerKey`, `ContractKey`, `CheckInfoKey`, `code`, `error`, `AuthCode`, and `PNRef`. ## ManageCheckInfo **Endpoint URL:**\ `https://secure.ftipgw.com/admin/ws/recurring.asmx?op=ManageCheckInfo` **Method:**\ Supports **SOAP POST**, **HTTP POST**, and **HTTP GET** (form-encoded) **Description:**\ Adds, updates, or deletes stored ACH/check account information for an existing customer. This endpoint is used to manage the customer’s check payment method, particularly in the context of recurring billing. *** ### Request Parameters | Parameter | Type | Required | Description | | ------------ | ------ | ----------- | ------------------------------------------------ | | UserName | string | Yes | Admin username | | Password | string | Yes | Admin password | | TransType | string | Yes | ADD, UPDATE, or DELETE | | Vendor | string | Yes | Merchant numeric key | | CustomerKey | string | Yes | Unique key for the customer | | CheckInfoKey | string | Conditional | Required for UPDATE or DELETE to identify record | | CheckType | string | Yes | PERSONAL or BUSINESS | | AccountType | string | Yes | CHECKING or SAVINGS | | CheckNum | string | No | Check number | | MICR | string | No | Scanned MICR line data | | AccountNum | string | Yes | Bank account number | | TransitNum | string | Yes | Bank routing number | | SS | string | No | SSN of the check holder | | DOB | string | No | Date of birth of the check holder | | BranchCity | string | No | Bank branch city | | DL | string | No | Driver's license number | | StateCode | string | No | State code on the license | | NameOnCheck | string | No | Printed name on the check | | Email | string | No | Customer email address | | DayPhone | string | No | Daytime phone number | | Street1 | string | No | Address line 1 | | Street2 | string | No | Address line 2 | | Street3 | string | No | Address line 3 | | City | string | No | Customer city | | StateID | string | No | 2-character state code | | Province | string | No | Province (for non-US addresses) | | PostalCode | string | No | Postal or ZIP code | | CountryID | string | No | 3-character country code (e.g., USA, CAN) | | ExtData | string | No | Optional metadata via XML | *** ### Notes * **TransType controls the action**:\ Use `ADD` to create a new check method, `UPDATE` to modify existing check info, and `DELETE` to remove it. `CheckInfoKey` is required for both `UPDATE` and `DELETE`. * **Dual protocol support**:\ This endpoint accepts SOAP requests and standard HTTP GET or POST (form-encoded), offering integration flexibility. * **MICR vs. Account Fields**:\ You may provide either MICR string or discrete fields like `CheckNum`, `AccountNum`, and `TransitNum`, depending on how your system captures check data. * **Supplementary identity fields**:\ Fields like `SS`, `DOB`, `DL`, and `StateCode` support extended identity verification and risk assessment but are optional. * **Response behavior**:\ A successful response returns a `RecurringResult` object including `CustomerKey`, `CheckInfoKey`, `Result`, `AuthCode`, `PNRef`, and `Message`. If relevant, it may also include billing contract information or status of the last transaction attempt. #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/recurring.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://www.tpisoft.com/Admin/ws/ManageCheckInfo" string string string string string string string string string string string string string string string string
string
string string string string string string string string string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string string string string string string OK or Unknown_Error or Access_Denied or Invalid_Login or Invalid_User_Status or Invalid_User or User_Not_Found or Username_Already_In_Use or Username_Has_Invalid_Characters or Not_Enough_Privilege or Invalid_PartnerID or Invalid_VendorID or Invalid_Argument or Invalid_Record or Transaction_Type_Not_Supported_By_Host or Internal_Error or Invalid_ProcessorID or Processor_Not_Found or InValidPassword string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/recurring.asmx/ManageCheckInfo HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length Username=string&Password=string&TransType=string&Vendor=string&CustomerKey=string&CheckInfoKey=string&CheckType=string&AccountType=string&CheckNum=string&MICR=string&AccountNum=string&TransitNum=string&RawMICR=string&SS=string&DOB=string&BranchCity=string&DL=string&StateCode=string&NameOnCheck=string&Email=string&DayPhone=string&Street1=string&Street2=string&Street3=string&City=string&StateID=string&Province=string&PostalCode=string&CountryID=string&ExtData=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string string string string string string OK or Unknown_Error or Access_Denied or Invalid_Login or Invalid_User_Status or Invalid_User or User_Not_Found or Username_Already_In_Use or Username_Has_Invalid_Characters or Not_Enough_Privilege or Invalid_PartnerID or Invalid_VendorID or Invalid_Argument or Invalid_Record or Transaction_Type_Not_Supported_By_Host or Internal_Error or Invalid_ProcessorID or Processor_Not_Found or InValidPassword string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` ## ManageCreditCardInfo **Endpoint URL:**\ `https://secure.ftipgw.com/admin/ws/recurring.asmx?op=ManageCreditCardInfo` **Method:**\ Supports **SOAP POST** and **HTTP POST** (form-encoded) **Description:**\ Adds, updates, or deletes stored credit card information for an existing customer. Commonly used in recurring billing workflows. *** ### Request Parameters | Parameter | Type | Required | Description | | ------------ | ------ | ---------------- | ------------------------------------------ | | UserName | string | Yes | Admin username | | Password | string | Yes | Admin password | | TransType | string | Yes | ADD, UPDATE, or DELETE | | Vendor | string | Yes | Merchant numeric key | | CustomerKey | string | Yes | Unique customer key | | CardInfoKey | string | Conditional | Required for UPDATE or DELETE | | CcAccountNum | string | Required for ADD | Credit card number | | CcExpDate | string | Required for ADD | Expiration date (MMYY) | | CcNameOnCard | string | No | Name as printed on the card | | CcStreet | string | No | Billing street address | | CcZip | string | No | Billing ZIP/postal code | | ExtData | string | No | Optional XML-formatted string for metadata | *** ### Notes * **Action driven by TransType:**\ Use `ADD` to store a new card, `UPDATE` to change existing card data, and `DELETE` to remove a card. `CardInfoKey` is required for update and delete operations. * **Flexible update behavior:**\ When updating a card, `CcAccountNum` and `CcExpDate` are optional. This allows updating address or metadata without resubmitting the card number. * **Protocol support:**\ Both SOAP and form-encoded HTTP POST are accepted, depending on the integration environment. * **Returns a standard RecurringResult:**\ Responses include keys such as `CustomerKey`, `CardInfoKey`, `Result`, `AuthCode`, `PNRef`, `code`, `error`, and `Message`, offering status and processing outcomes. #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/recurring.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://www.tpisoft.com/Admin/ws/ManageCreditCardInfo" string string string string string string string string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string string string string string string OK or Unknown_Error or Access_Denied or Invalid_Login or Invalid_User_Status or Invalid_User or User_Not_Found or Username_Already_In_Use or Username_Has_Invalid_Characters or Not_Enough_Privilege or Invalid_PartnerID or Invalid_VendorID or Invalid_Argument or Invalid_Record or Transaction_Type_Not_Supported_By_Host or Internal_Error or Invalid_ProcessorID or Processor_Not_Found or InValidPassword string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/recurring.asmx/ManageCreditCardInfo HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length Username=string&Password=string&TransType=string&Vendor=string&CustomerKey=string&CardInfoKey=string&CcAccountNum=string&CcExpDate=string&CcNameOnCard=string&CcStreet=string&CcZip=string&ExtData=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string string string string string string OK or Unknown_Error or Access_Denied or Invalid_Login or Invalid_User_Status or Invalid_User or User_Not_Found or Username_Already_In_Use or Username_Has_Invalid_Characters or Not_Enough_Privilege or Invalid_PartnerID or Invalid_VendorID or Invalid_Argument or Invalid_Record or Transaction_Type_Not_Supported_By_Host or Internal_Error or Invalid_ProcessorID or Processor_Not_Found or InValidPassword string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` ## ManageContract **Endpoint URL:**\ `https://secure.ftipgw.com/admin/ws/recurring.asmx?op=ManageContract` **Method:**\ Supports **SOAP POST** and **HTTP POST** (form-encoded) **Description:**\ Adds, updates, suspends, resumes, or deletes an existing billing contract associated with a customer. This endpoint allows direct control over the recurring billing schedule and status of an individual contract. *** ### Request Parameters | Parameter | Type | Required | Description | | -------------------- | ------ | ----------------------- | -------------------------------------------------------- | | UserName | string | Yes | Admin username | | Password | string | Yes | Admin password | | TransType | string | Yes | ADD, UPDATE, SUSPEND, RESUME, DELETE | | Vendor | string | Yes | Merchant numeric key | | CustomerKey | string | Yes | Unique key for the customer | | ContractKey | string | Conditional | Required for all types except ADD | | ContractID | string | Required for ADD | Merchant-supplied unique contract ID | | ContractName | string | No | Optional contract name | | BillAmt | string | Required for ADD/UPDATE | Amount to be charged per cycle | | TaxAmt | string | No | Tax amount to be included | | TotalAmt | string | Required for ADD/UPDATE | Must equal BillAmt + TaxAmt | | StartDate | string | Required for ADD | Start date for recurring billing | | EndDate | string | No | Optional end date; omit for indefinite billing | | BillingPeriod | string | Required for ADD | DAY, WEEK, MONTH, or YEAR | | BillingInterval | string | Required for ADD | Frequency multiplier for billing period | | MaxFailures | string | No | Number of allowed consecutive failures before suspension | | FailureInterval | string | No | Number of days between retry attempts | | EmailCustomer | string | No | TRUE/FALSE – Notify customer on successful creation | | EmailMerchant | string | No | TRUE/FALSE – Notify merchant on successful creation | | EmailCustomerFailure | string | No | TRUE/FALSE – Notify customer on failure | | EmailMerchantFailure | string | No | TRUE/FALSE – Notify merchant on failure | | ExtData | string | No | Optional XML-formatted string for metadata | *** ### Notes * **TransType defines the contract operation:**\ Use `ADD` to create a new billing contract, `UPDATE` to modify an existing one, and `SUSPEND`, `RESUME`, or `DELETE` to manage its active state. `ContractKey` is required for all actions except `ADD`. * **Billing logic:**\ `TotalAmt` must always equal the sum of `BillAmt` and `TaxAmt`. Incorrect totals will result in validation errors. * **StartDate and BillingInterval required on ADD:**\ These define the recurrence structure and are mandatory when creating a new contract. * **Notifications optional:**\ Email fields let you control which parties receive automated messages about success or failure events related to the contract. * **ExtData flexibility:**\ Can be used to pass additional metadata or custom fields into the platform, depending on merchant configuration. * **Typical usage:** * `ADD`: when creating a recurring billing plan * `UPDATE`: to change amount or schedule * `SUSPEND`: temporarily stop billing * `RESUME`: restart billing after suspension * `DELETE`: remove the contract entirely #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/recurring.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://www.tpisoft.com/Admin/ws/ManageContract" string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string string string string string string OK or Unknown_Error or Access_Denied or Invalid_Login or Invalid_User_Status or Invalid_User or User_Not_Found or Username_Already_In_Use or Username_Has_Invalid_Characters or Not_Enough_Privilege or Invalid_PartnerID or Invalid_VendorID or Invalid_Argument or Invalid_Record or Transaction_Type_Not_Supported_By_Host or Internal_Error or Invalid_ProcessorID or Processor_Not_Found or InValidPassword string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/recurring.asmx/ManageContract HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length Username=string&Password=string&TransType=string&Vendor=string&CustomerKey=string&ContractKey=string&PaymentInfoKey=string&PaymentType=string&CustomerID=string&CustomerName=string&FirstName=string&LastName=string&Title=string&Department=string&Street1=string&Street2=string&Street3=string&City=string&StateID=string&Province=string&Zip=string&CountryID=string&Email=string&DayPhone=string&NightPhone=string&Fax=string&Mobile=string&ContractID=string&ContractName=string&BillAmt=string&TaxAmt=string&TotalAmt=string&StartDate=string&EndDate=string&NextBillDt=string&BillingPeriod=string&BillingInterval=string&MaxFailures=string&FailureInterval=string&EmailCustomer=string&EmailMerchant=string&EmailCustomerFailure=string&EmailMerchantFailure=string&Status=string&ExtData=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string string string string string string OK or Unknown_Error or Access_Denied or Invalid_Login or Invalid_User_Status or Invalid_User or User_Not_Found or Username_Already_In_Use or Username_Has_Invalid_Characters or Not_Enough_Privilege or Invalid_PartnerID or Invalid_VendorID or Invalid_Argument or Invalid_Record or Transaction_Type_Not_Supported_By_Host or Internal_Error or Invalid_ProcessorID or Processor_Not_Found or InValidPassword string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` ## ManageCustomer **Endpoint URL:**\ `https://secure.ftipgw.com/admin/ws/recurring.asmx?op=ManageCustomer` **Method:**\ Supports **SOAP POST** and **HTTP POST** (form-encoded) **Description:**\ Adds, updates, or deletes a customer profile within the recurring billing system. This profile is used to associate payment methods and recurring billing contracts. *** ### Request Parameters | Parameter | Type | Required | Description | | ------------ | ------ | ---------------- | -------------------------------------------- | | UserName | string | Yes | Admin username | | Password | string | Yes | Admin password | | TransType | string | Yes | ADD, UPDATE, or DELETE | | Vendor | string | Yes | Merchant numeric key | | CustomerKey | string | Conditional | Required for UPDATE or DELETE | | CustomerID | string | Required for ADD | Unique merchant-supplied customer identifier | | CustomerName | string | Yes | Full name of the customer | | FirstName | string | No | First name | | LastName | string | No | Last name | | Title | string | No | Title (e.g., Mr., Dr.) | | Department | string | No | Department or division | | Street1 | string | No | Address line 1 | | Street2 | string | No | Address line 2 | | Street3 | string | No | Address line 3 | | City | string | No | City | | StateID | string | No | 2-character state code | | Province | string | No | Province (for non-US addresses) | | PostalCode | string | No | ZIP or postal code | | CountryID | string | No | 3-character country code (e.g., USA, CAN) | | Email | string | No | Email address | | DayPhone | string | No | Daytime phone number | | Fax | string | No | Fax number | | Mobile | string | No | Mobile phone number | | ExtData | string | No | Optional XML string for custom metadata | *** ### Notes * **TransType controls the operation:**\ Use `ADD` to create a new customer, `UPDATE` to modify an existing one, and `DELETE` to remove the customer profile. `CustomerKey` is required for both `UPDATE` and `DELETE`. * **CustomerID vs. CustomerKey:**\ `CustomerID` is the merchant-defined external identifier, while `CustomerKey` is the system-generated internal key returned by the platform after creation. * **Minimal required fields for creation:**\ `CustomerID`, `CustomerName`, `UserName`, `Password`, and `Vendor` must be supplied at minimum to create a valid customer record. * **Flexible structure for address data:**\ Street and location fields are optional but recommended to enable risk scoring, reporting, or downstream integrations. * **Use with other endpoints:**\ A customer must exist before you can attach recurring contracts or payment methods (such as via `AddRecurringCreditCard`, `AddRecurringCheck`, or `ManageContract`). * **ExtData usage:**\ The `ExtData` field supports merchant-defined XML key-value pairs and can be used to store custom tags, external system IDs, or control flags. #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/recurring.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://www.tpisoft.com/Admin/ws/ManageCustomer" string string string string string string string string string string string string string string string string string string string string string string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string string string string string string OK or Unknown_Error or Access_Denied or Invalid_Login or Invalid_User_Status or Invalid_User or User_Not_Found or Username_Already_In_Use or Username_Has_Invalid_Characters or Not_Enough_Privilege or Invalid_PartnerID or Invalid_VendorID or Invalid_Argument or Invalid_Record or Transaction_Type_Not_Supported_By_Host or Internal_Error or Invalid_ProcessorID or Processor_Not_Found or InValidPassword string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/recurring.asmx/ManageCustomer HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length Username=string&Password=string&TransType=string&Vendor=string&CustomerKey=string&CustomerID=string&CustomerName=string&FirstName=string&LastName=string&Title=string&Department=string&Street1=string&Street2=string&Street3=string&City=string&StateID=string&Province=string&Zip=string&CountryID=string&Email=string&DayPhone=string&NightPhone=string&Fax=string&Mobile=string&Status=string&ExtData=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string string string string string string OK or Unknown_Error or Access_Denied or Invalid_Login or Invalid_User_Status or Invalid_User or User_Not_Found or Username_Already_In_Use or Username_Has_Invalid_Characters or Not_Enough_Privilege or Invalid_PartnerID or Invalid_VendorID or Invalid_Argument or Invalid_Record or Transaction_Type_Not_Supported_By_Host or Internal_Error or Invalid_ProcessorID or Processor_Not_Found or InValidPassword string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` ## ManageContractAddDaysToNextBillDt **Endpoint URL:**\ `https://secure.ftipgw.com/admin/ws/recurring.asmx?op=ManageContractAddDaysToNextBillDt` **Method:**\ Supports **SOAP POST** and **HTTP POST** (form-encoded) **Description:**\ Adds a specified number of days to the next scheduled billing date of an existing recurring contract. This is typically used to delay the next payment without modifying the billing interval or period. *** ### Request Parameters | Parameter | Type | Required | Description | | ----------- | ------ | -------- | ------------------------------------------------ | | UserName | string | Yes | Admin username | | Password | string | Yes | Admin password | | Vendor | string | Yes | Merchant numeric key | | CustomerKey | string | Yes | Unique identifier for the customer | | ContractKey | string | Yes | Unique identifier for the contract to be updated | | AddDays | string | Yes | Number of days to add to the next billing date | | ExtData | string | No | Optional XML-formatted metadata | *** ### Notes * **Purpose:**\ This endpoint is used to delay the upcoming scheduled billing date of a recurring contract, without changing the recurring frequency or start/end dates. * **AddDays logic:**\ The number provided in `AddDays` will be **added to the contract’s current next billing date**. For example, if the next billing date is July 5 and `AddDays` is set to `10`, the new next billing date will be July 15. * **Non-destructive to billing cycle:**\ This does **not permanently alter** the contract’s recurrence settings. After the next billing event, the contract resumes its regular billing interval. * **Common use cases:** * To offer a grace period or deferral for a specific customer. * To realign a billing date with a customer’s preference or payroll cycle. * To compensate for prior billing failures or service issues. * **No date input required:**\ You only supply the number of days — the platform handles the date calculation internally based on the current contract schedule. * **ExtData support:**\ Optional field for tagging or logging additional context related to the update, such as administrative reason codes. #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/recurring.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://www.tpisoft.com/Admin/ws/ManageContractAddDaysToNextBillDt" string string string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string string string string string string OK or Unknown_Error or Access_Denied or Invalid_Login or Invalid_User_Status or Invalid_User or User_Not_Found or Username_Already_In_Use or Username_Has_Invalid_Characters or Not_Enough_Privilege or Invalid_PartnerID or Invalid_VendorID or Invalid_Argument or Invalid_Record or Transaction_Type_Not_Supported_By_Host or Internal_Error or Invalid_ProcessorID or Processor_Not_Found or InValidPassword string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/recurring.asmx/ManageContractAddDaysToNextBillDt HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length Username=string&Password=string&Vendor=string&CustomerKey=string&ContractKey=string&NumOfDays=string&ExtData=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string string string string string string OK or Unknown_Error or Access_Denied or Invalid_Login or Invalid_User_Status or Invalid_User or User_Not_Found or Username_Already_In_Use or Username_Has_Invalid_Characters or Not_Enough_Privilege or Invalid_PartnerID or Invalid_VendorID or Invalid_Argument or Invalid_Record or Transaction_Type_Not_Supported_By_Host or Internal_Error or Invalid_ProcessorID or Processor_Not_Found or InValidPassword string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` # Transaction Lookup & Reporting ##
## GetCardTrx **Endpoint URL:**\ `https://secure.ftipgw.com/admin/ws/trxdetail.asmx?op=GetCardTrx` **Method:**\ Supports **SOAP POST** and **HTTP POST** (form-encoded) **Description:**\ Retrieves detailed information about credit card transactions for a given date range or based on specific search criteria. This is commonly used for transaction reconciliation, reporting, or customer support queries. Request Parameters | Parameter | Type | Required | Description | | ------------ | ------ | ----------- | -------------------------------------------------------------- | | UserName | string | Yes | Admin username | | Password | string | Yes | Admin password | | Vendor | string | Yes | Merchant numeric key | | BeginDt | string | Conditional | Start date (MM/DD/YYYY) — required unless filtering by PNRef | | EndDt | string | Conditional | End date (MM/DD/YYYY) — required unless filtering by PNRef | | PNRef | string | Conditional | Platform reference number; overrides date filtering if present | | ApprovalCode | string | No | Filter by approval code | | Result | string | No | Filter by result code | | NameOnCard | string | No | Filter by cardholder name | | Amount | string | No | Filter by transaction amount | | ExtData | string | No | Optional XML-formatted metadata | *** ### Notes * **Flexible search options:**\ You can filter by: * A date range (`BeginDt` and `EndDt`) * A specific transaction reference (`PNRef`) * Or additional fields like `ApprovalCode`, `NameOnCard`, `Result`, or `Amount` * **When PNRef is provided:**\ If `PNRef` is included, it takes precedence over the date filters — only the referenced transaction will be returned. * **Response structure:**\ Returns one or more `RecurringResult` records containing key transaction data: `PNRef`, `Result`, `AuthCode`, `Message`, `TransType`, `CardType`, `Amount`, `CreateDate`, and more. * **Use cases:** * Transaction-level auditing * Customer dispute support * Internal reporting and reconciliation * Troubleshooting failed or duplicate charges * **ExtData support:**\ Allows passing of additional search qualifiers or logging flags, depending on your integration. #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/trxdetail.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://demo.tpisoft.com/Admin/ws/GetCardTrx" string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/trxdetail.asmx/GetCardTrx HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length UserName=string&Password=string&RPNum=string&PNRef=string&BeginDt=string&EndDt=string&PaymentType=string&ExcludePaymentType=string&TransType=string&ExcludeTransType=string&ApprovalCode=string&Result=string&ExcludeResult=string&NameOnCard=string&CardNum=string&CardType=string&ExcludeCardType=string&ExcludeVoid=string&User=string&invoiceId=string&SettleFlag=string&SettleMsg=string&SettleDt=string&TransformType=string&Xsl=string&ColDelim=string&RowDelim=string&IncludeHeader=string&ExtData=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string ``` ## GetCardTrxSummary **Endpoint URL:**\ `https://secure.ftipgw.com/admin/ws/trxdetail.asmx?op=GetCardTrxSummary` **Method:**\ Supports **SOAP POST** and **HTTP POST** (form-encoded) **Description:**\ Retrieves a summarized report of credit card transactions over a specified date range. This endpoint returns aggregate totals grouped by transaction type, result, and card type, making it ideal for high-level reporting and reconciliation. *** ### Request Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------------------- | | UserName | string | Yes | Admin username | | Password | string | Yes | Admin password | | Vendor | string | Yes | Merchant numeric key | | BeginDt | string | Yes | Start date for the summary period (MM/DD/YYYY) | | EndDt | string | Yes | End date for the summary period (MM/DD/YYYY) | | ExtData | string | No | Optional XML-formatted metadata | *** ### Notes * **Summarized vs. Detailed:**\ Unlike `GetCardTrx`, this endpoint does **not return individual transactions** — instead, it provides **aggregated totals** such as: * Total number of transactions * Total amount by result type (e.g., approved, declined) * Breakdown by card type (Visa, MasterCard, etc.) * Totals by transaction type (Sale, Credit, Auth, etc.) * **Use cases:** * Daily or monthly reconciliation * Dashboard summaries for business operations * Spot-checking performance or charge volume * Exporting totals for accounting systems * **Efficient and lightweight:**\ Because it returns aggregates only, the response payload is smaller and faster to process than full transaction logs. * **ExtData field:**\ This can be used to pass custom reporting tags or flags, though it is optional. #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/trxdetail.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://demo.tpisoft.com/Admin/ws/GetCardTrxSummary" string string string string string string string string string string string string string string string string string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/trxdetail.asmx/GetCardTrxSummary HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length UserName=string&Password=string&RPNum=string&BeginDt=string&EndDt=string&ApprovalCode=string&Register=string&NameOnCard=string&CardNum=string&CardType=string&ExcludeVoid=string&User=string&SettleFlag=string&SettleMsg=string&SettleDt=string&TransformType=string&Xsl=string&ColDelim=string&RowDelim=string&IncludeHeader=string&ExtData=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string ``` ## GetCheckTrx **Endpoint URL:**\ `https://secure.ftipgw.com/admin/ws/trxdetail.asmx?op=GetCheckTrx` **Method:**\ Supports **SOAP POST** and **HTTP POST** (form-encoded) **Description:**\ Retrieves detailed information about check (ACH) transactions processed through the system. The endpoint supports filtering by date range or specific reference number, and is useful for auditing, reporting, or investigating specific ACH transactions. *** ### Request Parameters | Parameter | Type | Required | Description | | ----------- | ------ | ----------- | ------------------------------------------------------------- | | UserName | string | Yes | Admin username | | Password | string | Yes | Admin password | | Vendor | string | Yes | Merchant numeric key | | BeginDt | string | Conditional | Start date (MM/DD/YYYY); required unless using PNRef | | EndDt | string | Conditional | End date (MM/DD/YYYY); required unless using PNRef | | PNRef | string | Conditional | Platform reference number; takes precedence over date filters | | NameOnCheck | string | No | Filter by customer name | | Amount | string | No | Filter by transaction amount | | Result | string | No | Filter by result code (e.g., 0 = Approved) | | ExtData | string | No | Optional XML-formatted metadata | *** ### Notes * **Flexible filtering options:**\ You can search by: * Date range (`BeginDt` and `EndDt`) * Specific transaction reference (`PNRef`) * Customer name, result code, or amount * **Behavior when PNRef is provided:**\ If `PNRef` is supplied, it overrides any date filtering and returns only the matching transaction. * **Response contents:**\ Returns one or more `RecurringResult` entries, each including fields like: * `PNRef` * `Result` * `CheckNum` * `Amount` * `Status` * `AuthCode` * `CreateDate` * `Message` * `CustomerKey`, etc. * **Use cases:** * Monitoring ACH transaction activity * Investigating failures or disputes * Internal reconciliation workflows * Searching for specific check payments * **ExtData field:**\ Can be used to pass optional metadata or request filters specific to certain merchant setups #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/trxdetail.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://demo.tpisoft.com/Admin/ws/GetCheckTrx" string string string string string string string string string string string string string string string string string string string string string string string string string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/trxdetail.asmx/GetCheckTrx HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length UserName=string&Password=string&RPNum=string&PNRef=string&BeginDt=string&EndDt=string&PaymentType=string&ExcludePaymentType=string&TransType=string&ExcludeTransType=string&ApprovalCode=string&Result=string&ExcludeResult=string&NameOnCheck=string&CheckNum=string&AcctNum=string&RouteNum=string&ExcludeVoid=string&User=string&invoiceId=string&SettleFlag=string&SettleMsg=string&SettleDt=string&TransformType=string&Xsl=string&ColDelim=string&RowDelim=string&IncludeHeader=string&ExtData=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string ``` ## GetOpenBatchSummary **Endpoint URL:**\ `https://secure.ftipgw.com/admin/ws/trxdetail.asmx?op=GetOpenBatchSummary` **Method:**\ Supports **SOAP POST** and **HTTP POST** (form-encoded) **Description:**\ Returns a summary of all authorized credit card transactions that are currently in the open batch (i.e., have not yet been settled). This is typically used to review totals before the batch is closed and submitted for settlement. *** ### Request Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------- | | UserName | string | Yes | Admin username | | Password | string | Yes | Admin password | | Vendor | string | Yes | Merchant numeric key | | ExtData | string | No | Optional XML-formatted metadata | *** ### Notes * **Open batch definition:**\ The open batch includes all **authorized** credit card transactions that have **not yet been settled**. Once a batch is settled (usually once per day), its totals are no longer included here. * **Response contents:**\ The response includes summarized totals grouped by: * Transaction type (e.g., Sale, Credit) * Card type (e.g., Visa, MasterCard) * Result code (e.g., Approved, Declined) * **Use cases:** * Verifying batch totals before settlement * Displaying same-day transaction volume on dashboards * Reconciliation against internal sales records * **Efficient reporting:**\ As a summary endpoint, it returns totals only — not individual transactions — making it performant even with high volume. * **ExtData usage:**\ Can be used to pass optional request metadata or reporting tags if needed. #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/trxdetail.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://demo.tpisoft.com/Admin/ws/GetOpenBatchSummary" string string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/trxdetail.asmx/GetOpenBatchSummary HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length username=string&password=string&rpNum=string&beginDt=string&endDt=string&extData=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length string ``` ## GetReturnedCheckReport **Endpoint URL:**\ `https://secure.ftipgw.com/admin/ws/trxdetail.asmx?op=GetReturnedCheckReport` **Method:**\ Supports **SOAP POST** and **HTTP POST** (form-encoded) **Description:**\ Retrieves a report of ACH (check) transactions that have been returned or rejected by the banking system. This includes failed debits due to insufficient funds, closed accounts, invalid information, or administrative returns. ### Request Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ---------------------------------- | | UserName | string | Yes | Admin username | | Password | string | Yes | Admin password | | Vendor | string | Yes | Merchant numeric key | | BeginDt | string | Yes | Start date for report (MM/DD/YYYY) | | EndDt | string | Yes | End date for report (MM/DD/YYYY) | | ExtData | string | No | Optional XML-formatted metadata | *** ### Notes * **Report focus:**\ This endpoint is used specifically to track **returned ACH transactions** — entries that were submitted successfully but were later returned by the bank. * **Common return reasons include:** * NSF (non-sufficient funds) * Invalid account or routing number * Account closed * Stop payment issued * Administrative errors * **Response contents:**\ Each returned entry typically includes: * `PNRef` * `CustomerKey` * `CheckNum` * `Amount` * `ReturnCode` * `ReturnDescription` * `ReturnDate` * `Status` or message from the bank * **Use cases:** * Identifying failed ACH payments * Triggering retry workflows or customer notifications * Managing customer account status or access * Feeding data into collections or risk systems * **Time window filter:**\ The `BeginDt` and `EndDt` must be used to specify the reporting period. Returned items will be limited to those that were processed within that range. * **ExtData field:**\ Optional; can be used to pass internal tracking flags or request-specific context. #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/trxdetail.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://demo.tpisoft.com/Admin/ws/GetReturnedCheckReport" string string string string string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length xml ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /admin/ws/trxdetail.asmx/GetReturnedCheckReport HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length UserName=string&Password=string&MerchantKey=string&BeginDt=string&EndDt=string&ExtData=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length xml ``` ## IsCommercialCard **Endpoint URL:**\ `https://secure.ftipgw.com/ArgoFire/validate.asmx?op=IsCommercialCard` **Method:**\ Supports **SOAP POST** and **HTTP POST** (form-encoded) **Description:**\ Determines whether a given credit card number corresponds to a commercial card (i.e., corporate, business, or purchasing card). This is typically used to inform surcharge decisions or compliance with card brand rules. *** ### Request Parameters | Parameter | Type | Required | Description | | ------------ | ------ | -------- | -------------------------------- | | UserName | string | Yes | Admin username | | Password | string | Yes | Admin password | | Vendor | string | Yes | Merchant numeric key | | CcAccountNum | string | Yes | Credit card number to be checked | | ExtData | string | No | Optional XML-formatted metadata | *** ### Notes * **Commercial card detection:**\ This endpoint checks the provided card number against issuer and BIN range databases to determine if it is classified as a commercial card. * **Use cases include:** * Identifying when surcharges are allowed (Visa/MC rules often allow fees on commercial cards) * Informing tax-exempt logic for B2B transactions * Risk assessment for business-related payment flows * **Response structure:**\ The response indicates whether the card is: * Commercial * Consumer * Unknown or unable to determine * **No authorization performed:**\ This check does **not** validate funds or perform a transaction—it is purely an identification utility. * **ExtData support:**\ Can be used for custom merchant tracking tags or context-specific attributes. #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/validate.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://localhost/SmartPayments/IsCommercialCard" string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length boolean ``` #### SOAP 1.2 The following is a sample SOAP 1.2 request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/validate.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/soap+xml; charset=utf-8 Content-Length: length string ``` ``` HTTP/1.1 200 OK Content-Type: application/soap+xml; charset=utf-8 Content-Length: length boolean ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/validate.asmx/IsCommercialCard HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length CardNumber=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length boolean ``` *** # Adjustments
## Forced Transactions **Endpoint URL:**\ `https://secure.ftipgw.com/ArgoFire/transaction.asmx?op=ProcessCreditCard` **Method:**\ Supports **SOAP POST** and **HTTP POST** (form-encoded) **Description:**\ Processes a "forced" credit card transaction by manually submitting a pre-authorized approval code. This is used when a merchant receives authorization through external means (e.g., phone approval) and must now force the transaction into the batch for settlement. *** ### Request Parameters | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------------------------------- | | UserName | string | Yes | Admin username | | Password | string | Yes | Admin password | | Vendor | string | Yes | Merchant numeric key | | TransType | string | Yes | Should be `FORCE` | | Amount | string | Yes | Transaction amount | | AuthCode | string | Yes | Authorization code manually provided by the card issuer | | CcAccountNum | string | Yes | Credit card number | | CcExpDate | string | Yes | Card expiration date (MMYY) | | CcNameOnCard | string | No | Cardholder name | | CcStreet | string | No | Billing street address | | CcZip | string | No | Billing ZIP/postal code | | Invoice | string | No | Optional invoice number | | CustomerID | string | No | Optional merchant-defined customer ID | | ExtData | string | No | Optional XML-formatted metadata | *** ### Notes * **Use `FORCE` as TransType:**\ This is required to indicate that the transaction is a post-authorization force-through. The gateway bypasses the real-time authorization request and uses the provided `AuthCode`. * **Common use cases:** * Recovery from a system or communications failure after voice authorization * Submitting a transaction when the original authorization was received outside the gateway * Consolidating manually approved sales into daily settlement * **Critical field: `AuthCode`**\ You must supply a valid authorization code that was previously issued by the card network or issuer. This tells the gateway to treat the transaction as already approved. * **Force transactions skip risk checks:**\ Since no authorization is performed, gateway-level fraud screening, CVV validation, or AVS are not applied. Merchants should exercise extra caution. * **Settlement timing:**\ Forced transactions are eligible for inclusion in the current day’s open batch and will settle normally unless flagged by downstream processing rules. # Verification & Validation
## ValidCard ### Endpoint Overview **Endpoint URL:**\ `https://secure.ftipgw.com/ArgoFire/validate.asmx?op=ValidCard` **Method:**\ Supports **SOAP POST** and **HTTP POST** (form-encoded) **Description:**\ Performs real-time validation of a credit card number, expiration date, and card security code (CVV). This endpoint is typically used during account setup, billing profile creation, or tokenization flows to verify that the card is structurally valid and passes preliminary risk checks. *** ### Request Parameters | Parameter | Type | Required | Description | | ------------ | ------ | -------- | --------------------------------- | | UserName | string | Yes | Admin username | | Password | string | Yes | Admin password | | Vendor | string | Yes | Merchant numeric key | | CcAccountNum | string | Yes | Credit card number | | CcExpDate | string | Yes | Expiration date (MMYY) | | CVNum | string | No | Card verification value (CVV/CVC) | | ExtData | string | No | Optional XML-formatted metadata | *** ### Notes * **Validation scope:**\ This endpoint performs **basic format checks** and **gateway-level rules validation**, but does **not submit an authorization to the issuer**. It is used for validation only, not for processing charges. * **Use cases:** * Confirming a card is correctly formatted and not obviously invalid * Pre-screening before saving card data or generating a token * Validating user input in hosted payment forms * Verifying CVV for consumer-facing applications * **Does not authorize funds:**\ No hold or charge is placed on the card — this is a **non-financial validation** operation. * **CVNum is optional but recommended:**\ Including the card security code improves the validation reliability and mimics real transaction conditions more closely. * **Not a substitute for full auth:**\ A successful `ValidCard` response **does not guarantee** that a future transaction will be approved. It should be used only as a basic card validation step. * **ExtData usage:**\ Can be used to pass optional context such as environment tags, session IDs, or integration-specific flags. #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/validate.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://localhost/SmartPayments/ValidCard" string string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length int ``` #### SOAP 1.2 The following is a sample SOAP 1.2 request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/validate.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/soap+xml; charset=utf-8 Content-Length: length string string ``` ``` HTTP/1.1 200 OK Content-Type: application/soap+xml; charset=utf-8 Content-Length: length int ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/validate.asmx/ValidCard HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length CardNumber=string&ExpDate=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length int ``` ## ValidCardLength **Endpoint URL:**\ `https://secure.ftipgw.com/ArgoFire/validate.asmx?op=ValidCardLength` **Method:**\ Supports **SOAP POST** and **HTTP POST** (form-encoded) **Description:**\ Checks whether the length and prefix (BIN/IIN) of a provided credit card number match known patterns for valid card types (Visa, MasterCard, etc.). This is a non-financial, pre-authorization check used for input validation and front-end form filtering. *** ### Request Parameters | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------- | | UserName | string | Yes | Admin username | | Password | string | Yes | Admin password | | Vendor | string | Yes | Merchant numeric key | | CcAccountNum | string | Yes | Credit card number to validate | | ExtData | string | No | Optional XML-formatted metadata | *** ### Notes * **Validation behavior:**\ This endpoint does **not perform authorization** or real-time card verification. It simply checks: * Whether the card number has the correct length for its prefix * Whether the card prefix (IIN/BIN) matches known issuers * Whether the card number passes the Luhn (mod-10) checksum * **Use cases:** * Real-time validation on hosted payment pages * Screening card data before attempting authorization * Sanitizing input in account setup flows * Filtering out mistyped or obviously invalid card numbers * **No expiration date or CVV required:**\ Only the card number is needed. This makes it ideal for client-side or early-stage backend validations. * **Response results:**\ The response typically includes: * Validation pass/fail status * Detected card type (if identifiable) * Optional message or error description * **Low risk, high utility:**\ Because it performs no network contact with issuers or processors, this check is fast, low-risk, and useful in real-time UX flows. * **ExtData support:**\ Can be used to pass tracking context or integration-specific flags, if needed. #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/validate.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://localhost/SmartPayments/ValidCardLength" string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length boolean ``` #### SOAP 1.2 The following is a sample SOAP 1.2 request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/validate.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/soap+xml; charset=utf-8 Content-Length: length string ``` ``` HTTP/1.1 200 OK Content-Type: application/soap+xml; charset=utf-8 Content-Length: length boolean ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/validate.asmx/ValidCardLength HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length CardNumber=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length boolean ``` ## ValidExpDate **Endpoint URL:**\ `https://secure.ftipgw.com/ArgoFire/validate.asmx?op=ValidExpDate` **Method:**\ Supports **SOAP POST** and **HTTP POST** (form-encoded) **Description:**\ Validates that a provided credit card expiration date is correctly formatted and not expired. This is a lightweight, non-financial check used for form validation and pre-processing flows. *** ### Request Parameters | Parameter | Type | Required | Description | | --------- | ------ | -------- | ------------------------------- | | UserName | string | Yes | Admin username | | Password | string | Yes | Admin password | | Vendor | string | Yes | Merchant numeric key | | CcExpDate | string | Yes | Expiration date in MMYY format | | ExtData | string | No | Optional XML-formatted metadata | *** ### Notes * **Validation scope:**\ This check ensures that: * The date is in valid MMYY format * The date is **not in the past** relative to the current system time * The month value is between `01` and `12` * **Use cases:** * Validating expiration dates during form entry * Filtering out invalid or expired cards before tokenization * Providing immediate UX feedback during card input * **No card number required:**\ This check only applies to the expiration date field — it does not require or validate any card number. * **No authorization performed:**\ This is a **non-transactional utility** endpoint — it does not contact any issuers or affect cardholder accounts. * **ExtData support:**\ Can be used to pass integration-specific context such as environment flags or UI tracking data. * **Best used with other validators:**\ For comprehensive validation, pair this with `ValidCard` or `ValidCardLength` to ensure complete format correctness. #### SOAP 1.1 The following is a sample SOAP 1.1 request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/validate.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: text/xml; charset=utf-8 Content-Length: length SOAPAction: "http://localhost/SmartPayments/ValidExpDate" string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length boolean ``` #### SOAP 1.2 The following is a sample SOAP 1.2 request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/validate.asmx HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/soap+xml; charset=utf-8 Content-Length: length string ``` ``` HTTP/1.1 200 OK Content-Type: application/soap+xml; charset=utf-8 Content-Length: length boolean ``` #### HTTP POST The following is a sample HTTP POST request and response. The placeholders shown need to be replaced with actual values. ``` POST /ArgoFire/validate.asmx/ValidExpDate HTTP/1.1 Host: secure.ftipgw.com Content-Type: application/x-www-form-urlencoded Content-Length: length ExpDate=string ``` ``` HTTP/1.1 200 OK Content-Type: text/xml; charset=utf-8 Content-Length: length boolean ``` ## ValidMod10 **Endpoint URL:**\ `https://secure.ftipgw.com/ArgoFire/validate.asmx?op=ValidMod10` **Method:**\ Supports **SOAP POST** and **HTTP POST** (form-encoded) **Description:**\ Performs a Luhn (Mod 10) checksum validation on a credit card number. This is a basic mathematical test used to verify that the card number is structurally valid and not obviously mistyped. *** ### Request Parameters | Parameter | Type | Required | Description | | ------------ | ------ | -------- | ------------------------------- | | UserName | string | Yes | Admin username | | Password | string | Yes | Admin password | | Vendor | string | Yes | Merchant numeric key | | CcAccountNum | string | Yes | Credit card number to validate | | ExtData | string | No | Optional XML-formatted metadata | *** ### Notes * **Luhn algorithm:**\ This check uses the **Mod 10 algorithm**, which is standard across the payments industry to validate card number integrity. If the number fails this check, it's likely mistyped or invalid. * **No issuer contact made:**\ This is a **local algorithmic check** and does not involve any authorization or communication with card networks. * **Use cases:** * Instant form validation in front-end applications * Filtering out fake or mistyped numbers before processing * Reducing unnecessary authorization attempts and failures * **Does not confirm legitimacy:**\ Passing the Luhn check only confirms that the number could be valid — it does **not** guarantee that the card is real, active, or authorized. * **No expiration or CVV required:**\ Only the card number is needed. This makes it especially useful early in the validation process. * **ExtData support:**\ Use to pass additional request metadata, logging preferences, or integration context, if applicable.