Settlements
The settlements object captures the status of transaction(s) associated with a merchant location. GET requests to this endpoint can be filtered according to settlement date, response, and method.
Settlements Object
Parameter | Description | Type | Req |
organization_id | The identification number of the associated organization. For example, org_5551236. | string | R |
location_id | The identification number of the associated location. For example, loc_1234568. | string | R |
funding_id | A unique string used to represent a funding entry. For example, fnd_ACH-0226-173C5. [max length = 20] | string | -- |
customer_token | A unique string used to represent a customer. For example, cst_SoGUG6mcLUS1nVzYBIbk3g. [max length = 26] | string | -- |
customer_id | A merchant-defined string created at the customer level to identify the customer. [max length = 15] | string | -- |
order_number | A merchant-defined string. [max length = 50] | string | -- |
reference_id | A merchant-defined string that identifies the transaction. [max length = 50] | string | -- |
settle_id | The settlement ID of the settled transaction (e.g., stl_51cf4633-1767-484f-8784-be76a4076791). [max length = 40] | string | R |
transaction_id | A 36-character code that uniquely identifies the transaction. | string | -- |
settle_batch_id | The ID of the credit card settlement batch, which the merchant can use to reconcile credit card bank deposits. This parameter is view-only and only for credit card transactions. | string | -- |
settle_date | The date when the transaction was settled. This parameter is return only. | datetime | -- |
settle_type | The type of settlement. Supported settlement types include the following values. For echeck transactions:
For credit card transactions:
This parameter is return only. | string | -- |
settle_response_code | See the Response Codes table for more information. This parameter is return only. NOTE: Credit card transactions that do not return a settle response can be considered settled. | object | O |
settle_amount | The amount the transaction settled for. This parameter is return only. | decimal | -- |
method | The payment method. This parameter is return only. The supported payment methods include the following values:
| string | -- |
GET All Settlements from a Location
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/settlements/
Â
This URI returns all the transaction settlements for a Location. To narrow your search data using specific criteria, use the following parameters to filter your results:
- customer_token
- transaction_id
- customer_id
- order_number
- reference_id
- start_settle_date / end_settle_date
- settle_response_code
- method
NOTES:
- All date filter parameters are time aware.
- If theÂ
start_settle_date andÂend_settle_date filters are not passed in via the body of the requst, the query automatically uses a default date range of 90 days. If you do not pass in any date filters, the system automatically uses the current date and the previous 90 days.
.
Example Request
curl --location -g 'https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/settlements/' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--data ''
Example Response
GET Settlements from a Specific Data Range
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/settlements/?filter=start_settle_date+eq+%272016-10-01%27+AND+end_settle_date+eq+%272016-10-31%27
Â
This URI returns all the transaction settlements for a Location within a specific date range.
Note: Please note that sending a request at the partner (org) level may result in a large data set and may cause timeout errors depending on the request. We recommend sending your GET request at the Merchant (Organization) level.
Example Request
curl --location -g 'https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/settlements/?filter=start_settle_date%2Beq%2B%25272016-10-01%2527%2BAND%2Bend_settle_date%2Beq%2B%25272016-10-31%2527' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--data ''
Example Response
GET Settlements by Transaction ID
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/transactions/trn_{{transactionID}}/settlements/
This URI returns all the settlement data for a specific transaction. NOTE: Most transactions only have one settlement, but due to disputes and returns, some transactions may have multiple settlements.
Example Request
curl --location -g 'https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}/transactions/{{transactionID}}/settlements/' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--data ''
Example Response
GET All Settlements from an Organization
{{baseURI}}/organizations/org_{{organizationID}}/settlements/
This URI returns all the transaction settlements for an Organization. To narrow your search data using specific criteria, use the following parameters to filter your results:
location_id
customer_token
transaction_id
customer_id
order_number
reference_id
start_settle_date / end_settle_date
settle_response_code
method
NOTES:
All date filter parameters are time aware.
If theÂ
start_settle_date andÂend_settle_date filters are not passed in via the body of the requst, the query automatically uses a default date range of 90 days. If you do not pass in any date filters, the system automatically uses the current date and the previous 90 days.
Please note that sending a request at the partner (org) level may result in a large data set and may cause timeout errors depending on the request. We recommend sending your GET request at the Merchant (Organization) level.
Example Request
curl --location -g 'https://api.forte.net/v3/organizations/org_{{organizationID}}/settlements/' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--data ''
Example Response