Forte’s REST API enables merchants and partners to perform a variety of powerful tasks such as creating and updating credit card, echeck, and scheduled transactions, securely managing customer and payment data, querying and tracking settlement information, and creating and submitting merchant applications for new Forte organizations and locations. Forte uses standard HTTP protocols within a PCI-compliant architecture that is simple to integrate.
To begin using Forte's REST web services, complete the following steps:
Sign up for a Test Account.
Create your API Credentials.
Create your Authentication Headers.
Craft a call.
Test your calls.
Step 1: Sign Up for a Test Account
If you are a merchant, navigate to the Forte Developer's Test Account sign-up page and enter your First Name, Last Name, Company Name, and Email address in the applicable fields. Forte uses this email address for verification purposes and as your Username for registering and signing into Dex, Forte's newest payment processing portal.
If you are a partner, contact Forte's Sales Team and request a partner sandbox account. Partner accounts in Dex have different permissions and different menu options.
After you verify your email address, Forte sends you a Dex invitation email where you can register for a sandbox account. Dex registration requires a mobile phone number that can receive SMS messages for account verification.
After registering and verifying your mobile number, Dex logs you in with your Organization ID. Your Organization ID represents a legal entity that can own multiple sub-organizations (for partners) or multiple locations (for merchants) as well as the customers, payment methods, and transactions that belong to those locations. Every request call made to the Forte REST API must contain the organization_id within the URI.
Every Dex sandbox account also comes with a Location ID. Your Location ID represents locations, which are processing endpoints that merchant organizations use to initiate transactions (in Forte legacy applications like Virtual Terminal, locations were known as MIDs). Locations own all the transaction data including sensitive payment method data and tokens. Tokens are random, alpha-numeric strings that represent stored, encrypted data. Tokenization is a common practice in the payment industry to protect sensitive data.
For questions or help with Dex registration or setup, contact Forte Technical Support at 888-235-4635 option 5.
Step 2: Create Your API Credentials
To begin integration with Forte's REST API, you first have to create your API authentication credentials. These include an API Access ID, which acts as your username, and an API Secure Key, which acts as a password. You will create and maintain these credentials in Dex.
Complete the following steps to generate your API Access ID and API Secure Key:
From your Google Chrome browser, log into your Dex Account.
Select Developer > API Credentials from the Dex Main Menu.
Click the CREATE button. The Create API Credentials screen displays.
Enter a name for this set of API credentials in the Name field.
Click the CREATE NEW API KEY button. The API Access ID and API Secure Key values display in their corresponding fields.
Click the COPY button next to the API Access ID and API Secure Key fields to record both of these newly generated values in a secure location to use in authenticating your REST API requests.
Once you save your API Secure Key, you will not be able to see the value again. If you forget your API Secure Key or it becomes compromised, you will have to regenerate the value in Dex.
Step 3: Create Your Authentication Headers
Requests to Forte's REST API must be authenticated using the Authorization header field and the custom header property, X-Forte-Auth-Organization-Id.
Forte's REST web services rely on Basic access authentication over HTTPS using the API Access ID and an API Secure Key as the username and password values. These unique values are combined with a colon and then encoded using the RFC2045-MIME variant of Base64. The encoded string is then added to the HTTP Authorization header. For example, if you created the following API credentials:
API Access ID = 315c7649520edde96c5cbad59a5b265f
API Secure Key = c233f2958bd855d09d98397e74950640
The value of the Authorization header field would look like the following:
Several different online tools can help you create your `Authorization` header, such as Postman. You can also add Base64 encoding to HMAC requests to automatically convert the API Access ID and API Secure Key values into the encoded ASCII string. To do so, use the following code:
The custom header property X-Forte-Auth-Organization-Id specifies at which organization Forte should authenticate the request. A partner can authenticate his or her Organization ID in the X-Forte-Auth-Organization-Id header property and then can access merchant sub-organizations by specifying the merchant Organization ID in the URI of the request.
The Accept Header
Forte’s REST service supports Content Negotiation through the Accept header sent in the request call.
The default value for Accept headers is application/json which returns JSON responses. However, you can also use application/xml which returns XML responses.
The Content-Type Header
The Content-Type header is only required for POST and PUT calls. Like the Accept header, the Content-Type header supports both application/json and application/xml. The default value for Content-Type headers is application/json.
Putting it All Together
In summary, you must include the following headers for every POST and PUT request call made to the Forte REST API. For GET and DELETE request calls, the Content-Type header is optional:
Content-Type - This header is only required for POST and PUT calls. This field defaults to application/json, but also supports application/xml.
Accept - Defaults to application/json, but also supports application/xml
X-Forte-Auth-Organization-Id - A custom header property that specifies at which organization Forte should authenticate the request (i.e., org_{AuthOrganizationID})
Authorization - The API Access ID and API Secure Key encoded using the RFC2045-MIME variant of Base64.
Step 4: Craft a Call
The following sections detail everything you'll need to create a request call. The API Reference section lists and explains all the resources you can use and provides samples of common requests and responses.
Base URI
When constructing a call, append the resource endpoint to the following base URIs in the specified environments:
All resources in Forte’s REST API require object prefixing to identify the specific resource and aid in troubleshooting in the event of errors. The resource ID is created by combining the object prefix with a unique ID number or token. The following table displays the prefixing standards used by Forte:
Object
Prefix
Example
organizations
org_ + ID
org_200000
locations
loc_ + ID
loc_100000
customers
cst_ + Token
cst_SoGUG6mcLUS1nVzYBIbk3g
addresses
add_ + Token
add_jUYRwbRjKUWgswNrFpSdKg
paymethods
mth + Token
mth_ymC20TMkHE-YmYxMt0UvMA
transactions
trn_ + GUID
trn_55c98c85-d3e8-4230-85e9-21d7d522eec0
fundings
fnd_ + ID
fnd_ACH-0226-173C5
settlements
stl_ + GUID
stl_51cf4633-1767-484f-8784-be76a4076791
schedules
sch_ + GUID
sch_2e5770ae-c120-414f-ae8c-d065753567e7
scheduleitems
sci_ + GUID
sci_4690fbfb-0b77-4477-a066-2c07ca2e5a3c
disputes
dsp_ + ID
dsp_2365435-e4ae-4ff4-a91e-abd8kjjfjffffc
applications
app_ + ID
app_258741
documents
doc_ + ID
doc_3131dddgwef0gpV2eYlo5
Supported Actions
Use the following HTTP verbs to perform an action on REST API resources:
Action
HTTP Method
Description
Create
POST
Creates the resource that corresponds to the data type defined in the endpoint. For example, making a POST call to the transactions URI creates a new transaction.
Find
GET
Returns summary information for all the resources that match the provided query parameters. For example, performing a GET call to the customers URI returns all the customers associated with that specific merchant location. To return comprehensive/detailed information on a specific resource, provide the resource’s ID to the defined URI. For example, to find a specific customer associated with a merchant location, perform a GET call to the customers endpoint and include the customer_token parameter in the URI
Update
PUT
Modifies the existing resource for the provided URI. All PUT calls require the resource’s ID.
Delete
DELETE
Deletes the existing resource for the provided URI. All DELETE calls require the resource’s ID.
Request Filters for General GET Requests
Forte REST web services support the following filtering parameters for GET requests without resource IDs (i.e., general resource searches). Use these search filters for all resources.
Some resources (e.g., transactions and settlements) may have additional filter parameters that you can use to narrow down your search results.
Parameter
Description
orderby
- Sets the order of the results during a search request - Uses the same fields accepted by the resource_filters - Can be followed by a space and one of the following values designating the order to use - asc - ascending (default if not specified) - desc - descending
page_size
- Sets the number of records returned on a page during a search request - Accepts values between 50 and 10000 - If no value is defined, this parameter uses the default value of 50
page_index
- Sets the index of the page of results returned during a search request - Index starts at 0 (zero) and has no upper limit - The given value must be a positive number - An index number set to a value higher than the max page value in a search request will return empty search results
When using search filters, the search_criteria object will display in the response and echo back all the resource parameters included in the search in the resource_specific object.
Understanding Responses
Forte includes the applicable parameters of the response object in all response calls returned to the client that made the request.
Optional request parameters whose values are null do not echo back in responses. The following table displays the response object and the parameters returned for each resource request.
Parameter
Description
Type
response_desc
A short description of the action's response. All resources use this parameter.
string
environment
The environment in which the user made the request. The value for this field can be either live or sandbox. All resources use this parameter.
string
authorization_code
The code indicating whether or not the transaction was authorized. This field is not used for voiding transactions.
string
response_type
The type of response this action generated: A - Approved D - Declined E - Error _____
The type of responses generated by authenticate action:
O-Overall match
M- FirstName/LastName match
B- Business name match
P- Conditional match
N- No match
U- No Info
E- Timeout or Invalid response/internal error or Bad request
Pre-authorization check result from Forte Verify with the following possible values: NOTE: The test account numbers below may be used on Sandbox (with any valid ABA number) to force the indicated response.
UNK - P92: Preauth Server Unavail — Test Account # 99992 _____
Pre-authorization check result from Authenticate with the following possible values:
NOTE: The test account numbers below may be used on Sandbox (with any valid ABA number) to force the indicated response.
POS-P60: Match - Test Account #99801
CON-P75: Conditional Match - Test Account #99809
NEG-P10: No Match - Test Account #99806
NEG-P94: Invalid Routing Number - Test Account #99824
NEG-P94: Invalid Account Number - Test Account #99828
NEG-P95: Bad Account - Test Account #99826
UNK-P50: No Info - Test Account #99820
UNK-P90: Preauth Vendor Unavail - Test Account #99821
UNK-P91: Preauth Vendor Error - Test Account #99822
ERROR-P94: Error - Test Account #99827
string
preauth_desc
Pre-authorization check description from Forte Verify with the following possible values: POS - Positive
NEG - Negative
UNK - No information available
___
Pre-authorization check description from Authenticate with the following possible values: P60: Match
P75: Conditional Match
P10: No Match
string
ownership_match
Provides ownership results based on the name fields being inquired upon, in a pipe delimited format. Possible values are Y, N, C or blank (Y-Match, N-Not Match, C-Conditional Match, Blank-No Info)
The name fields in the result are: FirstNameMatch I LastNameMatch I NameMatch I BusinessNameMatch
E.g., If First name match is Y, Last name match is N, no response in name match and Business name match is C, then the parameter will return the response as: ownership_match = Y I N I IC
string
preauth_neg_report
Negative database response information (unformatted) when pg_preauth_result=NEG.
string
avs_result
Forte only returns this field if the merchant passes any combination of billing address parameters from the physical_address object in the request. To test this service in Sandbox, see the testing parameters in the Verifying Credit Cards tutorial and Response Codes section. Supported values for this field include the following:
- X - Match: Street address and 9-digit zip code both match - Y = Match: Street address and 5-digit zip code both match - A = Partial Match: Street address matches, but both 5-digit and 9-digit zip code do not match - W = Partial Match: Street address does not match, but 9-digit zip code matches - Z = Partial Match: Street address does not match, but 5-digit zip code matches - N = No Match: Street address, 5-digit zip code, and 9-digit zip code all do not match - U = System unavailable: Address information unavailable. Forte returns this response if the street address is a non-US address, if the AVS service is unavailable, or if the AVS service for a particular US bank is not functioning properly - R = System unavailable: Forte will retry the AVS check because the issuer's system is unavailable or the request times out - E = Invalid: AVS data is invalid - S = Not supported: The US issuing bank does not support AVS checks
string
cvv_result
The card verification value response. Supported values for this field include the following:
- M = Match - N = No Match - E = Error (Unrecognized or Unknown Response) - I = Invalid or Null - P = Not Processed - S = Service Not Supported - U = Issuer Unable to Process - X = No Response - " "= A space will be sent as this response, only for Token transactions, where CVV must not be present in the request.
string
available_card_balance
The available balance on the credit card if a credit card is used for the transaction.
string
requested_amount
The transaction amount
string
Hypermedia
Forte’s REST API returns the following format for hypermedia responses. Result availability depends on the resource/action in the request.
The following sample of hypermedia responses are merely formatting examples provided for reference.
Forte's web services use standard HTTP status codes along with messages where appropriate. The table below displays the most common codes:
Code
Text
Description
200
Ok
This code indicates a successful HTTP request; the actual response depends on the request method. For example, responses for GET requests contain entities corresponding to the requested resource while responses for POST requests contain entities describing the result of the action.
201
Created
This code indicates that the server has fulfilled the request and has created a new resource.
400
Bad Request or Failed Transaction
This code indicates that the server cannot fulfill the request because of bad syntax (e.g., a create echeck request with a missing routing number) or the transaction failed (responses for failed transactions also contain the failed transaction information).
401
Unauthorized
This code occurs when the user sends a bad username, password, and X-Forte-Auth-Organization-Id combination with the request.
403
Forbidden
This code indicates that the server understands the request but refuses to authorize it. Unlike a 401 unauthorized response, authenticating will make no difference.
404
Not Found
This code occurs when the user attempts an ID GET request, but the ID he/she provides does not exist in the database.
500
Internal Error
This generic error code indicates that the server has encountered an unexpected condition and cannot provide a more specific or suitable error message.
For status codes in the 400s, ensure that you correctly formatted the JSON (or XML) in the original request, especially when the system returns a descriptive error message along with the status code such as the following example messages:
Example 1
{
message: "Authentication Organization ID in header is missing or invalid."
}
Example 2
{
message: "Authentication Organization ID in header is missing or invalid."
}
Understanding Webhooks
Webhooks provide near-real-time notifications about the events that occur during a transaction through POSTs to a customer-defined endpoint. Forte notifies merchants about events through subscriptions. Depending on these subscriptions, multiple events can occur during an operation. For example, a POST transaction request that creates tokens for a customer and a paymethod causes three events to be fired: transaction.sale, customer.create, and paymethod.create. These three events can be combined under a common event ID (e.g., evt_xxxxxx) for easier information management.
Depending on how you configure your event subscriptions, the same data may be generated twice in separate webhooks. For example, a POST to the customer object that includes the creation of a paymethod could (if subscribed) generate a customer webhook with both customer and paymethod data as well as a paymethod webhook.
Merchants can subscribe to the following webhook events:
Note: Merchant application webhooks provide the status of an application as the application status events trigger during the application process.
If a webhook post fails (i.e., does not result in an HTTP 200 response), Forte retries the webhook post up to twenty times adding one minute for each retry.
To help you gain a greater understanding of how Forte's REST API works, we've built a Postman collection of sample REST requests that you can use to test each resource. NOTE: While we've included sample body parameters in this collection of request calls, you'll still need to add the URLs and Authentication Headers described in Step 3 above.
A token is a unique string ID that references stored customer information, including payment, customer, and address data. Tokens provide customers convenient, secure access to their information, making the checkout process faster and easier. For merchants, tokens provide a convenient method of collecting scheduled recurring payments. For more information on tokens, see the Understanding Tokens tutorial on DevDocs.
Response Codes
For more information on response codes, see the Transaction Codes page on DevDocs.
Rate Limits
Forte throttles API requests to 10 per second. Once the request limit is met, Forte drops the connection and displays the following error: 403 - Forbidden: Access is denied. For general synchronization of your transaction data, query the settlements and fundings endpoints using strategic date and timestamp filters in the request. Do not query individual transactions; this will bog down your connection and limit your payment processing ability. We recommend using single transaction queries on a limited basis for user-initiated, real-time status updates.
1. Authentication using the API Access ID and API Secure Key that the developer creates in Dex. 2. Endpoints now using Organization IDs and Location ID.
Version 2 NOTE: Only version 3 is supported at this time. View version 2 here.
1. Authentication using an API Access ID and an API Secure Key provided by Forte Integration Team. 2. Endpoints using Account IDs and Location IDs. 3. Available for both Sandbox and Live.
1. Included only the following objects: Accounts, Locations, Customers, Addresses, Paymethods. 2. Authentication done using an API Login ID and a Secure Transaction Key provided by Forte Integration Team. 3.Only available in Sandbox.
Devices
CSG Forte offers multiple devices for a card present solution. The devices and supported processors are listed here.
Addresses
The addresses object represents the customer's billing and/or shipping addresses and includes the physical_address sub-object. NOTE: For token payments, Forte will use the default shipping and billing addresses. Set the customers default shipping and billing addresses prior to creating a token payment.
Addresses Object
Parameter
Description
Type
Req
address_token
A unique string used to represent an address. For example, add_tq0hemmmtf-zsxgq689rew. [max length = 26]
string
R
customer_token
A unique string used to represent a customer. For example, cst_SoGUG6mcLUS1nVzYBIbk3g. [max length = 26]
string
R
organization_id
The identification number of the associated organization. For example, org_5551236.
string
R
location_id
The identification number of the associated location. For example, loc_1234568.
string
R
first_name
The first name of the user associated with this billing or shipping address [max length = 25]. NOTE: Either the first_name, last_name, or company_name parameters are required when creating addresses.
string
O
last_name
The last name of the user associated with this billing or shipping address [max length = 25]. NOTE: Either the first_name, last_name, or company_name parameters are required when creating addresses.
string
O
company_name
The name of the company associated with this billing or shipping address [max length = 20]. NOTE: Either the first_name, last_name, or company_name parameters are required when creating addresses.
string
O
phone
The phone number associated with this billing or shipping address. This field supports both U.S. and Canadian phone numbers. [max length = 15]
string
O
email
The email address associated with this billing or shipping address [max length = 50]
string
O
label
A label that succinctly identifies the address. For example, "Work" or "Home." [max length = 50]
string
O
address_type
The type of address. Use one of the following values: default_billing - The default billing address
default_shipping - The default shipping address
none - The address is not a default address)
both - The address is both a default shipping and default billing address
string
O
shipping_address_type
Indicates whether the address is a residential or commercial address.
string
R
physical_address
The Physical Address Object.
object
O
physical_address.street_line1
The first line of the street address [max length = 35]
string
O
physical_address.street_line2
The second line of the street address [max length = 35]
string
O
physical_address.locality
Locality or city/town/village [max length = 25]
string
O
physical_address.region
Region or state/province. [max length = 10]
string
O
physical_address.country
The ISO 3166-1 alpha-2 country abbreviation. [max length = 2]
This URI creates a new address for the customer and returns a new address_token; however, you must include the location_id in the body of the request since this value is not included in the specified route. The Location ID identifies the location from where you are processing transactions.
This URI returns all addresses owned by a location. Remember, a location is a processing endpoints that merchant organizations use to initiate transactions. To narrow your search data, use the customer_token parameter to filter your results.
This URI returns all address(es) owned by an Organization. To narrow your search data using specific criteria, use the following parameters to filter your results:
location_id
customer_token
Note: Please note that sending a request at the partner (org) level may result in a large data set and may cause timeout errors depending on the request. We recommend sending your GET request at the Merchant (Organization) level.
The applications object enables Forte partners to create merchant applications and submit them automatically to Forte's Underwriting and decisioning queues. Partners can upload supporting documentation for applications using the documents object.
Applications Object
The applications object enables Forte partners to create merchant applications and submit them automatically to Forte's Underwriting and decisioning queues. Partners can upload supporting documentation for applications using the documents object.
Parameter
Description
Type
Req
fee_id
The ID of the rate plan, which details the fee values that Forte will charge the merchant. [max length = 6]
string
R
source_ip
The IP Address from which the merchant is applying. [max length = 80]
string
R
annual_volume
The anticipated annual volume of the business. [max length = 10]
double
R
average_transaction_amount
The average transaction amount of the business. NOTE: When testing, use this parameter to test success and fail responses. Passing a value greater than 10,000 in this field will trigger an automatic decline in the test environment. [max length = 5]
double
R
market_type
The method by which the business captures the majority of its transactions. Options for this parameter include the following values:
- internet - phone - mail - point_of_sale
string
R
t_and_c_version
The version of Forte's Terms and Conditions provided to the applying merchant. NOTE: This must match the version associated with the Rate Plan (fee_id).
string
R
t_and_c_time_stamp
The date and/or timestamp when the merchant agreed to Forte's Terms and Conditions. [max length = 20] NOTE: The value of this field can be up to one full day in the future. The following formats are supported:
A random unique code that partners generate on their client form and include in the API request call prior to sending the application (e.g., s3AH5fDIdXjI7y1disbZChw8Qrgl6Bz7uKZLjRrgNhYmu WApi2FhdhB5wW4MgqknPHx1WR7s4RX1vWs).
The value of the risk_session_id parameter can be up to 128 characters long and can only consist of the following characters:
- Upper and lowercase English letters (a–z or A–Z) - Digits (0–9) - Underscore or hyphen (_ or -)
The script that generates the risk_session_id value must be embedded on a page where the user will be for five or more seconds. For profiling to properly occur, the session must run on the applicant's browser for a minimum of five seconds. Additionally, the applicant's browser or front-end software must have javascript enabled. See the note below. [max length = 128bytes]
string
R
maximum_transaction_amount
The maximum allowable amount for a credit card or ACH transaction.
double
O
average_payable_amount
The average amount the merchant disburses in credit transactions (e.g., refunds, payroll, commissions, etc). NOTE: If either the average_payable_amount,maximum_payable_amount, or the monthly_payable_volume parameters are passed, all three parameters become required.
double
C
maximum_payable_amount
The maximum amount the merchant would disburse in a credit transaction (e.g., refunds, payroll, commissions, etc.). NOTE: If either the average_payable_amount,maximum_payable_amount, or the monthly_payable_volume parameters are passed, all three parameters become required.
double
C
monthly_payable_volume
An estimate of the amount the merchant disburses in credit transactions each month (e.g., refunds, payroll, commissions, etc). NOTE: If either the average_payable_amount,maximum_payable_amount, or the monthly_payable_volume parameters are passed, all three parameters become required.
double
C
received_date
The date and time when the application was received.
datetime
--
updated_date
The date and time when the application was last updated.
datetime
--
sales_rep
The name or ID of the sales representative associated with this application.
string
--
location_id
The merchant's location ID that Forte created after enrolling the applicant.
string
--
status
The status of the application. Supported values include the following:
approved - Forte has approved the application and sent the merchant's data to the enrollment queue. pending - Forte's Credit and Risk Team needs to review the application and may request additional documentation from the merchant. declined - The application failed one or more automated underwriting checks and Forte has declined to move forward with the merchant. The reason for the decline displays in the decline_reason field.
• enrolled - Merchant has completed enrollment and is ready to process transactions.
• rejected - Forte is unable to verify the identity data of an application or cannot authenticate the banking data or signatures. The reason for the rejected status displays in the rejected_reason dield.
• recalled - The applicant has stopped responding to requests for information from Forte or the Partner. The reason for the recalled status displays in the recalled_reason field.
decline_reason field.
enrrolled -
string
--
decline_reason
The reason for a declined status. Supported values include the following:
The name of the business as it will appear on your customer's statements. The default value for this parameter is the DBA (Doing Business As) Name. [max length = 50].
string
R
applicant_organization.organization_id
The merchant organization ID that Forte created after enrolling the applicant.
string
--
applicant_organization.street_address1
The physical address of the business. This parameter cannot contain P.O. boxes, including paid mailbox services provided by companies like the UPS Store. [max length = 50]
string
R
applicant_organization.locality
The city where the business is located. [max length = 50]
string
R
applicant_organization.region
The state or province where the business is located. [max length = 2]
string
R
applicant_organization.postal_code
The zip/postal code of the business. The following formats are supported [max length = 15]:
XXXXX XXXXX-XXXX
string
R
applicant_organization.customer_service_phone
The customer service phone number of the business. [max length = 12]
string
R
applicant_organization.website
The website of the business. The value of this parameter must be in www.yourcompanysite.com format. The www prefix is required. Slashes and underscore punctuation are allowed in the URL. [max length = 100]
The type of bank account. This bank account can only be a business checking or business savings account; it cannot be the applicant's personal checking or personal savings account. The following values are supported:
- checking - savings
string
O
applicant_organization.bank_routing_number
The transit routing number (TRN) of the merchant's bank. This field supports both U.S. and Canadian routing numbers. NOTE: A Canadian routing number displayed on a check needs to be reformatted differently for electronic payments. If a check displays a routing number as BBBBB-AAA (where AAA indicates the Financial Institution and BBBBB is the branch), then the routing number must be changed to 0AAABBBBB to process the payment electronically. For example, if a check from an account issued by the Bank of Montreal showed the routing number 00011-001, then that number would need to be reformatted to 000100011 for the payment to be electronically processed. Click here for a directory of Canadian financial institutions. This field is required when creating or updating a new record and can only contain digits. [max length = 9].
string
R
applicant_organization.bank_account_number
The account number (i.e., DDA) of the applicant's business bank account. The value of this parameter can only contain digits. [max length = 17]
string
R
owner
The primary owner object. All applications must include at least one primary owner. This owner must be the controller of the business.
object
R
owner.percentage
Indicates the percentage of the business owned by the primary owner (i.e., maximum ownership percentage = 100). NOTES:
- The sum of owner.percentage, owner_2.percentage, owner_3.percentage, and owner_4.percentage cannot be greater than 100. - This field is NOT required for the following legal structures:
- government - sole_proprietorship - publicly_held_corporation
double
R
owner.title
The primary owner’s official title at the company. Supported values include the following:
ceo cfo coo managing_member general_partner president vice_president treasurer other
string
R
owner.first_name
The first name of the account owner. [max length = 50]
string
R
owner.last_name
The last name of the account owner. [max length = 50]
string
R
owner.street_address1
The home address of the account owner. [max length = 50]
string
R
owner.locality
The city of the account owner's home address. [max length = 50]
string
R
owner.region
The state or province of the account owner's home address. [max length = 2]
string
R
owner.postal_code
The zip/postal code of the account owner's home address. [max length = 15]
string
R
owner.country
The country code of the account owner's home address NOTE: This field is NOT required for the following legal structures:
government sole_proprietorship publicly_held_corporation
[max length = 3]
string
R
owner.citizenship
The country code of the account owner's country of citizenship. NOTE: This field is NOT required for the following legal structures:
government sole_proprietorship publicly_held_corporation
[max length=3]
string
R
owner.email_address
The business email of the account owner. This email address cannot be a generic email address or a distribution list. The value of this parameter must be in a valid email format (e.g., john.doe@email.com). [max length = 100]
string
R
owner.mobile_phone
The cell phone number of the account owner. The value of this parameter can be up to 15 characters (with country code).
string
R
owner.last4_ssn
The last four digits of the account owner's Social Security Number (SSN). [max length = 4]
string
R
owner.date_of_birth
The birth date of the account owner in YYYY/MM/DD format. [max length = 10]
date
R
owner_2
The secondary owner object.NOTE: This object is only required for American merchants with additional owner(s) who own at least 25% of the business. Addtionally, do not pass this object for merchants set up in the following legal structures:
government sole_proprietorship publicly_held_corporation
object
C
owner_2.percentage
Indicates the percentage of the business owned by the secondary owner. This value must be 25 or greater.
double
C
owner_2.first_name
The first name of the account owner. [max length = 50]
string
C
owner_2.last_name
The last name of the account owner. [max length = 50]
string
C
owner_2.street_address1
The home address of the account owner. [max length = 50]
string
C
owner_2.locality
The city of the account owner's home address. [max length = 50]
string
C
owner_2.region
The state or province of the account owner's home address. [max length = 2]
string
C
owner_2.postal_code
The zip/postal code of the account owner's home address. [max length = 15]
string
C
owner_2.country
The country code of the account owner's home address. [max length=3]
string
C
owner_2.citizenship
The country code of the account owner's country of citizenship. [max length=3]
string
C
owner_2.email_address
The business email of the account owner. This email address cannot be a generic email address or a distribution list. The value of this parameter must be in a valid email format (e.g., john.doe@email.com). [max length = 100]
string
C
owner_2.mobile_phone
The cell phone number of the account owner. The value of this parameter can be up to 15 characters (with country code).
string
C
owner_2.last4_ssn
The last four digits of the account owner's Social Security Number (SSN). [max length = 4]
string
C
owner_2.date_of_birth
The birth date of the account owner in YYYY/MM/DD format. [max length = 10]
date
C
owner_3
The tertiary owner object. NOTE: This object is only required for American merchants with additional owner(s) who own at least 25% of the business. Addtionally, do not pass this object for merchants set up in the following legal structures:
government sole_proprietorship publicly_held_corporation
object
C
owner_3.percentage
Indicates the percentage of the business owned by the tertiary owner. This value must be 25 or greater.
double
C
owner_3.first_name
The first name of the account owner. [max length = 50]
string
C
owner_3.last_name
The last name of the account owner. [max length = 50]
string
C
owner_3.street_address1
The home address of the account owner. [max length = 50]
string
C
owner_3.locality
The city of the account owner's home address. [max length = 50]
string
C
owner_3.region
The state or province of the account owner's home address. [max length = 2]
string
C
owner_3.postal_code
The zip/postal code of the account owner's home address. [max length = 15]
string
C
owner_3.country
The country code of the account owner's home address. [max length=3]
string
C
owner_3.citizenship
The country code of the account owner's country of citizenship. [max length=3]
string
C
owner_3.email_address
The business email of the account owner. This email address cannot be a generic email address or a distribution list. The value of this parameter must be in a valid email format (e.g., john.doe@email.com). [max length = 100]
string
C
owner_3.mobile_phone
The cell phone number of the account owner. The value of this parameter can be up to 15 characters (with country code).
string
C
owner_3.last4_ssn
The last four digits of the account owner's Social Security Number (SSN). [max length = 4]
string
C
owner_3.date_of_birth
The birth date of the account owner in YYYY/MM/DD format. [max length = 10]
date
C
owner_4
The quaternary owner object. NOTE: This object is only required for American merchants with additional owner(s) who own at least 25% of the business. Addtionally, do not pass this object for merchants set up in the following legal structures:
government sole_proprietorship publicly_held_corporation
object
C
owner_4.percentage
Indicates the percentage of the business owned by the quaternary owner. This value must be 25 or greater.
double
C
owner_4.first_name
The first name of the account owner. [max length = 50]
string
C
owner_4.last_name
The last name of the account owner. [max length = 50]
string
C
owner_4.street_address1
The home address of the account owner. [max length = 50]
string
C
owner_4.locality
The city of the account owner's home address. [max length = 50]
string
C
owner_4.region
The state or province of the account owner's home address. [max length = 2]
string
C
owner_4.postal_code
The zip/postal code of the account owner's home address. [max length = 15]
string
C
owner_4.country
The country code of the account owner's home address. [max length=3]
string
C
owner_4.citizenship
The country code of the account owner's country of citizenship. [max length=3]
string
C
owner_4.email_address
The business email of the account owner. This email address cannot be a generic email address or a distribution list. The value of this parameter must be in a valid email format (e.g., john.doe@email.com). [max length = 100]
string
C
owner_4.mobile_phone
The cell phone number of the account owner. The value of this parameter can be up to 15 characters (with country code).
string
C
owner_4.last4_ssn
The last four digits of the account owner's Social Security Number (SSN). [max length = 4]
string
C
owner_4.date_of_birth
The birth date of the account owner in YYYY/MM/DD format. [max length = 10]
date
C
gateway
The gateway object. Use for gateway-only merchant applications.
object
C
gateway.provider
The processor the gateway-only merchant will use. Supported options include the following:
vantiv global vital firstdata Elavon Chase
string
C
gateway.bank_id_number
The banking ID associated with Vantiv, Global, or Vital merchants.
string
C
gateway.merchant_id
The merchant ID associated with Vantiv, Global, or FirstData merchants.
string
C
gateway.terminal_id
The terminal ID associated with Global, Vital, or FirstData merchants.
string
C
gateway.agent
The Agent number associated with Vital merchants.
string
C
gateway.chain
The Chain number associated with Vantiv or Vital merchants.
string
C
gateway.store
The Store number associated with Vantiv or Vital merchants.
string
C
gateway.terminal
The Terminal number associated with Vital merchants.
string
C
NOTE: The following PHP code sample uses the uniqid() function to generate the risk_session_id value:
To add this parameter to the applications object, complete the following steps:
STEP 1: Generate a unique risk_session_id code that fulfills the formatting requirements described above by using the PHP code sample provided or an alternative method.
STEP 2: Add the generated value to the following script (i.e., in place of UNIQUE_SESSION_ID). This script can be executed only once by the applicant’s browser.
STEP 3: When generating the applications POST request, assign the unique code value created in step 1 to the risk_session_id parameter.
This URI creates the merchant application, routes the information to Forte’s Underwriting and decisioning queues, and returns one of the following status codes:
approved
pending
declined
enrolled
rejected
recalled
NOTE: The organization_id referenced in this URI must be the home_organization_id of the Partner.
This URI returns all applications submitted by the partner organization, including their current status. Supported statuses include the following:
`approved` – Forte has approved the application and sent the merchant’s data to the enrollment queue.
`pending` – Forte’s Credit and Risk Team needs to review the application and may request additional documentation from the merchant.
`declined` – The application failed one or more automated underwriting checks and Forte has declined to move forward with the merchant. The reason for the decline displays in the `decline_reason` field.
`enrolled` – Merchant has completed enrollment and is ready to process transactions.
`rejected` – Forte is unable to verify the identity data of an application or cannot authenticate the banking data or signatures. The reason for the rejected status displays in the reject_reason field.
`recalled` – The applicant has stopped responding to requests for information from Forte or the Partner. The reason for the recalled status displays in the recalled_reason field.
To narrow your search data using specific criteria, use the following filter parameters:
start_updated_date / end_updated_date
start_received_date / end_received_date
status
NOTES: The organization_id referenced in this URI must be the home_organization_id of the partner.
Please note that sending a request at the partner (org) level may result in a large data set and may cause timeout errors depending on the request. We recommend sending your GET request at the Merchant (Organization) level.
This URI returns a specific application submitted by the partner using the application_id. NOTE: The organization_id referenced in this URI must be the home_organization_id of the partner. Applications can have the following statuses:
`approved` – Forte has approved the application and sent the merchant’s data to the enrollment queue.
`pending` – Forte’s Credit and Risk Team needs to review the application and may request additional documentation from the merchant.
`declined` – The application failed one or more automated underwriting checks and Forte has declined to move forward with the merchant. The reason for the decline displays in the `decline_reason` field.
`enrolled` – Merchant has completed enrollment and is ready to process transactions.
`rejected` – Forte is unable to verify the identity data of an application or cannot authenticate the banking data or signatures. The reason for the rejected status displays in the reject_reason field.
`recalled` – The applicant has stopped responding to requests for information from Forte or the Partner. The reason for the recalled status displays in the recalled_reason field.
The customers object represents a customer's information and enables the merchant to create, maintain, and retrieve customer data that can be tokenized (stored as a Wallet) for a more efficient checkout process. The customer object includes the address and paymethod sub-objects. For more information about tokens, click here.
NOTE: A customer token (Wallet) can be empty or can hold address / payment tokens.
Customers Object
Parameter
Description
Type
Req
organization_id
The identification number of the associated organization. For example, org_5551236.
string
R
location_id
The identification number of the associated location. For example, loc_1234568.
string
R
customer_token
A unique string used to represent a customer. For example, cst_SoGUG6mcLUS1nVzYBIbk3g. [max length = 26]
string
R
customer_id
A merchant-defined string used to identify the customer. [max length = 15]
string
O
default_paymethod_token
The customer's default paymethod token. The system returns this token when creating a customer with a paymethod. [max length = 26]
string
O
default_billing_address_token
A unique string used to represent the customer's default billing address. The system returns this token when creating a customer with a billing address. [max length = 26]
string
O
default_shipping_address_token
A unique string used to represent a customer's default shipping address. This system returns this token when creating a customer with a shipping address. [max length = 26]
string
O
status
Use one of the following values:
active suspended
string
O
first_name
The first name of the customer. NOTE: To ensure the customer name properly displays for token transactions, include the addresses.first_name and addresses.last_name parameters in addition to the first_name and last_name parameters. [max length = 50]
string
R
last_name
The last name of the customer. NOTE: To ensure the customer name properly displays for token transactions, include the addresses.first_name and addresses.last_name parameters in addition to the first_name and last_name parameters. [max length = 50]
string
R
company_name
The company name of the customer. [max length = 50]
string
O
display_name
Displays the first_name + last_name parameters if the company_name parameter is null. [max length = 100]
string
O
created_date
The date and time when the customer record was created. This parameter is return only.
datetime
--
updated_date
The date and time when the customer record was updated. This parameter is return only.
datetime
--
deleted_date
The date and time when the customer record was deleted. This parameter is return only.
datetime
--
paymethod
The Paymethod Object
object
O
paymethod.organization_id
d The identification number of the associated organization. For example, org_5551236.
string
R
paymethod.location_id
The identification number of the associated location. For example, loc_1234568.
string
R
paymethod.customer_token
A unique string used to represent a customer. For example, cst_SoGUG6mcLUS1nVzYBIbk3g. NOTE: When a merchant passes a customer token with a transaction, Forte ignores any other customer data in favor of the default data stored with the token. [max length = 26]
string
O
paymethod.paymethod_token
A unique string used to represent a payment method. For example,mth_1578436587. [max length = 26]
string
O
paymethod.label
A friendly, customer-defined name for the payment method. For example, "Moms Credit Card," "Work Credit Card," "Visa - 1234," etc. [max length = 50]
string
R
paymethod.card
The Card Object
object
O
paymethod.card.card_type
The type of credit card [max length = 6]. Options for this field include the following:
visa mast amex disc dine jcb
string
R
paymethod.card.name_on_card
The name printed on the on the credit card [max length = 50]. This field is required when creating a new record or creating a permanent token from a one-time token.
string
R
paymethod.card.account_number
The card number. This field is required when creating a new record and can only contain digits. [max length = 16]
string
O
paymethod.card.expire_month
The expiration month. This field is required when creating a new record and must be a valid future date [max length = 2].
string
O
paymethod.card.expire_year
The expiration year. This field is required when creating a new record and must be a valid future date. [max length = 4]
string
O
paymethod.card.card_verification_value
The card verification number. Forte does not store this field with the paymethod token, but echoes it back. [max length = 4]
string
O
paymethod.card.procurement_card
Indicates whether or not this is a procurement card transaction. Accepted values are either true or false. For procurement card transactions, merchants must pass the customer_accounting_code field in the card object and the sales_tax_amount field in the transaction object.
Bool
O
paymethod.card.customer_accounting_code
Lists the procurement card accounting code. Forte does not save this information if the merchant is creating a paymethod. [max length = 17]
string
O
paymethod.card.one_time_token
A single use token generated by Forte.js (e.g., ott_g7vnjqikszabzynu6eowbq). [max length = 26]
string
O
paymethod.echeck
The eCheck Object
object
O
paymethod.echeck.account_holder
The name of the account owner. This field is required when creating or updating a new record. [max length = 50]
string
R
paymethod.echeck.account_number
The DDA or eCheck account number. This field is required when creating or updating a new record and can only contain digits. [max length = 17]
string
O
paymethod.echeck.routing_number
The transit routing number. This field supports both U.S. and Canadian routing numbers. NOTE: A Canadian routing number displayed on a check needs to be reformatted differently for electronic payments. If a check displays a routing number as BBBBB-AAA (where AAA indicates the Financial Institution and BBBBB is the branch), then the routing number must be changed to 0AAABBBBB to process the payment electronically. For example, if a check from an account issued by the Bank of Montreal showed the routing number 00011-001, then that number would need to be reformatted to 000100011 for the payment to be electronically processed. Click here for a directory of Canadian financial institutions. This field is required when creating or updating a new record and can only contain digits. [max length = 9]
string
R
paymethod.echeck.account_type
Use one of the following values for this parameter:
checking savings
string
O
paymethod.echeck.sec_code
Use one of the following values for this standard-entry class code: ARC, CCD, CIE, CTX, POP, POS, PPD, RCK, TEL, WEB.
string
O
paymethod.notes
A short description of the paymethod. [max length = 50]
string
O
paymethod.vendor
The vendor Object
object
O
paymethod.vendor.vendor_type
The supported vendor types include the following.
PayPal
string
R
paymethod.vendor.vendor_billing_agreement_token
The ID of PayPal billing agreement token
string
R
paymethod.vendor.vendor_billing_agreement_id
The ID of PayPal billing agreement
string
_
addresses
An array of Address Objects.
object
O
addresses.address_token
A unique string used to represent an address. For example, add_tq0hemmmtf-zsxgq689rew. [max length = 26]
string
R
addresses.customer_token
A unique string used to represent a customer. For example, cst_SoGUG6mcLUS1nVzYBIbk3g. [max length = 26]
string
R
addresses.organization_id
The identification number of the associated organization. For example, org_5551236.
string
R
addresses.location_id
The identification number of the associated location. For example, loc_1234568.
string
R
addresses.first_name
The first name of the user associated with this billing or shipping address [max length = 25]. NOTE: The first_name and last_name parameters are required for billing addresses when creating transactions without tokens. For token transactions, add these parameters to dispay the customer name with the transaction.
string
R
addresses.last_name
The last name of the user associated with this billing or shipping address [max length = 25]. NOTE: The first_name and last_name parameters are required for billing addresses when creating transactions without tokens. For token transactions, add these parameters to dispay the customer name with the transaction.
string
R
addresses.company_name
The name of the company associated with this billing or shipping address [max length = 20]. NOTE: The company_name parameter is required for billing addresses when creating transactions without tokens.
string
R
addresses.phone
The phone number associated with this billing or shipping address. This field supports both U.S. and Canadian phone numbers. [max length = 15]
string
O
addresses.email
The email address associated with this billing or shipping address [max length = 50]
string
O
addresses.label
A label that succinctly identifies the address. For example, "Work" or "Home." [max length = 50]
string
O
addresses.address_type
The type of address. Use one of the following values:
- default_billing - The default billing address - default_shipping - The default shipping address - none - The address is not a default address - both - The address is both a default shipping address and a default billing address
string
O
addresses.shipping_address_type
Indicates whether the address is a residential or commercial address.
string
R
addresses.physical_address
The Physical Address Object.
object
R
addresses.physical_address.street_line1
The first line of the street address [max length = 35]
string
O
addresses.physical_address.street_line2
The second line of the street address [max length = 35]
string
O
addresses.physical_address.locality
Locality or city/town/village [max length = 25]
string
O
addresses.physical_address.region
Region or state/province. This field supports both U.S. and Canadian regions. [max length = 2]
string
O
addresses.physical_address.postal_code
Postal Code [max length = 15]. This field supports both U.S. and Canadian postal codes.
This endpoint creates a customer record with just the First and Last Name and the Customer ID while returning a new customer_token.
NOTE: Token-based transactions will use the default addresses. Token payments require you to set the customer’s default shipping and billing addresses prior to passing the transaction data.
Use this endpoint to create a customer at the merchant organization level (rather than the location level). Partners should authenticate at the partner level while specifying the merchant organization in the body of the request.
NOTE: Token-based transactions will use the default addresses. Token payments require you to set the customer’s default shipping and billing addresses prior to passing the transaction data.
This endpoint creates a customer record with just the First and Last Name while returning a new customer_token.
NOTE: Token-based transactions will use the default addresses. Token payments require you to set the customer’s default shipping and billing addresses prior to passing the transaction data.
This endpoint creates a customer record with Billing and Shipping Addresses while returning a new customer_token.
NOTE: Token-based transactions will use the default addresses. Token payments require you to set the customer’s default shipping and billing addresses prior to passing the transaction data.
This endpoint creates a customer record with a Payment Method while returning a new customer_token.
NOTE: Token-based transactions will use the default addresses. Token payments require you to set the customer’s default shipping and billing addresses prior to passing the transaction data.
This endpoint creates a customer record with Billing/Shipping Addresses and a Payment Method while returning a new customer_token.
NOTE: Token-based transactions will use the default addresses. Token payments require you to set the customer’s default shipping and billing addresses prior to passing the transaction data.
This URI returns all the customers for an Organization. To narrow your search data using specific criteria, use the following parameters to filter your results:
location_id
status
first_name
last_name
company_name
customer_id
Note: Please note that sending a request at the partner (org) level may result in a large data set and may cause timeout errors depending on the request. We recommend sending your GET request at the Merchant (Organization) level.
This URI returns all the customers for a location. To narrow your search data using specific criteria, use the following parameters to filter your results:
This URI returns all the customers for an Organization by search criteria provided within the route. To narrow your search data using specific criteria, use the following parameters to filter your results:
location_id
status
first_name
last_name
company_name
customer_id
Note: Please note that sending a request at the partner (org) level may result in a large data set and may cause timeout errors depending on the request. We recommend sending your GET request at the Merchant (Organization) level.
This URI can perform the following tasks while returning the customer_token. NOTE: This customer_token is an organization-level token, meaning it can be used across locations of this organization.
Change a customer’s status
Change the default billing and/or shipping address
Change the customer’s default paymethod
NOTE: This endpoint cannot update a customer’s addresses or paymethods. To update that data, you must use the address and paymethod resources.
This URI can associate an existing, clientless paymethod_token with a customer record. For more information on clientless paymethods, see the paymethods object.
The disputes object represents transactions that were disputed by the credit card account holder. Dispute records are automatically submitted to Forte by the processor. Merchants can view these records and upload supporting documentation using the documents object.
Disputes Object
Parameter
Description
Type
Req
dispute_id
A unique string defined by Forte that represents a dispute. For example, dsp_31wef05ABpV2eZvKYlo54.
string
R
transaction_id
A 36-character string that uniquely identifies the original transaction associated with this dispute.
string
R
dispute_number
A unique, processor-defined number that identifies the dispute record.
string
R
organization_id
The identification number of the associated organization. For example, org_5551236.
string
R
location_id
The identification number of the associated location. For example, loc_1234568.
string
R
status
The current status of the dispute. Supported values include the following:
documents_needed - The merchant needs to provide documents to Forte. exception - The dispute was created with a reason code that is unfamiliar to Dex or the dispute's reason code triggers a credit funding adjustment as the first funding adjustment in the dispute record. expired - A dispute has stayed in DRAFT status for 31 days. User actions are disabled, but funding adjustments may still occur. lost - The dispute was decided in favor of the cardholder. pending - Forte has submitted the required documents to the processor. reviewing - The required documents have been received by Forte and are under review. won - The dispute was decided in favor of the merchant. recalled - A condition has caused the dispute to disable all automated funding. Forte must now manually work the dispute. accepted - The merchant has accepted the dispute and funds will be returned to the cardholder. fulfilled - Indicates a dispute that was created as an Inquiry record type and remains an Inquiry for 31 consecutive days even after the merchant uploads supporting documentation.
string
R
dispute_amount
The amount the cardholder is disputing. This amount must match the value of the original_amount parameter.
decimal
R
original_amount
The original amount of the transaction.
decimal
R
action_code
A code that indicates what actions to take in resolving the dispute. Supported values include the following:
CACP - Accept of Collection CBRV - Create Outgoing Representment CDNL - Denial of Collection CHGM - Charge Merchant COLL - Collection Letter Ordered CRMR - Credit Merchant IACF - Incoming Compliance IACP - Issuer Accept IARB - Incoming Arbitration IDCL - Issuer Declines IFAV - Cased Decided in Issuer Favor (merchant liable) IPAB - Incoming Pre-Arbitration IREP - Create Outgoing Representment MACP - Merchant Accept MDCL - Merchant Declines MDNL - Merchant Denial MFAV - Case Decided in Merchant's Favor (merchant not liable) MREV - Merchant Reversal of Chargeback OARB - Outgoing Arbitration OPAR - Outgoing Pre-Arbitration OPARB - Outgoing Pre-Arbitration OREV - Operation Reversal of Chargeback PADM - Pre-Arbitration/Pre-Compliance Debit Merchant PARB - Incoming Visa Pre-Arbitration Request PARE - Pre-Arbitration/Pre-Compliance Response PCCR - Arbitration PCHG - Pending Charge Off PCMP - Pre-Compliance Prenote PICR - Arbitration PIDB - Arbitration PMCR - Arbitration/Pre-Compliance Credit Merchant PMDB - Arbitration/Pre-Compliance Credit Merchant RREQ - Incoming Retrieval Request RRSP - Retrieval Request Response VDNL - Vantiv Denies (The documentation the merchant provided is not enough to use for rebuttal)
string
R
adjustment_type
A code indicating the type of adjustment to be made for this dispute. Supported values include the following:
The date and time that Forte received the dispute record from the processor.
datetime
R
due_date
The date and time the resolution to the dispute is due. This date varies depending on whether or not the merchant is classified as a government or non-government merchant.
datetime
R
last_update_date
The date and time when the dispute was last updated.
datetime
R
last_funding_date
The date and time when the dispute was last funded.
datetime
R
comment_from_issuer
Comments provided to the processor by the card issuer.
string
R
reason
The Reason Object.
object
R
reason.code
A code that represents the reason for the dispute. This code varies between issuers; however, MasterCard reason codes are prefaced with an M (e.g.,M9999), VISA reason codes are prefaced with a V (e.g., V9999), and Discover reason codes are prefaced with a D (e.g., D9999)
string
O
reason.title
The name of the dispute reason.
string
R
reason.description
A brief description of the dispute reason.
string
R
reason.info_required
A comment about the dispute by a member of Forte's Risk Department.
string
R
card
The Card Object
object
R
card.card_type
The type of credit card [max length = 6]. Options for this field include the following:
visa mast disc
string
R
card.name_on_card
The name printed on the credit card [max length = 50].
string
R
card.last_4_account_number
The last four digits of the redacted account number. [max length = 4]
This URI returns all the dispute records associated with an organization. To narrow your search data using specific criteria, use the following filter parameters. NOTE: Dispute calls cannot be tested in Sandbox.
`dispute_number`
`location_id`
`start_due_date` / `end_due_date`
`start_last_update_date` / `end_last_update_date`
`start_received_date` / `end_received_date`
`status`
`amount`
`card_type`
`action_code`
`name_on_card`
`last_4_account_number`
NOTES: The following filter parameters support the listed values:
card_type
disc
mast
visa
action_code
CACP
CBRV
CDNL
CHGM
COLL
DRFT
MREV
MDNL
IREP
MACP
PADM
PARE
PCCR
PCHG
PCMP
PICR
PIDB
PMCR
PMDB
RTLV
status
accepted
deleted
documents_needed
expired
lost
pending
recalled
reviewing
won
Please note that sending a request at the partner (org) level may result in a large data set and may cause timeout errors depending on the request. We recommend sending your GET request at the Merchant (Organization) level.
This URI returns all the dispute records associated with an organization. To narrow your search data using specific criteria, use the following filter parameters. NOTE: Dispute calls cannot be tested in Sandbox.
last_4_account_number
card_type
name_on_card
start_last_update_date / end_last_update_date
start_due_date / end_due_date
start_received_date / end_received_date
action_code
dispute_amount
status
dispute_number
transaction_id
location_id
organization_id
NOTES: The following filter parameters support the listed values:
card_type
amex
disc
jcb
mast
visa
action_code
CACP
CBRV
CDNL
CHGM
COLL
DRFT
MREV
MDNL
IREP
MACP
PADM
PARE
PCCR
PCHG
PCMP
PICR
PIDB
PMCR
PMDB
RTLV
status
accepted
deleted
documents_needed
expired
lost
pending
recalled
reviewing
won
Note: Please note that sending a request at the partner (org) level may result in a large data set and may cause timeout errors depending on the request. We recommend sending your GET request at the Merchant (Organization) level.
{
"dispute_id": "dsp_f606a032-91b0-4b07-902e-3e23a0e30c91",
"organization_id": "org_300005",
"location_id": "loc_115161",
"transaction_id": "trn_05e5ed61-b7c6-48a8-a383-184db63336a3",
"dispute_number": "8050207938",
"status": "documents_needed",
"dispute_amount": 23.98,
"original_amount": 23.98,
"adjustment_type": "DRFT",
"received_date": "2018-12-10T14:30:49.837",
"due_date": "2018-12-30T14:30:49.837",
"draft_action_code_date": "2018-12-10T00:00:00",
"last_update_date": "2018-12-10T14:30:49.84",
"comment_from_issuer": "",
"reason": {
"code": "D4535",
"title": "Expired Card",
"description": "The credit card was expired but it was charged anyway.",
"info_required": "Copy of receipt showing the card was not expired at the time of sale"
},
"card": {
"name_on_card": "George McFly",
"last_4_account_number": "1117",
"masked_account_number": "****1117",
"card_type": "disc"
},
"response": {
"environment": "live",
"response_desc": "Get Successful."
},
"links": {
"documents": "https://api.forte.net/v3/disputes/dsp_f606a032-91b0-4b07-902e-3e23a0e30c91/documents",
"transactions": "https://api.forte.net/v3/disputes/dsp_f606a032-91b0-4b07-902e-3e23a0e30c91/transactions",
"self": "https://api.forte.net/v3/disputes/dsp_f606a032-91b0-4b07-902e-3e23a0e30c91"
}
}
Documents
The documents object enables merchants and partners to upload supporting documentation for applications and disputes. Documents must be under 8MB and conform to specific formats. See the documents object for more information.
Documents Object
Parameter
Description
Type
Req
document_id
A unique string used to represent a document. For example, doc_31wef05ABpV2eZvKYlo54.
string
R
resource
The object resource the document pertains to. Supported values include the following:
application dispute bankaccount
string
R
resource_id
The identification number of the associated resource. For example, app_109630, dsp_31wef05ABpV2eZvKYlo54, or bac_XBvmvvUAG0ur5Tl4-5eBnA.
string
R
type
The type of document. Supported values include the following:
jpeg png tiff txt bmp pdf wav mp3
NOTE: Files in wav or mp3 format can only be uploaded for echeck Proof of Authorization (POA) disputes.
string
O
description
A brief description of the document (e.g., receipt or voided check). [max length = 512 characters]
string
O
size
The size of the document in bytes. The maximum file size for a document is 8MB (i.e., 8,000,000 bytes).
int
O
received_date
The date that Forte received the document.
date
O
file
The name of the document file you're uploading to Forte.
To successfully upload a document that supports a merchant application or dispute, your request must include a multipart/form-data content type. A multipart/form-data message contains a series of sections separated by boundary strings. Boundary strings can be any combination of letters or numbers up to 70 characters as long as the string does not appear in the request body of the message. Each instance of a boundary string must be preceded by at least two dashes (--boundarystring), while the last boundary string must be preceded and followed by two dashes (--boundarystring--).
The section of a multipart/form-data message that contains the upload file must include a Content-Disposition header that indicates whether the file should be displayed as inline or, in our case, as an attachment. You must also add a field name (i.e., file) and a default filename to the attachment by using the name="file"; filename="filename.jpg" directives within the Content-Disposition header.
In curl, POST requests to upload documents use the -F or -form command as in the following example:
The following URI uploads the document to the Forte database. Documents must be under 8MB, must not be password protected or encrypted, and must be in one of the following formats:
jpeg
png
tiff
txt
bmp
pdf
wav
mp3
AUTHORIZATION Basic Auth
Username {{apiaccessid}}
Password{{apisecurekey}}
Body raw
--5ff9ef78-b4d7-4fb2-b179-1ff0b553b581
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data
{"resource":"application","resource_id":"app_132416","description":"This is a test file."}
--5ff9ef78-b4d7-4fb2-b179-1ff0b553b581
Content-Type: text/plain
Content-Disposition: form-data; filename=exampleTextFile.txt
Example content of text file
--5ff9ef78-b4d7-4fb2-b179-1ff0b553b581--
Example Request
curl --location -g '{{baseURI}}/v3/organizations/org_{{organizationID}}/documents/' \
--header 'Authorization: {{authorization}}' \
--header 'Accept: application/json' \
--header 'Content-Length: 419' \
--header 'Content-Type: multipart/form-data; boundary="5ff9ef78-b4d7-4fb2-b179-1ff0b553b581"' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--data '--5ff9ef78-b4d7-4fb2-b179-1ff0b553b581
Content-Type: application/json; charset=utf-8
Content-Disposition: form-data
{"resource":"application","resource_id":"app_133181","description":"This is a test file."}
--5ff9ef78-b4d7-4fb2-b179-1ff0b553b581
Content-Type: text/plain
Content-Disposition: form-data; filename=exampleTextFile.txt
Example content of text file
--5ff9ef78-b4d7-4fb2-b179-1ff0b553b581--
'
This URI returns all documents associated with an organization. To narrow your search data using specific criteria, use the following filter parameters.
start_received_date / end_received_date
type
resource
NOTE: All date filter parameters are time aware.
Please note that sending a request at the partner (org) level may result in a large data set and may cause timeout errors depending on the request. We recommend sending your GET request at the Merchant (Organization) level.
The fundings object captures the status of funding entries associated with an organization. GET requests to this endpoint can be filtered by the funding ID, effective date, net amount, routing number, location ID, last four digits of the account number, status and funding source. Merchants can also use this endpoint to find the transactions and settlement records related to this funding entry.
Fundings Object
Parameter
Description
Type
Req
organization_id
The identification number of the associated organization. For example, org_5551236.
string
R
location_id
The identification number of the associated location. For example, loc_1234568.
string
R
funding_id
A unique string used to represent a funding entry. For example, fnd_ACH-0226-173C5. [max length = 20]
string
R
status
The status of the funding entry. The following values are supported for this parameter:
completed - Forte processed the funding entry and added funds to the user's account. pending - Forte is processing the funding entry and it will post soon. failed - Forte attempted to process the funding entry, but it was rejected. not_applicable - The Net Amount is equal to zero and no funds will go into the user's account.
[max length = 14}
string
O
effective_date
The date and time when the net_amount is credited to the merchant's bank account. [max length = 19]
datetime
O
origination_date
The date the funds of the transaction go to the originating depository financial institution. [max length = 19]
datetime
O
net_amount
The amount that is being funded. [max length = 10]
decimal
O
echeck
The eCheck Object
object
R
echeck.routing_number
The transit routing number of the funding account. [max length = 9]
string
O
echeck.last_4_account_number
The last four digits of the redacted funding account number. [max length = 4]
string
O
funding_source
The Funding Source Object
object
R
funding_source.code
The type of funding used in this funding entry. The following values are supported:
GWCC ACH ACHD ACHC UNFD UNFC CC CCC CCD CHBD CHBC SFA SFC RSRV RELS
[max length = 4]
string
O
funding_source.description
A short description of the type of funding used in this funding entry. The following values are supported:
GWCC - Gateway Funding ACH - Net ACH Funding ACHD - ACH Debits ACHC - ACH Credits UNFD - ACH Debit Returns UNFC - ACH Credit Returns CC - Payfac Credit Card CCC - Payfac CC Credits CCD - Payfac CC Debits CHBD - Payfac Chargeback Debits CHBC - Payfac Charegback Credits SFA - Splitfund ACH SFC - Splitfund CC RSRV - Reserve Debit RELS - Reserve Release
[max length = 25]
string
O
entry_description
Details pertaining to the funding entry that can be overwritten by the merchant after the funds are in the merchant's bank account. [max length = 50]
string
O
funding_response_code
Contains the reason code for why a funding attempt failed. [max length = 50]
string
--
reserve
The part of the funding amount kept on funding hold based on CSG Forte's Risk department's Policy and Procedures. These funds are used to cover returns, past due invoices, fraud transactions, levies from state or federal governments, and other financial obligations of a merchant. Funds may also be held in reserve until 1099 TIN mismatches are resolved.
decimal
O
reserve_release
The amount of the reserve released by the CSG Forte Risk department after reviewing the merchant per Risk Department's policy and procedures.
decimal
O
discount_fee
The amount (fee) paid by a merchant to the merchant acquirer/bank or other contracted party for services related to the processing of the merchant's card transactions.
This URI returns all the funding entries for an organization. To narrow your search data using specific criteria, use the following parameters to filter your results.
start_effective_date / end_effective_date
start_net_amount / end_net_amount
routing_number
bank_information
location_id
last_4_account_number
code
status
NOTES:
All date filter parameters are time aware.
If both the start_effective_date and end_effective_date filters are not passed in, the query automatically uses a default date range of 90 days. If you do not pass in any date filters, the system automatically uses the current date and the previous 90 days.
Multiple filters can be passed to refine the results as required.
Note: Please note that sending a request at the partner (org) level may result in a large data set and may cause timeout errors depending on the request. We recommend sending your GET request at the Merchant (Organization) level.
This URI returns all the funding entries for an Organization within a specified date range.
Note: Please note that sending a request at the partner (org) level may result in a large data set and may cause timeout errors depending on the request. We recommend sending your GET request at the Merchant (Organization) level.
The locations object represents a merchant's processing endpoints. This object enables merchants to see address, contact, business, and services data related to their location. The locations object includes the contacts, services, card, and echeck subobjects.
Locations Object
Parameter
Description
Type
Req
location_id
The identification number of the associated location. For example, loc_1234568.
string
--
status
The status of this location. Supported values include the following:
Live Pending Closing On-Hold Deleted
string
--
created_date
The date that Forte created the location
datetime
--
dba_name
The merchant's Doing Business As (DBA) name.
string
--
street_address1
The first line of the location's street address.
string
--
street_address2
If needed, the second line of the location's street address.
string
--
locality
The city/town/village/locality of the location.
string
--
region
The state or province of the location. This field supports ISO-standard, 2-digit abbreviations for state and province names.
string
--
postal_code
The zip or postal code of the location.
string
--
country
The Alpha-3, ISO-standard country code of the location. For example, USA or CAN.
string
--
business_phone
The business phone number of the location. [max length = 15]
string
--
currency
The Alpha-3, ISO-standard currency code of the currency the location uses.
string
--
timezone
The timezone of the location. Supported values for this field include the following:
PT - Pacific Time MT - Mountain Time CT - Central Time ET - Eastern Time
object
--
business_type
The location's type of business. See Forte's list of Business Classification Codes for more information. [max length = 20]
string
--
organization_id
The identification number of the associated organization. For example, org_5551236.
string
--
organization_name
The name of the associated organization. [max length = 50]
string
--
parent_organization_id
The identification number of the associated parent organization. For example, org_5551236.
string
--
contacts
The contacts object.
object
--
contacts.full_name
The first and last name of this location's contact.
string
--
contacts.phone
The phone number of this location's contact. [max length = 15]
string
--
contacts.email
The business email address of this location's contact. This email cannot be a generic email address or from a distribution list. The value of this parameter must be in a valid email format (e.g., john.doe@email.com). [max length = 100]
string
--
contacts.type
The type of contact associated with this location. Supported values for this field include the following:
primary sales billing support technical
string
--
services
The services object
object
--
services.echeck
The echeck object
object
--
services.echeck.service_fee_percentage
The service fee (i.e., convenience fee) percentage amount for ACH transactions.
integer
--
services.echeck.service_fee_min_amount
The minimum service fee (i.e., convenience fee) amount for ACH transactions.
integer
--
services.echeck.service_fee_amount
The flat service fee (i.e., convenience fee) amount for ACH transactions.
integer
--
services.echeck.service_fee_range
The range of service fee (i.e., convenience fee) amounts for ACH transactions.
array
--
services.echeck.service_fee_tiered
The tiered service fee (i.e., convenience fee) amounts for ACH transactions.
array
--
services.echeck.service_fee_additional_amount
The additional service fee (i.e., convenience fee) amounts for ACH transactions.
integer
--
services.echeck.hold_days_sales
The number of days ACH funds from sale transactions are held before the receiving bank reconciles and settles the transaction.
integer
--
services.echeck.hold_days_refunds
The number of days ACH funds from refund/credit transactions are held before before the receiving bank reconciles and settles the transaction.
integer
--
services.echeck.hold_days_resubmits
The number of days ACH funds are held before the transaction is resubmitted to/from your customer's account.
integer
--
services.echeck.cut_off_time
The settlement cut-off times configured for this location based on the ACH processor.
datetime
--
services.echeck.entry_class_code
The list of standard entry class codes configured for this location. For more information, see Using ACH and SEC Return Codes.
array
--
services.echeck.nacha_id
The NACHA Co ID or Company ID used to process ACH transactions for this location.
string
--
services.card
The card object.
object
--
services.card.cut_off_time
The settlement cut-off times configured for this location based on the credit card processor.
datetime
--
services.card.market_type
The method by which the business captures the majority of its transactions. Supported values for this field include the following:
internet phone mail point_of_sale
string
--
services.card.service_fee_percentage
The service fee (i.e., convenience fee) percentage amount for credit card transactions.
integer
--
services.card.service_fee_min_amount
The minimum service fee (i.e., convenience fee) amount for credit card transactions.
integer
--
services.card.service_fee_amount
The flat service fee (i.e., convenience fee) amount for credit card transactions.
integer
--
services.card.service_fee_additional_amount
The additional service fee (i.e., convenience fee) amounts for credit card transactions.
integer
--
services.card.service_fee_range
The range of service fee (i.e., convenience fee) amounts for credit card transactions.
array
--
services.card.service_fee_tiered
The tiered service fee (i.e., convenience fee) amounts for credit card transactions.
array
--
services.card.service_fee_visa_tax_amount
The flat service fee (i.e., convenience fee) amount used for VISA Debit cards. NOTE: services:card:service_fee_visa_tax_amount is now a legacy field (the visa tax program has been ended) and should be ignored. Visa debit cards now preceded by debit service fee configuration
integer
--
services.card.debit_service_fee_percentage
The service fee (i.e., convenience fee) percentage amount for debit card transactions.
integer
--
services.card.debit_service_fee_min_amount
The minimun service fee (i.e., convenience fee) amount for debit card transactions.
integer
--
services.card.debit_service_fee_amount
The flat service fee (i.e., convenience fee) amount for debit card transactions.
integer
--
services.card.debit_service_fee_additional_amount
The additional service fee (i.e., convenience fee) amounts for debit card transactions.
integer
--
services.card.debit_service_fee_range
The range of service fee (i.e., convinience fee) amounts for debit card transactions.
array
--
services.card.debit_service_fee_tiered
The tiered service fee (i.e., convenience fee) amounts for debit card transactions.
array
--
services.card.card_types
The list of credit card types accepted by this merchant. Supported values for this field include the following:
VISA AMEX MC JCB DISC
string
--
services.card.account_updater
A flag indicating whether or not the Account Updater subscription is enabled for this location. Supported values for this field include the following:
enabled disabled
string
--
services.card.gateway
Indicates whether or not the location is processing credit card transactions using a gateway in which transactions are processed through a different Service Provider. Supported values for this field include the following:
true false
string
--
services.card.platform
The credit card transaction processor.
string
--
services.card.bin
The merchant's Bank Identification Number (BIN) for credit card processing.
string
--
services.card.tid
The merchant's Terminal Identification (TID) number for credit card processing.
string
--
bankaccount_credits_token
The token of the bank account that handles the merchant's credit transactions (e.g., refunds, payroll, chargebacks, reversals, etc.).
string
--
bankaccount_debits_token
The token of the bank account that handles the merchant's debit transactions (e.g., sales, chargeback wins, etc.).
string
--
bankaccount_billing_token
The token of the bank account that pays the merchant's billing obligations to Forte or the Reseller.
string
--
bankaccount_ccfee_token
The token of the bank account that collects the convenience fee debits for each of the merchant's credit card sale transactions.
string
--
bankaccount_ecfee_token
The token of the bank account that collects the convenience fee debits for each of the merchant's echeck sale transactions.
This URI returns all the locations that belong to an Organization. To narrow your search data using specific criteria, use the following parameters to filter your results:
NOTE: The processing limits that display in the card and echeck sub-objects require Payfac permissions. For more information, contact Forte Technical Support at 888-235-4635 option 3.
This URI returns detailed location data using the location_id.
NOTE: Only partners with special permissions can change processing limits on their merchant’s account. For more information, contact Forte Customer Support at 800-337-3060 option 1.
This URI enables partners to change the daily processing limits for echeck and credit card transactions for a merchant account.
Use this URI to update the following address parameters associated with a location:
street_address1
street_address2
locality
region
postal_code
country
When a location’s address is successfully updated, Forte sends an email notification to the location’s primary contact informing him/her of the update.
The organizations object represents a a legal entity that can own multiple sub-organizations (for Forte Partners) or multiple locations (for Forte Merchants) as well as the customers, payment methods, and transactions that belong to those locations.
NOTE: All the parameters of the organizations object are return only.
Parameter
Description
Type
Req
organization_id
The identification number of the organization. For example, org_1234568.
string
--
parent_organization_id
The identification number of the merchant's parent organization.
string
--
legal_name
The legal name of the business. The value of this parameter must match the name associated with the merchant's Tax ID Number. [max length = 50].
string
--
organization_name
The Doing-Business-As (DBA) name of the organization. For example, Bob Smith Enterprises.
string
--
status
The status of this organization. Supported values include the following: active suspended pending
string
--
organization_type
The type of organization. Supported values include the following:
merchant partner enterprise
string
--
last_4_tax_id
The last four digits of the Tax ID associated with this organization.
string
--
language
The language associated with the organization. Currently, the only supported language is English (en).
string
--
currency
The preferred currency of the organization. Currently, the only supported currency option is USD.
string
--
physical_address
The physical_address object.
string
--
physical_address.street_address1
The first line of the organization's street address.
string
--
physical_address.street_address2
If needed, the second line of the organization's street address.
string
--
physical_address.locality
The city/town/village/locality of the organization.
object
--
physical_address.region
The state or province of the organization. This field supports ISO-standard, 2-digit abbreviations for state and province names.
string
--
physical_address.postal_code
The zip or postal code of the organization.
string
--
physical_address.country
The Alpha-3, ISO-standard country code of the organization. For example, USA or CAN.
string
--
created_date
The date and time when this organization was created
string
--
legal_structure
The legal business struture of this organization. Supported values for this field include the following:limited_liability_corporation publicly_held_corporation sole_proprietorship partnership_general_or_limited c-corporation s-corporation government tax_exempt_or_non_profit_organization
string
--
contact
The contacts object.
object
--
contact.contact_type
The type of contact associated with this organization. Only the primary contact displays for "GET All Organizations" requests. SUpported values for this field include the following:
primary sales billing support technical
string
--
contact.full_name
The first and last name of the contact associated with this orgniaztion.
string
--
contact.phone
The phone number of this organization's contact. [max length = 15]
string
--
contact.email
The business email address of this organization's contact. This email cannot be a generic email address or from a distribution list. The value of this parameter must be in a valid email format (e.g., john.doe@email.com). [max length = 100]
string
--
GET Find All Organizations
{{baseURI}}/organizations
This URI returns all organizations beneath a parent organization (e.g., a partner organization or an enterprise organization). To narrow your search data using specific criteria, use the following parameters to filter your results:
organization_name
region
country
status:
active
suspended
pending
legal_structure:
limited_liability_corporation
publicly_held_corporation
sole_proprietorship
partnership_general_or_limited
c-corporation
s-corporation
government
tax_exempt_or_non_profit_organization
Note: Please note that sending a request at the partner (org) level may result in a large data set and may cause timeout errors depending on the request. We recommend sending your GET request at the Merchant (Organization) level.
The paymethods object represents a customer's form of payment and includes the card and echeck sub-objects. This object enables the merchant to tokenize the customer's payment information within Forte's secure data vault. These paymethod tokens can be used to streamline the checkout process for repeat customers or to handle recurring payments without the need to store a customer's sensitive payment information on the merchant's servers. The paymethod object supports both Canadian and U.S.-based credit cards and echecks. For more information on how to correctly format Canadian routing numbers see the echeck.routing_number parameter. For more information about tokens, click here.
Paymethods Object
Parameter
Description
Type
Req
organization_id
The identification number of the associated organization. For example, org_5551236.
string
R
location_id
The identification number of the associated location. For example, loc_1234568.
string
R
customer_token
A unique string used to represent a customer. For example, cst_SoGUG6mcLUS1nVzYBIbk3g. [max length = 26]
string
R
paymethod_token
A unique string used to represent a payment method. For example, mth_1578436587. [max length = 26]
string
O
label
A friendly, customer-defined name for the payment method. For example, "Moms Credit Card," "Work Credit Card," "Visa - 1234," etc. [max length = 50]
string
R
customer_id
A merchant-defined string used to identify the customer. [max length = 15]
string
O
is_default
Indicates whether or not a payment method is the Default Payment Method for a customer. This parameter only displays for GET requests.
string
--
billing_address_token
A unique string used to represent the billing address associated with this payment method. For example, add_tq0hemmmtf-zsxgq689rew.
string
O
notes
A short description of the paymethod. [max length = 50]
string
O
card
The Card Object
object
O
card.card_type
The type of credit card [max length = 6]. Options for this field include the following:
visa mast amex disc dine jcb
string
R
card.name_on_card
The name printed on the on the credit card [max length = 50]. This field is required when creating a new record or creating a permanent token from a one-time token.
string
R
card.last_4_account_number
The last four digits of the redacted account number. This field is return only. [max length = 4]
object
--
card.account_number
The card number. This field is required when creating a new record and can only contain digits. Forte echoes this parameter in the card.masked_account_number response parameter. [max length = 16]
string
O
card.expire_month
The expiration month. This field is required when creating a new record and must be a valid future date. [max length = 2]
string
O
card.expire_year
The expiration year. This field is required when creating a new record and must be a valid future date. [max length = 4]
string
O
card.card_verification_value
The card verification number. Forte does not store this field with the paymethod token, but echoes it back. [max length = 4]
string
O
card.procurement_card
Indicates whether or not this is a procurement card transaction. Accepted values are either true or false. For procurement card transactions, merchants must pass the customer_accounting_code field in the card object and the sales_tax_amount field in the transaction object.
string
O
card.one_time_token
A single use token generated by Forte.js (e.g., ott_g7vnjqikszabzynu6eowbq). [max length = 26]
string
O
card.customer_accounting_code
Lists the procurement card accounting code. Forte does not save this information if the merchant is creating a paymethod. [max length = 17]
string
O
card.au_code
Indicates the type of changes Account Updater found for the card associated with that payment token. This parameter supports the following values:
new - New Account Number closed - Account Closed expiry - Expiration Date Updated updated - Card Information Updated by Issuer
This parameter is return only for GET requests. For more information about Account Updater, contact Customer Service.
string
O
card.suppress_account_updater
A Boolean flag indicating whether or not Forte should run monthly Account Updater services on the paymethod token associated to this credit card. Account Updater subscription required. The following values are supported:
true - This paymethod token will not be included in the monthly Account Updater services. false - This paymethod token will be included in the monthly Account Updater services. This is the default value.
bool
O
card.au_updated_date
The date and timestamp when the token was last updated by Forte's Account Updater services. This parameter is return only for GET requests.
datetime
O
card.au_description
A concise description of what update was performed on the credit card associated with the payment token. The following options are supported:
"New account number" "Account closed" "Expiration date updated" "Card information updated by issuer"
This parameter is return only for GET requests.
O
echeck
The eCheck Object
object
O
echeck.account_holder
The name of the account owner. This field is required when creating or updating a new record. [max length = 50]
string
O
echeck.last_4_account_number
The last four digits of the redacted account number. This field is return only. [max length = 4]
string
--
echeck.account_number
The DDA or eCheck account number. This field is required when creating or updating a new record and can only contain digits. Forte echoes this parameter in the echeck.masked_account_number response parameter. [max length = 17]
string
O
echeck.routing_number
The transit routing number. This field supports both U.S. and Canadian routing numbers. NOTE: A Canadian routing number displayed on a check needs to be reformatted differently for electronic payments. If a check displays a routing number as BBBBB-AAA (where AAA indicates the Financial Institution and BBBBB is the branch), then the routing number must be changed to 0AAABBBBB to process the payment electronically. For example, if a check from an account issued by the Bank of Montreal showed the routing number 00011-001, then that number would need to be reformatted to 000100011 for the payment to be electronically processed. Click here for a directory of Canadian financial institutions. This field is required when creating or updating a new record and can only contain digits. [max length = 9]
string
O
echeck.account_type
Use one of the following values for this parameter:
Checking Savings
string
O
echeck.sec_code
Use one of the following values for this standard-entry class code: ARC, CCD, CIE, CTX, POP, POS, PPD, RCK, TEL, WEB.
string
R
echeck.one_time_token
A single use token generated by Forte.js (e.g., ott_g7vnjqikszabzynu6eowbq). [max length = 26]
This URI creates a new paymethod for the customer and returns a paymethod_token. Use this URI when creating permanent paymethod tokens from one-time tokens created in Forte.js. NOTE: You can also create a new paymethod for an existing customer by including the customer_token in the body of the request to the /organizations/org_{{organization}}/locations/loc_{{location}}/paymethods URI.
To associate an existing billing_address_token to a paymethod, include it in the body of the request.
This URI creates a new paymethod for the customer and returns a paymethod_token. Use this URI when creating permanent paymethod tokens from one-time tokens created in Forte.js. NOTE: You can also create a new paymethod for an existing customer by including the customer_token in the body of the request to the /organizations/org_{{organization}}/locations/loc_{{location}}/paymethods URI.
To associate an existing billing_address_token to a paymethod, include it in the body of the request.
This URI creates a clientless credit card payment method and returns a paymethod_token (i.e., a payment method that is not associated with a customer). To associate this payment method with an existing customer, include that customer’s customer_token in the body of the request or include the customer_token value in the route (e.g., /organizations/org_{{organization}}/locations/loc_{{location}}/customers/cst_{{customer_token}}/paymethods).
To associate an existing billing_address_token to the paymethod, include it in the body of the request.
This URI creates a clientless echeck payment method and returns a paymethod_token (i.e., a payment method that is not associated with a customer). To associate this payment method with an existing customer, include that customer’s customer_token in the body of the request or include the customer_token value in the route (e.g., /organizations/org_{{organization}}/locations/loc_{{location}}/customers/cst_{{customer_token}}/paymethods).
To associate an existing billing_address_token to a paymethod, include it in the body of the request.
Use this URI to create a permanent token from the one-time token you created in Forte.js. You can also create a permanent token from a one-time token by including the existing customer’s customer_token in the body of the request to the /organizations/org_{{organization}}/locations/loc{{location}}/paymethods URI. NOTE: At this time, one-time tokens cannot be used to create organization-level paymethod tokens.
To associate an existing billing_address_token to a paymethod, include it in the body of the request.
Use this URI to create a permanent token from the one-time token you created in Forte.js. You can also create a permanent token from a one-time token by including the existing customer’s customer_token in the body of the request to the /organizations/org_{{organization}}/locations/loc{{location}}/paymethods URI. NOTE: At this time, one-time tokens cannot be used to create organization-level paymethod tokens.
To associate an existing billing_address_token to a paymethod, include it in the body of the request.
This URI returns all the payment methods owned by a Location. To narrow your search data using specific criteria, use the following parameters to filter your results:
customer_token
customer_id
start_au_updated_date / end_au_updated_date
paymethod_type
NOTES:
All date filter parameters are time aware.
As a best practice, Forte recommends running your Account Updater report on the first day of the month for the previous month’s data. This method provides the most accurate Account Updater data to match to merchant invoice items.
This URI returns all the payment methods owned by an Organization. Account Updater customers use this URI to view the payment tokens that were updated in the prior months using the following filter parameters:
start_au_updated_date
end_au_updated_date
These filters ensure that Forte only returns card payment token results within the specified date range. NOTE: Account Updater services cannot be tested in Sandbox.
To narrow your search data using specific criteria, use the following parameters to filter your results.
location_id
customer_token
customer_id
start_au_updated_date / end_au_updated_date
paymethod_type
NOTE: All date filter parameters are time aware.
Please note that sending a request at the partner (org) level may result in a large data set and may cause timeout errors depending on the request. We recommend sending your GET request at the Merchant (Organization) level.
Account Updater customers use this URI with the start_au_updated_date and end_au_updated_date filters to view the payment tokens that were updated in the prior months.
NOTES:
Account Updater services cannot be tested in Sandbox.
As a best practice, Forte recommends running your Account Updater report on the first day of the month for the previous month’s data. This method provides the most accurate Account Updater data to match to merchant invoice items.
Please note that sending a request at the partner (org) level may result in a large data set and may cause timeout errors depending on the request. We recommend sending your GET request at the Merchant (Organization) level.
This URI updates the specified payment method (via the paymethod_token parameter) and assigns it to the customer_token specified in the request payload.
This URI updates the payment method specified in the route via the paymethod_token parameter. NOTE: You cannot update the account_number parameter when updating an echeck payment method.
This URI updates the billing_address_token associated with the payment method. The billing address you associate to a payment method must belong to the same organization referenced in the route.
This URI updates the payment method specified in the route via the paymethod_token parameter. NOTE: You cannot update the account_number or the card_verification_value parameters when updating a credit card payment method.
This URI updates the payment method specified in the route via the paymethod_token parameter. NOTE: You cannot update the account_number parameter when updating an echeck payment method.
This URI excludes a credit card token from the monthly Account Updater run when passed with the "suppress_account_updater"="true" parameter in the body of the request. NOTE: Account Updater functionality cannot be tested in Sandbox.
This URI deletes the payment method specified in the route via the paymethod_token parameter. NOTE: A payment method cannot be deleted if it is tied to a schedule in the active status.
The scheduleitems object captures the planned individual transactions that make up a schedule. This object enables merchants to create and make one-time adjustments to a scheduled transaction such as the amount or status of the transaction.
Scheduleitems Object
Parameter
Description
Type
Req
organization_id
The identification number of the associated organization. For example, org_5551236.
string
R
location_id
The identification number of the associated location. For example, loc_1234568.
string
R
schedule_item_id
A unique string used to represent a schedule item. For example, sci_2e5770ae-c120-414f-ae8c-d065753567e7. [max length = 40]
string
R
customer_token
A unique string used to represent a customer. For example, cst_SoGUG6mcLUS1nVzYBIbk3g. [max length = 26]
string
R
paymethod_token
A unique string used to represent a payment method. For example, mth_1578436587. [max length = 26]
string
R
transaction_id
A unique string used to represent a completed schedule item. For example, trn_55c98c85-d3e8-4230-85e9-21d7d522eec0. [max length = 36]
string
O
schedule_id
A unique string used to represent a schedule. For example, sch_2e5770ae-c120-414f-ae8c-d065753567e7. [max length = 40]
string
R
schedule_item_amount
Indicates the amount of the scheduled item. For service fee transactions, use this parameter as the base amount for calculating a service fee. [max length = 6]
decimal
O
schedule_item_service_fee_amount
The amount of the service fee (i.e., convenience fee).
decimal
O
schedule_item_authorization_amount
Indicates the amount of the scheduled item. For service fee transactions, this parameter is the resulting sum of the schedule_item_amount and the schedule_item_service_fee_amount values.
decimal
O
schedule_item_status
Indicates the status of the scheduled item. The supported values for this field include the following:
scheduled - The item is scheduled completed - The item is completed suspended - The item is suspended processing - The item is processing failed - The item has failed
string
R
schedule_item_date
Indicates the date of the scheduled item. For POSTs, the value of this field must be greater than today's date. [max length = 10]
datetime
R
schedule_item_processed_date
Indicates the date when the scheduled item will be processed. This parameter is return only.
datetime
--
schedule_item_created_date
Indicates the date when the merchant created the scheduled item. This parameter is return only.
datetime
--
schedule_item_description
A brief description of the scheduled item being processed. [max length = 50]
This URI creates a new scheduleitem and returns a unique schedule_item_id. If the schedule_item_date or schedule_item_amount fields are not passed, the system automatically calculates these values based on the last scheduleitem and the schedule definition records. The value of the schedule_item_date field must be a future date. NOTE: Scheduleitems cannot be created for non-active or continuous schedules.
This URI returns all scheduleitems for an Organization. To narrow your search data using specific criteria, use the following parameters to filter your results:
Note: Please note that sending a request at the partner (org) level may result in a large data set and may cause timeout errors depending on the request. We recommend sending your GET request at the Merchant (Organization) level.
This URI returns all scheduleitems for a Location. To narrow your search data using specific criteria, use the following parameters to filter your results:
This URI updates the specified scheduleitem. Only scheduleitems with a future date value in the schedule_item_date field and a status of scheduled or suspended in the schedule_item_status field can be updated. If the status of a scheduleitem in a continuous schedule is changed to suspended, the status of the schedule definition will also be suspended. NOTE: Updates to the schedule_item_created_date and schedule_item_processed_date are not allowed.
The schedules object captures scheduled transactions for a merchant's organization or location and includes the summary sub-object. Merchants can specify a particular quantity of scheduled transactions or can set up continuous transactions that will occur until the schedule is suspended or deleted. Subscription billing enables merchants to bill customers automatically on a fixed schedule for a specific product or service. Scheduled transactions can only be created with customer_token and paymethod_token parameters.
Schedules Object
Parameter
Description
Type
Req
organization_id
The identification number of the associated organization. For example, org_5551236.
string
R
location_id
The identification number of the associated location. For example, loc_1234568.
string
R
schedule_id
A unique string used to represent a schedule. For example, sch_2e5770ae-c120-414f-ae8c-d065753567e7. [max length = 40]
string
R
customer_token
A unique string used to represent a customer. For example, cst_SoGUG6mcLUS1nVzYBIbk3g. [max length = 26]
string
R
paymethod_token
A unique string used to represent a payment method. For example, mth_1578436587. [max length = 26]
string
R
action
The supported transaction types include the following values:
sale - Creates an ad-hoc or token transaction that will settle at the end of the day credit - Used to send funds back to the account/card holder rather than collecting funds from an account/card holder.
string
R
schedule_quantity
Indicates the quantity of transactions to perform. For continuous schedules, set the value of this field to 0. [max length = 6]
integer
R
schedule_frequency
Indicates the frequency of the scheduled transactions. The supported values for this field include the following:
Indicates the amount of each recurring transaction plus any sales taxes, shipping fees, tips or other extraneous amounts. For service fee transactions, use this parameter as the base amount for calculating a service fee. The value of this parameter depends on the value in the schedule_frequency parameter. [max length = 6]
decimal
O
schedule_service_fee_amount
The amount of the service fee (i.e., convenience fee).
decimal
O
schedule_authorization_amount
Indicates the amount of the recurring payment. For service fee transactions, this parameter is the resulting sum of the schedule_amount and the schedule_service_fee_amount values.
decimal
R
schedule_start_date
Indicates the start day of the next recurring transaction in MM/DD/YYYY format. This date can be today's date or greater. NOTE: If the merchant does not specify this value, the system defaults to today's date. [max length = 10]
datetime
R
schedule_created_date
The date the schedule was created. This parameter is return only.
datetime
--
customer_acct_code
The customer accounting code. This field only applies to credit card transactions. [max length = 17]
string
--
schedule_status
The current status of the schedule. The supported values for this field include the following:
active - The schedule is active. suspended - The schedule is suspended. completed - The schedule is completed
string
O
item_description
The check number or other description of the item to be processed. [max length = 50]
string
O
reference_id
A merchant-defined string that identifies the transaction. [max length = 50]
O
order_number
A merchant-assigned ID code that is returned with the transaction response. [max length = 26]
string
O
customer_id
A merchant-defined string created at the customer level to identify the customer. [max length = 15]
string
O
echeck
The eCheck Object
object
O
echeck.sec_code
The Standard Entry Class code for the transaction. This field is required for echeck transactions. Additionally, the available options for this field depend on your merchant configuration [max length = 3]
string
R
summary
The Summary Object
object
O
summary.schedule_next_amount
The amount of the next scheduled transaction that will be processed. This parameter is return only.
decimal
--
summary.schedule_next_date
The next date when a scheduled transaction will be processed. This parameter is return only.
datetime
--
summary.schedule_last_amount
The authorization amount for the last scheduled transaction that Forte processed. This parameter is return only.
decimal
--
summary.schedule_last_date
The date and timestamp when Forte processed the last scheduled transaction. This parameter is return only.
datetime
--
summary.schedule_successful_amount
The total amount of the successful transactions for this schedule. This parameter is return only.
decimal
--
summary.schedule_successful_authorization_amount
The authorization amount of the last scheduled transaction that Forte successfully processed. This parameter is return only.
decimal
--
summary.schedule_successful_quantity
The total number of successful transactions for this schedule. This parameter is return only.
integer
--
summary.schedule_failed_amount
The total amount of failed transactions for this schedule. This parameter is return only.
decimal
--
summary.schedule_failed_quantity
The total number of failed transactions for this schedule. This parameter is return only.
integer
--
summary.scheduled_remaining_amount
The total amount of the remaining transactions for this schedule. This parameter is return only.
decimal
--
summary.scheduled_remaining_quantity
The total number of the remaining transactions for this schedule. This parameter is return only.
integer
--
summary.scheduled_suspended_amount
The total amount of the suspended transactions for this schedule. This parameter is return only.
decimal
--
summary.scheduled_suspended_quantity
The total number of suspended transactions for this schedule. This parameter is return only.
integer
--
xdata
The Xdata Object
object
O
xdata.xdata_1-9
Up to nine fields (1-9) of extra data that can be associated with a schedule or transaction. Each xdata_# field can contain up to 255 characters.
Creates a new schedule and returns a new unique schedule_id. NOTE: Both the customer_token and the paymethod_token parameters must be specified in the body of the request.
Creates a new schedule and returns a new unique schedule_id. NOTE: Both the customer_token and the paymethod_token parameters must be specified in the body of the request.
Creates a new schedule and returns a new unique schedule_id. NOTE: Both the customer_token and the paymethod_token parameters must be specified in the body of the request.
Creates a new schedule and returns a new unique schedule_id. NOTE: Both the customer_token and paymethod_token parameters must be specified in the request.
This URI returns all schedules created for a location. To narrow your search data using specific criteria, use the following parameters to filter your results:
This URI returns a deleted schedule based on the schedule_id parameter and the schedule_status=deleted filter. The schedule detailed data that Forte returns includes schedule summary data that can be used to quickly find useful information about that schedule.
This URI returns a deleted schedule based on the schedule_id parameter and the schedule_status=deleted filter. The schedule detailed data that Forte returns includes schedule summary data that can be used to quickly find useful information about that schedule.
Updates the status of the schedule definition. When you reactivate a suspended schedule, its scheduleitems dated at least one day in the future are automatically reactivated as well.
The settlements object captures the status of transaction(s) associated with a merchant location. GET requests to this endpoint can be filtered according to settlement date, response, and method.
Settlements Object
Parameter
Description
Type
Req
organization_id
The identification number of the associated organization. For example, org_5551236.
string
R
location_id
The identification number of the associated location. For example, loc_1234568.
string
R
funding_id
A unique string used to represent a funding entry. For example, fnd_ACH-0226-173C5. [max length = 20]
string
--
customer_token
A unique string used to represent a customer. For example, cst_SoGUG6mcLUS1nVzYBIbk3g. [max length = 26]
string
--
customer_id
A merchant-defined string created at the customer level to identify the customer. [max length = 15]
string
--
order_number
A merchant-defined string. [max length = 50]
string
--
reference_id
A merchant-defined string that identifies the transaction. [max length = 50]
string
--
settle_id
The settlement ID of the settled transaction (e.g., stl_51cf4633-1767-484f-8784-be76a4076791). [max length = 40]
string
R
transaction_id
A 36-character code that uniquely identifies the transaction.
string
--
settle_batch_id
The ID of the credit card settlement batch, which the merchant can use to reconcile credit card bank deposits. This parameter is view-only and only for credit card transactions.
string
--
settle_date
The date when the transaction was settled. This parameter is return only.
datetime
--
settle_type
The type of settlement. Supported settlement types include the following values. For echeck transactions:
- deposit - A deposit to the merchant's bank account or a payment received - reject - An ACH return such as Non-Sufficient Funds or Account Closed. There is no corresponding funding on the merchant's bank account. - withdrawal - A withdrawal from the merchant's bank account such as a credit transaction or a transaction that was funded and then unfunded (such as an R10 return).
For credit card transactions:
- deposit - A deposit to the merchant's bank account or a payment received - withdrawal - A withdrawal from the merchant's bank account such as a credit transaction or a transaction that was funded and then unfunded, e.g., a credit card chargeback
This parameter is return only.
string
--
settle_response_code
See the Response Codes table for more information. This parameter is return only. NOTE: Credit card transactions that do not return a settle response can be considered settled.
object
O
settle_amount
The amount the transaction settled for. This parameter is return only.
decimal
--
method
The payment method. This parameter is return only. The supported payment methods include the following values:
This URI returns all the transaction settlements for a Location. To narrow your search data using specific criteria, use the following parameters to filter your results:
customer_token
transaction_id
customer_id
order_number
reference_id
start_settle_date / end_settle_date
settle_response_code
method
NOTES:
All date filter parameters are time aware.
If the start_settle_date and end_settle_date filters are not passed in via the body of the requst, the query automatically uses a default date range of 90 days. If you do not pass in any date filters, the system automatically uses the current date and the previous 90 days.
This URI returns all the transaction settlements for a Location within a specific date range.
Note: Please note that sending a request at the partner (org) level may result in a large data set and may cause timeout errors depending on the request. We recommend sending your GET request at the Merchant (Organization) level.
This URI returns all the settlement data for a specific transaction. NOTE: Most transactions only have one settlement, but due to disputes and returns, some transactions may have multiple settlements.
This URI returns all the transaction settlements for an Organization. To narrow your search data using specific criteria, use the following parameters to filter your results:
location_id
customer_token
transaction_id
customer_id
order_number
reference_id
start_settle_date / end_settle_date
settle_response_code
method
NOTES:
All date filter parameters are time aware.
If the start_settle_date and end_settle_date filters are not passed in via the body of the requst, the query automatically uses a default date range of 90 days. If you do not pass in any date filters, the system automatically uses the current date and the previous 90 days.
Please note that sending a request at the partner (org) level may result in a large data set and may cause timeout errors depending on the request. We recommend sending your GET request at the Merchant (Organization) level.
The transactions object captures all the transaction(s) associated with a merchant location. The transactions object includes the address, card, echeck, line_items and xdata sub-objects. Token-based transactions will use default addresses and will require you to set the customer's default shipping and billing addresses prior to passing transaction data. The transaction object supports both Canadian and U.S.-based addresses and payment methods. For more information on how to correctly format Canadian routing numbers see the echeck.routing_number parameter.
Transactions Object
Parameter
Description
Type
Req
organization_id
The identification number of the associated organization. For example, org_5551236.
string
R
location_id
The identification number of the associated location. For example, loc_1234568.
string
R
action
The supported transaction types include the following values:
sale - Used to collect funds from a debit/credit card or bank account. This action is the same as an authorization + capture operation in just one step, and should be the preferred option if the intent of the merchant is to capture the funds immediately upon authorization. authorize - Used to verify the specified account information (bank account or debit/credit card account) and balance (for credit cards). This transaction should be used when the capture of the funds will be initiated at a later time. For example, after the shipping or the delivery of goods subject to the transaction. If the intent is to authorize the transaction and capture the funds immediately a sale transaction call should be sent instead of authorization and capture calls. credit - Used to send fund to a bank account or credit/debit card. void - Used to stop a transaction or cancel the hold on a transaction that was authorized. Voids can only be performed on items that haven't yet originated (for echeck transactions) or settled (for credit card transactions). capture - Used to collect the funds that were previously authorized. See authorize. inquiry - Requests the available balance from a card. NOTE: This action is only for merchant organizations approved to process partial authorization transactions. verify - Used to verify a bank account or card account when there isn't a need to perform a capture operation later. NOTE: For credit cards, this action is only supported for merchants enrolled with Vantiv. authenticate - used to verify the ownership of a bank account. This service verifies if the given person/business (identified by the First & Last name or Business Name) is the owner of a given bank account. force - Used to capture funds by bypassing verification or authorization functionality. Merchants should verify or authorize a force operation prior to performing it. reverse - Used to reverse a previous sale (action=sale) transaction if it's too late to void that transaction. NOTE: Action = credit or force cannot be reversed.
string
R
status
The current dispositon of the transaction. For a list of transaction status values, click here
string
--
customer_token
A unique string used to represent a customer. For example, cst_SoGUG6mcLUS1nVzYBIbk3g. Transactions can be created using only a customer_token (i.e., the merchant does not need to pass the paymethods object or a paymethod_token) if the customer has defined a default_paymethod_token in the customer object. [max length = 26]
string
R
customer_id
A merchant-defined string used to identify the customer. [max length = 15]
string
O
paymethod_token
A unique string used to represent a payment method. For example, mth_1578436587. [max length = 26]
string
O
reference_id
A merchant-defined string that identifies the transaction.[max length = 15]
string
O
authorization_amount
The amount to be charged/credited to the customer.
decimal
R
order_number
A merchant-assigned ID code that is returned with the transaction response. [max length = 36]
string
O
original_transaction_id
The trace number returned by the original transaction. [max length = 36]
string
O
transaction_id
A 36-character code that uniquely identifies the transaction.
string
O
authorization_code
An approval code from a vendor that authorizes a merchant to void a transaction.
object
R
entered_by
The name or the ID of the person entering the data. [max length = 20]
string
O
received_date
The date the merchant received the transaction. This parameter is return only.
datetime
--
origination_date
The date the funds of the transaction go to the originating depository financial institution. This parameter is return only.
datetime
--
sales_tax_amount
The sales tax amount. This field is only required for procurement card transactions.
decimal
O
subtotal_amount
The base amount of the good or service. This parameter is auto-calculated and is not required for requests. Use this parameter when calculating service fees.
decimal
--
service_fee_amount
The service fee (i.e., convenience fee) for this transaction. Use the following definitions when calculating a service fee:
service_fee_amount - The percentage calculated (e.g., subtotal_amount * 2.45% for a service fee of 2.45%) authorization_amount - The resulting sum of the subtotal_amount and the service_fee_amount.
decimal
O
recurring_indicator
A merchant-assigned flag used to indicate recurring credit card transactions for the following transaction types when set to true for POST-only requests:
sale authorize credit force
NOTE: When set to true, this parameter could have an impact on a merchant's interchange rates depending on his or her credit card processor. Contact your processor for more information.
bool
O
customer_ip_address
The customer's originating IP address. This parameter is used for fraud prevention and does not echo back in the response. [max length = 80]
string
O
save_token
This parameter creates customer and/or paymethod tokens for any transaction POST request—whether passed via request parameters or via swipe data through the card.card_data parameter. Supported values include the following:
customer - Creates a new customer and paymethod tokens. paymethod - Creates a clientless paymethod token.
string
O
attempt_number
The number of times Forte has presented an ACH transaction for settlement. Values for this field can only be positive, whole numbers (e.g., attempt_number=1). This field is return only. [max length = 80]
string
--
cof_transaction_type
Indicates whether the credential on file (COF) transaction is recurring (0) or customer initiated (1). NOTE: If you are performing a zero-dollar authorization and only storing the payment method for future use, then the pg_cof_transaction_type should be 1.
int
--
cof_initial_transaction_id
The processor’s transaction ID of the first transaction for a stored credential on file. This field is required for non-tokenized, credential-on-file subsequent transactions. [max length = 20]
string
C
billing_address
The Address Object
object
R
billing_address.address_token
A unique string used to represent an address. For example, add_tq0hemmmtf-zsxgq689rew.
string
R
billing_address.customer_token
A unique string used to represent a customer. For example, cst_SoGUG6mcLUS1nVzYBIbk3g.
string
R
billing_address.organization_id
The identification number of the associated organization. For example, org_5551236.
string
R
billing_address.location_id
The identification number of the associated location. For example, loc_1234568.
string
R
billing_address.first_name
The first name of the user associated with this billing address [max length = 25]. NOTE: The first_name and last_name parameters are required for billing addresses when creating transactions without tokens.
string
R
billing_address.last_name
The last name of the user associated with this billing address [max length = 25]. NOTE: The first_name and last_name parameters are required for billing addresses when creating transactions without tokens.
string
R
billing_address.company_name
The name of the company associated with this billing address [max length = 20]. NOTE: The company_name parameter is required for billing addresses when creating transactions without tokens.
string
R
billing_address.phone
The phone number associated with this billing address. This field supports both U.S. and Canadian phone numbers. [max length = 15]
string
O
billing_address.email
The email address associated with this billing address. [max length = 50]
string
O
billing_address.label
A label that succinctly identifies the address. For example, "Work" or "Home." [max length = 50]
string
O
billing_address.address_type
The type of address. Use one of the following values:
default_billing - The default billing address none - The address is not a default address both - The address is both a default shipping and default billing address
string
O
billing_address.shipping_address_type
Indicates whether the address is a residential or commercial address (if the address is both a billing and shipping address).
string
R
billing_addreess.physical_address
The Physical Address Object.
object
O
billing_address.physical_address.street_line1
The first line of the street address. [max length = 35]
string
O
billing_address.physical_address.street_line2
The second line of the street address. [max length = 35]
string
O
billing_address.physical_address.locality
Locality or city/town/village. [max length = 25]
string
O
billing_address.physical_address.region
Region or state/province. This field supports both U.S. and Canadian regions. [max length = 2]
string
O
billing_address.physical_address.country
The ISO 3166-1 alpha-2 country abbreviation. [max length = 2]
string
O
billing_address.physical_address.postal_code
Postal Code [max length = 15]. This field supports both U.S. and Canadian postal codes.
string
O
shipping_address
The Address Object
object
O
shipping_address.address_token
A unique string used to represent an address. For example, add_tq0hemmmtf-zsxgq689rew.
string
R
shipping_address.customer_token
A unique string used to represent a customer. For example, cst_SoGUG6mcLUS1nVzYBIbk3g.
string
R
shipping_address.organization_id
The identification number of the associated organization. For example, org_5551236.
string
R
shipping_address.location_id
The identification number of the associated location. For example, loc_1234568.
string
R
shipping_address.first_name
The first name of the user associated with this shipping address [max length = 25]. NOTE: The first_name and last_name parameters are required for billing addresses when creating transactions without tokens.
string
R
shipping_address.last_name
The last name of the user associated with this shipping address [max length = 25]. NOTE: The first_name and last_name parameters are required for billing addresses when creating transactions without tokens.
string
R
shipping_address.company_name
The name of the company associated with this shipping address [max length = 20]. NOTE: The company_name parameter is required for billing addresses when creating transactions without tokens.
string
R
shipping_address.phone
The phone number associated with this shipping address. This field supports both U.S. and Canadian phone numbers. [max length = 15]
string
O
shipping_address.email
The email address associated with this shipping address. [max length = 50]
string
O
shipping_address.label
A label that succinctly identifies the address. For example, "Work" or "Home."
string
O
shipping_address.address_type
The type of address. Use one of the following values:
default_shipping - The default shipping address none - The address is not a default address both - The address is both a default shipping address and a default billing address
string
O
shipping_address.shipping_address_type
Indicates whether the address is a residential or commercial address.
string
R
shipping_address.physical_address
The Physical Address Object.
object
O
shipping_address.physical_address.street_line1
The first line of the street address. [max length = 35]
string
O
shipping_address.physical_address.street_line2
The second line of the street address. [max length = 35]
string
O
shipping_address.physical_address.locality
Locality or city/town/village [max length = 25]
string
O
shipping_address.physical_address.region
Region or state/province. This field supports both U.S. and Canadian regions. [max length = 2]
string
O
shipping_address.physical_address.country
The ISO 3166-1 alpha-2 country abbreviation. [max length = 2]
string
O
shipping_address.physical_address.postal_code
Postal Code [max length = 15]. This field supports both U.S. and Canadian postal codes.
string
O
card
The Card Object
object
R
card.card_type
The type of credit card [max length = 4]. Options for this field include the following:
visa mast amex disc dine jcb
string
R
card.name_on_card
The name printed on the credit card [max length = 50]. This field is required when creating a new record or creating a permanent token from a one-time token.
string
R
card.last_4_account_number
The last four digits of the redacted account number. This field is return only. [max length = 4]
string
--
card.account_number
The card number. This field is required when creating a new record and can only contain digits. Forte echoes this parameter in the card.masked_account_number response parameter. [max length = 19]. For Digital wallet transactions this device-specific identifier (DPAN - Device Primary Account Number) replaces the card number to securely conduct transactions. Note: Device Primary Account Number is used for alternative method of payments.
string
R
card.expire_month
The expiration month. This field is required when creating a new record and must be a valid future date. [max length = 2].
string
R
card.expire_year
The expiration year. This field is required when creating a new record and must be a valid future date. [max length = 4].
string
R
card.card_verification_value
The card verification number. Forte does not store this field with the paymethod token, but echoes it back. [max length = 5].
string
R
card.procurement_card
Indicates whether or not this is a procurement card transaction. Accepted values are either true or false. For procurement card transactions, merchants must pass the customer_accounting_code field in the card object and the sales_tax_amount field in the transaction object. [max length = 5].
bool
O
card.customer_accounting_code
Lists the procurement card accounting code. Forte does not save this information if the merchant is creating a paymethod. [max length = 17]
string
O
card.one_time_token
A single use token generated by Forte.js (e.g., ott_g7vnjqikszabzynu6eowbq).
string
O
card.card_reader
The eight-digit device part number specifying which swipe device was used to capture the card data. Currently, only the following models and part numbers are supported when capturing encrypted card data:
30050202 (IPAD) 30050203 (IPAD PIN Pad and Card Reader) 21073062 (Dynamag) 21073084 (iDynamo - used for iPhone mobile apps) 21073131 (iDynamo 5 (lightening adapter) - used for iPhone mobile apps) 21073092 (uDynamo - used for Android mobile apps) 21079802 (eDynamo)
[max length = 20]
string
O
card.card_data
The full set of swipe data received from the encrypting swipe device. [max length = 1500]
string
O
card.card_emv_data
The full set of emv data received from the emv device. [max length = 1500]
string
O
card.fallback_swipe
Indicates if this swiped transaction is a fallback swipe after a dipped transaction failed to process. Accepted values are either true or false [max length = 5]
bool
O
card.wallet_cryptogram
This one-time encrypted string represents the transaction and merchant information
string
R
card.wallet_type
This field will indicate the wallet used to obtain the cryptogram. Supported values: “ApplePay”
string
R
card.wallet_source
This will indicate the platform on which the payment request was received. Web: integrations capturing payments on browser Mobile: Data values describing an InApp Transaction
string
R
echeck
The eCheck Object
object
R
echeck.account_holder
The name of the account owner. This field is required when creating or updating a new record.
string
R
echeck.last_4_account_number
The last four digits of the redacted account number. This field is return only. [max length = 4]
string
--
echeck.account_number
The DDA or eCheck account number. This field is required when creating or updating a new record and can only contain digits. Forte echoes this parameter in the echeck.masked_account_number response parameter.
string
R
echeck.routing_number
The transit routing number. This field supports both U.S. and Canadian routing numbers. NOTE: A Canadian routing number displayed on a check needs to be reformatted differently for electronic payments. If a check displays a routing number as BBBBB-AAA (where AAA indicates the Financial Institution and BBBBB is the branch), then the routing number must be changed to 0AAABBBBB to process the payment electronically. For example, if a check from an account issued by the Bank of Montreal showed the routing number 00011-001, then that number would need to be reformatted to 000100011 for the payment to be electronically processed. Click here for a directory of Canadian financial institutions. This field is required when creating or updating a new record and can only contain digits. [max length = 9].
string
R
echeck.account_type
>Use one of the following values for this parameter:
Checking Savings
string
O
echeck.item_description
Check number or other description of item to be processed. NOTE: This field is only available for POST transactions and is not included in the paymethods object.
string
O
echeck.sec_code
Use one of the following values for this standard-entry class code: ARC, CCD, CIE, CTX, POP, POS, PPD, RCK, TEL, WEB.
For eCheck transactions, it is only required for action= "sale", "authorize", "credit" and "force". Otherwise (e.g. "verify", "authenticate") it should be null. For more information on SEC codes, see the ACH Standard Entry Class (SEC) Codes Tutorial. This parameter is required to conform with a NACHA requirement that states when submitting a transaction for processing, the originator must designate how the transaction was authorized. Forte customers primarily use the PPD, CCD, and WEB SEC codes.
string
C
echeck.one_time_token
A single use token generated by Forte.js (e.g., ott_g7vnjqikszabzynu6eowbq).
string
O
line_items
The Line Items Object.
object
O
line_items.line_item_header
Description of the data elements contained within each line item. This header will be displayed when viewing transaction details.
string
O
line_items.line_item_1-10000
Contents of the line item formatted according to the line_item_header.
string
O
xdata
The Xdata Object
object
O
xdata.xdata_1-9
Up to nine fields (1-9) of extra data that can be associated with a schedule or transaction. Each xdata_# field can contain up to 255 characters.
string
O
vendor
The vendor Object
object
O
vendor.vendor_type
The supported vendor types include the following.
PayPal
string
R
vendor.vendor_order_number
The ID of the order
**Note:**The vendor_order_number is required for vendor when creating transaction without PayPal tokens
string
R
vendor.vendor_billing_agreement_id
The ID of PayPal billing agreement
NOTE:The vendor_billing_agreement_id is required for vendor when creating transaction with PayPal tokens.
Accepted card types (debit and credit) include Visa, MasterCard, Amex, Discover, Diners and JCB.
This URI can perform the following tasks while returning a new transaction_id:
Create an ad-hoc transaction. Note: If the intent is to authorize and immediately capture the transaction, it is recommended that a sale transaction is sent.
Create a transaction based on the customer token using the default billing address
Create a transaction based on the customer and paymethod tokens using the customer default billing address
Create a transaction based on the paymethod token, which requires the address in the request message
Reverse a sale transaction and create a credit transaction, which requires the transaction_id and authorization_code of the original transaction
Note: Sending digital wallet transactions to Forte requires enablement at the merchant (location) label, and compliance with a set of prerequisites defined for each wallet. Currently this feature is certified for Apple Pay in merchants processing credit card payments with Fiserv, please check additional requirements here.
For the Initial sale transaction, the following additional parameters from the wallet’s decrypted payload should be sent to the transaction endpoint:
To send subsequent sale transactions after an initial transaction was authorized using DPAN you will need to submit transaction.cof_initial_transaction_id as received in the initial transaction response.
To send subsequent sale transactions after an initial transaction was authorized using Payment Method Tokens you will need to submit transaction.paymethod_token, indicate that this is a subsequent transaction sending transaction.cof_transaction_type: 0 and specifying card.wallet_source (optional).
This URI creates sale transactions using an existing paymethod_token. A token is a random string of alpha-numeric characters that represent a payment method, which Forte stores in an encrypted database. Along with encryption, tokenization is used in the payments industry to protect sensitive data.
This URI creates sale transactions using an existing paymethod_token. A token is a random string of alpha-numeric characters that represent a payment method, which Forte stores in an encrypted database. Along with encryption, tokenization is used in the payments industry to protect sensitive data.
Including the save_token parameter in the body of your request creates customer and/or paymethod tokens from the card’s swipe data. The save_token parameter supports the following values:
customer – Creates both a customer and paymethod tokens
paymethod – Creates a clientless paymethod token (i.e., a paymethod token that is not associated to a customer token).
If you wish to create tokens from swipe data without creating a transaction, include the "action": "authorize" and "authorization_amount": 0.01 parameters in the body of your request.
For service fee transactions, merchants must calculate the fee amount and then include it in the service_fee_amount parameter in the request. To look up your location’s service fee rates/amounts, perform a GET call to the Locations by ID endpoint.
EFT is an Electronic Funds Transfer, encompassing all electronic payments and including ACH (eCheck) payments. This URI can perform the following eCheck (ACH) tasks while returning a new transaction_id:
Create an ad-hoc transaction. Note: if the intent is to authorize and immediately capture the transaction, it is recommended that a sale transaction is sent.
Create a transaction based on the customer token using the default billing address
Create a transaction based on the customer and paymethod tokens using the customer default billing address
Create a transaction based on the paymethod token, which requires the address in the request message
Reverse a sale transaction and create a credit transaction, which requires the transaction_id and authorization_code of the original transaction
This URI can perform the following tasks while returning a new transaction_id:
Create an ad-hoc transaction
Create a transaction based on the customer token using the default billing address
Create a transaction based on the customer and paymethod tokens using the customer default billing address
Create a transaction based on the paymethod token, which requires the address in the request message
Reverse a sale transaction and create a credit transaction, which requires the transaction_id and authorization_code of the original transaction
NOTE: This endpoint does not specify the location of the transaction in the endpoint; rather, the location_id parameter is included in the body of the request.
A sale transaction is used to collect funds from a customer’s debit/credit card or bank account in exchange for goods or services. The sale action creates an authorization request and a capture operation in one step. Use this URI to create a sale transaction by appending the sale action to the end of the URI. You can also create a sale transaction by including the "action"="sale" parameter in the body of a request to the /organizations/{organization_id}/transactions URI.
A credit transaction is used to send funds to a bank account or credit/debit card. Typically, merchants use this action to refund a customer for a returned good or for payroll distributions. This URI creates a credit transaction by appending the credit action to the end of the URI. You can also create a credit transaction by including the "action"="credit" parameter in the body of a request to the /organizations/{organization_id}/transactions URI.
An authorization validates funds and occurs at the time of the transaction–such as when a card is swiped at a point-of-sale terminal. In a matter of seconds, a request is sent on behalf of the merchant and authorizations are approved or declined by the issuing bank. Authorizations ensure that cardholders have sufficient funds/credit limits available to complete the transaction. Forte supports both full and partial authorizations. Authorizations should be performed when the capture of the funds will be initiated later. If the intent is to authorize the transaction and capture the funds immediately, a sale transaction should be sent instead of authorization and capture.
This URI creates an authorize transaction by appending the authorize action to the end of the URI. You can also create an authorize transaction by including the "action"="authorize" parameter in the body of a request to the /organizations/{organization_id}/transactions URI.
Forte Verify is a service that automatically performs pre-authorization checks on EFT account numbers to ensure the account is valid and in good standing. This URI creates a Forte Verify transaction by appending the verify action to the end of the URI. You can also create a Forte Verify transaction by including the "action"="verify" parameter in the body of a request to the /organizations/{organization_id}/transactions URI.
Authenticate is a service that will verify the ownership of bank accounts. This service will verify if the given person/business (identified by the First & Last name or Business Name) is the owner of a given bank account. This URI creates an Authenticate transaction by appending the authenticate action to the end of the URI. You can also create an Authenticate transaction by including the "action"="authenticate" parameter in the body of a request to the /organizations/{organization_id}/transactions URI.
A force transaction captures the funds of an echeck transaction by bypassing verification or authorization functionality. Merchants should verify or authorize force operations prior to performing them. This URI creates a force transaction by appending the force action to the end of the URI. You can also create a force transaction by including the "action"="force" parameter in the body of a request to the /organizations/{organization_id}/transactions URI.
One-time tokens require a Forte.js integration. Forte.js is a script you can add to your payment form that sends sensitive payment data to Forte (instead of the directly to your server) in return for a one-time token. This one-time token keeps sensitive data safe and reduces your Payment Card Industry Data Security Standard (PCI-DSS) obligations and scope. One-time tokens expire after 60 minutes.
Line items require both a line_item_header and a numbered line item field (line_item_1). You can include up to 100 fields of line items (e.g., name, quantity, price, etc.)
You can include up to nine xdata fields. Each field can contain up to 80 characters. NOTE: Values within this field cannot contain double quotation characters (i.e., “text”); Forte supports single quotation characters (i.e., ‘text’). If you require double quotation characters within this value, use HTML escape characters to ensure the information properly displays (e.g., xdata_1="Marco's “Place”").
A reverse (i.e., refund) takes the original charge from a billing account and retracts it (e.g., reversed sales will have a disbursement or credit performed). Forte supports both full and partial reversals. Reversals can be performed on sale transactions that have been settled (credit cards) or funded (echecks). Including the reverse action in the body of your request automatically generates a credit transaction. The original_transaction_id and the authorization_code must also be included in the body of the request.
A reverse (i.e., refund) takes the original charge from a billing account and retracts it (e.g., reversed sales will have a disbursement or credit performed). Forte supports both full and partial reversals. Reverses can be performed on sale transactions that have been settled (credit cards) or funded (echecks). Including the reverse action in the body of your request automatically generates a credit transaction. The original_transaction_id and the authorization_code must also be included in the body of the request.
To narrow your search data using specific criteria, use the following filter parameters:
start_received_date / end_received_date
received_date
origination_date
customer_token
original_transaction_id
customer_id
order_number
reference_id
status
action
authorization_amount
entered_by
bill_to_company_name
bill_to_first_name
bill_to_last_name
paymethod_type
last_4_account_number
response_code
attempt_number
NOTES:
The action filter parameter supports the following values:
sale
credit
authorize
verify
authenticate
inquiry
Searches using the origination_date filter parameter will only yield results for echeck transactions.
To find transactions within a specified date range, use the start_received_date and end_received_date filter parameters or the start_origination_date and end_origination_date filter parameters.
To find transactions from a single day, use the received_date or origination_date (echeck only) filter paramters.
Date range filters must include both the start and end date parameters; otherwise, Forte uses a default 90-day date range from the provided date parameter or, when no date parameter is provided, from the current date.
A void is used to stop a transaction from originating (echecks) or going to settlement (credit cards) and for canceling holds on transactions that were previously authorized. You can only void a transaction once. Only sale, authorize, force (echecks only) or credit transactions in the Ready, Authorized, or Review status can be voided.
This endpoint stops the disbursement of funds back to the consumer after their original transaction was reversed/refunded. You must append the transaction_id of the refund transaction to the end of the endpoint, and include the void action and authorization_code of the refund/reversal transaction in the body of the request.
A capture enables merchants to collect the funds of a previous authorize transaction. A capture must be performed within the authorization/pre-authorization period (i.e., when the status of the transaction is in-progress) for credit card and echeck transactions. This transaction should be used when the capture of the funds will be initiated later. If the intent is to authorize the transaction and capture the funds immediately, a sale transaction should be sent instead of authorization and capture.
NOTE: authorization_amount field (capture amounts) are supported in sandbox environment but in production environment it is dependent on the processor