Locations
The locations object represents a merchant's processing endpoints. This object enables merchants to see address, contact, business, and services data related to their location. The locations object includes the contacts, services, card, and echeck subobjects.
Locations Object
Parameter | Description | Type | Req |
location_id | The identification number of the associated location. For example, loc_1234568. | string | -- |
status | The status of this location. Supported values include the following:
| string | -- |
created_date | The date that Forte created the location | datetime | -- |
dba_name | The merchant's Doing Business As (DBA) name. | string | -- |
street_address1 | The first line of the location's street address. | string | -- |
street_address2 | If needed, the second line of the location's street address. | string | -- |
locality | The city / town / village / locality of the location. | string | -- |
region | The state or province of the location. This field supports ISO-standard, 2-digit abbreviations for state and province names. | string | -- |
postal_code | The zip or postal code of the location. | string | -- |
country | The Alpha-3, ISO-standard country code of the location. For example, USA or CAN. | string | -- |
business_phone | The business phone number of the location. [max length = 15] | string | -- |
currency | The Alpha-3, ISO-standard currency code of the currency the location uses. | string | -- |
timezone | The timezone of the location. Supported values for this field include the following:
| object | -- |
business_type | The location's type of business. See Forte's list of Business Classification Codes for more information. [max length = 20] | string | -- |
organization_id | The identification number of the associated organization. For example, org_5551236. | string | -- |
organization_name | The name of the associated organization. [max length = 50] | string | -- |
parent_organization_id | The identification number of the associated parent organization. For example, org_5551236. | string | -- |
contacts | The contacts object. | object | -- |
contacts.full_name | The first and last name of this location's contact. | string | -- |
contacts.phone | The phone number of this location's contact. [max length = 15] | string | -- |
contacts.email | The business email address of this location's contact. This email cannot be a generic email address or from a distribution list. The value of this parameter must be in a valid email format (For example, john.doe@email.com). [max length = 100] | string | -- |
contacts.type | The type of contact associated with this location. Supported values for this field include the following:
| string | -- |
services | The services object | object | -- |
services.echeck | The echeck object | object | -- |
services.echeck.service_fee_percentage | The service fee (i.e., convenience fee) percentage amount for ACH transactions. | integer | -- |
services.echeck.service_fee_min_amount | The minimum service fee (i.e., convenience fee) amount for ACH transactions. | integer | -- |
services.echeck.service_fee_amount | The flat service fee (i.e., convenience fee) amount for ACH transactions. | integer | -- |
services.echeck.service_fee_range | The range of service fee (i.e., convenience fee) amounts for ACH transactions. | array | -- |
services.echeck.service_fee_tiered | The tiered service fee (i.e., convenience fee) amounts for ACH transactions. | array | -- |
services.echeck.service_fee_additional_amount | The additional service fee (i.e., convenience fee) amounts for ACH transactions. | integer | -- |
services.echeck.hold_days_sales | The number of days ACH funds from sale transactions are held before the receiving bank reconciles and settles the transaction. | integer | -- |
services.echeck.hold_days_refunds | The number of days ACH funds from refund/credit transactions are held before before the receiving bank reconciles and settles the transaction. | integer | -- |
services.echeck.hold_days_resubmits | The number of days ACH funds are held before the transaction is resubmitted to/from your customer's account. | integer | -- |
services.echeck.cut_off_time | The settlement cut-off times configured for this location based on the ACH processor. | datetime | -- |
services.echeck.entry_class_code | The list of standard entry class codes configured for this location. For more information, see Using ACH and SEC Return Codes. | array | -- |
services.echeck.nacha_id | The NACHA Co ID or Company ID used to process ACH transactions for this location. | string | -- |
services.card | The card object. | object | -- |
services.card.cut_off_time | The settlement cut-off times configured for this location based on the credit card processor. | datetime | -- |
services.card.market_type | The method by which the business captures the majority of its transactions. Supported values for this field include the following:
| string | -- |
services.card.service_fee_percentage | The service fee (i.e., convenience fee) percentage amount for credit card transactions. | integer | -- |
services.card.service_fee_min_amount | The minimum service fee (i.e., convenience fee) amount for credit card transactions. | integer | -- |
services.card.service_fee_amount | The flat service fee (i.e., convenience fee) amount for credit card transactions. | integer | -- |
services.card.service_fee_additional_amount | The additional service fee (i.e., convenience fee) amounts for credit card transactions. | integer | -- |
services.card.service_fee_range | The range of service fee (i.e., convenience fee) amounts for credit card transactions. | array | -- |
services.card.service_fee_tiered | The tiered service fee (i.e., convenience fee) amounts for credit card transactions. | array | -- |
services.card.service_fee_visa_tax_amount | The flat service fee (i.e., convenience fee) amount used for VISA Debit cards. NOTE: services:card:service_fee_visa_tax_amount is now a legacy field (the visa tax program has been ended) and should be ignored. Visa debit cards now preceded by debit service fee configuration | integer | -- |
services.card.debit_service_fee_percentage | The service fee (i.e., convenience fee) percentage amount for debit card transactions. | integer | -- |
services.card.debit_service_fee_min_amount | The minimun service fee (i.e., convenience fee) amount for debit card transactions. | integer | -- |
services.card.debit_service_fee_amount | The flat service fee (i.e., convenience fee) amount for debit card transactions. | integer | -- |
services.card.debit_service_fee_additional_amount | The additional service fee (i.e., convenience fee) amounts for debit card transactions. | integer | -- |
services.card.debit_service_fee_range | The range of service fee (i.e., convinience fee) amounts for debit card transactions. | array | -- |
services.card.debit_service_fee_tiered | The tiered service fee (i.e., convenience fee) amounts for debit card transactions. | array | -- |
services.card.card_types | The list of credit card types accepted by this merchant. Supported values for this field include the following:
| string | -- |
services.card.account_updater | A flag indicating whether or not the Account Updater subscription is enabled for this location. Supported values for this field include the following:
| string | -- |
services.card.gateway | Indicates whether or not the location is processing credit card transactions using a gateway in which transactions are processed through a different Service Provider. Supported values for this field include the following:
| string | -- |
services.card.platform | The credit card transaction processor. | string | -- |
services.card.bin | The merchant's Bank Identification Number (BIN) for credit card processing. | string | -- |
services.card.tid | The merchant's Terminal Identification (TID) number for credit card processing. | string | -- |
bankaccount_credits_token | The token of the bank account that handles the merchant's credit transactions (For example: refunds, payroll, chargebacks, reversals, etc.). | string | -- |
bankaccount_debits_token | The token of the bank account that handles the merchant's debit transactions (For example: sales, chargeback wins, etc.). | string | -- |
bankaccount_billing_token | The token of the bank account that pays the merchant's billing obligations to Forte or the Reseller. | string | -- |
bankaccount_ccfee_token | The token of the bank account that collects the convenience fee debits for each of the merchant's credit card sale transactions. | string | -- |
bankaccount_ecfee_token | The token of the bank account that collects the convenience fee debits for each of the merchant's echeck sale transactions. | string | -- |
terminals. serial_number | The serial number of a V400c device, enabled in cloud mode for the location. [max length = 11] | string | -- |
terminals. connection_status | The status of the cloud connection to the terminal. Supported values for this field include:
| boolean | -- |
terminals. lock_status | The lock status shows if a terminal is in use. Supported values for this field include:
NOTE: The terminal is in use when the lock status is “true” and it is available to use when the lock status is “false”. | boolean | -- |
terminals. device_status | The status of the device as set up in Dex-Terminal Management. Supported values for this field include:
| boolean | -- |
GET All Locations
{{baseURI}}/organizations/org_{{organizationID}}/locations
This URI returns all the locations that belong to an Organization. To narrow your search data using specific criteria, use the following parameters to filter your results:
- dba_name
- start_created_date / end_created_date
- status
- region
- country
- postal_code
Example Request
curl --location -g 'https://api.forte.net/v3/organizations/org_{{organization}}/locations/' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}'
Example Response
GET Location by ID
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}
This URI returns detailed location data using the location_id.
Example Request
curl --location -g 'https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}' \
--header 'Accept: application/json' \
--header 'Authorization: {{Authorization}}' \
--header 'Content-Type: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}'
Example Response
GET Location by ID (Payfac)
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}
NOTE: The processing limits that display in the card and echeck sub-objects require Payfac permissions. For more information, contact Forte Technical Support at 888-235-4635 option 3.
This URI returns detailed location data using the location_id.
Example Request
curl --location -g 'https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}'
Example Response
PUT Change Processing Limits (Payfac)
{{baseURI}}/organizations/org_{{organizationID}}/locations/loc_{{locationID}}
NOTE:Â Only partners with special permissions can change processing limits on their merchant’s account. For more information, contact Forte Customer Support at 800-337-3060 option 1.
This URI enables partners to change the daily processing limits for echeck and credit card transactions for a merchant account.
{
"services": {
"echeck": {
"daily_debit" : 1000,
"daily_credit" : 1000,
"monthly_debit" : 50000,
"monthly_credit" : 50000,
"per_trans_debit" : 500.00,
"per_trans_credit" : 500.00
},
"card": {
"daily_debit" : 10000,
"daily_credit" : 10000,
"monthly_debit" : 100000,
"monthly_credit" : 100000,
"per_trans_debit" : 500.00,
"per_trans_credit" : 500.00
}
}
}
Example Request
curl --location -g --request PUT 'https://api.forte.net/v3/organizations/org_{{organizationID}/locations/loc_{{locationID}}' \
--header 'Accept: application/json' \
--header 'Authorization: {{Authorization}}' \
--header 'Content-Type: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_{{AuthOrganizationID}}' \
--data '{
"services": {
"echeck": {
"daily_debit" : 1000,
"daily_credit" : 1000,
"monthly_debit" : 50000,
"monthly_credit" : 50000,
"per_trans_debit" : 500.00,
"per_trans_credit" : 500.00
},
"card": {
"daily_debit" : 10000,
"daily_credit" : 10000,
"monthly_debit" : 100000,
"monthly_credit" : 100000,
"per_trans_debit" : 500.00,
"per_trans_credit" : 500.00
}
}
}'
Example Response
PUT Update a Location's Address
{{baseURI}}/organizations/org_{{organizationID}}/fundings/fnd_{{fundingID}}/settlements
Use this URI to update the following address parameters associated with a location:
street_address1street_address2localityregionpostal_codecountry
When a location’s address is successfully updated, Forte sends an email notification to the location’s primary contact informing him/her of the update.
{
"street_address1": "1200 Clock Tower Lane",
"street_address2": "Suite 500",
"locality": "Hill Valley",
"region": "CA",
"postal_code": "90214",
"country": "US"
}
Example Request
curl --location -g --request PUT 'https://api.forte.net/v3/organizations/org_{{organizationID}}/locations/loc_{{locationID}}' \
--header 'Authorization: {{Authorization}}' \
--header 'Accept: application/json' \
--header 'X-Forte-Auth-Organization-Id: org_300382' \
--header 'Content-Type: application/json' \
--data '{
"street_address1": "1200 Clock Tower Lane",
"street_address2": "Suite 500",
"locality": "Hill Valley",
"region": "CA",
"postal_code": "90214",
"country": "US"
}'
Example Response