Set Up a REST API Integration

Quick, efficient integration

Integrating with CSG Forte's REST API takes only a few simple steps. Once you're connected, you will have access to a robust payment processing solution that provides efficient access to your business' data.

Your Sandbox account gives you the ability to create testing credentials, which you will need for authenticating test calls. The process of creating a Sandbox account differs between merchants and partners.

Merchant Process

If you are a merchant, navigate to the Forte Developer's Test Account sign-up page and enter your First Name, Last Name, Company Name, and Email address in the applicable fields. Forte uses this email address for verification purposes and as your Username for registering and signing into Dex, Forte's newest payment processing portal where you will create your credentials for this testing account.

Partner Process

If you are a partner, contact Forte's Sales Team and request a partner Sandbox account. Partner accounts in Dex have different permissions and different menu options.

Verification and Registration

After requesting a Sandbox account, you will receive three emails: one from Forte Sales and two more from Dex. In the Dex email, "Verify Email," click the Verify Email Address button. Emails must be verified within 24 hours. After verifying your email address, open the Dex email, "You are invited to join Dex." Click the Accept Invitation button. A browser window opens where you can register for your Dex account. Dex registration requires a mobile phone number that can receive SMS messages for account verification.

Once you complete registration, Dex logs you into your new Dex organization as an Admin. A organization represents a legal entity that can own multiple sub-organizations (for partners) or multiple locations (for merchants) as well as the customers, payment methods, and transactions that belong to those locations (see location description below). Every request call made to the CSG Forte REST API must contain the organization_id within the URI.

In addition to an organization, every Dex Sandbox account also comes with at least one location. Locations are processing endpoints that merchant organizations use to initiate transactions (in Forte legacy applications like Virtual Terminal, locations were known as MIDs). Locations own all the transaction data including sensitive payment method data and tokens. Tokens are random, alpha-numeric strings that represent stored, encrypted data. Tokenization is a common practice in the payment industry to protect sensitive data.

NOTE: For questions or help with Dex registration or setup, contact Forte Technical Support at 888-235-4635 option 5.

Creating Credentials

Before creating your first API request, you first have to create your API authentication credentials. These include an API Access ID, which acts as your username, and an API Secure Key, which acts as a password. You will create and maintain these credentials exclusively in Dex.

To generate your API Access ID and API Secure Key, complete the following steps:

  1. From a Google Chrome browser, log into your Dex Account.

  2. Select Developer > API Credentials from the Dex Main Menu.

  3. Click the CREATE button. The Create API Credentials screen displays.

  4. Enter a name for this set of API credentials in the Name field.

  5. Click the CREATE NEW API KEY button. The API Access ID and API Secure Key values display in their corresponding fields.

  6. Click the COPY button next to the API Access ID and API Secure Key fields to record both of these newly generated values in a secure location to use in authenticating your REST API requests.

NOTE: Once you save your API Secure Key, you will not be able to see the value again. If you forget your API Secure Key or it becomes compromised, you will have to regenerate the value in Dex.

To help you become familiar with the objects and methods of CSG Forte's REST API, we've created a Postman collection that you can download from our REST docs. Simply click the button that displays at the top of the screen. To help you become familiar with all the features of our REST API, this section will guide you through your first call creating a transaction.

Supported Actions

To begin crafting your call, you must choose an action and add its corresponding HTTP verb to the call. CSG Forte's REST API supports the following actions:

Action HTTP Method Description
Create POST Creates the resource that corresponds to the data type defined in the endpoint. For example, making a POST call to the transactions URI creates a new transaction.
Find GET Returns summary information for all the resources that match the provided query parameters. For example, performing a GET call to the customers URI returns all the customers associated with that specific merchant location. To return comprehensive/detailed information on a specific resource, provide the resource’s ID to the defined URI. For example, to find a specific customer associated with a merchant location, perform a GET call to the customers endpoint and include the customer_token filter parameter in the URI
Update PUT Modifies the existing resource for the provided URI. All PUT calls require the resource’s ID.
Delete DELETE Deletes the existing resource for the provided URI. All DELETE calls require the resource’s ID.

Since we want to create a transaction in our call, we'll use the POST verb.

curl --location -g --request POST

Defining the Resource Path

Resource paths define the locations where you want the action to occur. All resource paths contain two components, the base URI, that identifies Forte's server and environment, and an endpoint that identifies the merchant and the resource where the action should occur.

Base URI

When constructing a call, you will append the endpoint to one of the following base URIs for the specified environments:

URI Environment Sandbox Production


Forte's REST API Endpoint reference includes a listing of all available resource endpoints. All endpoints require object prefixing to identify the specific resource in the path. This helps with troubleshooting in the event of an error response. A 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
Addresses add_ + Token add_jUYRwbRjKUWgswNrFpSdKg
applications app_ + ID app_258741
bankaccounts bac_ + Token bac_48BdhGkl6UOtnrO4BmoeWg
customers cst_ + Token cst_SoGUG6mcLUS1nVzYBIbk3g
disputes dsp_ + ID dsp_2365435-e4ae-4ff4-a91e-abd8kjjfjffffc
documents doc_ + ID doc_3131dddgwef0gpV2eYlo5
funding fnd_ + ID fnd_ACH-0226-173C5
locations loc_ + ID loc_100000
organizations org_ + ID org_200000
paymethods mth_ + Token mth_ymC20TMkHE-YmYxMt0UvMA
scheduleitems sci_ + GUID sci_4690fbfb-0b77-4477-a066-2c07ca2e5a3c
schedules sch_ + GUID sch_2e5770ae-c120-414f-ae8c-d065753567e7
settlements stl_ + GUID stl_51cf4633-1767-484f-8784-be76a4076791
transactions trn_ + GUID trn_55c98c85-d3e8-4230-85e9-21d7d522eec0


Going back to our Create Transaction call, we can now add the complete resource path, or URI, to the call: 

curl --location -g --request POST '{organizationID}/locations/loc_{locationID}/transactions' \

Create Headers

To ensure our call is secure and readable, we now need to add headers. Requests to Forte's REST API must be authenticated using the Authorization header field and the custom header property, X-Forte-Auth-Organization-Id.

Authorization Header

Forte's REST web services rely on Basic access authentication over HTTPS using the API Access ID and API Secure Key (i.e., the credentials you created in Step 2 above) as the username and password values, respectively. These unique values are combined with a colon and then encoded using the RFC2045-MIME variant of Base64. The encoded string is then added to the HTTP Authorization header. For example, if you created the following API credentials:

  • API Access ID = 315c7649520edde96c5cbad59a5b265f

  • API Secure Key = c233f2958bd855d09d98397e74950640

The value of the Authorization header field would look like the following:


Several different online tools can help you create your Authorization header, such as Postman. You can also add Base64 encoding to HMAC requests to automatically convert the API Access ID and API Secure Key values into the encoded ASCII string. To do so, use the following code:

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

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 partner can authenticate his or her Organization ID in the X-Forte-Auth-Organization-Id header property and then can access merchant sub-organizations by specifying the merchant Organization ID in the URI of the request.

Accept Header

Forte’s REST service supports Content Negotiation through the Accept header sent in the request call.

The default value for Accept headers is application/json which returns JSON responses. However, you can also use application/xml which returns XML responses.

The Content-Type Header

The Content-Type header is only required for POST and PUT calls. Like the Accept header, the Content-Type header supports both application/json and application/xml. The default value for Content-Type headers is application/json.


For our example request, we'll add our headers for authentication: 

curl --location -g --request POST '{organizationID}/locations/loc_{locationID}/transactions' \
--header 'Authorization: {{Authorization}}' \ --header 'Accept: application/json' \ --header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \ --header 'Content-Type: application/json' \

Adding Parameters

Only POST and PUT requests include parameters since these actions are adding resources or updating existing resources. GET or DELETE requests require only the action, the resource path, and the headers. The CSG Forte REST docs list the available parameters for each object in a resource. At a minimum, you must include the required parameters of each object for every request. For our Create Transaction example, we'll use the minimum required parameters to create a credit card transaction: 

curl --location -g --request POST '{{organizationID}}/locations/loc_{{locationID}}/transactions' \
	--header 'Authorization: {{Authorization}}' \
	--header 'Accept: application/json' \
	--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
	--header 'Content-Type: application/json' \
	--data-raw '{
		"authorization_amount": 102.45,
		"subtotal_amount": 99.95,
			"first_name": "Jennifer",
			"last_name": "McFly"
			"card_type": "visa",
			"name_on_card": "Jennifer McFly",
			"account_number": "4111111111111111",
			"expire_month": "12",
			"expire_year": "2017",

If fomatted and authenticated correctly, this call will produce the following 201 - Created success response.

"transaction_id": "trn_9eab1d30-5326-4d15-b500-5d04c1e74839",
"location_id": "loc_192642",
"action": "sale",
"authorization_amount": 102.45,
"entered_by": "4fefaf5f77d944ce10bdd3d88f7a2da9",
"billing_address": {
	"first_name": "Jennifer",
	"last_name": "McFly"
	"card": {
		"name_on_card": "Jennifer McFly",
		"last_4_account_number": "1111",
		"masked_account_number": "****1111",
		"expire_month": 12,
		"expire_year": 2017,
		"card_type": "visa"
	"response": {
		"environment": "live",
		"response_type": "A",
		"response_code": "A01",
		"response_desc": "TEST APPROVAL",
		"authorization_code": "123456",
		"avs_result": "Y",
		"cvv_result": "M"

Responses echo back all the parameters included in the body of the request. NOTE: Optional request parameters whose values are null do not echo back in responses.

Forte includes all the applicable parameters of the response object in responses returned to the client. The following table displays the response object and the string parameters returned for each resource request.

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.

The type of response this action generated:

  • A - Approved

  • D - Declined

response_code The response code of the action.

Pre-authorization check result from Forte Verify with the following possible values:

  • POS - Positive

  • NEG - Negative

  • UNK - No information available

preauth_desc Pre-authorization check description from Forte Verify.
preauth_neg_report Negative database response information (unformatted) when pg_preauth_result=NEG.

Forte only returns this field if the merchant passes any combination of billing address parameters from the physical_address object in the request. To test this service in Sandbox, see the testing parameters in the Verifying Credit Cards tutorial and Response Codes section. Supported values for this field include the following:

  • X - Match: Street address and 9-digit zip code both match

  • Y = Match: Street address and 5-digit zip code both match

  • A = Partial Match: Street address matches, but both 5-digit and 9-digit zip code do not match

  • W = Partial Match: Street address does not match, but 9-digit zip code matches

  • Z = Partial Match: Street address does not match, but 5-digit zip code matches

  • N = No Match: Street address, 5-digit zip code, and 9-digit zip code all do not match

  • U = System unavailable: Address information unavailable. Forte returns this response if the street address is a non-US address, if the AVS service is unavailable, or if the AVS service for a particular US bank is not functioning properly

  • R = System unavailable: Forte will retry the AVS check because the issuer's system is unavailable or the request times out

  • E = Invalid: AVS data is invalid

  • S = Not supported: The US issuing bank does not support AVS checks


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

Going Further

Now that you've created your first call, you can test additional calls for different resources. Create a customer profile or two and then search for a specific customer. Create a credit card or echeck payment profile for each customer and test different types of transactions. For a full list of potential test calls, see CSG Forte's REST API docs.

Once you've completed your testing in Sandbox and established your merchant account with Forte, you're ready to go Live in production.

When Forte enrolls you as a new merchant, you'll receive your production Organization ID and, if applicable, Location ID. These values may be different than the Organization ID and Location ID for the Sandbox account you created on the Forte Developer's Test Account sign-up page or the test account provided to you by the Sales Team. If so, ensure you change these values in your integration.

Additionally, you will need to change the Base URI of the resource path to, to point to the Live environment.

Finally, Sandbox credentials do not carry over to Live, so you'll need to create and implement new API credentials into your integration. Fortunately, the process to create new credentials in Live is the same process in Sandbox. After creating new Live credentials remember to update/recreate your authentication headers before sending your first Live request.

Once you've changed these values in your integration, you can craft your first Live call.