openapi: 3.1.0
info:
title: CSG Forte REST API
description: >-
CSG Forte provides full-stack REST APIs for payment processing within a PCI-compliant
architecture. The API enables merchants and partners to create and update credit card,
echeck, and scheduled transactions, securely manage customer and payment data, and query
settlement information. Authentication uses standard HTTP credential headers with organization
ID, location ID, and API key.
version: 3.0.0
contact:
name: Forte Support
url: https://support.forte.net/
license:
name: Forte Terms of Service
url: https://www.forte.net/
servers:
- url: https://api.forte.net/v3
description: Forte REST API v3 Production
- url: https://sandbox.forte.net/api/v3
description: Forte REST API v3 Sandbox
security:
- basicAuth: []
tags:
- name: Customers
description: Customer record management
- name: Payment Methods
description: Payment method tokenization and management
- name: Settlements
description: Settlement query and reconciliation
- name: Transactions
description: Payment transaction processing (credit card, echeck, scheduled)
paths:
/organizations/{organizationId}/locations/{locationId}/transactions:
get:
operationId: listTransactions
summary: List transactions for a location
description: >-
Returns a paginated list of transactions for the specified organization and location.
Supports filtering by date range, status, and payment method type.
tags:
- Transactions
parameters:
- name: organizationId
in: path
required: true
description: Organization identifier (org_XXXXX format)
schema:
type: string
pattern: '^org_[A-Za-z0-9]+$'
- name: locationId
in: path
required: true
description: Location identifier (loc_XXXXX format)
schema:
type: string
pattern: '^loc_[A-Za-z0-9]+$'
- name: start_date
in: query
description: Filter transactions on or after this date (YYYY-MM-DD)
schema:
type: string
format: date
- name: end_date
in: query
description: Filter transactions on or before this date (YYYY-MM-DD)
schema:
type: string
format: date
- name: action
in: query
description: Filter by transaction action
schema:
type: string
enum: [sale, authorize, capture, void, credit, force]
- name: response_code
in: query
description: Filter by response code (A for approved, D for declined, etc.)
schema:
type: string
- name: page_index
in: query
schema:
type: integer
default: 1
- name: page_size
in: query
schema:
type: integer
default: 50
maximum: 200
responses:
'200':
description: List of transactions
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionList'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
post:
operationId: createTransaction
summary: Create a payment transaction
description: >-
Submits a new payment transaction. Supports credit card sales, authorizations, captures,
voids, credits, and ACH/echeck transactions. Also supports scheduled/recurring transactions.
tags:
- Transactions
parameters:
- name: organizationId
in: path
required: true
schema:
type: string
- name: locationId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionRequest'
responses:
'201':
description: Transaction created
content:
application/json:
schema:
$ref: '#/components/schemas/Transaction'
'400':
$ref: '#/components/responses/BadRequest'
/organizations/{organizationId}/locations/{locationId}/transactions/{transactionId}:
get:
operationId: getTransaction
summary: Get transaction details
description: Returns detailed information for a specific transaction.
tags:
- Transactions
parameters:
- name: organizationId
in: path
required: true
schema:
type: string
- name: locationId
in: path
required: true
schema:
type: string
- name: transactionId
in: path
required: true
schema:
type: string
responses:
'200':
description: Transaction details
content:
application/json:
schema:
$ref: '#/components/schemas/Transaction'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateTransaction
summary: Update a transaction (void or capture)
description: Updates an existing transaction. Used to void, capture, or credit a prior transaction.
tags:
- Transactions
parameters:
- name: organizationId
in: path
required: true
schema:
type: string
- name: locationId
in: path
required: true
schema:
type: string
- name: transactionId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/TransactionUpdateRequest'
responses:
'200':
description: Transaction updated
content:
application/json:
schema:
$ref: '#/components/schemas/Transaction'
/organizations/{organizationId}/locations/{locationId}/customers:
get:
operationId: listCustomers
summary: List customers
description: Returns a list of customer records for the specified location.
tags:
- Customers
parameters:
- name: organizationId
in: path
required: true
schema:
type: string
- name: locationId
in: path
required: true
schema:
type: string
- name: first_name
in: query
schema:
type: string
- name: last_name
in: query
schema:
type: string
- name: customer_token
in: query
schema:
type: string
- name: page_index
in: query
schema:
type: integer
default: 1
- name: page_size
in: query
schema:
type: integer
default: 50
responses:
'200':
description: List of customers
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerList'
post:
operationId: createCustomer
summary: Create a customer record
description: Creates a new customer record for storing payment method tokens and billing information.
tags:
- Customers
parameters:
- name: organizationId
in: path
required: true
schema:
type: string
- name: locationId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerRequest'
responses:
'201':
description: Customer created
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
/organizations/{organizationId}/locations/{locationId}/customers/{customerId}:
get:
operationId: getCustomer
summary: Get customer details
description: Returns a specific customer record including stored payment methods.
tags:
- Customers
parameters:
- name: organizationId
in: path
required: true
schema:
type: string
- name: locationId
in: path
required: true
schema:
type: string
- name: customerId
in: path
required: true
schema:
type: string
responses:
'200':
description: Customer details
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
'404':
$ref: '#/components/responses/NotFound'
put:
operationId: updateCustomer
summary: Update a customer record
description: Updates an existing customer record.
tags:
- Customers
parameters:
- name: organizationId
in: path
required: true
schema:
type: string
- name: locationId
in: path
required: true
schema:
type: string
- name: customerId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CustomerRequest'
responses:
'200':
description: Customer updated
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
delete:
operationId: deleteCustomer
summary: Delete a customer record
description: Permanently removes a customer record and all associated payment methods.
tags:
- Customers
parameters:
- name: organizationId
in: path
required: true
schema:
type: string
- name: locationId
in: path
required: true
schema:
type: string
- name: customerId
in: path
required: true
schema:
type: string
responses:
'200':
description: Customer deleted
/organizations/{organizationId}/locations/{locationId}/paymentmethods:
get:
operationId: listPaymentMethods
summary: List payment methods for a location
description: Returns all stored payment method tokens for the location, optionally filtered by customer.
tags:
- Payment Methods
parameters:
- name: organizationId
in: path
required: true
schema:
type: string
- name: locationId
in: path
required: true
schema:
type: string
- name: customer_token
in: query
schema:
type: string
responses:
'200':
description: List of payment methods
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethodList'
post:
operationId: createPaymentMethod
summary: Create a payment method token
description: Tokenizes a payment method (credit card or bank account) for future use.
tags:
- Payment Methods
parameters:
- name: organizationId
in: path
required: true
schema:
type: string
- name: locationId
in: path
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethodRequest'
responses:
'201':
description: Payment method tokenized
content:
application/json:
schema:
$ref: '#/components/schemas/PaymentMethod'
/organizations/{organizationId}/locations/{locationId}/settlements:
get:
operationId: listSettlements
summary: List settlements
description: Returns settlement records for reconciliation, including batch details and totals.
tags:
- Settlements
parameters:
- name: organizationId
in: path
required: true
schema:
type: string
- name: locationId
in: path
required: true
schema:
type: string
- name: start_settle_date
in: query
schema:
type: string
format: date
- name: end_settle_date
in: query
schema:
type: string
format: date
responses:
'200':
description: List of settlements
content:
application/json:
schema:
$ref: '#/components/schemas/SettlementList'
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: >-
HTTP Basic authentication using API access ID as username and API secure key as password.
Include organization ID and location ID in the X-Forte-Auth-Organization-Id and
X-Forte-Auth-Location-Id request headers.
schemas:
TransactionList:
type: object
properties:
number_results:
type: integer
page_index:
type: integer
page_size:
type: integer
results:
type: array
items:
$ref: '#/components/schemas/Transaction'
Transaction:
type: object
properties:
transaction_id:
type: string
description: Unique transaction identifier (trn_XXXXX format)
location_id:
type: string
action:
type: string
enum: [sale, authorize, capture, void, credit, force, verify]
authorization_amount:
type: number
format: double
authorization_code:
type: string
entered_by:
type: string
received_date:
type: string
format: date-time
transaction_date:
type: string
format: date
response:
$ref: '#/components/schemas/TransactionResponse'
billing_address:
$ref: '#/components/schemas/Address'
card:
$ref: '#/components/schemas/CardInfo'
echeck:
$ref: '#/components/schemas/EcheckInfo'
customer_token:
type: string
paymethod_token:
type: string
schedule_id:
type: string
TransactionRequest:
type: object
required: [action, authorization_amount]
properties:
action:
type: string
enum: [sale, authorize, capture, void, credit, force, verify]
authorization_amount:
type: number
format: double
minimum: 0.01
entered_by:
type: string
order_number:
type: string
customer_token:
type: string
paymethod_token:
type: string
card:
$ref: '#/components/schemas/CardRequest'
echeck:
$ref: '#/components/schemas/EcheckRequest'
billing_address:
$ref: '#/components/schemas/Address'
xdata:
type: object
description: Custom key-value pairs for extended transaction data
additionalProperties:
type: string
TransactionUpdateRequest:
type: object
required: [action]
properties:
action:
type: string
enum: [capture, void, credit]
authorization_amount:
type: number
format: double
TransactionResponse:
type: object
properties:
environment:
type: string
enum: [live, sandbox]
response_type:
type: string
enum: [A, D, E, F, U]
description: A=Approved, D=Declined, E=Error, F=Force, U=Undetermined
response_code:
type: string
response_desc:
type: string
authorization_code:
type: string
avs_result:
type: string
cvv_result:
type: string
CardInfo:
type: object
properties:
card_type:
type: string
enum: [visa, mstr, disc, amex, jcb, dine, enrt]
name_on_card:
type: string
masked_account_number:
type: string
description: Masked card number (e.g., XXXX-XXXX-XXXX-1234)
expire_month:
type: string
expire_year:
type: string
CardRequest:
type: object
properties:
card_type:
type: string
name_on_card:
type: string
account_number:
type: string
description: Full card number (PCI sensitive)
expire_month:
type: string
pattern: '^(0[1-9]|1[0-2])$'
expire_year:
type: string
pattern: '^[0-9]{4}$'
cvv:
type: string
EcheckInfo:
type: object
properties:
account_type:
type: string
enum: [checking, savings]
masked_account_number:
type: string
routing_number:
type: string
EcheckRequest:
type: object
properties:
account_type:
type: string
enum: [checking, savings]
account_number:
type: string
routing_number:
type: string
sec_code:
type: string
enum: [PPD, CCD, WEB, TEL]
CustomerList:
type: object
properties:
number_results:
type: integer
results:
type: array
items:
$ref: '#/components/schemas/CustomerSummary'
CustomerSummary:
type: object
properties:
customer_token:
type: string
first_name:
type: string
last_name:
type: string
company_name:
type: string
created_date:
type: string
format: date
Customer:
allOf:
- $ref: '#/components/schemas/CustomerSummary'
- type: object
properties:
email:
type: string
format: email
phone:
type: string
billing_address:
$ref: '#/components/schemas/Address'
updated_date:
type: string
format: date
CustomerRequest:
type: object
properties:
first_name:
type: string
last_name:
type: string
company_name:
type: string
email:
type: string
format: email
phone:
type: string
billing_address:
$ref: '#/components/schemas/Address'
PaymentMethodList:
type: object
properties:
number_results:
type: integer
results:
type: array
items:
$ref: '#/components/schemas/PaymentMethod'
PaymentMethod:
type: object
properties:
paymethod_token:
type: string
customer_token:
type: string
method_type:
type: string
enum: [cc, ec]
card:
$ref: '#/components/schemas/CardInfo'
echeck:
$ref: '#/components/schemas/EcheckInfo'
created_date:
type: string
format: date
PaymentMethodRequest:
type: object
required: [method_type]
properties:
method_type:
type: string
enum: [cc, ec]
customer_token:
type: string
card:
$ref: '#/components/schemas/CardRequest'
echeck:
$ref: '#/components/schemas/EcheckRequest'
SettlementList:
type: object
properties:
number_results:
type: integer
results:
type: array
items:
$ref: '#/components/schemas/Settlement'
Settlement:
type: object
properties:
settlement_id:
type: string
settle_date:
type: string
format: date
total_approved:
type: number
total_credited:
type: number
transaction_count:
type: integer
status:
type: string
enum: [pending, settled, failed]
Address:
type: object
properties:
first_name:
type: string
last_name:
type: string
company_name:
type: string
physical_address:
type: string
locality:
type: string
description: City
region:
type: string
description: State/province
postal_code:
type: string
country_code:
type: string
default: US
Error:
type: object
properties:
response_type:
type: string
response_code:
type: string
response_desc:
type: string
responses:
Unauthorized:
description: Authentication required
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
Forbidden:
description: Insufficient permissions
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
BadRequest:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/Error'