REST API Endpoints

Robust, Efficient Solutions

Overview

CSG Forte's REST API gives merchants and partners access to powerful payment processing and business management solutions. Use the API to simplify the complexity of payment processing through simple HTTP requests within a PCI-compliant architecture.

To begin, you will need to set up your merchant organization and location. For partner organizations, call the CSG Forte Sales Team to set up a partner organization. Organizations are legal entities that own all the data collected by locations (or for partners, sub-organizations). Locations are the processing endpoints where you initiate transactions. Both organizations and locations are assigned unique, string IDs which are used within the endpoints to identify your CSG Forte account.

After setting up your organization, you'll then need to create your API Access ID and API Secure Key credentials for the Authorization header, which must be included in every call. Additional required headers include the following:

  • X-Forte-Auth-Organization-Id - This is the organization where you are authenticating. For merchants, this value will be your merchant organization ID. For partners, this value will be your partner organization ID. Authenticating at the partner level gives you more permissions.

  • Accept - This header supports both application/json and application/xml.

  • Content Type - This header is only required for POST and PUT requests and supports both application/json and application/xml.

Once you've created these values, you're ready to make your first call. To use the endpoints listed below, you'll need to append them to the Base URI, which indicates the environment and API version of the request. The following table provides the Base URIs available for each version of the API and each environment:

Version Sandbox Live
V2 https://sandbox.forte.net/api/v2 https://api.forte.net/v2
V3 https://sandbox.forte.net/api/v3 https://api.forte.net/v3

For more details on API setup and endpoints, see the REST API reference (v3 (recommended), v2).

Transactions

Use the following endpoints to create, retrieve, and update transactions.

HTTP Method URI Path Description
POST, GET, PUT /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/transactions
  • Creates a new transaction
  • Updates a transaction
  • Retrieves all transactions for a location
POST, GET /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/transactions/sale
  • Creates a sale transaction
  • Retrieves all sale transactions for a location
POST, GET /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/transactions/credit
  • Creates a credit transaction
  • Retrieves all credit transactions for a location
POST, GET /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/transactions/authorize
  • Creates an authorization transaction
  • Retrieves all authorization transactions for a location
POST, GET /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/transactions/verify
POST, GET /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/transactions/force
  • Creates a force transaction (echecks only)
  • Retrieves all force transactions for a location
GET, PUT /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/transactions/trn_{{transactionID}}
  • Retrieves a specific transaction
  • Updates specified transaction

Fundings

Funding endpoints provide insights into an organization's funded transactions. Use them to find specific funding entries or the funding entries related to a specific settlement or transaction. NOTE: These endpoints do not require the location ID to be part of the complete URI.

HTTP Method URI Path Description
GET /organizations/org_{{organizationID}}/fundings Retrieves all funding entries for an organization.
GET /organizations/org_{{organizationID}}/fundings/fnd_{{fundingID}} Retrieves a specific funding entry.
GET /organizations/org_{{organizationID}}/fundings/
fnd_{{fundingID}}/transactions 		Retrieves the transactions associated with a specific funding entry.
GET /organizations/org_{{organizationID}}/fundings/
fnd_{{fundingID}}/settlements 		Retrieves the settlements associated with a specific funding entry.

Settlements

Use these endpoints to retrieve information about settlements for your location or organization.

HTTP Method URI Path Description
GET /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/settlements Retrieves all settlements belonging to a location
GET /organizations/org_{{organizationID}}/settlements Retrieves all settlements belonging to an organization
GET /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/
transactions/trn_{{transactionID}}/settlements 		Retrieves the settlement from the specified transaction

Disputes

Dispute endpoints can retrieve all disputes for an organization or a specific dispute. NOTE: These endpoints do not require the location ID to be part of the complete URI.

HTTP Method URI Path Description
GET /organizations/org_{{organizationID}}/disputes Retrieves all dispute records belonging to an organization.
GET /organizations/org_{{organizationID}}/disputes/dsp_{{disputeID}} Retrieves a specific dispute record.

Documents

Use these endpoints to create, retrieve, or delete supporting documents for new merchant applications or new disputes. Documents cannot be over 8MB. NOTE: These endpoints do not require the location ID to be part of the complete URI.

HTTP Method URI Path Description
POST, GET /organizations/org_{{organizationID}}/documents
  • Uploads an 8MB or less document for either a dispute or application record
  • Retrieves all document records belonging to an organization
GET, DELETE /organizations/org_{{organizationID}}/documents/doc_{{documentID}}
  • Retrieves a specific document
  • Deletes the specified document.

Customers

Use these endpoints to manage your customer data.

HTTP Method URI Path Description
POST, GET /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/customers
  • Creates a customer record
  • Retrieves all customers belonging to a location
POST /customers Creates a locationless customer record. You must include the merchant's organization_id in the body of the request.
GET /organizations/org_{{organizationID}}/customers Retrieves all customer records for an organization.
GET, PUT, DELETE /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/customers/cst_{{customertoken}}
  • Retrieves a specific customer record
  • Updates the specified customer record
  • Deletes the specified customer record
PUT /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/customers/cst_{{customertoken}}/paymethods Updates a customer record with a paymethod.

Payment Methods

The payment method endpoints can create, retrieve, or delete payment methods. Use them to associate payment methods with a specific customer record, create permanent payment method tokens from one-time tokens, or for reporting on Account Updater changes.

HTTP Method URI Path Description
POST, GET /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/customers/cst_{{customertoken}}/paymethods
  • Adds a payment method to a customer record
  • Creates a permanent paymethod token from a one-time token that was created in Forte.js
  • Retrieves all the payment methods associated with a customer
POST /customers/cst_{{customertoken}}/paymethods Adds a payment method to a locationless customer record.
POST, GET /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/paymethods
  • Creates a clientless (i.e., not associated with a customer record) payment method
  • Retrieves all payment methods associated with a location
GET, PUT, DELETE /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/paymethods/mth_{{paymethodtoken}}
  • Retrieves a specific payment method
  • Assigns the specified payment method to a customer record when the customer_token is specified in the request body
  • Suppresses a specific token from an Account Updater run
  • Deletes the specified payment method
GET /organizations/org_{{organizationID}}/paymethods
  • Retrieves all payment methods associated with an organization
  • Retrieves all tokens updated by Account Updater with the filters start_au_updated_date and end_au_updated_date

Schedules

Use these endpoints to manage schedules of recurring payments.

HTTP Method URI Path Description
POST, GET /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/customers/cst_{{customertoken}}/schedules
  • Creates a new schedule
  • Retrieves all schedules for the specified customer
POST, GET /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/schedules
  • Creates a new schedule
  • Retrieves all schedules for a location.
GET, PUT, DELETE /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/schedules/sch_{{scheduleID}}
  • Retrieves a specific schedule, including deleted schedules (using the schedule_status=deleted filter)
  • Updates the specified schedule's status or payment method
  • Deletes the specified schedule.

Schedule Items

These endpoints enable merchants to create, retrieve, update, and delete specific transactions (i.e., schedule items) within a schedule.

HTTP Method URI Path Description
POST /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/schedules/sch_{{scheduleID}}/scheduleitems Creates a new schedule item for the specified schedule
GET /organizations/org_{{organizationID}}/scheduleitems/ Retrieves all schedule items associated with an organization
GET, PUT, DELETE /organizations/org_{{organizationID}}/scheduleitems/sci_{{scheduleitemID}}
  • Retrieves the specified schedule item
  • Updates the specified schedule item
  • Deletes the specified schedule item
GET /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/scheduleitems Retrieves all schedule items associated with a location
GET /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/customers/cst_{{customertoken}}/scheduleitems Retrieves all future schedule items for the specified customer record.
GET /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/paymethods/mth_{{paymethodtoken}}/scheduleitems Retrieves all future schedule items for the specified payment method.

Addresses

Use the address endpoints to manage your organization's address data.

HTTP Method URI Path Description
POST /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/customers/cst_{{customertoken}}/addresses Creates an address record for a specific customer
GET, DELETE /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/addresses/add_{{addresstoken}}
  • Retrieves a specific address record
  • Deletes a specific address record
GET /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/customers/cst_{{customertoken}}/addresses Retrieves a customer's address record(s)
GET /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/addresses Retrieves all address records belonging to a location
GET /organizations/org_{{organizationID}}/addresses Retrieves all address records belonging to an organization.
PUT /organizations/org_{{organizationID}}/locations/loc_{{locationID}}/customers/cst_{{customertoken}}/addresses/add_{{addresstoken}} Updates an address record

Organizations

NOTE: These endpoints are primarily for partners. Organization endpoints retrieve information about merchant organizations.

HTTP Method URI Path Description
GET /organizations Retrieves all organizations below a parent organization.
GET /organizations/org_{{organizationID}} Retrieves a specific organization.

Locations

Use the locations endpoints to retrieve and update location data associated with an organization.

HTTP Method URI Path Description
GET /organizations/org_{{organizationID}}/locations Retrieves all locations associated with an organization.
GET, PUT /organizations/org_{{organizationID}}/locations/loc_{{locationID}}
  • Retrieves a specific location
  • Updates the specified location by either assigning bank accounts, changing processing limits, or changing the address.

Applications

NOTE: These endpoints are for partners only. Use these endpoints to create and retrieve merchant applications.

HTTP Method URI Path Description
POST, GET /organizations/org_{{organizationID}}/applications
  • Creates an application for an organization
  • Retrieves all applications belonging to an organization
GET /organizations/org_{{organizationID}}/applications/app_{{applicationID}} Retrieves a specific application