Web Services v2

Ready. . .Set. . .Integrate.

NOTE: For the best experience, we recommend upgrading your REST API integration to Version 3.

Introduction

Forte’s REST API allows merchants to perform a variety of powerful tasks, such as querying, retrieving detailed object information, and updating or deleting customer and transaction records. Merchants can access information through standard HTTP methods within a secure and simple-to-integrate architecture. This architecture begins with an Account ID. You can find the Account ID in various places in the REST API as it can denote a home_account_id at the top of a hierarchy of child accounts or a parent account_id where objects live. Forte's REST API offers the following benefits:

  • Simplicity
    Use the existing infrastructure of the web (e.g., web servers, client libraries, caches, etc.) to make integrations simple and fast
  • Access
    Make requests through standard HTTP protocols with any language or on any platform to retrieve information from Forte
  • Flexibility
    Serialize the data through XML or JSON

Base URI

Use the following URI when making REST calls:

  • https://sandbox.forte.net/api/v2 for sandbox testing
  • https://api.forte.net/v2 for production.

Supported Actions

Forte REST web services support the following actions to the defined endpoints.

Action

HTTP Method

Description

Create

POST

Creates the resource that corresponds to the data type defined in the endpoint.

Find

GET

Returns summary information for all the items that match the provided query parameters. To return detailed
information on an item, provide the item's id to the defined endpoint.

Update

PUT

Modifies the existing resource for the provided endpoint.

Delete

DELETE

Deletes the existing resource for the provided endpoint.

Request/Response Formatting

The service supports Content Negotiation using the Accept header sent in the request. The default value for this is "application/json," which returns JSON responses. You can also use "application/xml," which returns XML responses.

The Forte REST API does not support cross-origin resource sharing (CORS).

ID Formatting

Requests and responses require object prefixing followed by an underscore and an ID number or a token. Prefixing identifies the corresponding object and can aid in troubleshooting. Use these prefixing and formatting standards for the following objects:

Object

Prefix

Example

accounts

act_ + ID

act_200000

locations

loc_ + ID

loc_100000

customers

cst_ + Token

cst_SoGUG6mcLUS1nVzYBIbk3g

addresses

add_ + Token

add_jUYRwbRjKUWgswNrFpSdKg

paymethods

mth_ + Token

mth_ymC20TMkHE-YmYxMt0UvMA

transactions

trn_ + GUID

trn_55c98c85-d3e8-4230-85e9-21d7d522eec0

settlements

stl_ + GUID

stl_51cf4633-1767-484f-8784-be76a4076791

schedules

sch_ + GUID

sch_2e5770ae-c120-414f-ae8c-d065753567e7

scheduleitems

sci_+ GUID

sci_4690fbfb-0b77-4477-a066-2c07ca2e5a3c

Hypermedia

The REST service returns the following format for hypermedia responses. Result availability is dependent on the resource/action. NOTE: The following sample of hypermedia responses are merely formatting examples provided for reference.

				
					{
   "links": {
      "self":"/customers?page_index=1",
      "prev":"/customers?page_index=0",
      "next":"/customers?page_index=2",
      "paymethod":"/customers/cst_SoGUG6mcLUS1nVzYBIbk3g/paymethods",
      "transactions":"/customers/cst_SoGUG6mcLUS1nVzYBIbk3g/transactions",
      "addresses":"/customers/cst_SoGUG6mcLUS1nVzYBIbk3g/addresses",
   }
}

Request Filters

Forte REST web services support the following filtering parameters for GET requests without resource IDs (i.e., general resource searches). Use these search filters for all resources. NOTE: Some resources (e.g., transactions and settlements) may have additional filter parameters that you can use to narrow down your search results.

Parameter

Description

Example

orderby

• Sets the order of the results during a search request
• Uses the same fields accepted by the resource_filters
• Can be followed by a space and one of the following values designating the order to use:

       1. asc - ascending (default if not specified)

        2. desc - descending

/settlements?filter=start_settle_date eq '2014-11-20'&orderby=settle_date desc&page_size=2&page_index=0

page_size

• Sets the number of records returned in a page during a search request
• Accepts values between 50 and 1000
• If no value is defined, this parameter uses the default value of 50
• The maximum value of 1000 is used for any values greater than 1000

/transactions?filter=action eq sale &orderby=received_date+desc&page_size=1000&page_index=3

page_index

• Sets the index of the page of results returned during a search request
• Index starts at 0 (zero) and has no upper limit
• The given value must be a positive number
• An index number set to a value higher than the max page value in a search request will return empty search results

/paymethods/??filter=paymethod_type eq card &orderby=name_on_cardasc;page_size=50&page_index=0

When using search filters, the search_criteria object will display in the response and echo back all the resource parameters included in the GET request in the resource_specific object.

Status Codes

Forte's REST web services uses standard HTTP status codes along with messages where appropriate. The table below displays the most common codes:

Code

Text

Description

200

OK

This code indicates a successful HTTP request; the actual response depends on the request method. For example, responses for GET requests contain entities corresponding to the requested resource while responses for POST requests contain entities describing the result of the action.

201

Created

This code indicates that the server has fulfilled the request and has created a new resource.

400

Bad Request or
Failed Transaction

This code indicates that the server cannot fulfill the request because of bad syntax (e.g., a create echeck request with a missing routing number) or the transaction failed (responses for failed transactions also contain the failed transaction information).

401

Unauthorized

This code occurs when the user sends a bad username, password, and/or X-Forte-Auth-Account-Id combination with the request.

404

Not Found

This code occurs when the user attempts an ID GET request, but the ID he/she provides does not exist in the database.

500

Internal Error

This generic error code indicates that the server has encountered an unexpected condition and cannot provide a more specific or suitable error message.

Forte’s REST web services uses standard HTTP status codes along with messages where appropriate. The table below displays the most common codes:

				
					{
   message: "Authentication Account ID in header is missing or invalid."
}
				
			
				
					{
   message: "Payment Method's routing number length is invalid."
}

Integration

To begin the integration process, merchants should contact their Forte representative who will provision their information to a sandbox account. Once provisioned, Forte sends the merchant an Account ID, Location ID, an API Access ID, and an API Secure Key for the sandbox environments. NOTE: The Location ID represents the same information as the Merchant ID in the Virtual Terminal.

Authentication

Forte's REST services rely on Basic access authentication over HTTPS using an API Access ID and an API Secure Key as the username and password values. Forte will assign your APIAccessID and APISecureKey. Then, an HTTP Header field named "Authorization" will be required with data content:

				
					Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==

Additionally, user agents must authenticate their Account IDs using the custom header property X-Forte-Auth-Account-Id (e.g., act_nnnnnn). NOTE: A user who authenticates his or her account in the X-Forte-Auth-Account-Id header property can access sub-accounts through the Account ID listed in the route of the resource

Authenticating Requests

HMAC requests must be Base64 encoded, which converts the request into a simple ASCII string that you can attach to the request. To add Base64 encoding, use the following code:

				
					Convert.ToBase64String(Encoding.Default.GetBytes(APIAccessID + ":" + APISecureKey)).Trim()

If you’re including the authentication request directly into the URI, you must encode the plus sign character (+) using %2B; and the forward slash character (/) using %2F; .

Responses

Forte includes the response subobject in responses for POST and PUT operations to the transactions, customers, paymethods, and addresses resources. NOTE: Forte returns the response_desc and environment parameters for all resources; the remaining parameters are returned for the transactions resource only.

response Object

Parameter

Description

response_desc

A short description of the action's response. All resources use this parameter.

environment

The environment in which the user made the request. The value for this field can be either live or sandbox. All
resources use this parameter.

authorization_code

The code indicating the transaction was authorized. This field is not used for voiding transactions

response_type

The type of response this action generated.

response_code

The response code of the action.

preauth_result

The result of the pre-authorization attempt on the transaction.

preauth_description

A short description of the transaction's pre-authorization attempt.

preauth_neg_report

Indicates whether the pre-authorization attempt contains a negative report.

avs_result

Forte only returns this field if the merchant passes any combination of billing address parameters from the physical_address object in the request. To test this service in the Sandbox environment, see the testing parameters
in the FAQ and Response Codes section. Supported values for this field include the following:


• X = Match: Street Address and 9-digit Zip Code both match


• Y = Match: Street Address and 5-digit Zip Code both match


• A = Partial Match: Street Address matches, but both 5-digit and 9-digit Zip Code do not match


• W = Partial Match: Street Address does not match, but 9-digit Zip Code matches


• Z = Partial Match: Street Address does not match, but 5-digit Zip Code matches


• N = No Match: Street Address, 5-digit Zip Code, and 9-digit Zip Code all do not match


• U = System Unavailable: Address information unavailable. Forte returns this response if the Street Address is a non-US address, if the AVS service is unavailable, or if the AVS service for a particular US bank is not properly functioning.


• R = System Unavailable: Forte will retry the AVS check because the issuer's system is unavailable or the request times out.


• E = Invalid: AVS data is invalid


• S = Not Supported: The US issuing bank does not support AVS checks.

cvv_code

The card verification value response. Supported values for this field include the following:


• M = Match


• N = No Match


• E = Error (Unrecognized or Unknown Response)


• I = Invalid or Null


• P = Not Processed


• S = Service Not Supported


• U = Issuer Unable to Process


• X = No Response

available_card_balance

The available balance on the credit card if a credit card is used for the transaction.

requested_amount

The transaction amount

Webhooks

NOTE: Currently, Forte IT must configure webhooks.

Webhooks provide near-real-time notifications about the events that occur during a transaction through POSTs to a customer-defined endpoint. Forte notifies merchants about events through subscriptions. Depending on these subscriptions, multiple events can occur during an operation. For example, a POST transaction request that creates tokens for a customer and a paymethod causes three events to be fired: transaction.sale, customer.create, and paymethod.create. These three events can be combined under a common event ID (e.g., evt_xxxxxx) for easier information management. NOTE: Depending on how you configure your event subscriptions, the same data may be generated twice in separate webhooks. For example, a POST to the customer object that includes the creation of a paymethod could (if subscribed) generate a customer webhook with both customer and paymethod data as well as a paymethod webhook.

If a webhook post fails (i.e., does not result in an HTTP 200 response), Forte retries the webhook post up to twenty times adding one minute for each retry.

The following code samples display example webhooks for common operations.

Example - Webhook Payloads
Sale Transaction Webhook
				
					{  
  "location_id":"124125",
  "account_id":"300005",
  "event_id":"evt_N5blR1nLqEe4VAH6Sou64A",
  "transaction":{  
     "transaction_id":"trn_cc2435ad-b80f-4059-b437-0831857842da",
     "location_id":"loc_124125",
     "action":"sale",
     "authorization_amount":8.1,
     "sales_tax_amount":5.1,
     "service_fee_amount":0.0,
     "authorization_code":"123456",
     "entered_by":"Biff Tannen",
     "received_date":"2015-05-04T17:36:08.489Z",
     "billing_address":{  
        "first_name":"Marty",
        "last_name":"McFly",
        "company_name":"Brown Associates",
        "physical_address":{  
           "street_line1":"2101 DeLorean Way",
           "locality":"Hill Valley",
           "region":"CA",
           "postal_code":"95420"
        }
     },
     "shipping_address":{  
        "company_name":"Brown Associates",
        "physical_address":{  
           "street_line1":"2102 Delorean Way",
           "locality":"Hill Valley",
           "region":"CA",
           "postal_code":"95420"
        }
     },
     "echeck":{  
        "account_holder":"Brown Associates"
     },
     "response":{  
        "response_type":"A",
        "response_code":"A01",
        "response_desc":"APPROVED"
     },
     "links":{  
        "self":"https://api.forte.net/v2/transactions/trn_cc2435ad-b80f-4059-b437-0831857842da",
        "settlements":"https://api.forte.net/v2/transactions/trn_cc2435ad-b80f-4059-b437-0831857842da/settlements"
     }
  },
  "source":"RESTAPI",
  "type":"transaction.sale",
  "environment":"live"
}
Customer Webhook
				
					{  
  "location_id":"124125",
  "event_id":"evt_H7DBFDm3IEWOzH5zzwyKJA",
  "customer":{  
     "customer_token":"cst_Yay0gm3vP0GS7G0NPMh7RQ",
     "location_id":"loc_124125",
     "first_name":"Jennifer",
     "last_name":"McFly",
     "company_name":"Brown Associates",
     "addresses":[  
        {  
          "address_token":"add_qfRWidQmJk2ReYGDV5z8GA",
          "location_id":"loc_124125",
          "customer_token":"cst_Yay0gm3vP0GS7G0NPMh7RQ",
          "first_name":"Jennifer",
          "last_name":"McFly",
          "company_name":"Brown Associates",
          "phone":"2145565747",
          "fax":"2148876565",
          "email":"jennifer.mcfly@brownassociates.com",
          "label":"billing",
          "address_type":"default_billing",
          "physical_address":{  
             "street_line1":"8003 Clock Tower Ln",
             "locality":"Hill Valley",
             "region":"CA",
             "postal_code":"95420"
          },
          "links":{  
             "self":"https://api.forte.net/v2/addresses/add_qfRWidQmJk2ReYGDV5z8GA"
          }
       },
       {  
          "address_token":"add_7tKyzLLA3k2xwiyxgbbVLw",
          "location_id":"loc_124125",
          "customer_token":"cst_Yay0gm3vP0GS7G0NPMh7RQ",
          "first_name":"Jennifer",
          "last_name":"McFly",
          "company_name":"Brown Associates",
          "phone":"2145565747",
          "fax":"2148876565",
          "email":"mcflyshipping@brownassociates.com",
          "label":"shipping",
          "address_type":"default_shipping",
          "physical_address":{  
             "street_line1":"2110 DeLorean Drive",
             "locality":"Hill Valley",
             "region":"CA",
             "postal_code":"95420"
          },
          "links":{  
             "self":"https://api.forte.net/v2/addresses/add_7tKyzLLA3k2xwiyxgbbVLw"
          }
       }
    ],
    "paymethod":{  
       "paymethod_token":"mth_cQsUjApw1k6d4o_8cT_5TQ",
       "location_id":"loc_124125",
       "customer_token":"cst_Yay0gm3vP0GS7G0NPMh7RQ",
       "echeck":{  
          "account_holder":"Jennifer McFly",
          "masked_account_number":"************",
          "routing_number":"211170101",
          "account_type":"checking",
          "check_number":"444"
      },
      "links":{  
         "self":"https://api.forte.net/v2/paymethods/mth_cQsUjApw1k6d4o_8cT_5TQ"
      }
   },
   "links":{  
      "self":"https://api.forte.net/v2/customers/cst_Yay0gm3vP0GS7G0NPMh7RQ",
      "addresses":"https://api.forte.net/v2/customers/cst_Yay0gm3vP0GS7G0NPMh7RQ/addresses",
      "paymethods":"https://api.forte.net/v2/customers/cst_Yay0gm3vP0GS7G0NPMh7RQ/paymethods",
      "transactions":"https://api.forte.net/v2/customers/cst_Yay0gm3vP0GS7G0NPMh7RQ/transactions",
      "settlements":"https://api.forte.net/v2/customers/cst_Yay0gm3vP0GS7G0NPMh7RQ/settlements"
   }
 },
 "source":"RESTAPI",
 "type":"customer.create",
 "environment":"live"
}
Payment Method Webhook
				
					{
  "location_id":"124125",
  "event_id":"evt_KuySXGizEk2LHdCNLXDK9w",
  "paymethod":{
     "paymethod_token":"mth_cQsUjApw1k6d4o_8cT_5TQ",
     "location_id":"loc_124125",
     "customer_token":"cst_Yay0gm3vP0GS7G0NPMh7RQ",
     "echeck":{
        "account_holder":"Marty McFly",
        "masked_account_number":"************",
        "routing_number":"211170101",
        "account_type":"checking",
        "check_number":"444"
     },
     "links":{
        "self":"https://api.forte.net/v2/paymethods/mth_cQsUjApw1k6d4o_8cT_5TQ"
     }
  },
  "source":"RESTAPI",
  "type":"payment.create",
  "environment":"live"
}

Testing

To help you gain a greater understanding of how Forte's REST API works, we've built a Postman collection of sample REST requests based on the examples displayed for each request type in each resource section below. To import the collection of requests and really dig into Forte's robust version 2 REST API, simple click:

Resource Descriptions

Transactions

The transaction object represents transaction(s) with a merchant's location. The transaction object includes the customer , card, echeck, and settlement sub-objects. Token-based transactions will use the default addresses. Token payments require you to set the customer's default shipping and billing addresses prior to passing the transaction data. The transaction object supports both Canadian and U.S.-based addresses and payment methods. For more information on how to correctly format Canadian routing numbers see the echeck object.

Schedules

The schedule object represents scheduled transactions for a merchant's account or location. Merchants can specify a particular quantity of scheduled transactions or can set up continuous transactions that will occur until the schedule is suspended or deleted. Scheduled transactions can only be created with the customer_token and paymethod_token values.

Scheduleitems

The scheduleitems object represents the planned individual transactions that make up a schedule. This object enables merchants to create and make one-time adjustments to a scheduled transaction such as the amount or status of the transaction.

Settlements

The settlement object represents the status of transactions within a merchant's location. GET requests to this endpoint can be filtered according to settlement date, response, and method.

Customers

The customer object represents a customer's information and enables the merchant to create, maintain, and retrieve customer data that can be tokenized for a more efficient checkout process.

Addresses

The address object represents the customer's billing and/or shipping addresses.

Paymethods

The paymethod object represents a customer's form of payment—be it a credit card or an echeck. This object enables the merchant to tokenize the customer's payment information within Forte's secure data vault. These paymethod tokens can be used to streamline the checkout process for repeat customers or to handle recurring payments without the need to store a customer's sensitive payment information on your own servers. The paymethod object supports both Canadian and U.S.-based credit cards and echecks. For more information on how to correctly format Canadian routing numbers see the echeck object.

Transactions

Create and maintain customer transaction data with the transaction object using the following input parameters and code samples.

transaction Object

Parameter

Description

Req

account_id

The identification number of the associated account. For example, act_5551236.

Required

location_id

The merchant's six-digit ID code.

Required

action

The supported transaction types include the following values:


• sale - Used to collect funds from a debit/credit card or bank account. Same as an Authorization + Capture operation in just one step.


• authorize - Used to verify the account information (bank account or debit/credit card account) specified.


• disburse - Used to send funds back to a bank account or credit/debit card


• void - Used to stop a transaction or cancel the hold on a Transaction that was Authorized. Voids can only be performed on items that haven’t yet originated (for echeck transactions) or settled (for credit card transactions).


• capture - Used to collect the funds that was previously authorized. See authorize.


• inquiry - Requests the available balance from a card. NOTE: This action is only for merchant accounts approved to process partial authorization transactions.


• verify - Used to verify a bank account or card account when there isn’t a need to perform a Capture operation later.


• force - Used to capture funds bypassing verification or authorization functionality. Forces should have been verified or authorized prior to being performed.


• reverse - Used to reverse a previous sale transaction if it’s too late to void. Reversed sales will have a disbursement performed. A reverse can only be performed on original sale transactions.

Required

customer_token

A unique string used to represent a customer. For example, cst_SoGUG6mcLUS1nVzYBIbk3g. Transactions can be created using only a customer_token (i.e., the merchant does not need to pass the paymethod object or a paymethod_token) if the customer has defined a default_paymethod_token in the customer object.
[max length = 26]

Optional

customer_id

A merchant-defined string created at the customer level to identify the customer.

Optional

paymethod_token

A unique string used to represent a payment method. For example, mth_1578436587.
[max length = 26]

Optional

reference_id

A merchant-defined string that identifies the transaction.

Optional

authorization_amount

The amount to be charged/credited to the customer.

Required

order_number

A merchant-assigned ID code that is returned with the transaction response.

Optional

original_transaction_id

The trace number returned by the original transaction.

Optional

transaction_id

A 36-character code that uniquely identifies the transaction.

Optional

authorization_code

An approval code from a vendor that authorizes a merchant to void a transaction.

Optional

entered_by

The name or the ID of the person entering the data.

Optional

received_date

The date the merchant received the transaction

Optional
(Return only)

origination_date

The date the funds of the transaction go to the originating depository financial institution.

Optional
(Return only)

sales_tax_amount

The sales tax amount. This field is only required for procurement card transactions.

Optional

service_fee_amount

The service fee (i.e., convenience fee) for this transaction. Use the following definitions when calculating a service fee


• Original Amount = The base amount for calculating the convenience fee


• service_fee_amount = The percentage calculated


• authorization_amount = The resulting sum of the Original Amount and the service_fee_amount
 

For a service fee of 2.45% for example, you will need to follow the scenario below:

service_fee_amount = original amount * 2.45%


authorization_amount = service_fee_amount + original amount


The Create Transaction - Credit Card code sample provides an example of a service fee calculation.

Optional

billing_address

The Address Object

Required

shipping_address

The Address Object

Optional

card

The card Object

Required

echeck

The echeck Object

Required

line_items

The line_items Object

Optional

xdata

The xdata Object

Optional

Info: When a merchant passes a customer token with a transaction, Forte ignores the stored default values in favor of any inline values the merchant passes in.

card Object

The transaction cards object contains the following parameters

Parameter

Description

Req

card_type

The type of credit card [max length = 4]. Options for this field include the following:


• visa
• mast
• amex
• disc
• dine
• jcb

Required

name_on_card

The name printed on the credit card [max length = 50]. This field is required when creating a new record or creating a permanent token from a one-time token.

Required

last_4_account_number

The last four digits of the redacted account number. This field is return only. [max length = 4]

----

account_number

The card number. This field is required when creating a new record and can only contain digits. Forte echoes this parameter in the card.masked_account_number response parameter. [max length = 19].

Required

expire_month

The expiration month. This field is required when creating a new record and must be a valid future date. [max length = 2].

Required

expire_year

The expiration year. This field is required when creating a new record and must be a valid future date. [max length = 4].

Required

card_verification_value

The card verification number. Forte does not store this field with the paymethod token, but echoes it back. [max length = 5].

Required

procurement_card

Indicates whether or not this is a procurement card transaction. Accepted values are either true or false. For procurement card transactions, merchants must pass the customer_accounting_code field in the card object and the sales_tax_amount field in the transaction object. [max length = 5].

Optional

customer_accounting_code

Lists the procurement card accounting code. Forte does not save this information if the merchant is creating a paymethod. [max length = 17]

Optional

one_time_token

A single use token generated by Forte.js (e.g., ott_g7vnjqikszabzynu6eowbq).

Optional

card_reader

The eight-digit device part number specifying which swipe device was used to capture the card data. Currently, only the following models and part numbers are supported when capturing encrypted card data:

• 30050202 (IPAD)

• 30050203 (IPAD PIN Pad and Card Reader)

• 21073062 (Dynamag)

• 21073084 (iDynamo - used for iPhone mobile apps)

• 21073131 (iDynamo 5 (lightening adapter) - used for iPhone mobile apps)

• 21073092 (uDynamo - used for Android mobile apps)

• 21079802 (eDynamo)
[max length = 20]

Optional

card_data

The full set of swipe data received from the encrypting swipe device. [max length = 1500]

Optional

card_emv_data

The full set of emv data received from the emv device. [max length = 1500]

Optional

fallback_swipe

Indicates if this swiped transaction is a fallback swipe after a dipped transaction failed to process. Accepted values are either true or false [max length = 5]

Optional

echeck Object

The transaction echecks object contains the following parameters.

Parameter

Description

Req

account_holder

The name of the account owner. This field is required when creating or updating a new record.

Optional

account_number

The DDA or eCheck account number. This field is required when creating or updating a new record and can only contain digits.

Optional

routing_number

The transit routing number. This field supports both U.S. and Canadian routing numbers. NOTE: A Canadian routing number displayed on a check needs to be reformatted differently for electronic payments. If a check displays a routing number as BBBBB-AAA (where AAA indicates the Financial Institution and BBBBB is the branch), then the routing number must be changed to 0AAABBBBB to process the payment electronically. For example, if a check from an account issued by the Bank of Montreal showed the routing number 00011-001, then that number would need to be reformatted to 000100011 for the payment to be electronically processed. Click here for a directory of Canadian financial institutions.


This field is required when creating or updating a new record and can only contain digits.
[max length = 9]

Optional

account_type

Use one of the following values for this parameter:

a. Checking


b. Savings

Optional

check_number

The customer's check number. NOTE: This field is only available for transactions and is not included in the Paymethods object.

Optional

sec_code

Use one of the following values for this standard-entry class code: 

ARC, CCD, CIE, CTX, POP, POS, PPD, RCK, TEL, WEB.


For more information on these codes, see Using ACH and SEC Return Codes. While this parameter is optional for REST echeck transactions, Forte recommends passing it to conform to a NACHA requirement that states when submitting a transaction for processing, the originator must designate how the transaction was authorized. Forte customers primarily use the PPD, CCD, and WEB SEC codes.

Optional

line_items Object

The transaction line_items object contains the following parameters. Merchants can include up to 100 line item fields.

Parameter

Description

Req

line_item_header

Description of the data elements contained within each line item. This header will be displayed when viewing transaction details.

Optional

line_item_1

Contents of the line item formatted according to the line_item_header.

Optional

line_item_100

Contents of the line item formatted according to the line_item_header.

Optional

xdata Object

The transaction xdata object contains the following parameters. Merchants can include up to nine fields of extra data that they can associate with a schedule or transaction.

Parameter

Description

Req

xdata_1

Up to nine fields (1-9) of extra data that can be associated with a schedule or transaction. Each xdata_# field can contain up to 255 characters.

Optional

Find Transactions

Use the following endpoints to find transactions.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/transactions

Returns all transactions for a location. Use the filters in the filter table to narrow down your search results.

NOTES:

• Searches using origination_date filters will only yield results for echeck transactions.


• To find transactions within a specified date range: 
start_received_date, end_received_date, start_origination_date, and end_origination_date


• To find transactions from a single day:
received_date, origination_date


• Date range filters must include both the start and end date parameters; otherwise, the system uses a default 90-day date range from the provided date parameter or, when no date parameter is provided, from the current date.

/accounts/{account_id}/locations/{location_id}/transactions/{action}

Returns the following transactions types (actions) for a location:

• sale
• disburse
• authorize
• verify
i• nquiry

/accounts/{account_id}/locations/{location_id}/transactions/{transaction_id}

Returns transaction object detail

/accounts/{account_id}/locations/{location_id}/customers/{customer_token}/transactions

Returns all transactions for a customer

To narrow your search data using specific criteria, use the following parameters with the endpoints above to filter your results:

Filter Parameter

Example

account_id

/accounts/{account_id}/locations/{location_id}/transactions/?filter=account_id+eq+act_300005

location_id

/accounts/{account_id}/locations/{location_id}/transactions/?filter=location_id+eq+loc_115161

start_received_date/
end_recevied_date

/accounts/{account_id}/locations/{location_id}/transactions/?filter=start_received_date+eq+
'2002-01-08'+and+end_received_date+eq+'2013-12-08'

start_origination_date/
end_origination_date

/accounts/{account_id}/locations/{location_id}/transactions/?filter=start_origination_date+eq+
'2002-01-08'+and+end_origination_date+eq+'2013-12-08'

received_date

/accounts/{account_id}/locations/{location_id}/transactions/?filter=received_date+eq+'2002-01-08'

origination_date

/accounts/{account_id}/locations/{location_id}/transactions/?filter=origination_date+eq+'2002-01-08'

customer_token

/accounts/{account_id}/locations/{location_id}/transactions/?filter=customer_token+eq+
cst_6cHpUhBG_02bIb4SXxOm5A

paymethod_token

/accounts/{account_id}/locations/{location_id}/transactions/?filter=paymethod_token+eq+
mth_LCaCk2jdLUOfdrPxtsgjWA

original_transaction_id

/accounts/{account_id}/locations/{location_id}/transactions/?filter=original_transaction_id+eq+
trn_2c2261e9-e506-4178-810b-699614bf741e

customer_id

/accounts/{account_id}/locations/{location_id}/transactions/?filter=customer_id+eq+000012359864

order_number

/accounts/{account_id}/locations/{location_id}/transactions/?filter=order_number+eq+12AFE968-09

reference_id

/accounts/{account_id}/locations/{location_id}/transactions/?filter=reference_id+eq+123456789

status

/accounts/{account_id}/locations/{location_id}/transactions/?filter=status+eq+voided

action

/accounts/{account_id}/locations/{location_id}/transactions/?filter=action+eq+sale

authorization_amount

/accounts/{account_id}/locations/{location_id}/transactions/?filter=authorization_amount+eq+501.23

entered_by

/accounts/{account_id}/locations/{location_id}/transactions/?filter=entered_by+eq+GriffTannen123

bill_to_company_name

/accounts/{account_id}/locations/{location_id}/transactions/?filter=bill_to_company_name+eq+'MJF Productions'

bill_to_first_name

/accounts/{account_id}/locations/{location_id}/transactions/?filter=bill_to_first_name+eq+Marty

bill_to_last_name

/accounts/{account_id}/locations/{location_id}/transactions/?filter=paymethod_type+eq+card

/accounts/{account_id}/locations/{location_id}/transactions/?filter=paymethod_type+eq+echeck

paymethod_type

/accounts/{account_id}/locations/{location_id}/transactions/?filter=paymethod_type+eq+card

/accounts/{account_id}/locations/{location_id}/transactions/?filter=paymethod_type+eq+echeck

last_4_account_number

/accounts/{account_id}/locations/{location_id}/transactions/?filter=last_4_account_number+eq+'1111'

The following code samples display example endpoints and GET calls you can use to find a transaction.

POST

/accounts/act_300005/locations/loc_115161/transactions

Request (eCheck)
				
					{
  "action":"sale",
  "authorization_amount": 240.52,
  "billing_address":{
    "first_name": "Marty",
    "last_name": "McFly"
  },
    "echeck":{
       "sec_code": "WEB",
       "account_type": "Checking",
       "routing_number": "021000021",
       "account_number": "000111222",
       "account_holder": "Marty McFly"
     }
}
Request (Credit Card)
				
					{
  "action":"sale",
  "authorization_amount": 102.45,
  "service_fee_amount": 2.45,
  "billing_address":{
    "first_name": "Jennifer",
    "last_name": "McFly"
  },
    "card":{
      "card_type": "visa",
      "name_on_card": "Jennifer McFly",
      "account_number": "4111111111111111",
      "expire_month": "12",
      "expire_year": "2017",
      "card_verification_value":"123"
    }
}
Response (eCheck)
				
					{
  "transaction_id": "trn_e311647a-98f5-43dc-92c0-7c40d097f04f",
  "location_id": "loc_115161",
  "action": "sale",
  "authorization_amount": 240.52,
  "authorization_code": "84257270",
  "billing_address": {
    "first_name": "Marty",
    "last_name": "McFly"
  },
    "echeck": {
      "account_holder": "Marty McFly",
      "masked_account_number": "****1222",
      "routing_number": "021000021",
      "account_type": "checking",
      "sec_code": "WEB"
    },
   "response": {
     "authorization_code": "84257270",
     "preauth_result": "POS",
     "preauth_desc": "P70:VALIDATED",
     "environment": "live",
     "response_type": "A",
     "response_code": "A01",
     "response_desc": "APPROVED"
   },
  "links": {
    "self": "/v2/transactions/trn_e311647a-98f5-43dc-92c0-7c40d097f04f",
    "settlements": "/v2/transactions/trn_e311647a-98f5-43dc-92c0-7c40d097f04f/settlements"
   }
 }
Response (Credit Card)
				
					{
  "transaction_id": "trn_d17b6bfa-5ee1-44ef-a7f6-16c43478414a",
  "location_id": "loc_115161",
  "action": "sale",
  "authorization_amount": 102.45,
  "service_fee_amount": 2.45
  "authorization_code": "123456",
  "billing_address": {
    "first_name": "Jennifer",
    "last_name": "McFly"
  },
    "card": {
      "name_on_card": "Jennifer McFly",
      "masked_account_number": "****1111",
      "expire_month": 12,
      "expire_year": 2017,
      "card_verification_value": "***",
      "card_type": "visa"
    },
   "response": {
     "authorization_code": "123456",
     "avs_result": "Y",
     "cvv_code": "M",
     "environment": "live",
     "response_type": "A",
     "response_code": "A01",
     "response_desc": "APPROVED"
   },
  "links": {
    "self": "/v2/transactions/trn_d17b6bfa-5ee1-44ef-a7f6-16c43478414a",
    "settlements": "/v2/transactions/trn_d17b6bfa-5ee1-44ef-a7f6-16c43478414a/settlements"
  }
}
GET

/accounts/act_300005/locations/loc_115161/transactions/trn_986cad51-854b-4e42-bd83-39de91042758

Response
				
					{
  "transaction_id": "trn_986cad51-854b-4e42-bd83-39de91042758",
  "account_id": "act_300005",
  "location_id": "loc_115161",
  "original_transaction_id": "",
  "customer_id": "",
  "order_number": "",
  "reference_id": "",
  "action": "sale",
  "authorization_amount": 11.0,
  "sales_tax_amount": 10.0,
  "service_fee_amount": 0.0,
  "authorization_code": "163434",
  "entered_by": "",
  "customer_accounting_code": "123456",
  "received_date": "2015-01-01T04:14:09.29",
  "billing_address": {
    "first_name": "John",
    "last_name": "Smith",
    "company_name": "",
    "physical_address": {
      "street_line1": "12115 Lackland",
      "street_line2": "",
      "locality": "",
      "region": "",
      "postal_code": "63146"
    }
  },
  "card": {
    "name_on_card": "",
    "masked_account_number": "*******4507",
    "card_type": "visa"
  },
  "settlements": [],
  "response": {
    "environment": "live",
    "response_type": "A",
    "response_code": "A01",
    "response_desc": "Get Successful."
  },
  "links": {
    "self": "/v2/accounts/act_300005/locations/loc_115161/transactions/trn_986cad51-854b
    -4e42-bd83-39de91042758",
    "settlements": "/v2/accounts/act_300005/locations/loc_115161/transactions/trn_986cad51
    -854b-4e42-bd83-39de91042758/settlements"
  } 
}
POST

/accounts/act_300005/locations/loc_115161/transactions/

Request
				
					{
  "action":"sale",
  "customer_token":"cst_SoGUG6mcLUS1nVzYBIbk3g",
  "paymethod_token":"mth_ymC20TMkHE-YmYxMt0UvMA",
  "reference_id": "000159",
  "authorization_amount": 1.00,
  "entered_by":"Griff Tannen",
  "sales_tax_amount": 0.25,
  "xdata":{
    "xdata_1":"Branch 00189",
    "xdata_2":"Hill Valley, CA",
    "xdata_3":"Region WEST"
  }
}
Response
				
					{
  "transaction_id": "trn_b17fdf19-6205-476e-80ec-6f50e1ac5ad4",
  "location_id": "loc_115161",
  "customer_token": "cst_SoGUG6mcLUS1nVzYBIbk3g",
  "paymethod_token": "mth_ymC20TMkHE-YmYxMt0UvMA",
  "reference_id": "000159",
  "action": "sale",
  "authorization_amount": 10.00,
  "sales_tax_amount": 0.25,
  "authorization_code": "123456",
  "entered_by": "Griff Tannen",
  "xdata": {
    "xdata_1": "Branch 00189",
    "xdata_2": "Hill Valley, CA",
    "xdata_3": "Region WEST"
   },
  "response": {
    "authorization_code": "123456",
    "avs_result": "Y",
    "cvv_code": "M",
    "environment": "live",
    "response_type": "A",
    "response_code": "A01",
    "response_desc": "TEST APPROVAL"
   },
  "links": {
    "self": "/v2/transactions/trn_b17fdf19-6205-476e-80ec-6f50e1ac5ad4",
    "settlements": "/v2/transactions/trn_b17fdf19-6205-476e-80ec-6f50e1ac5ad4/settlements"
   }
}
Create Transactions

Use the following endpoints to create transactions.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/transactions

This endpoint can perform the following tasks while returning a new Transaction ID:

Create an ad-hoc transaction


• Create a transaction based on the customer token using the default billing address


• Create a transaction based on the customer and paymethod tokens using the customer default billing address


• Create a transaction based on the paymethod token, which requires the address in the message


• Reverse a sale transaction and create a credit transaction, which requires the transaction ID and authorization code of the original transaction

/accounts/{account_id}/transactions

This endpoint can perform the same tasks listed above; however, the data that the user passes in must specify a location_id. For example, if the user was creating an ad-hoc transaction, he or she would also need to pass in the location_id parameter.

/accounts/{account_id}/locations/{location_id}/transactions/{action}

Creates the following transactions types (actions) for a location:

• sale
• disburse
• authorize
• verify
• inquiry
• force

The following code samples display example endpoints and POST calls you can use to create a transaction.

POST

/accounts/act_300005/locations/loc_115161/transactions

Request (eCheck)
				
					{
  "action":"sale",
  "authorization_amount": 240.52,
  "billing_address":{
    "first_name": "Marty",
    "last_name": "McFly"
  },
    "echeck":{
       "sec_code": "WEB",
       "account_type": "Checking",
       "routing_number": "021000021",
       "account_number": "000111222",
       "account_holder": "Marty McFly"
     }
}
Request (Credit Card)
				
					{
  "action":"sale",
  "authorization_amount": 102.45,
  "service_fee_amount": 2.45,
  "billing_address":{
    "first_name": "Jennifer",
    "last_name": "McFly"
  },
    "card":{
      "card_type": "visa",
      "name_on_card": "Jennifer McFly",
      "account_number": "4111111111111111",
      "expire_month": "12",
      "expire_year": "2017",
      "card_verification_value":"123"
    }
}
Response (eCheck)
				
					{
  "transaction_id": "trn_e311647a-98f5-43dc-92c0-7c40d097f04f",
  "location_id": "loc_115161",
  "action": "sale",
  "authorization_amount": 240.52,
  "authorization_code": "84257270",
  "billing_address": {
    "first_name": "Marty",
    "last_name": "McFly"
  },
    "echeck": {
      "account_holder": "Marty McFly",
      "masked_account_number": "****1222",
      "routing_number": "021000021",
      "account_type": "checking",
      "sec_code": "WEB"
    },
   "response": {
     "authorization_code": "84257270",
     "preauth_result": "POS",
     "preauth_desc": "P70:VALIDATED",
     "environment": "live",
     "response_type": "A",
     "response_code": "A01",
     "response_desc": "APPROVED"
   },
  "links": {
    "self": "/v2/transactions/trn_e311647a-98f5-43dc-92c0-7c40d097f04f",
    "settlements": "/v2/transactions/trn_e311647a-98f5-43dc-92c0-7c40d097f04f/settlements"
   }
 }
Response (Credit Card)
				
					{
  "transaction_id": "trn_d17b6bfa-5ee1-44ef-a7f6-16c43478414a",
  "location_id": "loc_115161",
  "action": "sale",
  "authorization_amount": 102.45,
  "service_fee_amount": 2.45
  "authorization_code": "123456",
  "billing_address": {
    "first_name": "Jennifer",
    "last_name": "McFly"
  },
    "card": {
      "name_on_card": "Jennifer McFly",
      "masked_account_number": "****1111",
      "expire_month": 12,
      "expire_year": 2017,
      "card_verification_value": "***",
      "card_type": "visa"
    },
   "response": {
     "authorization_code": "123456",
     "avs_result": "Y",
     "cvv_code": "M",
     "environment": "live",
     "response_type": "A",
     "response_code": "A01",
     "response_desc": "APPROVED"
   },
  "links": {
    "self": "/v2/transactions/trn_d17b6bfa-5ee1-44ef-a7f6-16c43478414a",
    "settlements": "/v2/transactions/trn_d17b6bfa-5ee1-44ef-a7f6-16c43478414a/settlements"
  }
}
POST

/accounts/act_300005/locations/loc_115161/transactions/

Request
				
					{
  "action":"sale",
  "authorization_amount": 109.49,
  "billing_address":{
    "first_name": "Emmett",
    "last_name": "Brown"
  },
    "echeck":{
       "sec_code": "WEB",
       "account_type": "Checking",
       "routing_number": "021000021",
       "account_number": "000111222",
       "account_holder": "Emmett Brown"
  },
   "line_items":{
       "line_item_header":"SKU,Price,Qty",
       "line_item_1":"021000021,45.00,2",
       "line_item_2":"021000022,36.99,10",
       "line_item_3":"021000023,27.50,7"
  }
}
Response
				
					{
  "transaction_id": "trn_20a1e506-711b-40d7-86d2-131f46f78bc8",
  "location_id": "loc_115161",
  "action": "sale",
  "authorization_amount": 109.49,
  "authorization_code": "123456",
  "billing_address": {
    "first_name": "Emmett",
    "last_name": "Brown"
   },
  "echeck": {
    "account_holder": "Emmett Brown",
    "masked_account_number": "****1222",
    "routing_number": "021000021",
    "account_type": "***",
    "card_type": "checking",
    "sec_code": "WEB"
   },
  "line_items": {
    "line_item_header": "SKU,Price,Qty",
    "line_item_1": "021000021,45.00,2",
    "line_item_2": "021000022,36.99,10",
    "line_item_3": "021000023,27.50,7"
   },
  "response": {
    "authorization_code": "123456",
    "preauth_result": "POS",
    "preauth_desc": "P70:VALIDATED",
    "environment": "live",
    "response_type": "A",
    "response_code": "A01",
    "response_desc": "APPROVED."
   },
  "links": {
    "self": "/v2/transactions/trn_20a1e506-711b-40d7-86d2-131f46f78bc8",
    "settlements": "/v2/transactions/trn_20a1e506-711b-40d7-86d2-131f46f78bc8/settlements"
  }
}
POST

/accounts/act_300005/locations/loc_115161/transactions/

Request
				
					{
  "action":"sale",
  "customer_token":"cst_SoGUG6mcLUS1nVzYBIbk3g",
  "paymethod_token":"mth_ymC20TMkHE-YmYxMt0UvMA",
  "reference_id": "000159",
  "authorization_amount": 1.00,
  "entered_by":"Griff Tannen",
  "sales_tax_amount": 0.25,
  "xdata":{
    "xdata_1":"Branch 00189",
    "xdata_2":"Hill Valley, CA",
    "xdata_3":"Region WEST"
  }
}
Response
				
					{
  "transaction_id": "trn_b17fdf19-6205-476e-80ec-6f50e1ac5ad4",
  "location_id": "loc_115161",
  "customer_token": "cst_SoGUG6mcLUS1nVzYBIbk3g",
  "paymethod_token": "mth_ymC20TMkHE-YmYxMt0UvMA",
  "reference_id": "000159",
  "action": "sale",
  "authorization_amount": 10.00,
  "sales_tax_amount": 0.25,
  "authorization_code": "123456",
  "entered_by": "Griff Tannen",
  "xdata": {
    "xdata_1": "Branch 00189",
    "xdata_2": "Hill Valley, CA",
    "xdata_3": "Region WEST"
   },
  "response": {
    "authorization_code": "123456",
    "avs_result": "Y",
    "cvv_code": "M",
    "environment": "live",
    "response_type": "A",
    "response_code": "A01",
    "response_desc": "TEST APPROVAL"
   },
  "links": {
    "self": "/v2/transactions/trn_b17fdf19-6205-476e-80ec-6f50e1ac5ad4",
    "settlements": "/v2/transactions/trn_b17fdf19-6205-476e-80ec-6f50e1ac5ad4/settlements"
   }
}
POST

/accounts/act_300005/locations/loc_115161/transactions/

Request
				
					{
   "action":"reverse", 
   "authorization_amount":1.00,
   "original_transaction_id":"trn_4bcfa57d-18e9-456e-8ce0-da7eb3a4f37d",
   "authorization_code":"123456"
}
Response
				
					{
  "transaction_id":"trn_4aa187d1-330a-4993-96a0-3d83f321c5d4"
  "original_transaction_id":"trn_4bcfa57d-18e9-456e-8ce0-da7eb3a4f37d",
  "customer_id": "delorean122182",
  "location_id": "loc_115161",
  "action":"reverse",
  "authorization_amount": 1.00,
  "authorization_code":"123456",
  "response": {
    "environment": "live",
    "response_type":"A",
    "response_code":"A01",
    "response_desc": "APPROVED"
  },
"links":{
   "self":"/API/v2/accounts/act_300005/locations/loc_115161/transactions/trn_4aa187d1-330a-4993-
   96a0-3d83f321c5d4",
   "settlements": "https://api.forte.net/v2/transactions/trn_4aa187d1-330a-4993-96a0-3d83f321c5d4
   /settlements" 
}
POST

/accounts/act_300005/locations/loc_115161/transactions/

Request 
				
					{
   "action":"sale", 
   "authorization_amount":1.00,
   "billing_address":{
      "first_name":"Emmett",
      "last_name":"Brown",
   },
   "card":{
      "one_time_token":"ott_tq0hemmmtf-zsxgp689rew"
   }
}
Response
				
					{
  "transaction_id":"trn_4aa187d1-330a-4993-96a0-3d83f321c5d4"
  "location_id": "loc_115161",
  "action":"sale",
  "authorization_amount": 1.00,
  "billing_address": {                                                
     "first_name": "Emmett",
     "last_name": "Brown"
  },
  "card": {
     "one_time_token": "ott_tq0hemmmtf-zsxgq689rew"
  },
  "response": {
     "environment": "live",
     "response_type": "A",
     "response_code": "A01",
     "response_desc": "APPROVED"
  },
  "links": {
     "self": "/v2/accounts/act_300005/locations/loc_115161/transactions/trn_0836f440
     -f183-4ed1-9f79-395d3c2528ee",
     "settlements": "/v2/accounts/act_300005/locations/loc_115161/transactions/trn_0836f440
     -f183-4ed1-9f79-395d3c2528ee/settlements"
  }
}
Update Transactions

Use the following endpoints to update a transaction.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/transactions/{transaction_id}

Updates the Transaction and returns a new Transaction ID

Updates the Transaction and returns a new Transaction ID

Updates the following Transactions types (actions) for a Location:


• void
• capture

PUT

/accounts/act_300005/locations/loc_115161/transactions/trn_cbd20a2-f3ed-46be-b500-c47b9e40e3ee

Request 
				
					{
   "account_id":"act_300005",
   "action":"void",
   "authorization_code":"33717372",
   "entered_by":"Griff Tannen"
}
Response
				
					{
  "transaction_id":"trn_4aa187d1-330a-4993-96a0-3d83f321c5d4"
  "account_id":"act_300005",
  "location_id": "loc_115161",
  "action":"void",
  "authorization_code": "33717372",
  "entered_by": "Griff Tannen",
  "response": {
    "authorization_code":"33717372",
    "environment": "live",
    "response_type":"A",
    "response_code":"A01",
    "response_desc": "APPROVED"
  },
"links":{
   "self":"/API/v2/accounts/act_300005/locations/loc_115161/transactions/trn_4aa187d1-330a-4993-
   96a0-3d83f321c5d4",
   "settlements":"/API/v2/accounts/act_300005/locations/loc_115161/transactions/trn_4aa187d1-330a-
   4993-96a0-3d83f321c5d4/settlements"
}

Schedule

Find, create, and update scheduled transactions with the schedule object using the following input parameters and code samples.

schedule Object

Parameter

Description

Req

account_id

The identification number of the associated account. For example, act_5551236.

Required

location_id

The identification number of the associated location. For example, loc_1234568.

Required

schedule_id

A unique string used to represent a schedule. For example, 
sch_2e5770ae-c120-414f-ae8c-d065753567e7.

Required

customer_token

A unique string used to represent a customer. For example, 
cst_SoGUG6mcLUS1nVzYBIbk3g. [max length = 26]

Required

paymethod_token

A unique string used to represent a payment method. For example, 
mth_1578436587.
[max length = 26]

Required

action

The supported transaction type includes the following value:


• sale - Creates an ad-hoc or token transaction that will settle at the end of the day


• disburse - used to send funds back to the account/card holder rather than collecting funds from an account/card holder

Required

schedule_quantity

Indicates the quantity of transactions to perform. For continuous schedules, set the value of this field to 0.

Required

schedule_frequency

Indicates the frequency of the scheduled transactions. The supported values for this field include the following:

• one_time_future
• weekly
• bi-weekly
• monthly
• bi-monthly
• quarterly
• semi-annually
• annually

Required

schedule_amount

Indicates the amount of the recurring payment. The value of this parameter depends on the value in the schedule_frequency parameter.

Optional

schedule_start_date

Indicates the start day of the next recurring transaction in MM/DD/YYYY format. This date can be today's date or greater. NOTE: If the merchant does not specify this value, the system defaults to today's date.

Optional

schedule_created_date

The date the schedule was created.

Optional

customer_acct_code

The customer accounting code. This field only applies to credit card transactions.

Optional

sec_code

The Standard Entry Class code for the transaction. This field only applies to echeck transactions.

Optional

schedule_status

The current status of the schedule. The supported values for this field include the following:


• active = The schedule is active.


• suspended = The schedule is suspended.


• completed = The schedule is completed.

Optional

item_description

The check number or other description of the item to be processed.

Optional

reference_id

A merchant-defined string that identifies the transaction.

Optional

order_number

A merchant-assigned ID code that is returned with the transaction response.

Optional

customer_id

A merchant-defined string created at the customer level to identify the customer.

Optional

summary

The summary object.

Optional

xdata

The xdata object.

Optional

summary Object

The schedule summary object enables merchants to quickly access schedule information such as the amount of the next scheduled transaction or when the next scheduled transaction will be processed. To find summary information for a schedule, use the following parameters.

Parameter

Description

Req

schedule_next_date

The next date when a scheduled transaction will be processed. This parameter is return only.

—

schedule_next_amount

The amount of the next scheduled transaction that will be processed. This parameter is return only.

—

schedule_last_amount

The authorization amount for the last scheduled transaction that Forte processed. This parameter is return only.

—

schedule_last_date

The date and timestamp when Forte processed the last scheduled transaction. This parameter is return only.

—

schedule_successful_amount

The total amount of the successful transactions for this schedule. This parameter is return only.

—

schedule_successful_authorization_amount

The authorization amount of the last scheduled transaction that Forte successfully processed. This parameter is return only.

—

schedule_successful_quantity

The total number of successful transaction for this schedule. This parameter is return only.

—

schedule_failed_amount

The total amount of failed transactions for this schedule. This parameter is return only.

—

schedule_failed_quantity

The total number of failed transactions for this schedule. This parameter is return only.

—

scheduled_remaining_amount

The total amount of the remaining transactions for this schedule. This parameter is return only.

—

scheduled_remaining_quantity

The total number of the remaining transactions for this schedule. This parameter is return-onlyThe total amount of the suspended transactions for this schedule. This parameter is return only..

—

scheduled_suspended_amount

The total number of suspended transactions for this schedule. This parameter is return only.

—

scheduled_suspended_quantity

—

Find Schedules

Use the following endpoints to find a schedule.

Endpoint

Description

/accounts/{account_id}/schedules

This endpoint returns all schedules for an account.

/accounts/{account_id}/locations/{location_id}/schedules

This endpoint returns all schedules for a location.

/accounts/{account_id}/locations/{location_id}/customers/{customer_token}/schedules

This endpoint returns all schedules associated with a
particular customer.

/accounts/{account_id}/locations/{location_id}/schedules/{schedule_id}

This endpoint returns a specific schedule, including schedule
summary data that can be used to quickly find useful schedule information.

To narrow your search data using specific criteria, use the following parameters with the endpoints above to filter your results:

Filter Parameter

Example

account_id

/accounts/{account_id}/locations/{location_id}/schedules/?filter=account_id+eq+act_300005

location_id

/accounts/{account_id}/locations/{location_id}/schedules/?filter=location_id+eq+loc_115161

customer_token

/accounts/{account_id}/locations/{location_id}/schedules/?filter=customer_token+eq+
cst_6cHpUhBG_02bIb4SXxOm5A

paymethod_token

/accounts/{account_id}/locations/{location_id}/schedules/?filter=paymethod_token+eq+
mth_LCaCk2jdLUOfdrPxtsgjWA

action

/accounts/{account_id}/locations/{location_id}/schedules/?filter=action+eq+sale

schedule_quantity

/accounts/{account_id}/locations/{location_id}/schedules/?filter=schedule_quantity+eq+'12'

schedule_frequency

/accounts/{account_id}/locations/{location_id}/schedules/?filter=schedule_frequency+eq+monthly

schedule_amount

/accounts/{account_id}/locations/{location_id}/schedules/?filter=schedule_amount+eq+'100.01'

start_schedule_created_date/
end_schedule_created_date

/accounts/{account_id}/locations/{location_id}/schedules/?filter=start_schedule_created_date+eq+
'2002-01-08'+and+end_schedule_created_date+eq+'2013-12-08'

start_schedule_start_date/
end_schedule_start_date

/accounts/{account_id}/locations/{location_id}/schedules/?filter=start_schedule_start_date+eq+
'2002-01-08'+and+end_schedule_start_date+eq+'2013-12-08'

The following code samples display example endpoints and GET calls you can use to find a schedule.

GET

/accounts/act_300005/locations/loc_115161/customers/cst_cgUS6uBRoUaELceb4snWmw/schedules

Response
				
					{
  "number_results": 2,
  "search_criteria": {
    "home_account_id": "act_300005",
    "resource_specific": {
      "location_id": "loc_115161",
      "customer_token": "cst_cgUS6uBRoUaELceb4snWmw"
     }
  },
  "results": [{
     "schedule_id": "sch_9a74e2a8-a182-40ef-89c1-4e38b9667206",
     "location_id": "loc_115161",
     "customer_token": "cst_cgUS6uBRoUaELceb4snWmw",
     "paymethod_token": "mth_cp459q53Q0W5wJdMG35f1w",
     "action": "sale",
     "schedule_quantity": 0,
     "schedule_frequency": "monthly",
     "schedule_amount": 25,
     "schedule_created_date": "2016-11-03T06:38:50.857",
     "schedule_start_date": "2016-12-11T08:00:00",
     "schedule_status": "active",
     "schedule_summary": {
        "schedule_successful_amount": 0,
        "schedule_successful_authorization_amount": 0,
        "schedule_successful_quantity": 0,
        "schedule_failed_amount": 0,
        "schedule_failed_quantity": 0,
        "schedule_remaining_amount": 25,
        "schedule_remaining_quantity": 1,
        "schedule_suspended_amount": 0,
        "schedule_suspended_quantity": 0
     },
     "links": {
        "scheduleitems": "/v2/schedules/sch_9a74e2a8-a182-40ef-89c1-4e38b9667206/scheduleitems",
        "self": "/v2/schedules/sch_9a74e2a8-a182-40ef-89c1-4e38b9667206"
     }
     },
  {
     "schedule_id": "sch_2ed98062-18c0-4d1b-9f84-4f25f07b498c",
     "location_id": "loc_115161",
     "customer_token": "cst_cgUS6uBRoUaELceb4snWmw",
     "paymethod_token": "mth_cp459q53Q0W5wJdMG35f1w",
     "action": "sale",
     "schedule_quantity": 0,
     "schedule_frequency": "monthly",
     "schedule_amount": 25,
     "schedule_created_date": "2016-11-17T12:00:29.913",
     "schedule_start_date": "2016-12-11T08:00:00",
     "schedule_status": "active",
     "schedule_summary": {
        "schedule_successful_amount": 0,
        "schedule_successful_authorization_amount": 0,
        "schedule_successful_quantity": 0,
        "schedule_failed_amount": 0,
        "schedule_failed_quantity": 0,
        "schedule_remaining_amount": 25,
        "schedule_remaining_quantity": 1,
        "schedule_suspended_amount": 0,
        "schedule_suspended_quantity": 0
     },
     "links": {
        "scheduleitems": "/v2/schedules/sch_2ed98062-18c0-4d1b-9f84-4f25f07b498c/scheduleitems",
        "self": "/v2/schedules/sch_2ed98062-18c0-4d1b-9f84-4f25f07b498c"
     }
  }
  ],
  "response": {
     "environment": "live",
     "response_desc": "Get Successful."
  },
  "links": {
     "self": "/v2/schedules/"
  }
}
GET

/accounts/act_300005/locations/loc_115161/schedules/sch_94e8e011-3f53-4ff3-81e2-c1876754e721

Response
				
					{
  "schedule_id": "sch_94e8e011-3f53-4ff3-81e2-c1876754e721",
  "location_id": "loc_115161",
  "customer_token": "cst_cgUS6uBRoUaELceb4snWmw",
  "paymethod_token": "mth_ymC20TMkHE-YmYxMt0UvMA",
  "action": "sale",
  "schedule_quantity": 12,
  "schedule_frequency": "monthly",
  "schedule_amount": 25,
  "schedule_start_date": "2016-12-11T16:00:00Z",
  "schedule_status": "active",
  "schedule_source": "",
  "customer_acct_code": "",
  "sec_code": "arc",
  "item_description": "Car Payment",
  "reference_id": "INV-123",
  "order_number": "98762222",
  "customer_id": "",
  "schedule_summary": {
    "schedule_next_amount": 25,
    "schedule_next_date": "2016-12-11T16:00:00Z",
    "schedule_last_amount": 25,
    "schedule_last_date": "2016-11-11T16:00:00Z"
    "schedule_successful_amount": 25,
    "schedule_successfu_authorization_amount": 25,
    "schedule_successful_quantity": 1,
    "schedule_failed_amount": 0,
    "schedule_failed_quantity": 0,
    "schedule_remaining_amount": 300,
    "schedule_remaining_quantity": 12
    "schedule_suspended_amount": 0,
    "schedule_suspended_quantity": 0
   },
  "xdata": {
    "xdata_1": "inv-321",
    "xdata_2": "Southern Branch"
   },
  "response": {
    "environment": "live",
    "response_desc": "Get Successful."
   },
  "links": {
    "self": "/v2/schedules/sch_94e8e011-3f53-4ff3-81e2-c1876754e721",
    "scheduleitems": "/v2/schedules/sch_94e8e011-3f53-4ff3-81e2-c1876754e721/scheduleitems"
   }
  }
}
Create Schedules

Use the following endpoints to create a schedule.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/schedules

dules
Creates a new schedule and returns a new unique schedule ID.
NOTE: 
Both the customer_token and paymethod_token parameters
must be specified in the request.

/accounts/{account_id}/locations/{location_id}/customers/{customer_token}/schedules

Creates a new schedule and returns a new unique schedule ID
for the customer. NOTE: The paymethod_token must be specified in the request.

The following code samples display example endpoints and POST calls you can use to find a schedule.

POST

/accounts/act_300005/locations/loc_115161/schedules

Request 
				
					{
  "customer_token":"cst_cgUS6uBRoUaELceb4snWmw",
  "paymethod_token":"mth_ymC20TMkHE-YmYxMt0UvMA",
  "action": "sale",
  "schedule_quantity": "12",
  "schedule_frequency": "monthly",
  "schedule_amount": 25.00,
  "schedule_start_date": "12/11/2016",
  "reference_id":"INV-123",
  "order_number":"98762222",
  "item_description":"Car Payment",
  "xdata": {
    "xdata_1": "inv-321",
    "xdata_2": "Southern Branch"
   }
  }
Response
				
					{
  "schedule_id": "sch_b0a06e66-437a-4416-ad63-24c5cb3f75b9",
  "location_id": "loc_115161",
  "customer_token": "cst_cgUS6uBRoUaELceb4snWmw",
  "paymethod_token": "mth_ymC20TMkHE-YmYxMt0UvMA",
  "action": "sale",
  "schedule_quantity": 12,
  "schedule_frequency": "monthly",
  "schedule_amount": 25,
  "schedule_start_date": "2016-12-11T08:00:00Z",
  "item_description": "Car Payment",
  "reference_id": "INV-123",
  "order_number": "98762222",
  "xdata": {
    "xdata_1": "inv-321",
    "xdata_2": "Southern Branch"
   },
  "response": {
    "environment": "live",
    "response_desc": "Create Successful."
   },
  "links": {
    "self": "/v2/schedules/sch_b0a06e66-437a-4416-ad63-24c5cb3f75b9",
    "scheduleitems": "/v2/schedules/sch_b0a06e66-437a-4416-ad63-24c5cb3f75b9/scheduleitems"
   }
  }
POST

/accounts/act_300005/locations/loc_115161/customers/cst_cgUS6uBRoUaELceb4snWmw/schedules

Request
				
					{
  "action": "sale",
  "schedule_amount": 25.00,
  "schedule_quantity": 0,
  "schedule_frequency": "one_time_future",
  "schedule_start_date": "12/11/2016",
  "paymethod_token":"mth_ymC20TMkHE-YmYxMt0UvMA"
}
Response
				
					{
  "schedule_id": "sch_560445bf-78c8-4ee5-a351-7eef52215933",
  "location_id": "loc_115161",
  "customer_token": "cst_cgUS6uBRoUaELceb4snWmw",
  "paymethod_token": "mth_ymC20TMkHE-YmYxMt0UvMA",
  "action": "sale",
  "schedule_quantity": 1,
  "schedule_frequency": "one_time_future",
  "schedule_amount": 25,
  "schedule_start_date": "2016-12-11T08:00:00Z",
  "response": {
    "environment": "live",
    "response_desc": "Create Successful."
   },
  "links": {
    "self": "/v2/schedules/sch_560445bf-78c8-4ee5-a351-7eef52215933",
    "scheduleitems": "/v2/schedules/sch_560445bf-78c8-4ee5-a351-7eef52215933/scheduleitems"
   }
  }
POST

/accounts/act_300005/locations/loc_115161/schedules

Request
				
					{
  "customer_token": "cst_odJPNht1D0mYDnPJPOF3jQ",
  "paymethod_token": "mth_54gZWsvvDUGQ8X9Xu6h5xg",
  "action": "sale",
  "schedule_frequency": "one_time_future",
  "schedule_amount": 25.00,
  "schedule_start_date": "12/11/2016",
  "reference_id":"INV-123",
  "order_number":"98762222",
  "item_description":"DeLorean Payment",
  "xdata": {
     "xdata_1": "inv-321",
     "xdata_2": "Southern Branch"
  }
}
Response
				
					{
  "schedule_id": "sch_5cddbbd5-a6f6-40fb-a7b1-49e7d6050c70",
  "location_id": "loc_*******",
  "customer_token": "cst_odJPNht1D0mYDnPJPOF3jQ",
  "paymethod_token": "mth_54gZWsvvDUGQ8X9Xu6h5xg",
  "action": "sale",
  "schedule_quantity": 1,
  "schedule_frequency": "one_time_future",
  "schedule_amount": 25.0,
  "schedule_start_date": "2016-12-11T00:00:00",
  "item_description": "DeLorean Payment",
  "reference_id": "INV-123",
  "order_number": "98762222",
  "xdata": {
     "xdata_1": "inv-321",
     "xdata_2": "Southern Branch"
  },
  "response": {
     "environment": "sandbox",
     "response_desc": "Create Successful."
  },
  "links": {
     "self": "/v2/schedules/sch_5cddbbd5-a6f6-40fb-a7b1-49e7d6050c70",
     "scheduleitems": "/v2/schedules/sch_5cddbbd5-a6f6-40fb-a7b1-49e7d6050c70/scheduleitems"
  }
}
Update Schedules

Use the following endpoints to update a schedule's status or paymethod_token.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/schedules/{schedule_id}

Updates the schedule definition's status and/or paymethod token. NOTE: When updating a schedule definition from suspended to active status, the scheduleitems associated with that schedule definition must be individually updated to ensure the scheduled transactions occur.

The following code samples display example endpoints and PUT calls you can use to update a schedule definition.

PUT

/accounts/act_300005/locations/loc_115161/schedules/sch_94e8e011-3f53-4ff3-81e2-c1876754e721

Request
				
					{
  "schedule_status": "suspended"
}
Request
				
					{
  "schedule_id": "sch_94e8e011-3f53-4ff3-81e2-c1876754e721",
  "location_id": "loc_115161",
  "schedule_status": "suspended",
  "response": {
    "environment": "live",
    "response_desc": "Update Successful."
   }
  }
PUT

/accounts/act_300005/locations/loc_115161/schedules/sch_b0a06e66-437a-4416-ad63-24c5cb3f75b9

Request
				
					{
  "paymethod_token":"mth_ymC20TMkHE-YmYxMt0UvMA"
}
Response
				
					{
  "schedule_id": "sch_b0a06e66-437a-4416-ad63-24c5cb3f75b9",
  "location_id": "loc_115161",
  "paymethod_token": "mth_ymC20TMkHE-YmYxMt0UvMA",
  "response": {
    "environment": "live",
    "response_desc": "Update Successful."
   }
  }
Delete Schedules

Use the following endpoint to delete a schedule.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/schedules/{schedule_id}

Deletes the schedule. When deleting a schedule, all scheduleitems are also deleted.

The following code samples display example endpoints and DELETE calls you can use to delete a schedule.

DELETE

/accounts/act_300005/locations/loc_115161/schedules/sch_94e8e011-3f53-4ff3-81e2-c1876754e721

Response
				
					{
  "schedule_id": "sch_94e8e011-3f53-4ff3-81e2-c1876754e721",
  "response": {
    "environment": "live",
    "response_desc": "Delete Successful."
   }
 }

Scheduleitems

Find, create, and update individual future transactions with the scheduleitems object using the following input parameters and code samples.

scheduleitems Object

Parameter

Description

Req

account_id

The identification number of the associated account. For example, act_5551236.

Required

location_id

The identification number of the associated location. For example, loc_1234568.

Required

schedule_item_id

A unique string used to represent a schedule item. For example, 
sci_2e5770ae-c120-414f-ae8c-d065753567e7.

Required

customer_token

A unique string used to represent a customer. For example, cst_SoGUG6mcLUS1nVzYBIbk3g.
[max length = 26]

Required

paymethod_token

A unique string used to represent a payment method. For example, mth_1578436587.
[max length = 26]

Required

schedule_id

A unique string used to represent a schedule. For example, sch_2e5770ae-c120-414f-ae8c-d065753567e7.

Required

schedule_item_amount

Indicates the amount of the scheduled item.

Optional

schedule_item_status

Indicates the status of the scheduled item. The supported values for this field include the following:


• scheduled = The item is scheduled.


• completed = The item is completed.


• suspended = The item is suspended.


• processing = The item is processing.


• failed = The item has failed.

Required

schedule_item_date

Indicates the date of the scheduled item. For POSTs, the value of this field must be greater than today's date.

Required

schedule_item_processed_date 

Indicates the date when the scheduled item will be processed.

Optional

schedule_item_created_date

Indicates the date when the merchant created the scheduled item.

Optional

schedule_item_description

A brief description of the scheduled item being processed.

Optional

Find Scheduleitems

Use the following endpoints to find a scheduleitems.

Endpoint

Description

/accounts/{account_id}/scheduleitems

This endpoint returns all scheduleitems for an
account.

/accounts/{account_id}/locations/{location_id}/scheduleitems

This endpoint returns all scheduleitems for a location.

/accounts/{account_id}/locations/{location_id}/paymethods/{paymethod_token}/scheduleitems

This endpoint returns all future scheduleitems for a
particular customer or paymethod.

/accounts/{account_id}/scheduleitems/{schedule_item_id}

This endpoint returns a specific scheduleitem.

To narrow your search data using specific criteria, use the following parameters with the endpoints above to filter your results:

Filter Parameter

Example

account_id

/accounts/{account_id}/locations/{location_id}/scheduleitems/?filter=account_id+eq+act_300005

location_id

/accounts/{account_id}/locations/{location_id}/scheduleitems/?filter=location_id+eq+loc_115161

customer_token

/accounts/{account_id}/locations/{location_id}/scheduleitems/?filter=customer_token+eq+
cst_6cHpUhBG_02bIb4SXxOm5A

paymethod_token

/accounts/{account_id}/locations/{location_id}/scheduleitems/?filter=paymethod_token+eq+
mth_LCaCk2jdLUOfdrPxtsgjWA

schedule_id

/accounts/{account_id}/locations/{location_id}/scheduleitems/?filter=schedule_id+eq+
sch_2e5770ae-c120-414f-ae8c-d065753567e7

schedule_item_amount

/accounts/{account_id}/locations/{location_id}/scheduleitems/?filter=schedule_item_amount+eq+'100.01'

schedule_item_status

/accounts/{account_id}/locations/{location_id}/scheduleitems/?filter=schedule_item_status+eq+
scheduled

start_schedule_item_date/
end_schedule_item_date

/accounts/{account_id}/locations/{location_id}/scheduleitems/?filter=start_schedule_item_date+eq+
'2002-01-08'+and+end_schedule_item_date+eq+'2013-12-08'

start_schedule_item_processed_date/
end_schedule_item_processed_date

/accounts/{account_id}/locations/{location_id}/scheduleitems/?filter=
start_schedule_item_processed_date+eq+'2002-01-08'+and+end_schedule_item_processed_date+eq+'2013-12-08'

start_schedule_item_created_date/
end_schedule_item_created_date

/accounts/{account_id}/locations/{location_id}/scheduleitems/?filter=
start_schedule_item_created_date+eq+'2002-01-08'+and+end_schedule_item_created_date+eq+'2013-12-08'a

The following code samples display example endpoints and GET calls you can use to find a scheduleitem.

GET

/accounts/act_300005/location/loc_115161/paymethods/mth_3534210/scheduleitems/

Response
				
					{
  "number_results": 2,
  "search_criteria": {
    "home_account_id": "act_300005",
    "resource_specific": {
      "location_id": "loc_115161",
      "paymethod_token": "mth_ymC20TMkHE-YmYxMt0UvMA"
     }
   },
  "results": [{
     "schedule_item_id": "sci_03c0a9be-fa93-478c-afa6-ee73fe9ed7a0",
     "account_id": "act_300005",
     "customer_token": "cst_h_TrrHANEU6XjmMV_EMVrA",
     "paymethod_token": "mth_ymC20TMkHE-YmYxMt0UvMA",
     "schedule_id": "sch_efb0d951-3f54-40b2-8ad8-febca0131562",
     "schedule_item_amount": 100,
     "schedule_item_status": "scheduled",
     "schedule_item_date": "2017-12-21T08:00:00",
     "schedule_item_created_date": "2017-01-06T09:45:09.463",
     "schedule_item_description": "",
     "links": {
        "self": "/v2/scheduleitems/sci_03c0a9be-fa93-478c-afa6-ee73fe9ed7a0"
     }
     },
  {
     "schedule_item_id": "sci_19ccd5d1-f3b4-4888-b183-c62543653d21",
     "account_id": "org_300005",
     "customer_token": "cst_h_TrrHANEU6XjmMV_EMVrA",
     "paymethod_token": "mth_ymC20TMkHE-YmYxMt0UvMA",
     "schedule_id": "sch_efb0d951-3f54-40b2-8ad8-febca0131562",
     "schedule_item_amount": 100,
     "schedule_item_status": "scheduled",
     "schedule_item_date": "2017-12-21T08:00:00",
     "schedule_item_created_date": "2017-01-06T10:25:54.51",
     "schedule_item_description": "",
     "links": {
        "self": "/v2/scheduleitems/sci_19ccd5d1-f3b4-4888-b183-c62543653d21"
     }
   }
   ],
   "response": {
      "environment": "live",
      "response_desc": "Get Successful."
   },
   "links": {
      "self": "/v2/scheduleitems/"
   }
}
GET

/accounts/act_300005/scheduleitems/sci_14ade23f-d1a5-4cad-9a73-3e41452469f7

Response
				
					{
    "schedule_item_id": "sci_14ade23f-d1a5-4cad-9a73-3e41452469f7",
    "account_id": "act_300005",
    "customer_token": "cst_h_TrrHANEU6XjmMV_EMVrA",
    "paymethod_token": "mth_cp459q53Q0W5wJdMG35f1w",
    "schedule_id": "sch_857eed95-b661-468c-8037-1cb63a13f23a",
    "schedule_item_amount": 25,
    "schedule_item_service_fee_amount": 0,
    "schedule_item_authorization_amount": 25,
    "schedule_item_status": "scheduled",
    "schedule_item_date": "2017-07-11T08:00:00",
    "schedule_item_created_date": "2016-11-02T13:19:59.907",
    "schedule_item_description": "Item 8 of 12",
    "response": {
       "environment": "live",
       "response_desc": "Get Successful."
    },
    "links": {
       "self": "/v2/scheduleitems/sci_ef428d98-aaa5-42af-b63e-3ccdad88805b"
    }
}
Create Scheduleitems

Use the following endpoint to create a scheduleitems.

Endpoint

Description

/accounts/{account_id}/location/{location_id}/schedules/{schedule_id}/scheduleitems/

This endpoint creates a new scheduleitem and returns a unique schedule_item_id. If the schedule_item_date or schedule_item_amount fields are not passed, the system
automatically calculates these values based on the last
scheduleitem and the schedule definition records. The value of the schedule_item_date field must be a future date.

NOTE: Scheduleitems cannot be created for non-active or
continuous schedules.

The following code samples display example endpoints and POST calls you can use to create a scheduleitem.

POST

/accounts/act_300005/location/loc_115161/schedules/sch_94e8e011-3f53-4ff3-81e2-c1876754e721/scheduleitems/

Request
				
					{
  "schedule_item_id": "",
  "customer_token": "cst_cgUS6uBRoUaELceb4snWmw",
  "paymethod_token": "mth_ymC20TMkHE-YmYxMt0UvMA",
  "schedule_item_amount": 100.00,
  "schedule_item_status": "scheduled",
  "schedule_item_date": "12/21/2016"
}
Response
				
					{
  "schedule_item_id": "sci_4690fbfb-0b77-4477-a066-2c07ca2e5a3c",
  "location_id": "loc_115161",
  "customer_token": "cst_cgUS6uBRoUaELceb4snWmw",
  "paymethod_token": "mth_ymC20TMkHE-YmYxMt0UvMA",
  "schedule_id": "sch_94e8e011-3f53-4ff3-81e2-c1876754e721",
  "schedule_item_amount": 100,
  "schedule_item_status": "scheduled",
  "schedule_item_date": "2016-12-21T08:00:00Z",
  "response": {
    "environment": "live",
    "response_desc": "Create Successful."
   },
  "links": {
    "self": "/v2/scheduleitems/sci_4690fbfb-0b77-4477-a066-2c07ca2e5a3c"
   }
 }
Update Scheduleitems

Use the following endpoint to create a scheduleitems.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/scheduleitems/{schedule_item_id}

This endpoint updates the specified scheduleitem. Only scheduleitems
with a future date value in the schedule_item_date field and a status of scheduled or suspended in the schedule_item_status field can be updated. If the status of a scheduleitem in a continuous schedule is changed to suspended, the status of the schedule definition will also be suspended. 
NOTE: Updates to the schedule_item_created_date and schedule_item_processed_date are not allowed.

The following code samples display example endpoints and POST calls you can use to create a scheduleitem.

PUT

/accounts/act_300005/location/loc_115161/scheduleitems/sci_4690fbfb-0b77-4477-a066-2c07ca2e5a3c/

Request
				
					{
  "schedule_item_amount": 200.00,
}
Response
				
					{
  "schedule_item_id": "sci_4690fbfb-0b77-4477-a066-2c07ca2e5a3c",
  "location_id": "loc_115161",
  "schedule_item_amount": 200,
  "response": {
    "environment": "live",
    "response_desc": "Update Successful."
   }
 }
Delete Scheduleitems

Use the following endpoint to delete a scheduleitems.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/scheduleitems/{schedule_item_id}

This endpoint deletes the specified scheduleitem. Deleting a
scheduleitem will not delete the schedule definition.

The following code samples display example endpoints and POST calls you can use to create a scheduleitem.

DELETE

/accounts/act_300005/location/loc_115161/scheduleitems/sci_14ade23f-d1a5-4cad-9a73-3e41452469f7/

Response
				
					{
  "scheduleitem_id": "sci_14ade23f-d1a5-4cad-9a73-3e41452469f7",
  "response": {
    "environment": "live",
    "response_desc": "Delete Successful."
   }
 }

Settlement

Find transaction settlement data with the settlement object using the following input parameters and code samples. Use the settle_date, settle_response_code, and method fields to filter your data.

settlement Object

Parameter

Description

Req

account_id

The identification number of the associated account. For example, act_5551236.

Required

location_id

The identification number of the associated location. For example, loc_1234568.

Required

customer_token

A unique string used to represent a customer. For example, cst_SoGUG6mcLUS1nVzYBIbk3g.
[max length = 26]

Optional

customer_id

A merchant-defined string created at the customer level to identify the customer.

Optional

order_number

A merchant-defined string.

Optional

reference_id

A merchant-defined string that identifies the transaction.

Optional

settle_id

The settlement ID of the settled transaction (e.g., stl_51cf4633-1767-484f-8784-be76a4076791)

Required

transaction_id

A 36-character code that uniquely identifies the transaction.

Optional

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.

Optional

settle_date

The date when the transaction was settled.

Optional

settle_type

The type of settlement. Supported settlement types include the following values.

For echeck transactions:


• deposit
• reject
• withdrawal
 

For credit card transactions:


• deposit
• withdrawal

Optional

settle_response_code

See the Response Codes table for more information. NOTE: Credit card transactions that do not return a settle response can be considered settled.

Optional

settle_amount

The amount the transaction settled for.

Optional

method

The payment method. The supported payment methods include the following values:


• echeck
• cc

Optional

NOTE: When a merchant passes a customer token with a transaction, Forte ignores any other customer data in favor of the default data stored with the token.

Find Settlements

Use the following endpoint to find a settlement.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/settlement

This endpoint returns all the transaction settlements for a Location.

To narrow your search data using specific criteria, use the following parameters with the endpoints above to filter your results:

Filter Parameter

Example

account_id

/accounts/{account_id}/locations/{location_id}/settlements/?filter=account_id+eq+act_300005

location_id

/accounts/{account_id}/locations/{location_id}/settlements/?filter=location_id+eq+loc_115161

customer_token

/accounts/{account_id}/locations/{location_id}/settlements/?filter=customer_token+eq+cst_6cHpUhBG_02bIb4SXxOm5A

transaction_id

/accounts/{account_id}/locations/{location_id}/settlements/?filter=transaction_id+eq+
trn_55c98c85-d3e8-4230-85e9-21d7d522eec0a

customer_id

/accounts/{account_id}/locations/{location_id}/settlements/?filter=customer_id+eq+'ABC5698350001'

order_number

/accounts/{account_id}/locations/{location_id}/settlements/?filter=order_number+eq+'0000012598756'

reference_id

/accounts/{account_id}/locations/{location_id}/settlements/?filter=reference_id+eq+'456789123'

start_settle_date/
end_settle_date

/accounts/{account_id}/locations/{location_id}/settlements/?filter=start_settle_date+eq+'2002-01-08'+and+end_settle_date+eq+'2013-12-08'

settle_response_code

/accounts/{account_id}/locations/{location_id}/settlements/?filter=settle_response_code+eq+'R21'

method

/accounts/{account_id}/locations/{location_id}/settlements/?filter=method+eq+'cc'

NOTE: If both the start_settle_date and end_settle_date filters are not passed in, 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.

 

The following code samples display example endpoints and GET calls you can use to find a settlement.

GET

/accounts/act_300005/locations/loc_115161/settlements/

Response
				
					{
  "number_results": 2,
  "search_criteria": {
    "home_account_id": "act_300005",
    "resource_specific": {
      "location_id": "loc_115161",
      "start_settle_date": "2014-12-31T00:00:00-08:00",
      "end_settle_date": "2015-04-01T00:00:00-07:00"
    }
  },
  "results": [
    {
      "settle_id": "stl_0dde9c0d-a816-4ed1-9eb1-490207a87c35",
      "account_id": "act_300005",
      "location_id": "loc_115161",
      "customer_token": "cst_11017799",
      "transaction_id": "trn_8bb0c376-8ab9-4351-af7d-991452d21429",
      "customer_id": "45687545",
      "order_number": "000001",
      "reference_id": "0002315",
      "settle_date": "2014-02-09T00:00:00",
      "settle_type": "deposit",
      "settle_response_code": "S01",
      "settle_amount": 5.4,
      "method": "echeck",
      "links": {
        "self": "/v2/accounts/act_300005/locations/loc_115161/settlements/stl_0dde9c0d
        -a816-4ed1-9eb1-490207a87c35"
      }
    },
   {
      "settle_id": "stl_54da660a-13be-4f09-ac0e-84685b9a0860",
      "account_id": "act_300005",
      "location_id": "loc_115161",
      "customer_token": "cst_4554037",
      "transaction_id": "trn_48e1759d-e9ed-4eba-8861-c16807a7a510",
      "customer_id": "568987",
      "order_number": "456987",
      "reference_id": "000002",
      "settle_date": "2014-03-12T00:00:00",
      "settle_type": "withdrawal",
      "settle_response_code": "S01",
      "settle_amount": -3.4,
      "method": "echeck",
      "links": {
        "self": "/v2/accounts/act_300005/locations/loc_115161/settlements/stl_54da660a
        -13be-4f09-ac0e-84685b9a0860"
      }
     }
  ],
  "response": {
    "environment": "live",
    "response_desc": "Get Successful."
  },
  "links": {
    "self": "/v2/accounts/act_300005/locations/loc_115161/settlements?filter=start_settle_date
    +eq+%272014-01-01T00%3a00%3a00%27+and+end_settle_date+eq+%272014-01-15T00%3a00%3a00%27&r=1%3f"
  } 
}
GET

/accounts/act_300005/locations/loc_115161/settlements/?filter=start_settle_date+eq+%272014-01-01T00:00:00%27+
and+end_settle_date+eq+%272014-01-15T00:00:00%27&r=1

Response
				
					{
  "number_results": 2,
  "search_criteria": {
    "home_account_id": "act_300005",
    "resource_specific": {
      "location_id": "loc_115161",
      "start_settle_date": "2014-01-01T00:00:00",
      "end_settle_date": "2014-01-15T00:00:00"
    }
  },
  "results": [
    {
      "settle_id": "stl_0dde9c0d-a816-4ed1-9eb1-490207a87c35",
      "account_id": "act_300005",
      "location_id": "loc_115161",
      "customer_token": "cst_11017799",
      "transaction_id": "trn_8bb0c376-8ab9-4351-af7d-991452d21429",
      "customer_id": "45687545",
      "order_number": "000001",
      "reference_id": "0002315",
      "settle_date": "2014-01-09T00:00:00",
      "settle_type": "deposit",
      "settle_response_code": "S01",
      "settle_amount": 5.4,
      "method": "echeck",
      "links": {
        "self": "/v2/accounts/act_300005/locations/loc_115161/settlements/stl_0dde9c0d-a816
        -4ed1-9eb1-490207a87c35"
      }
    },
   {
      "settle_id": "stl_54da660a-13be-4f09-ac0e-84685b9a0860",
      "account_id": "act_300005",
      "location_id": "loc_115161",
      "customer_token": "cst_4554037",
      "transaction_id": "trn_48e1759d-e9ed-4eba-8861-c16807a7a510",
      "customer_id": "568987",
      "order_number": "456987",
      "reference_id": "000002",
      "settle_date": "2014-01-12T00:00:00",
      "settle_type": "withdrawal",
      "settle_response_code": "S01",
      "settle_amount": -3.4,
      "method": "echeck",
      "links": {
        "self": "/v2/accounts/act_300005/locations/loc_115161/settlements/stl_54da660a-13be
        -4f09-ac0e-84685b9a0860"
      }
     }
  ],
  "response": {
    "environment": "live",
    "response_desc": "Get Successful."
  },
  "links": {
    "self": "/v2/accounts/act_300005/locations/loc_115161/settlements?filter=start_settle_date
    +eq+%272014-01-01T00%3a00%3a00%27+and+end_settle_date+eq+%272014-01-15T00%3a00%3a00%27&r=1%3f"
  } 
}
GET

/accounts/act_300005/locations/loc_115161/transactions/trn_48e1759d-e9ed-4eba-8861-c16807a7a510/settlements/

Response
				
					{
  "number_results": 1,
  "search_criteria": {
    "home_account_id": "act_300005",
    "resource_specific": {
      "location_id": "loc_115161",
      "transaction_id": "trn_48e1759d-e9ed-4eba-8861-c16807a7a510"
    }
  },
  "results": [
    {
      "settle_id": "stl_54da660a-13be-4f09-ac0e-84685b9a0860",
      "account_id": "act_300005",
      "location_id": "loc_115161",
      "customer_token": "cst_4554037",
      "transaction_id": "trn_48e1759d-e9ed-4eba-8861-c16807a7a510",
      "customer_id": "45687",
      "order_number": "88965",
      "reference_id": "78965",
      "settle_date": "2014-01-12T00:00:00",
      "settle_type": "withdrawal",
      "settle_response_code": "S01",
      "settle_amount": -3.4,
      "method": "echeck",
      "links": {
        "self": "/v2/accounts/act_300005/locations/loc_115161/transactions/trn_48e1759d
        -e9ed-4eba-8861-c16807a7a510/settlements/stl_54da660a-13be-4f09-ac0e-84685b9a0860"
      }
   }
  ],
  "response": {
    "environment": "live",
    "response_desc": "Get Successful."
  },
  "links": {
    "self": "/v2/accounts/act_300005/locations/loc_115161/transactions/trn_48e1759d-e9ed
    -4eba-8861-c16807a7a510/settlements"
  }
}

Customer

Create and maintain customer transaction data with the transaction object using the following input parameters and code samples.

customer Object

Parameter

Description

Req

account_id

The identification number of the associated Home Account. For example, act_5551236.

Required

location_id

The identification number of the associated location. For example, loc_1234568.

Required

customer_token

A unique string used to represent a customer. For example, cst_SoGUG6mcLUS1nVzYBIbk3g.
[max length = 26]

Optional

customer_id

A merchant-defined string created at the customer level to identify the customer.

Optional

default_paymethod_token

The customer's default paymethod token. The system returns this token when creating a customer with a paymethod.

Optional

default_billing_address_token

A unique string used to represent the customer's default billing address. The system returns this token when creating a customer with a billing address.

Optional

default_shipping_address_token

A unique string used to represent a customer's default shipping address. This system returns this token when creating a customer with a shipping address.

Optional

status

Use one of the following values:

a. active
b. suspended

Optional

first_name

The first name of the customer. [max length = 50]

Required

last_name

The last name of the customer. [max length = 50]

Required

company_name

The company name of the customer. [max length = 50]

Optional

paymethod

Optional

addresses

An array of Address Objects

Find Customers

Use the following endpoints to find a customer within a specific location.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/customers

This endpoint returns all the customers for a location.

/accounts/{account_id}/locations/{location_id}/customers/{customer_token}

This endpoint returns all the default information of a specific customer.

To narrow your search data using specific criteria, use the following parameters with the endpoints above to filter your results:

Filter Parameter

Example

account_id

/accounts/{account_id}/locations/{location_id}/customers/?filter=account_id+eq+act_300005

location_id

/accounts/{account_id}/locations/{location_id}/customers/?filter=location_id+eq+loc_115161

status

/accounts/{account_id}/locations/{location_id}/customers/?filter=status+eq+active

first_name

/accounts/{account_id}/locations/{location_id}/customers/?filter=first_name+eq+Marty

last_name

/accounts/{account_id}/locations/{location_id}/customers/?filter=last_name+eq+McFly

company_name

/accounts/{account_id}/locations/{location_id}/customers/?filter=company_name+eq+'Brown Associates'

customer_id

/accounts/{account_id}/locations/{location_id}/customers/?filter=customer_id+eq+025897

The following code samples display example endpoints and GET calls you can use to find a customer.

GET

/accounts/act_300005/locations/loc_115161/customers/?filter=last_name_eq_McFly

Response
				
					{
  "number_results": 2,
  "search_criteria": {
    "home_account_id": "act_300005",
    "resource_specific": {
      "location_id": "loc_115161"
    }
  },
  "results": [
    {
      "customer_token": "cst_4714042",
      "account_id": "act_300005",
      "location_id": "loc_115161",
      "default_paymethod_token": "mth_5557325",
      "default_billing_address_token": "add_4714042",
      "status": "active",
      "first_name": "Marty",
      "last_name": "McFly",
      "company_name": "Brown Associates",
      "customer_id": "4568963",
      "links": {
        "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_4714042",
        "addresses": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_4714042/addresses",
        "paymethods": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_4714042/paymethods",
        "transactions": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_4714042/
        transactions",
        "settlements": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_4714042/
        settlements"
      }
   },
  {
    "customer_token": "cst_4714048",
    "account_id": "act_300005",
    "location_id": "loc_115161",
    "default_paymethod_token": "mth_5557335",
    "default_billing_address_token": "add_4714048",
    "status": "active",
    "first_name": "Jennifer",
    "last_name": "McFly",
    "company_name": "Brown Associates",
    "customer_id": "4568633",
    "links": {
      "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_4714048",
      "addresses": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_4714048/addresses",
      "paymethods": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_4714048/paymethods",
      "transactions": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_4714048/transactions",
      "settlements": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_4714048/settlements"
    }
   }
  ],
  "response": {
    "environment": "live",
    "response_desc": "Get Successful."
  },
  "links": {
    "self": "/v2/accounts/act_300005/locations/loc_115161/customers?filter=%3ffilter
    %3dbill_to_last_name%2beq%2bMcFly",
    "next": "/v2/accounts/act_300005/locations/loc_115161/customers?filter=%3ffilter
    %3dbill_to_last_name%2beq%2bMcFly&page_index=1"
  }
}
GET

/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A

Response
				
					{
  "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
  "account_id": "act_300005",
  "location_id": "loc_115161",
  "default_paymethod_token": "mth_jSrW_4HsdEmo0J2oOZ36Uw",
  "default_billing_address_token": "add_Di5DRA0VuECJ_Xk1N0zJVw",
  "status": "active",
  "first_name": "Martin",
  "last_name": "McFly",
  "company_name": "Brown Associates",
  "customer_id": "456123",
  "addresses": [
    {
      "address_token": "add_Di5DRA0VuECJ_Xk1N0zJVw",
      "account_id": "act_300005",
      "location_id": "loc_115161",
      "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
      "first_name": "Marty",
      "last_name": "McFly",
      "company_name": "Brown Associates",
      "phone": "2145565747",
      "fax": "2148876565",
      "email": "m.mcfly@brownassociates.com",
      "label": "Billing",
      "address_type": "default_billing",
      "shipping_address_type": "commercial",
      "physical_address": {
        "street_line1": "300 Delorean Drive",
        "street_line2": "Suite 200",
        "locality": "Hill Valley",
        "region": "CA",
        "postal_code": "94502"
      },
      "links": {
        "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_
        02bIb4SXxOm5A/addresses/add_Di5DRA0VuECJ_Xk1N0zJVw"
      }
    }
  ],
  "paymethod": {
    "paymethod_token": "mth_jSrW_4HsdEmo0J2oOZ36Uw",
    "account_id": "act_300005",
    "location_id": "loc_115161",
    "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
    "label": "Visa - 1243",
    "notes": "Brown Work Card",
    "card": {
      "name_on_card": "Emmett L. Brown",
      "masked_account_number": "************1111",
      "expire_month": 10,
      "expire_year": 2015,
      "procurement_card": false,
      "card_type": "visa"
    },
    "links": {
      "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_
      02bIb4SXxOm5A/paymethods/mth_jSrW_4HsdEmo0J2oOZ36Uw"
    }
  },
  "response": {
    "environment": "live",
    "response_desc": "Get Successful."
  },
  "links": {
    "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A",
    "addresses": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_
    02bIb4SXxOm5A/addresses",
    "paymethods": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_
    02bIb4SXxOm5A/paymethods",
    "transactions": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_
    02bIb4SXxOm5A/transactions",
    "settlements": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_
    02bIb4SXxOm5A/settlements"
  }
}
Create Customers

Use the following endpoints to create a customer within a specific location.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/customers

This endpoint can perform the following tasks while returning a new customer_token. NOTE: Token-based transactions will use the default addresses. Token payments require you to set the customer's default shipping and billing addresses prior to passing the transaction data:

• Create a customer with first and last name only


• Create a customer with billing and shipping addresses


• Create a customer with a paymethod


• Create a customer with a billing/shipping address and a paymethod

/accounts/{account_id}/customers

This endpoint can perform the same tasks listed above; however, the data that the user passes in must specify a location_id. For example, if the user was creating a customer with a payment method, he or she would also need to pass in the location_id parameter.

The following code samples display example endpoints and POST calls you can use to create a customer.

POST

/accounts/act_300005/locations/loc_115161/customers/

Request
				
					{
   "first_name": "Emmett",
   "last_name": "Brown",
   "company_name": "Brown Associates",
   "customer_id": "025897"
}
Response
				
					{
   "customer_token": "cst_azuGh39NXUu_NM5pVYA1vw",
   "location_id": "loc_115161",
   "first_name": "Emmett",
   "last_name": "Brown",
   "company_name": "Brown Associates",
   "customer_id": "025897",
   "response": {
     "environment": "live",
     "response_desc": "Create Successful."
   },
   "links": {
     "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_azuGh39NXUu_NM5pVYA1vw",
     "addresses": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_azuGh39NXUu_
     NM5pVYA1vw/addresses",
     "paymethods": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_azuGh39NXUu_
     NM5pVYA1vw/paymethods",
     "transactions": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_azuGh39NXUu_
     NM5pVYA1vw/transactions",
     "settlements": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_azuGh39NXUu_
     NM5pVYA1vw/settlements"
   }
}
POST

/accounts/act_300005/locations/loc_115161/customers/

Request
				
					{
   "first_name": "Emmett",
   "last_name": "Brown",
   "company_name": "Brown Associates",
   "addresses": [
      {
         "label": "Brown Shipping",
         "first_name": "Emmett",
         "last_name": "Brown",
         "company_name": "Brown Associates",
         "phone": "444-444-4444",
         "fax": "444-444-4445",
         "email": "e.brown@brown.net",
         "shipping_address_type": "residential",
         "address_type": "default_shipping",
         "physical_address": {
            "street_line1": "123 Hill Valley Rd.",
            "street_line2": "APT 1001",
            "locality": "Hill Valley",
            "region": "CA",
            "postal_code": "95420"
         }
      },
      {
         "label": "Brown Billing",
         "first_name": "Emmett",
         "last_name": "Brown",
         "company_name": "Brown Associates",
         "phone": "444-444-4444",
         "fax": "444-444-4446",
         "email": "e.brown@forte.net",
         "shipping_address_type": "commercial",
         "address_type": "default_billing",
         "physical_address": {
            "street_line1": "500 Delorean Dr",
            "street_line2": "Suite 200",
            "locality": "Hill Valley",
            "region": "CA",
            "postal_code": "95420"
         }
      }
      ],
      "paymethod": {
         "label": "Visa - 1243",
         "notes": "Business CC",
         "card": {
            "account_number": "4111111111111111",
            "expire_month": 10,
            "expire_year": 2015,
            "card_verification_value": "693",
            "card_type": "visa",
            "name_on_card": "Emmett L. Brown",
            "card_data": "none",
            "card_reader": "no"
         }
      }
}
Response
				
					{
   "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
   "location_id": "loc_115161",
   "default_paymethod_token": "mth_jSrW_4HsdEmo0J2oOZ36Uw",
   "default_shipping_address_token": "add_VRURfxRxnUGDUHVW7xqqpA",
   "default_billing_address_token": "add_Di5DRA0VuECJ_Xk1N0zJVw",
   "first_name": "Emmett",
   "last_name": "Brown",
   "company_name": "Brown Associates",
   "addresses": [
     {
       "address_token": "add_Di5DRA0VuECJ_Xk1N0zJVw",
       "location_id": "loc_115161",
       "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
       "first_name": "Emmett",
       "last_name": "Brown",
       "company_name": "Brown Associates",
       "phone": "444-444-4444", 
       "fax": "444-444-4444",
       "email": "e.brown@forte.net",
       "label": "Brown Billing",
       "address_type": "default_billing",
       "shipping_address_type": "commercial",
       "physical_address": {
         "street_line1": "500 Delorean Dr",
         "street_line2": "Suite 200",
         "locality": "Hill Valley",
         "region": "CA",
         "postal_code": "95420"
       },
      "links": {
         "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_
         02bIb4SXxOm5A/addresses/add_Di5DRA0VuECJ_Xk1N0zJVw"
        }
      },  
      {
       "address_token": "add_VRURfxRxnUGDUHVW7xqqpA",
       "location_id": "loc_115161",
       "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
       "first_name": "Emmett",
       "last_name": "Brown",
       "company_name": "Brown Associates",
       "phone": "444-444-4444",
       "fax": "444-444-4444",
       "email": "e.brown@brown.net",
       "label": "Brown Shipping",
       "address_type": "default_shipping",
       "shipping_address_type": "residential",
       "physical_address": {
         "street_line1": "123 Hill Valley Rd.",
         "street_line2": "APT 1001",
         "locality": "Hill Valley",
         "region": "CA",
         "postal_code": "95420"
      },
      "links": {
        "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_
         02bIb4SXxOm5A/addresses/add_VRURfxRxnUGDUHVW7xqqpA"
       }
    } ],
  "paymethod": {
    "paymethod_token": "mth_jSrW_4HsdEmo0J2oOZ36Uw",
    "location_id": "loc_115161",
    "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
    "label": "Visa - 1243",
    "notes": "Business CC",
    "card": {
      "name_on_card": "Emmett L. Brown",
      "masked_account_number": "************",
      "expire_month": 10,
      "expire_year": 2015,
      "card_type": "visa"
    },
    "links": {
      "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_
      02bIb4SXxOm5A/paymethods/mth_jSrW_4HsdEmo0J2oOZ36Uw"
      "transactions": "/v2/accounts/act_300005/locations/loc_115161/paymethods/
      mth_jSrW_4HsdEmo0J2oOZ36Uw", 
      "settlements": "/v2/accounts/act_300005/locations/loc_115161/paymethods/
      mth_jSrW_4HsdEmo0J2oOZ36Uw",
      "scheduleds": "/v2/accounts/act_300005/locations/loc_115161/paymethods/
      mth_jSrW_4HsdEmo0J2oOZ36Uw"
    }
  },
 "response": {
    "environment": "live",
    "response_desc": "Create Successful."
  },
  "links": {
    "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A",
    "addresses": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A
    /addresses",
    "paymethods": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A
    /paymethods",
    "transactions": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxO
    m5A/transactions",
    "settlements": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm
    5A/settlements"
    "schedules": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm
    5A/schedules"
 }
}
Update Customers

Use the following endpoint to update a  customer.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/customers/{customer_token}

This endpoint can perform the following tasks while returning the customer_token:

• Change a customer's status

• Change the default billing and/or shipping address

• Change the default paymethod


NOTE: This endpoint cannot update a customer's addresses or paymethods. To update that data, you must use the address and paymethod resources.

The following code samples display example endpoints and PUT calls you can use to update a customer record.

PUT

/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A

Request
				
					{
   "first_name": "Dr. Emmett",
   "last_name": "Brown",
   "customer_id": "456778",
   "company_name": "Brown Associates",
   "status": "active"
}
Response
				
					{
  "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
  "location_id": "loc_115161",
  "status": "active",
  "first_name": "Dr. Emmett",
  "last_name": "Brown",
  "company_name": "Brown Associates",
  "customer_id": "456778",
  "response": {
    "environment": "live",
    "response_desc": "Update Successful."
  }
}
PUT

/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A

Request
				
					{
   "default_shipping_address_token": "add_VRURfxRxnUGDUHVW7xqqpA",
   "default_billing_address_token": "add_Di5DRA0VuECJ_Xk1N0zJVw",
   "default_paymethod_token": "mth_jSrW_4HsdEmo0J2oOZ36Uw",
   "first_name": "Martin",
   "last_name": "McFly",
   "customer_id": "456123",
   "company_name": "Brown Associates",
   "status": "active"
}
Response
				
					{
   "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
   "location_id": "loc_115161",
   "default_paymethod_token": "mth_jSrW_4HsdEmo0J2oOZ36Uw",
   "default_shipping_address_token": "add_VRURfxRxnUGDUHVW7xqqpA",
   "default_billing_address_token": "add_Di5DRA0VuECJ_Xk1N0zJVw",
   "status": "active",
   "first_name": "Martin",
   "last_name": "McFly",
   "company_name": "Brown Associates",
   "customer_id": "456123",
   "response": {
     "environment": "live",
     "response_desc": "Update Successful."
   }
}
Delete Customers

Use the following endpoint to delete a customer. NOTE: A customer cannot be deleted if he or she is tied to an active schedule.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/customers/{customer_token}

This endpoint deletes the specified customer record.

The following code samples display example endpoints and DELETE calls you can use to delete a customer record.

DELETE

/accounts/act_200000/locations/loc_100000/customers/cst_SoGUG6mcLUS1nVzYBIbk3g

Response
				
					{
   "customer_token": "cst_SoGUG6mcLUS1nVzYBIbk3g"
}

Address

Create, maintain, and delete customer address data with the address object using the following input parameters and code samples. NOTE: For token payments, Forte will use the default shipping and billing addresses. Set the customers default shipping and billing addresses prior to creating a token payment.

address Object

Parameter

Description

Req

address_token

A unique string used to represent an address. For example, 
add_tq0hemmmtf-zsxgq689rew.

Required

customer_token

A unique string used to represent a customer. For example, 
cst_SoGUG6mcLUS1nVzYBIbk3g.

Required

account_id

The identification number of the associated account. For example, act_5551236.

Required

location_id

The identification number of the associated location. For example, 
loc_1234568.

Required

first_name

The first name of the user associated with this billing or shipping address [max length = 50].
NOTE: The first_name and last_name parameters are required for billing addresses when creating transactions without tokens.

Required

last_name

The last name of the user associated with this billing or shipping address [max length = 50].
NOTE: The first_name and last_name parameters are required for billing addresses when creating transactions without tokens.

Required

company_name

The name of the company associated with this billing or shipping address [max length = 50].
NOTE: The company_name parameter is required for billing addresses when creating transactions without tokens.

Required

phone

The phone number associated with this billing or shipping address. This field supports both U.S. and Canadian phone numbers. [max length = 15]

Optional

fax

The fax number associated with this billing or shipping address.

Optional

email

The email address associated with this billing or shipping address [max length = 50]

Optional

label

A label that succinctly identifies the address. For example, "Work" or "Home."

Optional

address_type

The type of address. Use one of the following values:


a. default_billing - the default billing address

b. default_shipping - the default shipping address

c. none - the address is not a default address

d. both- the address is both a default shipping and default billing address

Optional

shipping_address_type

Indicates whether the address is a residential or commercial address.

Required

physical_address

The Physical Address object.

Optional

physical_address Object

The physical_address object is returned within GET, POST, and PUT Address calls and contains the following child parameters.

Parameter

Description

Req

street_line1

The first line of the street address [max length = 35]

Optional

street_line2

The second line of the street address [max length = 35]

Optional

locality

Locality or city/town/village [max length = 25]

Optional

region

Region or state/province. This field supports both U.S. and Canadian regions. [max length = 2]

Optional

postal_code

Postal Code [max length = 15]. This field supports both U.S. and Canadian postal codes.

Optional

Find Addresses

Use the following endpoints to find an address.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/customers/{customer_token}/addresses/

Returns all Address(es) for a Customer

/accounts/{account_id}/locations/{location_id}/customers/{customer_token}/addresses/{address_token}

Returns Address object detail

To narrow your search data using specific criteria, use the following parameters with the endpoints above to filter your results:

Filter Parameter

Example

account_id

/accounts/{account_id}/locations/{location_id}/addresses/?filter=account_id+eq+act_300005

location_id

/accounts/{account_id}/locations/{location_id}/addresses/?filter=location_id+eq+loc_115161

customer_token

/accounts/{account_id}/locations/{location_id}/addresses/?filter=customer_token+eq+cst_SoGUG6mcLUS1nVzYBIbk3g

The following code samples display example endpoint and GET calls you can use to find a customer address.

GET

/accounts/act_300005/locations/loc_115161/customers/cst_XdiEhB2GMkiTDc3uKQtz-A/addresses/

Response
				
					{
  "number_results": 2,
  "search_criteria": {
    "home_account_id": "act_300005",
    "resource_specific": {
      "location_id": "loc_115161",
      "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A"
    }
  },
  "results": [
    {
      "address_token": "add_Di5DRA0VuECJ_Xk1N0zJVw",
      "account_id": "act_300005",
      "location_id": "loc_115161",
      "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
      "first_name": "Emmett",
      "last_name": "Brown",
      "company_name": "Brown Associates",
      "phone": "555-555-7896",
      "fax": "555-555-7412",
      "email": "e.brown@brownassociates.com",
      "label": "Brown Billing",
      "address_type": "default_billing",
      "billing_address_type": "commercial",
      "physical_address": {
        "street_line1": "502 Delorean Way",
        "street_line2": "Suite 400",
        "locality": "Hill Valley",
        "region": "CA",
        "postal_code": "95420"
      },
      "links": {
        "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_
        02bIb4SXxOm5A/addresses/add_Di5DRA0VuECJ_Xk1N0zJVw"
      }
    },
    {
      "address_token": "add_VRURfxRxnUGDUHVW7xqqpA",
      "account_id": "act_300005",
      "location_id": "loc_115161",
      "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
      "first_name": "Emmett",
      "last_name": "Brown",
      "company_name": "Brown Associates",
      "phone": "555-555-5393",
      "fax": "555-555-5394",
      "email": "e.brown@brownassociates.com",
      "label": "Brown Shipping",
      "address_type": "default_shipping",
      "shipping_address_type": "residential",
      "physical_address": {
        "street_line1": "502 Delorean Way",
        "street_line2": "Suite 200",
        "locality": "Hill Valley",
        "region": "CA",
        "postal_code": "95420"
      },
      "links": {
        "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_
        02bIb4SXxOm5A/addresses/add_VRURfxRxnUGDUHVW7xqqpA"
      }
    }
  ],
  "response": {
    "environment": "live",
    "response_desc": "Get Successful."
  },
  "links": {
    "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A
    /addresses"
  }
}
GET

/accounts/act_300005/locations/loc_115161/addresses/add_VRURfxRxnUGDUHVW7xqqpA

Response
				
					{
  "address_token": "add_VRURfxRxnUGDUHVW7xqqpA",
  "account_id": "act_300005",
  "location_id": "loc_115161",
  "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
  "first_name": "Emmett",
  "last_name": "Brown",
  "company_name": "Brown Associates",
  "phone": "555-555-5393",
  "fax": "555-555-5394",
  "email": "e.brown@brownassociates.com",
  "label": "Brown Shipping",
  "address_type": "default_shipping",
  "shipping_address_type": "residential",
  "physical_address": {
    "street_line1": "502 Delorean Way",
    "street_line2": "Suite 200",
    "locality": "Hill Valley",
    "region": "CA",
    "postal_code": "95420"
  },
  "response": {
    "environment": "live",
    "response_desc": "Get Successful."
  },
  "links": {
    "self": "/v2/accounts/act_300005/locations/loc_115161/addresses/add_VRURfxRxnUGDUHVW7xqqpA"
  }
}
Create Addresses

Use the following endpoints to create an address.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/customers/{customer_token}/addresses/

Creates a new Address for the Customer. Returns the address_token.

/accounts/{account_id}/customers/{customer_token}/addresses/

This endpoint also creates a new address for the specified customer; however, the data that the user passes in must specify a Location ID. For example, if the user was creating an address, he or she would also need to pass in the location_id field.

The following code samples display example endpoints and POST calls you can use to create an address.

POST

/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A/addresses/

Request
				
					{
   "physical_address": {
      "street_line1": "8003 Clock Tower Ln",
      "street_line2": "Suite 200",
      "locality": "Hill Valley",
      "region": "CA",
      "postal_code": "95420"
   }
}
Response
				
					{
  "address_token": "add_hPAgRmhOcEy_ki2NB0u07g",
  "location_id": "loc_115161",
  "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
  "physical_address": {
    "street_line1": "8003 Clock Tower Ln",
    "street_line2": "Suite 200",
    "locality": "Hill Valley",
    "region": "CA",
    "postal_code": "95420"
  },
  "response": {
    "environment": "live",
    "response_desc": "Create Successful."
  },
  "links": {
    "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A
    /addresses/add_hPAgRmhOcEy_ki2NB0u07g"
  }
}
POST

/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A/addresses/

Request
				
					{
   "address_token": "",
   "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
   "label": "Shipping",
   "first_name": "Marty",
   "last_name": "McFly",
   "company_name": "Brown Associates",
   "phone": "444-444-4444",
   "fax": "444-444-4445",
   "email": "m.mcfly@brown.net",
   "physical_address":{
      "street_line1": "8003 Clock Tower Ln",
      "street_line2": "Suite 200",
      "locality": "Hill Valley",
      "postal_code": "95420"
   }
}
Response
				
					{
  "address_token": "add_MYvKPdNB5kOHOEAaW6LZ5w",
  "location_id": "loc_115161",
  "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
  "first_name": "Marty",
  "last_name": "McFly",
  "company_name": "Brown Associates",
  "label": "Shipping",
  "physical_address": {
    "street_line1": "8003 Clock Tower Ln",
    "street_line2": "Suite 200",
    "locality": "Hill Valley",
    "postal_code": "95420"
  },
  "response": {
    "environment": "live",
    "response_desc": "Create Successful."
  },
  "links": {
    "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A
    /addresses/add_MYvKPdNB5kOHOEAaW6LZ5w"
  }
}
Update Addresses

Use the following endpoints to update an address.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/customers/{customer_token}/addresses/{address_token}

Updates the Address and returns the address_token.

The following code samples display example endpoints and PUT calls you can use to create an address.

PUT

/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A/addresses/
add_MYvKPdNB5kOHOEAaW6LZ5w

Request
				
					{
   "physical_address": {
      "street_line1": "8003 Clock Tower Ln",
      "street_line2": "Suite 101",
      "locality": "Hill Valley",
      "region": "CA"
   }
}
Response
				
					{
  "address_token": "add_MYvKPdNB5kOHOEAaW6LZ5w",
  "location_id": "loc_115161",
  "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
  "physical_address": {
    "street_line1": "8003 Clock Tower Ln",
    "street_line2": "Suite 101",
    "locality": "Hill Valley",
    "region": "CA"
  },
  "response": {
    "environment": "live",
    "response_desc": "Update Successful."
  }
}
PUT

/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A/
addresses/add_VRURfxRxnUGDUHVW7xqqpA

Request
				
					{
   "label": "Shipping",
   "first_name": "Jennifer",
   "last_name": "Parker-McFly",
   "company_name": "Brown Associates",
   "phone": "444-444-4444",
   "fax": "555-555-5555",
   "email": "j.mcfly@brown.net",
   "shipping_address_type": "commercial",
   "address_type": "none",
   "physical_address": {
      "street_line1": "58003 Clock Tower Ln",
      "street_line2": "Suite 101",
      "locality": "Hill Valley",
      "region": "CA",
      "postal_code": "95420"
   }
}
Response
				
					{
  "address_token": "add_VRURfxRxnUGDUHVW7xqqpA",
  "location_id": "loc_115161",
  "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
  "first_name": "Jennifer",
  "last_name": "Parker-McFly",
  "company_name": "Brown Associates",
  "label": "Shipping",
  "address_type": "none",
  "shipping_address_type": "commercial",
  "physical_address": {
    "street_line1": "58003 Clock Tower Ln",
    "street_line2": "Suite 101",
    "locality": "Hill Valley",
    "region": "CA",
    "postal_code": "95420"
  },
  "response": {
    "environment": "live",
    "response_desc": "Update Successful."
  }
}
Delete Addresses

Use the following endpoint to delete an address.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/customers/{customer_token}/addresses/{address_token}

This endpoint deletes the specified address.

The following code samples display example endpoints and DELETE calls you can use to delete an address.

DELETE

/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A/
addresses/add_VRURfxRxnUGDUHVW7xqqpA

Response
				
					{
   "address_token":"add_VRURfxRxnUGDUHVW7xqqpA"
}

Paymethods

Create, maintain, and delete customer payment data with the paymethod object using the following input parameters and code samples.

paymethod Object

Parameter

Description

Req

account_id

The identification number of the associated account. For example, 
act_5551236.

Required

location_id

The identification number of the associated location. For example, 
loc_1234568.

Required

customer_token

A unique string used to represent a customer. For example, 
cst_SoGUG6mcLUS1nVzYBIbk3g.
[max length = 26]

NOTE: When a merchant passes a customer token with a transaction, Forte ignores any other customer data in favor of the default data stored with the token.

Optional

paymethod_token

A unique string used to represent a payment method. For example, 
mth_1578436587.
[max length = 26]

Optional

label

A friendly, customer-defined name for the payment method. For example,
"Moms Credit Card," "Work Credit Card," "Visa - 1234," etc.
[max length = 50]

Required

card

The card object

Optional

echeck

The echeck object

Optional

notes

A short description of the paymethod.

Optional

Find Paymethods

Use the following endpoints to find paymethods.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/paymethods/{paymethod_token}

Returns Paymethod object detail

/accounts/{account_id}/locations/{location_id}/paymethods

Returns all Paymethods for a Location

/accounts/{account_id}/locations/{location_id}/customers/{customer_token}/paymethods

Returns all Paymethods for a Customer

To narrow your search data using specific criteria, use the following parameters with the endpoints above to filter your results:

Filter Parameter

Example

account_id

/accounts/{account_id}/locations/{location_id}/paymethods/?filter=account_id+eq+act_300005

location_id

/accounts/{account_id}/locations/{location_id}/paymethods/?filter=location_id+eq+loc_115161

customer_token

/accounts/{account_id}/locations/{location_id}/paymethods/?filter=customer_token+eq+cst_SoGUG6mcLUS1nVzYBIbk3g

start_au_updated_date/
end_au_updated_date

/accounts/{account_id}/locations/{location_id}/transactions/?filter=start_au_updated_date+eq+
'2002-01-08'+and+end_au_updated_date+eq+'2013-12-08'

paymethod_type

/accounts/{account_id}/locations/{location_id}/paymethods/?filter=paymethod_type+eq+card

/accounts/{account_id}/locations/{location_id}/paymethods/?filter=paymethod_type+eq+echeck

The following code samples display example endpoints and GETcalls you can use to find a paymethod.

GET

/accounts/act_300005/customers/cst_6cHpUhBG_02bIb4SXxOm5A/paymethods/

Response
				
					{
  "number_results": 1,
  "search_criteria": {
    "home_account_id": "act_300005",
    "resource_specific": {
      "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A"
    }
  },
  "results": [
  {
    "paymethod_token": "mth_LCaCk2jdLUOfdrPxtsgjWA",
    "account_id": "act_300005",
    "location_id": "loc_115161",
    "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
    "label": "Account Ending - 1111",
    "notes": "Brown Work",
    "echeck": {
      "account_holder": "Marty McFly",
      "masked_account_number": "************1111",
      "routing_number": "044000804",
      "account_type": "checking"
    },
    "links": {
      "self": "/v2/accounts/act_300005/customers/cst_6cHpUhBG_02bIb4SXxOm5A/paymethods/
      mth_LCaCk2jdLUOfdrPxtsgjWA"
    } 
  }
  ],
  "response": {
    "environment": "live",
    "response_desc": "Get Successful."
  },
  "links": {
    "self": "/v2/accounts/act_300005/customers/cst_6cHpUhBG_02bIb4SXxOm5A/paymethods"
  }
}
GET

/accounts/act_300005/customers/cst_6cHpUhBG_02bIb4SXxOm5A/paymethods/mth_LCaCk2jdLUOfdrPxtsgjWA

Response (Credit Card)
				
					{
  "paymethod_token": "mth_LCaCk2jdLUOfdrPxtsgjWA",
  "account_id": "act_300005",
  "location_id": "loc_115161",
  "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
  "label": "Visa Credit Card - 1111",
  "notes": "Brwn Work Card",
  "card": {
    "name_on_card": "Emmett Brown",
    "masked_account_number": "************1111",
    "expire_month": 12,
    "expire_year": 2015,
    "procurement_card": false,
    "card_type": "visa"
  },
  "response": {
    "environment": "live",
    "response_desc": "Get Successful."
  },
  "links": {
    "self": "/v2/accounts/act_300005/customers/cst_6cHpUhBG_02bIb4SXxOm5A/paymethods/
    mth_LCaCk2jdLUOfdrPxtsgjWA"
  }
}
Response (eCheck)
				
					{
  "paymethod_token": "mth_LCaCk2jdLUOfdrPxtsgjWA",
  "account_id": "act_300005",
  "location_id": "loc_115161",
  "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
  "label": "Account Ending - 1111",
  "notes": "Brown Work",
  "echeck": {
    "account_holder": "Marty McFly",
    "masked_account_number": "************1111",
    "routing_number": "044000804",
    "account_type": "checking"
  },
  "response": {
    "environment": "live",
    "response_desc": "Get Successful."
  },
  "links": {
    "self": "/v2/accounts/act_300005/customers/cst_6cHpUhBG_02bIb4SXxOm5A/paymethods/
    mth_LCaCk2jdLUOfdrPxtsgjWA"
  }
}
Create Paymethods

Use the following endpoint to create paymethods.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/paymethods

This endpoint can perform the following tasks while returning a new Paymethod token:


• Create Paymethod credit card or echeck information only


• Create a Paymethod token using a one-time token

NOTE: At this time, one-time tokens cannot be used to
create account-level paymethod tokens.


• Create a Paymethod with the billing address

/accounts/{account_id}/paymethods

This endpoint can perform the same tasks listed above; however,
the data that the user passes in must specify a location_id. For
example, if the user was creating a paymethod with only credit card information, he or she would also need to pass in the location_id field.

/accounts/{account_id}/locations/{location_id}/customers/{customer_token}/paymethods

Creates a new paymethod for the customer and returns a paymethod token. A permanent Paymethod token can be created from a
one-time token.

The following code samples display example endpoints and POST calls you can use to create a paymethod. For information on creating a one-time token, see the Forte.js documentation.

POST

/accounts/act_200000/locations/loc_100000/customers/cst_ToEFV6mcQWE1nVzFCIbg78/paymethods

Request (eCheck)
				
					{
   "notes":"Brwn echeck",
   "echeck":
     {
     "account_holder": "Emmett Brown",
     "account_number":"1111111111111",
     "routing_number":"021000021",
     "account_type":"checking"
     }
}
Request (Credit Card)
				
					{
   "notes":"Brwn Work Card",
   "card":
     {
      "name_on_card":"Emmett Brown",
      "account_number":"4111111111111111",
      "card_type":"visa",
      "expire_month":12,
      "expire_year":2015,
      "card_verification_value": "123"
     }
}
Response (eCheck)
				
					{
  "paymethod_token": "mth_VTPXxurqoU6TqsSMMvWEgA",
  "location_id": "loc_115161",
  "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
  "notes": "Brwn echeck",
  "echeck": {
    "account_holder": "Emmett Brown",
    "masked_account_number": "************1111",
    "routing_number": "021000021",
    "account_type": "checking"
  },
  "response": {
    "environment": "live",
    "response_desc": "Create Successful."
  },
  "links": {
    "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A
    /paymethods/mth_VTPXxurqoU6TqsSMMvWEgA"
  }
}
Response (Credit Card)
				
					{
  "paymethod_token": "mth_Qh6W5lDWsUOx1hXNPl5iFw",
  "location_id": "loc_115161",
  "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
  "notes": "Brwn Work Card",
  "card": {
    "name_on_card": "Emmett Brown",
    "masked_account_number": "************1111",
    "card_type":"visa",
    "expire_month": 12,
    "expire_year": 2015
  },
  "response": {
    "environment": "live",
    "response_desc": "Create Successful."
  },
  "links": {
    "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A
    /paymethods/mth_Qh6W5lDWsUOx1hXNPl5iFw"
  }
}
POST

/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A/paymethods/

Request (eCheck)
				
					{
   "label": "Brown Work- 1111",
   "notes": "Brown Work Checking",
   "echeck": {
      "account_holder": "Marty McFly",
      "account_number": "1111111111111",					
      "routing_number": "021000021",
      "check_number": "1001",
      "account_type": "checking"
   }
}
Request (Credit Card)
				
					{  
   "label": "Visa - 1234",
   "notes": "Brown Work CC",
   "card": {
	"account_number": "4488563295465231",
	"expire_month": 12,
	"expire_year": 2015,
	"card_verification_value": "645",
	"card_type": "visa",
	"name_on_card": "Dr. Emmett Brown",
   }
}
Response (eCheck)
				
					{
  "paymethod_token": "mth_0bmJ3SSbNEu90ZnBgBfLDg",
  "location_id": "loc_115161",
  "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
  "label": "Brown Work- 1111",
  "notes": "Brown Work Checking",
  "echeck": {
    "account_holder": "Marty McFly",
    "masked_account_number": "************1111",
    "routing_number": "021000021",
    "account_type": "checking",
    "check_number": "1001"
  },
  "response": {
    "environment": "live",
    "response_desc": "Create Successful."
  },
  "links": {
    "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A
    /paymethods/mth_0bmJ3SSbNEu90ZnBgBfLDg"
  }
}
Response (Credit Card)
				
					{
  "paymethod_token": "mth_L1E6cCHEp0ek23w809dG9A",
  "location_id": "loc_115161",
  "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
  "label": "Visa - 1234",
  "notes": "Brown Work CC",
  "card": {
    "name_on_card": "Dr. Emmett Brown",
    "masked_account_number": "************5231",
    "expire_month": 12,
    "expire_year": 2015,
    "card_type": "visa"
  },
  "response": {
    "environment": "live",
    "response_desc": "Create Successful."
  },
  "links": {
    "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A
    /paymethods/mth_L1E6cCHEp0ek23w809dG9A"
  }
}
POST

/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A/paymethods/

Request 
				
					{
   "label": "Brown VISA",
   "notes": "Brown Work Card",
   "card": {
     "one_time_token": "ott_ki99oclmr8c0gduavrcjww",
     "name_on_card":"Marty McFly"
   }
}
Response
				
					{
   "paymethod_token": "mth_HKO25RCkjl-AmYxWt6Bkli",
   "location_id": "loc_115161",
   "customer_token": "cst_ToEFV6mcQWE1nVzFCIbg78",
   "label": "Brown VISA",
   "notes": "Brown Work Card",
   "card": {
      "name_on_card": "Marty McFly",
      "masked_account_number": "************1256",
      "expire_month": 12,
      "expire_year": 2015,
      "card_type": "visa"
   },
   "response": {
      "environment": "live",
      "response_desc": "Create Successful."
   },
   "links": {
      "self": "/v2/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A
      /paymethods/mth_L1E6cCHEp0ek23w809dG9A"
   }
}
Update Paymethods

Use the following endpoint to update paymethods.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/paymethods/{paymethod_token}

Updates Paymethods while returning a paymethod_token

The following code samples display example endpoints and PUTcalls you can use to update a paymethod.

PUT

/accounts/act_300005/locations/loc_115161/customers/cst_6cHpUhBG_02bIb4SXxOm5A/
paymethods/mth_L1E6cCHEp0ek23w809dG9A

Request (eCheck)
				
					{
   "label": "Brown Work- 1111",
   "notes": "Brown Work Checking",
   "echeck": {
      "account_holder": "Jennifer McFly",
      "account_number": "1111111111111",
      "routing_number": "021000021",
      "check_number": "1001",
      "account_type": "checking"
   }
}
Request (Credit Card)
				
					{
   "label": "Visa - 1111",
   "notes": "Brown Work CC",
   "card": {
      "expire_month": 12,
      "expire_year": 2020,
      "card_verification_value": "123",
      "card_type": "visa",
      "name_on_card": "Dr. Emmett Brown",
  }
}
Response (eCheck)
				
					{
  "paymethod_token": "mth_L1E6cCHEp0ek23w809dG9A",
  "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
  "label": "Brown Work- 1111",
  "notes": "Brown Work Checking",
  "echeck": {
    "account_holder": "Emmett Brown",
    "account_number": "1111111111111",
    "routing_number": "021000021",
    "account_type": "checking",
    "check_number": "1001"
  },
  "response": {
    "environment": "live",
    "response_desc": "Update Successful."
  }
}
Response (Credit Card)
				
					{
  "paymethod_token": "mth_L1E6cCHEp0ek23w809dG9A",
  "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A",
  "label": "Visa - 1111",
  "notes": "Brown Work CC",
  "card": {
    "name_on_card": "Dr. Emmett Brown",
    "expire_month": 12,
    "expire_year": 2020,
    "card_verification_value": "123",
    "card_type": "visa",
  },
  "response": {
    "environment": "live",
    "response_desc": "Update Successful."
  }
}
PUT

/accounts/act_300005/locations/loc_115161/paymethods/mth_ZK01TBclw0mTgMdrmSevdg

Request 
				
					{
  "card": {
    "expire_month": 04,
    "expire_year": 2020,
    "card_verification_value": "123",
  }
}
Response 
				
					{
  "paymethod_token": "mth_ZK01TBclw0mTgMdrmSevdg",
  "location_id": "loc_******",
  "card": {
     "expire_month": 4,
     "expire_year": 2020,
     "card_verification_value": "123"
  },
  "response": {
     "environment": "live",
     "response_desc": "Update Successful."
  }
}
Delete Paymethods

Use the following endpoint to delete paymethods. NOTE: A paymethod cannot be deleted if it is tied to an active schedule.

Endpoint

Description

/accounts/{account_id}/locations/{location_id}/paymethods/{paymethod_token}

Deletes the specified paymethod

The following code samples display example endpoints and DELETEcalls you can use to delete a paymethod.

DELETE

/accounts/acct_500000/locations/loc_100000/paymethods/mth_b5hP6e7ydU2TOhTZ4FAqxg

Response
				
					{
   "paymethod_token": "mth_b5hP6e7ydU2TOhTZ4FAqxg"
}
Click on the Edit Content button to edit/add the content.
On this page