Tracking Settlement and Funding Updates with Smart Querying

Once you’ve accepted payment for a good or service, you’ll want to know when that money appears in your bank account, a process known as settlement and funding.

For credit card transactions, settlement occurs between the processor and the issuer via the card network. Once the issuer debits the funds from the cardholder’s account, it sends settlement details back to the processor and transaction details to the Federal Reserve for distribution to the merchant. Funding occurs when the funds for the transaction are credited to the merchant’s bank account.

For ACH transactions, settlement occurs between the Merchant Bank, the Customer Bank, and the Federal Reserve via the ACH Network. The ACH transaction becomes a debit that is sent from the Merchant Bank to the Federal Reserve and then to the Customer Bank where—barring insufficient funds—the transaction becomes a credit and is returned to the merchant via the same route (i.e., Customer Bank to Federal Reserve to Merchant Bank). Funding occurs when the funds for the transaction are credited to the merchant’s bank account.

CSG Forte’s REST API gives you the ability to track your money from capture to funding with a few simple calls. While querying individual transactions can tell you whether a transaction has settled or funded, you don’t want to bog down the transactions endpoint with unnecessary requests for updates—especially when you’re tracking thousands of transactions. This can significantly slow down your payment processing ability as Forte throttles API requests to 10 per second.

Instead, you can use smart querying techniques using the settlements and fundings objects to track your money without slowing down your processing. Since settlement and funding times can vary depending on transaction parameters and your merchant location setup, you’ll want to create strategically timed queries using the settle_date and effective_date filters of the settlements and fundings objects. Use these date and timestamp queries to poll daily or intermittently throughout the day to synchronize and reconcile your data.

Monitoring Settlements

Transaction settlements can come in throughout the day. Rather than constantly polling the settlements object for new data, we recommend using date and timestamp queries using the settle_date filter parameter in the URI to keep systems synchronized. This can include a daily query for the prior day’s activity or multiple, intra-day queries. When setting up these GET calls, allow for a short period of time (i.e., 15 minutes) for the data to propagate (e.g., run the 1AM–4AM query at 4:15AM). Use additional filter parameters like method or settle_response_code to narrow your results further. Using the timestamp filter ensures the response contains only settlements that Forte received since the previous query.

The following sections include common use cases for smart querying the settlements object.

Single Query for Prior Day Activity

The following query captures all the settlement activity between midnight, October 1, 2019 and midnight, October 2, 2019. We would run this query at 12:15AM on October 2, 2019 to include data propagation time.

curl --location --request GET 
"https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/settlements/?filter=start_settle_date+eq+2019-10-01T00:00:00+AND+end_settle_date+eq+2019-10-2T00:00:00" \ 
--header "Authorization: {{Authorization}}" \ 
--header "Accept: application/json" \ 
--header "X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}" \ 
--data ""

Four Queries Per Day

The following queries capture all settlement activity within 6-hour blocks throughout the day.

6:15AM Query

curl --location --request GET 
"https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/settlements/?filter=start_settle_date+eq+2019-10-01T00:00:00+AND+end_settle_date+eq+2019-10-1T06:00:00" \
--header "Authorization: {{Authorization}}" \
--header "Accept: application/json" \
--header "X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}" \
--data ""

12:15PM Query

curl --location --request GET 
"https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/settlements/?filter=start_settle_date+eq+2019-10-01T06:00:00+AND+end_settle_date+eq+2019-10-1T12:00:00" \
--header "Authorization: {{Authorization}}" \
--header "Accept: application/json" \
--header "X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}" \
--data ""

6:15PM Query

curl --location --request GET 
"https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/settlements/?filter=start_settle_date+eq+2019-10-01T12:00:00+AND+end_settle_date+eq+2019-10-1T18:00:00" \
--header "Authorization: {{Authorization}}" \
--header "Accept: application/json" \
--header "X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}" \
--data ""

12:15AM Query

curl --location --request GET 
"https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/settlements/?filter=start_settle_date+eq+2019-10-01T18:00:00+AND+end_settle_date+eq+2019-10-2T00:00:00" \
--header "Authorization: {{Authorization}}" \
--header "Accept: application/json" \
--header "X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}" \
--data ""

Six Queries per Day

The following queries capture all settlement activity within 4-hour blocks throughout the day.

4:15AM Query

curl --location --request GET 
"https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/settlements/?filter=start_settle_date+eq+2019-10-01T00:00:00+AND+end_settle_date+eq+2019-10-1T04:00:00" \
--header "Authorization: {{Authorization}}" \ 
--header "Accept: application/json" \ 
--header "X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}" \ 
--data ""

8:15AM Query

curl --location --request GET 
"https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/settlements/?filter=start_settle_date+eq+2019-10-01T04:00:00+AND+end_settle_date+eq+2019-10-1T08:00:00" \
--header "Authorization: {{Authorization}}" \
--header "Accept: application/json" \
--header "X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}" \
--data ""

12:15PM Query

curl --location --request GET 
"https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/settlements/?filter=start_settle_date+eq+2019-10-01T8:00:00+AND+end_settle_date+eq+2019-10-1T12:00:00" \
--header "Authorization: {{Authorization}}" \
--header "Accept: application/json" \
--header "X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}" \
--data ""

4:15PM Query

curl --location --request GET 
"https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/settlements/?filter=start_settle_date+eq+2019-10-01T12:00:00+AND+end_settle_date+eq+2019-10-1T16:00:00" \
--header "Authorization: {{Authorization}}" \
--header "Accept: application/json" \
--header "X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}" \
--data ""

8:15PM Query

curl --location --request GET 
"https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/settlements/?filter=start_settle_date+eq+2019-10-01T16:00:00+AND+end_settle_date+eq+2019-10-1T20:00:00" \
--header "Authorization: {{Authorization}}" \
--header "Accept: application/json" \
--header "X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}" \
--data ""

12:15AM Query

curl --location --request GET 
"https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/settlements/?filter=start_settle_date+eq+2019-10-01T20:00:00+AND+end_settle_date+eq+2019-10-2T00:00:00" \
--header "Authorization: {{Authorization}}" \
--header "Accept: application/json" \
--header "X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}" \
--data ""

Monitoring Funding

The fundings object enables you to directly track the movement of money in and out of your organizations bank account(s) and to act quickly when transactions are rejected or fail using the effective_date filter.

Like the filtered settlements URI, the filtered fundings URI also includes a timestamp that ensures you receive only new data populated in your results. For example, let’s say you want to query for funding entries that occurred from Midnight (12AM) to Noon (12PM) each day. To allow for data propagation, you would schedule the following query to run at 12:15PM:

curl --location --request GET 
"https://api.forte.net/v3/organizations/org_{{organizationID}}/fundings/?filter=start_effective_date+eq+2019-10-01T00:00:00+and+end_effective_date+eq+2019-10-01T12:00:00" \
--header "Authorization: {{Authorization}}" \
--header "Accept: application/json" \
--header "X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}" \
--data ""

To capture funding entries that occurred from Noon to Midnight the next day, you would schedule the following query to run at 12:15AM:

curl --location --request GET 
"https://api.forte.net/v3/organizations/org_{{organizationID}}/fundings/?filter=start_effective_date+eq+2019-10-01T12:00:00+and+end_effective_date+eq+2019-10-02T00:00:00" \
--header "Authorization: {{Authorization}}" \
--header "Accept: application/json" \
--header "X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}" \
--data ""

To view the settlement record(s) for a funded transaction, you can append settlements to the funding entry’s URI as in this example:

curl --location --request GET 
"https://api.forte.net/v3/organizations/org_{{organizationID}}/fundings/fnd_{{fundingID}}/settlements" \
--header "Authorization: {{Authorization}}" \
--header "Accept: application/json" \
--header "X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}" \
--data ""

This endpoint gives you the ability to:

  • View the individual settlement record of a funded transaction
  • Troubleshoot failed funding entries or pending funding entries that should have funded by now
  • Get ahead of any chargebacks (credit cards) or ACH returns

Request Rate Limitations

Forte throttles API requests to 10/second. Once the request limit is met, Forte drops the connection and displays the following error: 403 – Forbidden: Access is denied.

Single Transaction Queries

Single transaction queries should be used on a very limited basis for user-initiated, real-time status updates instead of for general synchronization. For settlement information for a specific transaction, use the following URI:

curl --location --request GET 
"https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/transactions/trn_{{transactionID}}/settlements/" \
--header "Authorization: {{Authorization}}" \
--header "Accept: application/json" \
--header "X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}" \
--data ""

NOTE: Most transactions only have one settlement entry, but due to disputes and returns, some transactions may have multiple settlement entries.

Conclusion

With smart querying to the settlements and fundingsobjects, you can efficiently track the progress of your transactions without slowing down the payment processing abilities of the transactions object. CSG Forte wants to make processing your transactions as painless and transparent as possible. For more information about the settlements and fundings objects, see CSG Forte’s REST API Specification.

  • See the entire product suite

Related Posts

Stay connected to the latest Forte updates
Check out Forte’s new Release Notes blog!
The Benefits of REST API