Questions

1. What is REST API?

2. What are the key features and benefits of REST API?

3. Which REST API endpoints and resources are available for transactions, customers, payment methods, and schedules?

4. How does this solution work?

        4.1. HTTP Methods

        4.2. Basic request-and-response model

        4.3. Payment Methods and tokenization

        4.4. What do REST API error codes mean?

5. How is REST API different from other CSG Forte products?

6. Are there examples or resources available for reference?

7. How can scheduling information be retrieved for a processed transaction?

8. How can transactions be voided, refunded, captured, or reversed through the REST API?

9. How can Credit Card data be verified in REST API?

        16.1. How are CVV and AVS results interpreted?

10. What should be done when a REST API request times out or no response is received to avoid creating a duplicate transaction?

CSG Forte Representational State Transfer Application Programming Interface (REST API) is a secure application programming interface that allows merchants and partners to integrate their systems directly with the CSG Forte payment platform. Using standard HTTP requests (HTTP methods GET, POST, PUT, DELETE generally exchanging data in JSON format), developers can automate payment-related functions such as processing transactions, managing customers, storing payment methods, creating recurring payment schedules, and retrieving transaction information without manually accessing the CSG Forte portal. 

Note: An API is a communication channel that enables two software systems to interact with each other. In CSG Forte’s case, the API allows merchants, partners, and developers to securely integrate their applications with CSG Forte’s payment gateway. For example, a customer pays through a merchant’s website, the website sends payment information to CSG Forte through an API request, the request is processed and CSG Forte sends back a response indicating whether the payment was approved, declined, or requires another status check.

REST API provides a comprehensive set of capabilities that enable merchants and partners to integrate payment processing directly into their business applications and workflows. Designed to support secure, scalable, and automated payment operations.  

REST API provides access to core resources used to manage payment activity and related records:

• Transactions: Payments, authorizations, captures, credits, voids, inquiries, verifications, and other actions. 
• Customers: Creation, retrieval, updating, and deletion of customer records. 
• Paymethods: Storage and management of supported payment methods. 
• Schedules: Creation and management of recurring payment schedules. 
• Schedule Items: Retrieval of individual payment occurrences associated with a schedule. 
• Merchant Applications: Submission and status management for supported partner workflows. 
• Webhooks: Event notifications for subscribed transaction and resource activity. 

The required endpoint path, HTTP method, fields, and permissions vary by resource and operation. The applicable REST API reference should therefore be reviewed before a request is implemented. 

Note: An endpoint is the web address used to access a resource. For example, a transaction endpoint may allow an application to create, retrieve, or manage transactions. See Set Up a REST API Integration for more details.

REST API solution enables secure, direct communication between a merchant's application and the CSG Forte payment platform through standardized HTTP requests. Once API credentials have been generated and the required authentication headers have been configured, the application can interact with CSG Forte services to perform a wide range of payment-related operations, including transaction processing, customer management, payment method storage, recurring payment administration, and data retrieval. 

Each request submitted to the API is authenticated, processed by CSG Forte, and returned with a structured response in a supported format such as JSON or XML. This approach allows organizations to automate payment workflows, improve operational efficiency, integrate payment capabilities into existing business systems, and reduce the need for manual intervention. 

For enhanced automation and real-time updates, the solution also supports Webhooks, which can automatically notify applications when specific events occur, such as transaction activity, customer updates, or payment method changes. This enables systems to react to events as they happen without the need for continuous polling of the API.

Note: CSG Forte’s REST API supports transaction lifecycle actions such as authorization, capture, void, and refund. Consider the distinction between an approved transaction, which means the payment was authorized, and a settled transaction, which means the payment has completed the settlement process.

REST API can work with payment methods such as: 

• Credit and debit cards 
• eChecks or ACH 
• Digital wallets 

It also supports tokenization, which replaces sensitive card/bank details with a secure token. This improves security to safely store and reuse payment information rather than storing raw information for recurring payments.  

REST API error codes indicate why a request failed. Common examples include 400 (Bad Request), 401 (Unauthorized), 403 (Forbidden), 404 (Not Found), 405 (Method Not Allowed), and 500 (Internal Server Error). These codes help identify whether the problem is with the request, authentication, permissions, the requested resource, or the server. 

Common scenarios include:

The HTTP status code and the response details should be reviewed together to determine why a REST API request was unsuccessful. Transaction responses may also contain fields such as “response_type”, “response_code”, and “response_desc”, which provide additional processing information.

Unlike hosted solutions such as Forte Checkout (FCO) or Secure Web Pay (SWP), the REST API enables direct system-to-system integration and automation. It provides developers with programmatic access to payment information, making it the preferred solution for organizations requiring customized and scalable payment integrations.

Several sample implementations, codes, client libraries, and third-party resources are available to assist developers with integrating applications with the REST API:

Note: The Java example, Ruby wrapper, .NET wrapper, and PHP sample are provided as reference resources and may require modification before use in a production environment. Developers should validate compatibility with current REST API functionality, security requirements, authentication methods, and supported endpoints. It is recommended to navigate DevDocs > Downloads > Third Party Models.

The standard SLA is 1-5 business days for review and initial response. The time frame on decisions for manually reviewed applications is largely dependent on the merchant’s response to any requests for additional information or documentation. 

Once an application has been approved, the account will be enrolled within 1-2 business days.

In this example: 

• service_fee identifies the portion of the transaction that represents the Service Fee. 
• authorization_amount reflects the total amount to be authorized and charged, including the Service Fee. 

Note: The ability to process Service Fee must be enabled and configured by CSG Forte at the merchant's location level. If service fees have not been configured for the location, transactions containing the “service_fee” parameter may not be processed as expected. . 

Transaction-management operations are submitted through the REST API transactions resource. The request action and endpoint depend on the operation, the original transaction type, the payment method, and the transaction’s status. Before submitting an administrative transaction, the merchant must verify: 

• The original transaction ID and authorization code. 
• The current transaction status and response details. 
• The payment method and processor. 
• The original, captured, settled, or funded amount, as applicable. 
• Whether the requested action is still permitted within the authorization or settlement window. 
• Whether the merchant location is configured for any required feature, such as service fees, surcharging, or incremental authorizations. 

A successful authorization is not the same as settlement. For example, an approved credit-card authorization may still be in “Authorized” status, while a completed credit-card payment is in Settled status. An eCheck normally progresses through “Ready”, “Settling”, and “Funded” statuses. See the Transaction Status and Decline Codes for the current definitions. 

Credit Card data can be verified before a transaction is performed to help identify potentially fraudulent transactions and reduce the risk of rate downgrades by the Credit Card authorizer. Verification may be performed when creating a recurring or future payment or when generating a payment method token.

Historically, card-not-present merchants used US$1.00 “ghost authorizations” to verify cards. These authorizations temporarily captured funds, remained pending, and later expired. Visa and Mastercard subsequently enabled zero-dollar transactions so that merchants could perform Address Verification Service (AVS) and Card Verification Value (CVV) checks without capturing funds. 

CSG Forte verifies whether the card is associated with an open, valid account by comparing the following information with the customer’s issuing bank. Credit Cards can be verified through REST API or Advanced Gateway Interface (AGI): 

• Primary Account Number (PAN) 
• CVV or CVV2 
• Expiration month and year 
• Cardholder’s street address and ZIP or postal code 

The verification process follows these steps: 

1. The merchant uses the Advanced Gateway Interface (AGI) or REST API to submit a US$0.00 non-swipe, ad-hoc credit card transaction or a US$0.01 swiped ad-hoc Credit Card transaction to CSG Forte. 
2. CSG Forte securely transfers the transaction data to the Credit Card processor. 
3. The Credit Card processor runs the data and obtains an authorization (“Completed”) or a decline (“Failed”). No funds are captured and the transaction is not settled. 
4. CSG Forte sends a postback stating whether the transaction authorization “Completed” or “Failed”. Credit Card verifications do not affect Split-Fund merchants. 

Through REST API Credit Card can be verified by sending transaction parameters (i) or swipe data (ii) in a POST request to the transactions URI: 

i. Transaction parameters: Use the following values in the request. 

ii.Swipe data: Swiped transactions require an authorization amount greater than zero. For verification, CSG Forte recommends “authorization_amount”= 0.01. Use the following values: 

• authorization_amount=0.01 
• action=sale or action=verify 
• Billing address fields, including first name, last name, street address, locality, region, and postal code 
• card.card_reader 
• card.card_data 

The swipe-data request must be submitted as a POST request to the transactions URI. The response includes the transaction details and the AVS and CVV results when those checks are performed. 

CSG Forte returns the following verification results: 

• CVV in the “cvv_result” field (in the sandbox environment, CVV testing can simulate only M and N). 

• AVS in the “avs_result” field (in the sandbox environment, AVS testing can simulate only Y and N):

Note: The following test values are intended for the sandbox environment only:

For more details on AVS and CVV verifications, see Verifying Credit Cards.

A REST API request has a 60-second connection timeout. If the request does not complete within this period, the connection is terminated. However, a timeout or lack of response does not necessarily mean that the transaction failed. The transaction may have been processed even though the response was not received. 

Before resubmitting the transaction, verify whether the original request was processed by checking: 

• The request timestamp. 
• The transaction amount. 
• The associated customer or payment method. 
• Any merchant-defined reference or order number submitted with the request. 
• Available transaction records or Webhook notifications. 

If a matching transaction is found, use the result of the original transaction and do not resubmit the payment. 

To reduce the risk of duplicate transactions, integrations should also be designed to account for the 60-second timeout, particularly for long-running operations. Where available, merchant-defined reference values or order numbers should be used consistently to help identify and reconcile transaction requests. 

Recommended best practices include: 

• Use Webhooks as the primary method for confirming transaction processing events. 
• Use REST API transaction inquiries only when confirmation cannot be obtained through Webhooks. 
• When searching for transactions, use filters such as merchant-defined order numbers, transaction references, timestamps, and date ranges to narrow results, more detail Transactions with Filter Forte REST API v3 
• Configure transaction notification options in Dex when appropriate. 
• Monitor service health and availability through the CSG Forte Status Page.