Web Services v3

Ready. . .Set. . .Integrate.


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:

  1. Contact Forte to obtain an Organization ID and Keys.
  2. Create Your Authentication Headers.
  3. Craft a call.

To begin the integration process, contact Forte Technical Support. Your Forte representative will provision your information to a sandbox account. Once provisioned, Forte will send you the following information for testing:

  • Organization ID
    Your Organization ID represents a legal entity that can own multiple sub-organizations (for Forte Resellers) or multiple locations (for Forte 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.

  • Location ID
    Locations are processing endpoints that merchant organizations use to initiate transactions. Locations own all the transaction data including sensitive payment method data and tokens. NOTE: The Location ID represents the same information as the Merchant ID in the Virtual Terminal.

  • API Access ID
    Use your API Access ID as a username for authentication.

  • API Secure Key
    Use your API Secure Key as a password for authentication.

Requests to Forte's REST API must be authenticated using the Authorization header field and the custom header property, X-Forte-Auth-Organization-Id.

The Authorization Header

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 Authorizationheader. For example, the Authorization header field for a user with username Gozer_the_Gozerian and password ZuultheGatekeeper would look like the following:

Authorization: Basic R296ZXJfdGhlX0dvemVyaWFuOlp1dWx0aGVHYXRla2VlcGVy

 

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:

Convert.ToBase64String(Encoding.Default.GetBytes(APIAccessID + ":" + APISecureKey)).Trim()

 

The X-Forte-Auth-Organization-Id Header

The custom header property X-Forte-Auth-Organization-Id specifies at which organization Forte should authenticate the request. A Forte Reseller 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 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.

 

Request/Response Formatting

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. Forte’s REST API does not support cross-origin resource sharing (CORS).

 

Base URI

When constructing a call, append the resource endpoint to the following base URIs in the specified environments:

URI Environment
https://sandbox.forte.net/api/v3 Sandbox
Contact Forte Technical Support Production

 

For example, to find a specific customer in Sandbox, you would append the customer endpoint /organizations/{organization_id}/locations/{location_id}/customers/{customer_token} to the base URI https://sandbox.forte.net/api/v3 and perform a GET call. The complete URI https://sandbox.forte.net/api/v3/organizations/{organization_id}/locations/{location_id}/customers/{customer_token} will return all the customer data attached to that customer's token.

 

ID Formatting

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
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
applications app_+ ID app_258741

 

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 POSTcall to the transaction endpoint (e.g.,https://sandbox.forte.net/api/v3/organizations/{organization_id}/locations/{location_id}/transactions) creates a new transaction.
Find GET

Returns summary information for all the resources that match the provided query parameters. For example, performing a GETcall to the customersendpoint (e.g.,https://sandbox.forte.net/api/v3/organizations/{organization_id}/locations/{location_id}/customers)
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 endpoint. For example, to find a specific customer associated with a merchant location, perform a GETcall to the customersendpoint and include the customer_token parameter in the endpoint URL (e.g.,https://sandbox.forte.net/api/v3/organizations/{organization_id}/locations/{location_id}/
customers/cst_6cHpUhBG_02bIb4SXxOm5A
)

Update PUT Modifies the existing resource for the provided endpoint. All PUT calls require the resource’s ID.
Delete DELETE Deletes the existing resource for the provided endpoint. 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. NOTE: Some resources (e.g., transactions and settlements) may have additional filter parameters that you can use to narrow down your search results.

Parameter Description Example
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
/settlements?filter=start_settle_date+eq+
%272014-1120%27&orderby=settle_date+desc&
page_size=2&page_index=0
page_size
  • Sets the number of records returned in a page during a search request
  • Accepts values between 50 and 1000
  • If no value is defined, this parameter uses the default value of 50
  • The maximum value of 1000 is used for any values greater than 1000
/transactions/?filter=bill_to_companyname
+eq+%27ACME%27&orderby=received_date+desc&
page_size=1000&page_index=3
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
/paymethods/?filter=card_type+eq+
%27visa%27&orderby=name_on_cardasc&
page_size=50&page_index=0

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.

 

Forte includes the applicable parameters of the responseobject in all response calls returned to the client that made the request. The following table displays the responseobject and the parameters returned for each resource request.

Response Object

Parameter Description
response_desc A short description of the action's response. All resources use this parameter.
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.
authorization_code The code indicating whether or not the transaction was authorized. This field is not used for voiding transactions
response_type The type of response this action generated.
response_code The response code of the action.
preauth_result The result of the pre-authorization attempt on the transaction.
preauth_desc A short description of the transaction's pre-authorization attempt.
preauth_neg_report Indicates whether the pre-authorization attempt contains a negative report.
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 the Sandbox environment, see the testing parameters
in the FAQ 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 properly functioning.

  • 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.
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
available_card_balance The available balance on the credit card if a credit card is used for the transaction.
requested_amount The transaction amount

 

Hypermedia

Forte’s REST API returns the following format for hypermedia responses. Result availability depends on the resource/action in the request. NOTE: The following sample of hypermedia responses are merely formatting examples provided for reference.

{
   "links": {
     "self":"/customers?page_index=1",
     "prev":"/customers?page_index=0",
     "next":"/customers?page_index=2",
     "paymethod":"/customers/cst_SoGUG6mcLUS1nVzYBIbk3g/paymethods",
     "transactions":"/customers/cst_SoGUG6mcLUS1nVzYBIbk3g/transactions",
     "addresses":"/customers/cst_SoGUG6mcLUS1nVzYBIbk3g/addresses",
   }
}

 

Status Codes

Forte's web services uses 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.
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:

{
    message: "Authentication Organization ID in header is missing or invalid."
}

 

{
    message: "Payment Method's routing number length is invalid."
}

 

Understanding Webhooks

NOTE: Currently, Forte IT must configure 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. NOTE: 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:

  • transaction.sale
  • transaction.authorize
  • transaction.credit
  • transaction.void
  • transaction.capture
  • transaction.inquiry
  • transaction.verify
  • customer.create
  • customer.update
  • customer.delete
  • paymethod.create
  • paymethod.update
  • paymethod.delete
  • schedule.create
  • schedule.update
  • schedule.delete
  • scheduleitem.create
  • scheduleitem.update
  • scheduleitem.delete

 

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.

For more information on Webhooks, see Using Webhooks.

 

Testing

To help you gain a greater understanding of how Forte's REST API works, we've built a Postman collection of sample REST requests based on the examples displayed for each request type in each resource section below. To import the collection of requests and really dig into Forte's robust version 3 REST API, simple click:

 


Transactions

The transaction object captures all the transaction(s) associated with a merchant location. The transaction 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 transaction object..

Schedules

The schedule 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. Scheduled transactions can only be created with customer_token and paymethod_token parameters.

Scheduleitems

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.

Settlements

The settlement 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.

Customers

The customer object represents a customer's information and enables the merchant to create, maintain, and retrieve customer data that can be tokenized for a more efficient checkout process. The customer object includes the address and paymethod sub-objects.

Addresses

The address object represents the customer's billing and/or shipping addresses and includes the physical_address sub-object.

Paymethods

The paymethod 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 your own 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.

 


Create and maintain customer transaction data with the transaction object, which includes the following input parameters and sub-objects.

 

Transaction Object

Parameter Description Type Req
organization_id The identification number of the associated organization. For example, org_5551236. string R
location_id The merchant's six-digit ID code. 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.

  • authorize - Used to verify the specified account information (bank account or debit/credit card account).

  • credit - Used to send funds 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.

  • 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 transaction if it’s too late to void that transaction. Reversed sales will have a credit performed. Credits will have a sale.
string R
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 paymethod object or a paymethod_token) if the customer has defined a default_paymethod_token in the customerobject.
[max length = 26]

string O
customer_id A merchant-defined string created at the customer level to identify the customer. 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. 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. string O
original_transaction_id The trace number returned by the original transaction. 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. string O
entered_by The name or the ID of the person entering the data. 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
service_fee_amount

The service fee (i.e., convenience fee) for this transaction. Use the following definitions when calculating a service fee

  • Original Amount = The base amount for calculating the convenience fee

  • service_fee_amount = The percentage calculated

  • authorization_amount = The resulting sum of the Original Amount and the service_fee_amount

 

For a service fee of 2.45% for example, you will need to follow the scenario below:

service_fee_amount = original amount * 2.45%

authorization_amount = service_fee_amount + Original Amount

The Create Transaction - Credit Card code sample provides an example of a service fee calculation.

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
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 = 50]. 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 = 50]. 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 = 50]. 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." string O
billing_address.address_type

The type of address. Use one of the following values:

  1. default_billing - the default billing address

  2. none - the address is not a default address

  3. 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_address.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.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 = 50]. 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 = 50]. 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 = 50]. 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:

  1. default_shipping - the default shipping address

  2. none - the address is not a default address

  3. both - the address is both a default shipping and 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.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 = 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 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.account_number The card number. This field is required when creating a new record and can only contain digits. [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. 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.customer_accounting_code Lists the procurement card accounting code, which is used for Level 2 data. Forte does not save this information if the merchant is creating a paymethod. string O
card.one_time_token A single use token generated by Forte.js (e.g., ott_g7vnjqikszabzynu6eowbq). string O
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 O
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. 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:
  1. Checking

  2. Savings
string O
echeck.item_description Check number or other description of item to processed. NOTE: This field is only available for 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

string O
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-100 Contents of the line item formatted according to the line_item_header. string O
xdata The xdata 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

 

Find Transactions

Use the following endpoints to find transactions.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/transactions

Returns all transactions for a location. Use the following filters to narrow down your search results. NOTE: Searches using origination_date filters will only yield results for echeck transactions.

  • To find transactions within a specified date range: start_received_date, end_received_date, start_origination_date (echeck transactions only), end_origination_date (echeck transactions only)

  • To find transactions from a single day:
    received_date, origination_date (echeck transactions only)

  • first_name, last_name, company_name

  • status

  • authorization_amount

  • order_number

  • entered_by

 

NOTE: Date range filters must include both the start and end date parameters; otherwise, the system uses a default 90-day date range from the provided date parameter or, when no date parameter is provided, from the current date.

/organizations/{organization_id}/locations/{location_id}/transactions/{action}

Returns the following transactions types (actions) for a location:

  • sale

  • credit

  • authorize

  • verify

  • inquiry
/organizations/{organization_id}/locations/{location_id}/transactions/{transaction_id} Returns transaction object detail
/organizations/{organization_id}/locations/{location_id}/customers/{customer_token}/transactions Returns all transactions for a customer

 

The following code samples display example endpoints and GET calls you can use to find a transaction.

 

Example - Find Transactions

 

Create Transactions

Use the following endpoints to create transactions.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/transactions

This endpoint 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 message

  • Reverse a sale transaction and create a credit transaction, which requires the transaction ID and authorization code of the original transaction
/organizations/{organization_id}/transactions This endpoint can perform the same tasks listed above; however, the data that the user passes in must specify a location_id. For example, if the user was creating an ad-hoc transaction, he or she would also need to pass in the location_id parameter.
/organizations/{organization_id}/locations/{location_id}/transactions/{action}

Creates the following transactions types (actions) for a location:

  • sale

  • credit

  • authorize

  • verify

  • inquiry

  • force

 

The following code samples display example endpoints and POST calls you can use to create a transaction.

Example - Create Transactions

 

Update Transactions

Use the following endpoints to update a transaction.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/transactions/{transaction_id}

Updates the Transaction and returns a new transaction_id

/organizations/{organization_id}/locations/{location_id}/transactions/{transaction_id}/{action}

Updates the following Transactions types (actions) for a Location:

  • void

  • capture

 

The following code samples display example endpoints and PUT calls you can use to update a transaction.

 

Example - Void Transactions

 

Find, create, and update scheduled transactions with the schedule object using the following input parameters and code samples.

 

Schedule 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. 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. integer R
schedule_frequency

Indicates the frequency of the scheduled transactions. The supported values for this field include the following:

  • one_time_future

  • weekly

  • bi_weekly

  • monthly

  • bi_monthly

  • quarterly

  • semi_annually

  • annually
string R
schedule_amount Indicates the amount of the recurring payment. The value of this parameter depends on the value in the schedule_frequency parameter. decimal O
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.

datetime O
schedule_created_date The date the schedule was created. datetime O
customer_acct_code The customer accounting code. This field only applies to credit card transactions. string O
sec_code The Standard Entry Class code for the transaction. This field only applies to echeck transactions. string O
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. string O
reference_id A merchant-defined string that identifies the transaction. string O
order_number A merchant-assigned ID code that is returned with the transaction response. string O
customer_id A merchant-defined string created at the customer level to identify the customer. string O
summary The summary object. object O
summary.schedule_next_date The next date when a scheduled transaction will be processed. datetime O
summary.schedule_next_amount The amount of the next scheduled transaction that will be processed. decimal O
summary.schedule_successful_amount The total amount of the successful transactions for this schedule. decimal O
summary.schedule_successful_quantity The total number of successful transactions for this schedule. integer O
summary.schedule_failed_amount The total amount of failed transactions for this schedule. decimal O
summary.schedule_failed_quantity The total number of failed transactions for this schedule. integer O
summary.scheduled_remaining_amount The total amount of the remaining transactions for this schedule. decimal O
summary.scheduled_remaining_quantity The total number of the remaining transactions for this schedule. integer O
summary.scheduled_suspended_amount The total amount of the suspended transactions for this schedule. decimal O
summary.scheduled_suspended_quantity The total number of suspended transactions for this schedule. integer 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

 

Find Schedules

Use the following endpoints to find a schedule.

Endpoint Description
/organizations/{organization_id}/schedules

This endpoint returns all schedules for an organization.

/organizations/{organization_id}/locations/{location_id}/schedules This endpoint returns all schedules for a location.
/organizations/{organization_id}/locations/{location_id}/customers/{customer_token}/schedules This endpoint returns all schedules associated with a particular customer.
/organizations/{organization_id}/locations/{location_id}/schedules/{schedule_id} This endpoint returns a specific schedule, including schedule summary data that can be used to quickly find useful schedule information.

 

The following code samples display example endpoints and GET calls you can use to find a schedule.

 

Example - Find Schedules

 

Create Schedules

Use the following endpoints to create a schedule.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/schedules 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.
/organizations/{organization_id}/locations/{location_id}/customers/{customer_token}/schedules Creates a new schedule and returns a new unique schedule_id for the customer. NOTE: The paymethod_token must be specified in the request.

 

The following code samples display example endpoints and POST calls you can use to find a schedule.

 

Example - Create Schedules

 

Update Schedules

Use the following endpoints to update a schedule's status or paymethod_token.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/schedules/{schedule_id} Updates the schedule definition's status and/or paymethod token. NOTE: When updating a schedule definition from suspended to active status, the scheduleitems associated with that schedule definition must be individually updated to ensure the scheduled transactions occur.

 

The following code samples display example endpoints and PUT calls you can use to update a schedule definition.

 

Example - Update Schedules

 

Delete Schedules

Use the following endpoint to delete a schedule.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/schedules/{schedule_id} Deletes the specified schedule. When deleting a schedule, all scheduleitems are also deleted.

 

The following code samples display example endpoints and DELETE calls you can use to delete a schedule.

 

Example - Delete Schedules

 

Find, create, and update individual future transactions with the scheduleitems object using the following input parameters and code samples.

 

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. 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. string O
schedule_id

A unique string used to represent a schedule. For example, sch_2e5770ae-c120-414f-ae8c-d065753567e7.

string R
schedule_item_amount Indicates the amount of the scheduled item. 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. datetime R
schedule_item_processed_date

Indicates the date when the scheduled item will be processed.

datetime O
schedule_item_created_date Indicates the date when the merchant created the scheduled item. datetime O
schedule_item_description A brief description of the scheduled item being processed. string O

 

Find Scheduleitems

Use the following endpoint to find a scheduleitems.

Endpoint Description
/organizations/{organization_id}/scheduleitems

This endpoint returns all scheduleitems for an
organization. This endpoint can
be filtered by schedule_item_date (e.g.,
/organizations{organization_id}/
schedulesitems?filter=start_schedule_item_date
eq'YYYY-MM-DD'and end_schedule_item_date
eq 'YYYY-MM-DD'
)

/organizations/{organization_id}/locations/{location_id}/scheduleitems This endpoint returns all scheduleitems for a location.
This endpoint can
be filtered by schedule_item_date
(e.g./organizations{organization_id}/locations
/{location_id}/schedulesitems?
filter=start_schedule_item_date
eq'YYYY-MM-DD'and end_schedule_item_date
eq 'YYYY-MM-DD'
)

/organizations/{organization_id}/locations/{location_id}/paymethods/{paymethod_token}/scheduleitems

This endpoint returns all future scheduleitems for a
particular customer or paymethod. These endpoints
can be filtered by schedule_item_date
(e.g., /organizations/{organization_id}/locations
/{location_id}/customers/{customer_token}
/schedulesitems?filter=start_
schedule_item_date eq 'YYYY-MM-DD'
and end_schedule_item_date
eq 'YYYY-MM-DD'
or
/organizations/{organization_id}/locations/
{location_id}/paymethods/{paymethod_token}
/schedulesitems?filter=start_schedule_item_date
eq 'YYYY-MM-DD' and end_schedule_item_date
eq 'YYYY-MM-DD'
)
/organizations/{organization_id}/scheduleitems/{schedule_item_id} This endpoint returns a specific scheduleitem.

The following code samples display example endpoints and GET calls you can use to find a scheduleitem.

 

Example - Find Scheduleitems

 

Create Scheduleitems

Use the following endpoint to create a scheduleitems.

Endpoint Description
/organizations/{organization_id}/location/{location_id}/schedules/{schedule_id}/scheduleitems/

This endpoint 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.

The following code samples display example endpoints and POST calls you can use to create a scheduleitem.

 

Example - Create Scheduleitems

 

Update Scheduleitems

Use the following endpoint to create a scheduleitems.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/scheduleitems/{schedule_item_id}

This endpoint updates the specified scheduleitem. Only scheduleitems with a future date value in the schedule_item_date field and a status of scheduledor suspendedin 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 following code sample displays an example endpoint and PUT call you can use to update a scheduleitem.

 

Example - Update the Amount of a Scheduleitem

 

Delete Scheduleitems

Use the following endpoint to delete a scheduleitem.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/scheduleitems/{schedule_item_id}

This endpoint deletes the specified scheduleitem. Deleting a scheduleitem will not delete the schedule definition.

The following code sample displays an example endpoint and DELETE call you can use to delete a scheduleitem.

 

Example - Delete Scheduleitems

 

Find transaction settlement data with the settlement object using the following input parameters and code samples. Use the settle_date, settle_response_code, and method fields to filter your data.

 

Settlement 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 O
customer_id A merchant-defined string created at the customer level to identify the customer. string O
order_number A merchant-defined string. string O
reference_id A merchant-defined string that identifies the transaction. string O
settle_id The settlement ID of the settled transaction (e.g., stl_51cf4633-1767-484f-8784-be76a4076791) string R
transaction_id A 36-character code that uniquely identifies the transaction. string O
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 O
settle_date The date when the transaction was settled. datetime O
settle_type

The type of settlement. Supported settlement types include the following values.

For echeck transactions:

  • deposit

  • reject

  • withdrawal

 

For credit card transactions:

  • deposit

  • withdrawal

 

string O
settle_response_code See the Response Codes table for more information. NOTE: Credit card transactions that do not return a settle response can be considered settled. string O
settle_amount

The amount the transaction settled for.

decimal O
method

The payment method. The supported payment methods include the following values:

  • echeck

  • cc
string O

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.

 

Find Settlements

Use the following endpoint to find a settlement.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/settlements

This endpoint returns all the transaction settlements for a Location.

To narrow this data to a specific time frame, settlement type, response code, or settlement amount, use the following parameters to filter your results:

Filter Parameter Example
settle_date* /organizations/{organization_id}/locations/{location_id}/settlements/?filter=start_settle_date+eq+
'2002-01-08'+and+end_settle_date+eq+'2013-12-08'
settle_response_code /organizations/{organization_id}/locations/{location_id}/settlements/?filter=settle_response_code+eq+'R21'
method /organizations/{organization_id}/locations/{location_id}/settlements/?filter=method+eq+'cc'

 

NOTE: If both the start_settle_date and end_settle_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.

 

The following code samples display example endpoints and GET calls you can use to find a settlement.

 

Example - Find Settlements

 

Create, maintain, and delete customer data with the customer object using the following input parameters and code samples.

 

Customer 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 O
customer_id A merchant-defined string created at the customer level to identify the customer. string O
default_paymethod_token The customer's default paymethod token. The system returns this token when creating a customer with a paymethod. 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. 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. string O
status Use one of the following values:
  1. active

  2. suspended
string O
first_name

The first name of the customer. [max length = 50]

string R
last_name

The last name of the customer. [max length = 50]

string R
company_name

The company name of the customer. [max length = 50]

  O
paymethod The Paymethod Object object O
paymethod.organization_id 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. [max length = 26]

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.

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. 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 cardobject and the sales_tax_amount field in the transactionobject. string O
paymethod.card.customer_accounting_code Lists the procurement card accounting code, which is used for Level 2 data. Forte does not save this information if the merchant is creating a paymethod. string O
paymethod.card.one_time_token A single use token generated by Forte.js (e.g., ott_g7vnjqikszabzynu6eowbq). string O
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. string O
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. 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 O
paymethod.echeck.account_type Use one of the following values for this parameter:
  1. checking

  2. 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. string O
addresses An array of Address Objects object O
addresses.address_token A unique string used to represent an address. For example, add_tq0hemmmtf-zsxgq689rew. string R
addresses.customer_token A unique string used to represent a customer. For example, cst_SoGUG6mcLUS1nVzYBIbk3g. 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 = 50]. NOTE: The first_name and last_name parameters are required for billing addresses when creating transactions without tokens. string R
addresses.last_name The last name of the user associated with this billing or shipping address [max length = 50]. NOTE: The first_name and last_name parameters are required for billing addresses when creating transactions without tokens. string R
addresses.company_name The name of the company associated with this billing or shipping address [max length = 50]. 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." string O
addresses.address_type

The type of address. Use one of the following values:

  1. default_billing - the default billing address

  2. default_shipping - the default shipping address

  3. none - the address is not a default address

  4. both- the address is both a default shipping and 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

O

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. string O

 

Find Customers

Use the following endpoints to find a customer within a specific location.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/customers This endpoint returns all the customers for a location.
/organizations/{organization_id}/locations/{location_id}/customers/{customer_token} This endpoint returns all the default information of a specific customer.

 

The following code samples display example endpoints and GET calls you can use to find a customer.

 

Example - Find Customers

Create Customers

Use the following endpoints to create a customer under a specific location.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/customers

This endpoint can perform the following tasks 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:

  • Create a customer with first and last name only

  • Create a customer with billing and shipping addresses

  • Create a customer with a paymethod

  • Create a customer with a billing/shipping address and a paymethod
/organizations/{organization_id}/customers This endpoint can perform the same tasks listed above; however, the data that the user passes in must specify a location_id. For example, if the user was creating a customer with a payment method, he or she would also need to pass in the location_id parameter.

 

The following code samples display example endpoints and POST calls you can use to create a customer.

 

Example - Create Customers

 

Update Customers

Use the following endpoint to update a customer.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/customers/{customer_token}

This endpoint can perform the following tasks while returning the customer_token:

  • Change a customer's status

  • Change the default billing and/or shipping address

  • Change the 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.

 

The following code samples display example endpoints and PUT calls you can use to update a customer record.

 

Example - Update Customers

 

Delete Customers

Use the following endpoint to delete a customer. NOTE: A customer cannot be deleted if he or she is tied to an active schedule.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/customers/{customer_token} This endpoint deletes the specified customer record.

 

The following code samples display example endpoints and DELETE calls you can use to delete a customer record.

 

Example - Delete Customers

 

Create, maintain, and delete customer address data with the address object using the following input parameters and code samples. 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.

 

Address Object

Parameter Description Type Req
address_token A unique string used to represent an address. For example, add_tq0hemmmtf-zsxgq689rew. string R
customer_token A unique string used to represent a customer. For example, cst_SoGUG6mcLUS1nVzYBIbk3g. string R
orgnization_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 = 50]. NOTE: The first_name and last_name parameters are required for billing addresses when creating transactions without tokens. string R
last_name The last name of the user associated with this billing or shipping address [max length = 50]. NOTE: The first_name and last_name parameters are required for billing addresses when creating transactions without tokens. string R
company_name The name of the company associated with this billing or shipping address [max length = 50]. NOTE: The company_name parameter is required for billing addresses when creating transactions without tokens. string R
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." string O
address_type

The type of address. Use one of the following values:

  1. default_billing - the default billing address

  2. default_shipping - the default shipping address

  3. none - the address is not a default address

  4. 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. This field supports both U.S. and Canadian regions. [max length = 2] string O
physical_address.postal_code Postal Code [max length = 15]. This field supports both U.S. and Canadian postal codes. string O

 

Find Addresses

Use the following endpoints to find an address.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/customers/{customer_token}/addresses/ Returns all Address(es) for a Customer
/organizations/{organization_id}/locations/{location_id}/customers/{customer_token}/addresses/{address_token} Returns Address object detail

 

The following code samples display example endpoint and GET calls you can use to find a customer address.

 

Example - Find Addresses

 

Create Addresses

Use the following endpoint to create an address.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/customers/{customer_token}/addresses/ Creates a new Address for the Customer and returns a new address_token.
/organizations/{organization_id}/customers/{customer_token}/addresses/ This endpoint also creates a new address for the specified customer; however, the data that the user passes in must specify a Location ID. For example, if the user was creating an address, he or she would also need to pass in the location_id field.

 

The following code samples display example endpoints and POST calls you can use to create an address.

 

Example - Create Addresses

 

Update Addresses

Use the following endpoint to update an address.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/customers/{customer_token}/addresses/{address_token} Updates the specified address.

 

The following code samples display example endpoints and PUT calls you can use to create an address.

 

Example - Update Addresses

 

Delete Addresses

Use the following endpoint to delete an address.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/customers/{customer_token}/addresses/{address_token} This endpoint deletes the specified address.

 

The following code samples display example endpoints and DELETE calls you can use to delete an address.

 

Example - Delete Addresses

 

Create, maintain, and delete customer payment data with the paymethod object using the following input parameters and code samples.

 

Paymethod 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]

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.

string O
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
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.account_number The card number. This field is required when creating a new record and can only contain digits
[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. string O
card.procurement_card Indicates whether or not this is a procurement card transaction. Accepted values are either trueor false. For procurement card transactions, merchants must pass the customer_accounting_code field in the cardobject and the sales_tax_amount field in the transactionobject. string O
card.one_time_token A single use token generated by Forte.js (e.g., ott_g7vnjqikszabzynu6eowbq) string O
card.customer_accounting_code Lists the procurement card accounting code, which is used for Level 2 data. Forte does not save this information if the merchant is creating a paymethod. 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

 

This paramater is return only. 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 paramater is return only. 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"

 

This paramater is return only.

string 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. string O
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. 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:
  1. Checking

  2. 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 O
echeck.one_time_token A single use token generated by Forte.js (e.g., ott_g7vnjqikszabzynu6eowbq) string O
notes A short description of the paymethod. string O

 

Find Paymethods

Use the following endpoints to find paymethods.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/paymethods/{paymethod_token} Returns a Paymethod object detail
/organizations/{organization_id}/locations/{location_id}/paymethods Returns all Paymethods for a Location
/organizations/{organization_id}/locations/{location_id}/customers/{customer_token}/paymethods Returns all Paymethods for a Customer
/organizations/{organization_id}/paymethods

Returns all Paymethods for a Organization. Account Updater customers use this endpoint to view the payment tokens that were updated in 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.

 

The following code samples display example endpoints and GETcalls you can use to find a paymethod.

 

Example - Find Paymethods

 

Create Paymethods

Use the following endpoint to create paymethods.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/paymethods

This endpoint can perform the following tasks while returning a new paymethod_token:

  • Create Paymethod credit card or echeck information only

  • Create a Paymethod token using a one-time token
    NOTE: At this time, one-time tokens cannot be used to create organization-level paymethod tokens.

  • Create a Paymethod with the billing address
/organizations/{organization_id}/paymethods This endpoint can perform the same tasks listed above; however, the data that the user passes in must specify a location_id. For example, if the user was creating a paymethod with only credit card information, he or she would also need to pass in the location_id field.
/organizations/{organization_id}/locations/{location_id}/customers/{customer_token}/paymethods Creates a new paymethod for the customer and returns a paymethod_token. A permanent paymethod token can be created from a one-time token.

 

The following code samples display example endpoints and POST calls you can use to create a paymethod.

 

Example - Create Paymethods

 

Update Paymethods

Use the following endpoint to update paymethods.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/paymethods/{paymethod_token} Updates the specified paymethod.

 

The following code samples display example endpoints and PUTcalls you can use to update a paymethod.

 

Example - Update Paymethods

 

Delete Paymethods

Use the following endpoint to delete paymethods. NOTE: A paymethod cannot be deleted if it is tied to an active schedule.

Endpoint Description
/organizations/{organization_id}/locations/{location_id}/paymethods/{paymethod_token} Deletes the specified paymethod

 

The following code samples display example endpoints and DELETEcalls you can use to delete a paymethod.

 

Example - Delete Paymethod

 

NOTE: Only Forte re-seller organizations can use the application object endpoint.

Create merchant applications with the application object using the following parameters and code samples.

 

Application Object

Parameter Description Type Req
fee_id The ID of the rate plan, which details the fee values that Forte will charge the merchant. string R
source_ip The IP Address from which the merchant is applying. string R
annual_volume

The anticipated annual volume of the business.

double R
average_transaction_amount The average transaction amount of the business. NOTE: When testing in the Sandbox environment, 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 Sandbox. 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. string R
t_and_c_time_stamp

The date and/or timestamp when the merchant agreed to Forte's Terms and Conditions. NOTE: The value of this field can be up to one full day in the future. The following formats are supported:

  • YYYY/MM/DD, MM/DD/YYYY

  • YYYY-MM-DDTHH:MM:SSZ, YYYYMM-DDTHH:MM:SS
datetime R
applicant_organization The applicant_organization object. object R
applicant_organization.legal_name The legal name of the business. The value of this parameter must match the customer's Tax ID Number. [max length = 50]. string R
applicant_organization.tax_id_number

The Tax ID Number of the business (e.g., TIN, EIN, SSN, etc.). The following formats are supported [max length = 30]:

  • SSN = XXXXXXXXX, XXX-XX-XXXX

  • ITIN = 9XXXXXXXX, 9XX-XX-XXXX

  • EIN = XXXXXXXXX, XX-XXXXXXX
string R
applicant_organization.legal_structure

The ownership type of the business. Options for this parameter include the following values:

  • c_corporation

  • government

  • limited_liability_corporation

  • other

  • partnership_general_or_limited

  • publicly_held_corporation

  • s_corporation

  • sole_proprietorship

  • tax_exempt_or_non_profit_organization
string R
applicant_organization.dba_name 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.street_address1 The physical address of the business. This parameter cannot contain P.O. boxes.
[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] string R
applicant_organization.business_type The type of business. [max length = 50] string R
applicant_organization.bank_routing_number The routing number (i.e., TRN) of the business' bank. The value of this parameter must be nine digits. string R
applicant_organization.bank_account_number The account number (i.e., DDA) of the business' bank. The value of this parameter can only contain digits. string R
owner The owner object. object 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.email_address The business email of the account owner. The value in 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

 

Create Applications

Use the following endpoint to create applications. NOTE: Only Forte re-seller organizations can use the application object endpoint.

Endpoint Description
/organizations/{organization_id}/applications

This endpoint creates the merchant application, routes the information to Forte's Underwriting and decisioning queues, and returns one of the following status codes:

  • approved

  • pending

NOTE: The organization_id referenced in this endpoint must be the home_organization_id of the Reseller.

 

The following code sample displays an example endpoint and POST call you can use to create an application.


Example - Create Applications

Request

curl -X POST 
    -H "Content-Type: application/json" 
    -H "X-Forte-Auth-Organization-Id: org_300005" 
    -H "Authorization: Basic {encoded APIAccessID:APISecureKey string}"
    -H "Cache-Control: no-cache" -d '{
       "fee_id": 14081,
       "source_ip":"55.5.55.555",
       "annual_volume":"100000", 
       "average_transaction_amount": "10000",
       "market_type":"internet",
       "t_and_c_version" : "Tc1",
       "t_and_c_time_stamp": "4/3/2016",
       "applicant_organization": {
          "legal_name":"George McFly Enterprises",
          "tax_id_number":"123456789",
          "legal_structure":"sole_proprietorship",
          "dba_name":"GMF Enterprises",
          "street_address1":"503 DeLorean Way",
          "locality":"Hill Valley",
          "region":"CA",
          "postal_code":"95420-4344",
          "customer_service_phone":"5555236987",
          "website":"www.GMFEnterprises.com",
          "business_type":"2741",
          "bank_routing_number":"211170101",
          "bank_account_number":"121245611"
       },
       "owner": {
          "first_name":"George",
          "last_name":"McFly",
          "street_address1":"49 Great Scott! Drive",
          "locality":"Hill Valley", 
          "region":"CA",
          "postal_code":"95420-4345",
          "email_address":"george.mcfly@GMFEnterprises.com",
          "mobile_phone":"5555698965",
          "last4_ssn":"6789",
          "date_of_birth":"3/3/1938"
       }
}' "/organizations/org_300005/applications"

 

Response

{
    "application_id":"app_109630",
    "status":"approved",
    "fee_id":"14081",
    "source_ip":"55.5.55.555",
    "annual_volume":"100000", 
    "average_transaction_amount": "10000",
    "market_type":"internet",
    "t_and_c_version" : "Tc1",
    "t_and_c_time_stamp": "4/3/2016",
    "applicant_organization": {
       "legal_name":"George McFly Enterprises",
       "tax_id_number":"123456789",
       "legal_structure":"sole_proprietorship",
       "dba_name":"GMF Enterprises",
       "street_address1":"503 DeLorean Way",
       "locality":"Hill Valley",
       "region":"CA",
       "postal_code":"95420-4344",
       "customer_service_phone":"5555236987",
       "website":"www.GMFEnterprises.com",
       "business_type":"2741",
       "bank_routing_number":"211170101"
    },
    "owner": {
       "first_name":"George",
       "last_name":"McFly",
       "street_address1":"49 Great Scott! Drive",
       "locality":"Hill Valley", 
       "region":"CA",
       "postal_code":"95420-4345",
       "email_address":"george.mcfly@GMFEnterprises.com",
       "mobile_phone":"5555698965",
       "date_of_birth":"3/3/1938"
    }
    "response": {
       "environment":"live",
       "response_desc":"Application submitted has been approved."
    },
    "links": {
       "self":"/v3/applications/app_109630"
    }
}

 

Change Log

Release Updates
1.19

Version 3 of Forte's REST API includes the following parameter updates:

  • The echeck.check_number parameter in the transactionobject was changed to echeck.item_description.

  • The disburse action in the transaction and schedule objects was changed to credit.

  • The account_id parameter is now the organization_id in all objects, routes, authentication headers, and object prefixes.

  • The cvv_code parameter in the response object and webhooks was changed to cvv_result.

  • The payment webhook events were changed to paymethod webhook events.`
1.20
  • Added the transactions_id of completed scheduled transactions to the scheduleitems object.

  • Added the recurring_indicator parameter to the transaction object for merchants who want to flag a transaction as recurring, which may have an impact on their Interchange rates.

  • Forte's REST API now supports ad-hoc one-time token transactions from echeck paymethods. Both echeck and credit card one-time tokens can also be converted to permanent paymethod tokens using Forte's REST services.

  • Added support for Account Updater services including:

    • The suppress_account_updater flag that enables merchants to exclude tokens from being automatically included in their monthly Account Updater services

    • A filterable GET request to the paymethods endpoint that enables merchants to see what card tokens were updated within a specified date range

1.21
  • Updated Merchant Application T&C Timestamp validation to allow users to set the date up to one day in the future.

  • Updated all resource GET responses to include page_size and page_index default values when the user does not specify a filter value in the request.

  • Reverse Transactions now include the customer_id parameter, if defined.