Web Services

Ready. . .Set. . .Integrate.


NOTE: Forte is currently conducting beta testing of our new web services. If you would like to participate in the beta testing program, please contact Customer Service at customerservice@forte.net.

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

Use the following URI when making REST calls:

  • https://sandbox.forte.net/api/v2 for sandbox testing
  • For the production URI, contact Forte Technical Support.

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

Action HTTP Method Description
Create POST Creates an item 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 comprehensive information on an item, provide the item's id to the defined endpoint.
Update PUT Modifies the existing item for the provided endpoint.
Delete DELETE Deletes the existing item for the provided endpoint.

 

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.

Currently, the Forte REST API does not support cross-origin resource sharing (CORS); however, future versions of the API may enable this feature.

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 [max = 26 ] cst_SoGUG6mcLUS1nVzYBIbk3g
Addresses add_ + Token [max = 26] add_jUYRwbRjKUWgswNrFpSdKg
Paymethods mth_ + Token [max = 26] mth_ymC20TMkHE-YmYxMt0UvMA
Transactions trn_ + GUID [max = 36] trn_55c98c85-d3e8-4230-85e9-21d7d522eec0
Settlements stl_ + GUID [max = 36] stl_51cf4633-1767-484f-8784-be76a4076791

 

Hypermedia

The 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",
}
}

 

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:
    • asc = ascending (default if not specified)
    • desc - descending
/settlements?filter=start_settle_date+eq+%27
2014-11-20%27&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=bill_to_company_name+eq
+%27ACME%27&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=card_type+eq+%27visa%27
&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 search in the resource_filters object.

 

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 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.

 

For status codes in the 400's, ensure that you correctly formatted the JSON in the original request, especially when the system returns a descriptive error message along with the status code, like the following example messages:

{
message: "Authentication Account ID in header is missing or invalid."
}

 

{
message: "Payment Method's routing number length is invalid."
}

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 Login ID, and a Secure Transaction Key for the sandbox environments. NOTE: The Location ID represents the same information as the Merchant ID in the Virtual Terminal.

Forte's REST services rely on Basic access authentication over HTTPS using an API Login ID and a Secure Transaction Key as the username and password values (e.g., APILoginID:Secure Transaction Key).

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(APILoginID + ":" + SecureTransactionKey)).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; .

 

Forte includes the response subobject in responses for POST and PUT operations to the transaction, customer, paymethod, and address resources. NOTE: Forte returns the response_desc and environment parameters for all resources; the remaining parameters are returned for the transaction resource only.

response Object

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

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.

{  
  "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"
}
	

{ "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" }

{ "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" }


Transaction

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.

Settlement

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.

Customer

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.

Address

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

Paymethod

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.

 


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

transaction Object

 

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 - Creates an ad-hoc or token transaction that will settle at the end of the day
  • authorize - authorizes the payment method, but does not create a transaction
  • disburse - used to send funds back to the account/card holder rather than collecting funds from an account/card holder
  • void - voids the unsettled transaction. Attempts to void settled transactions will be declined.
  • capture - authorizes the payment method and creates a transaction that will settle at the end of the day
  • inquiry - Requests the available balance from a card. NOTE: This action is only for merchant accounts approved to process partial authorization transactions.
  • verify - The payment method is verified but no authorization is obtained and it cannot be settled. Used in conjunction with Forte Verify.
  • force - The transaction is complete and the funds will be captured at the end of the day. Forte does not perform verification checks for this type of transaction.
Required
one_time_token A single use token generated by Forte.js. Optional
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. Optional
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
software_name The version number of the software used to create the 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
origination_date The date the funds of the transaction go to the originating depository financial institution. Optional
sales_tax_amount The sales tax amount. This field is only required for procurement card transactions. Optional
service_fee_amount The calculated service fee for this transaction 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

Optional
billing_address The Address Object Optional
shipping_address The Address Object Optional
card The card Object Optional
echeck The echeck Object  

 

card Object

The transaction card object contains the following parameters.

card_type

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

  • visa
  • mast
  • amex
  • disc
Required
name_on_card The name printed on the 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
account_number The card number. This field is required when creating a new record and can only contain digits
[max length = 16].
Optional
expire_month The expiration month. This field is required when creating a new record and must be a valid future date
[max length = 2].
Optional
expire_year The expiration year. This field is required when creating a new record and must be a valid future date
[max length = 4].
Optional
card_verification_value The card verification number. Forte does not store this field with the paymethod token, but echoes it back. Optional
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. Optional
customer_accounting_code Lists the procurement card accounting code, which is used for Level 2 data. Forte does not save this information if the merchant is creating a paymethod. Optional
one_time_token A single use token generated by Forte.js. Optional

echeck Object

The transaction echeck object contains the following parameters.

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 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:
  1. Checking
  2. 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

Find Transactions

Use the following endpoints to find a transaction.

/accounts/{id}/locations/{id}/transactions

Returns all Transactions for a Location. Use the following filters to narrow down your search results. NOTE: 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 (echeck transactions only), end_origination_date (echeck transactions only)
  • To find transactions from a single day:
    received_date, origination_date (echeck transactions only)
  • bill_to_first_name, bill_to_last_name, bill_to_company_name
  • status
  • authorization_amount
  • order_number
  • entered_by
  • last4

NOTE: 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/{id}/locations/{id}/transactions/{action}

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

  • sale
  • disburse
  • authorize
  • verify
  • inquiry
/accounts/{id}/locations/{id}/transactions/{id} Returns Transaction object detail
/accounts/{id}/locations/{id}/customers/{id}/transactions Returns all Transactions for a Customer

 

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

 

 

GET

/accounts/act_300005/locations/loc_115161/transactions/?filter=bill_to_last_name+eq+McFly

 

Response

{ "number_results": 2, "search_criteria": { "home_account_id": "act_300005", "resource_specific": { "location_id": "loc_115161" } }, "results": [ { "transaction_id": "trn_2c2261e9-e506-4178-810b-699614bf741e", "account_id": "act_300005", "location_id": "loc_115161", "customer_token": "cst_bzGojNYBZ0e62xYaPWO-_A", "customer_id": "456987", "order_number": "3330256", "reference_id": "4569874", "status": "ready", "action": "sale", "authorization_amount": 0.23, "authorization_code": "86697776", "entered_by": "Griff Tannen", "received_date": "2015-01-02T04:18:33.417", "bill_to_first_name": "Michael", "bill_to_last_name": "Fox", "bill_to_company_name": "MJF Productions", "response": { "response_code": "A01" }, "links": { "self": "/v2/accounts/act_300005/locations/loc_115161/transactions/trn_2c2261e9-e506 -4178-810b-699614bf741e", "settlements": "/v2/accounts/act_300005/locations/loc_115161/transactions/trn_2c2261e9 -e506-4178-810b-699614bf741e/settlements" } }, { "transaction_id": "trn_54641352-f279-4f45-981a-7909f03a97eb", "account_id": "act_300005", "location_id": "loc_115161", "customer_id": "32215", "order_number": "33302547", "reference_id": "789654", "status": "ready", "action": "sale", "authorization_amount": 0.23, "authorization_code": "86697777", "entered_by": "", "received_date": "2015-01-02T04:18:33.967", "bill_to_first_name": "Christoper", "bill_to_last_name": "Lloyd", "bill_to_company_name": "MJF Productions", "response": { "response_code": "A01" }, "links": { "self": "/v2/accounts/act_300005/locations/loc_115161/transactions/trn_54641352-f279 -4f45-981a-7909f03a97eb", "settlements": "/v2/accounts/act_300005/locations/loc_115161/transactions/trn_54641352 -f279-4f45-981a-7909f03a97eb/settlements" } } ], "response": { "environment": "live", "response_desc": "Get Successful." }, "links": { "self": "/v2/accounts/act_300005/locations/loc_115161/transactions?filter=%3ffilter%3 dbill_to_last_name%2beq%2bqa", "next": "/v2/accounts/act_300005/locations/loc_115161/transactions?filter=%3ffilter%3 dbill_to_last_name%2beq%2bqa&page_index=1" } }

 

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" } }

 

GET

accounts/act_300005/locations/loc_115161/transactions/?filter=start_origination_date+eq+
%272014-01-01T00:00:00%27+and+end_origination_date+eq+%272014-01-15T00:00:00%27&r=1

 

Response

{ "number_results": 23, "search_criteria": { "home_account_id": "act_300005", "resource_specific": { "location_id": "loc_115161", "start_origination_date": "2014-01-01T00:00:00", "end_origination_date": "2014-01-15T00:00:00" } }, "results": [ { "transaction_id": "trn_05d60999-b4c9-477d-a139-b71ed894bef0", "account_id": "act_300005", "location_id": "loc_115161", "customer_id": "1234567", "order_number": "456897", "reference_id": "456", "status": "funded", "action": "sale", "authorization_amount": 2.73, "authorization_code": "47538412", "entered_by": "m1NrGv9pM", "received_date": "2014-01-15T08:31:20.26", "origination_date": "2014-01-15T00:00:00", "bill_to_first_name": "Michael", "bill_to_last_name": "Fox", "bill_to_company_name": "MJF Productions", "response": { "response_code": "A01" }, "links": { "self": "/v2/accounts/act_300005/locations/loc_115161/transactions/trn_05d60999-b4c9 -477d-a139-b71ed894bef0", "settlements": "/v2/accounts/act_300005/locations/loc_115161/transactions/trn_05d60999 -b4c9-477d-a139-b71ed894bef0/settlements" } }, { "transaction_id": "trn_d8113d12-3730-4e5b-b021-2f7c13e0d0e9", "account_id": "act_300005", "location_id": "loc_115161", "customer_id": "458745", "order_number": "698523", "reference_id": "7412", "status": "funded", "action": "sale", "authorization_amount": 2.73, "authorization_code": "47521541", "entered_by": "m1NrGv9pM", "received_date": "2014-01-15T08:48:55.997", "origination_date": "2014-01-15T00:00:00", "bill_to_first_name": "Christopher", "bill_to_last_name": "Lloyd", "bill_to_company_name": "MJF Productions", "response": { "response_code": "A01" }, "links": { "self": "/v2/accounts/act_300005/locations/loc_115161/transactions/trn_d8113d12 -3730-4e5b-b021-2f7c13e0d0e9", "settlements": "/v2/accounts/act_300005/locations/loc_115161/transactions/trn_d8113d12 -3730-4e5b-b021-2f7c13e0d0e9/settlements" } } ], "response": { "environment": "live", "response_desc": "Get Successful." }, "links": { "self": "/v2/accounts/act_300005/locations/loc_115161/transactions?filter=start_origination_date +eq+%272014-01-01T00%3a00%3a00%27+and+end_origination_date+eq+%272014-01-15T00%3a00%3a00%27&r= 1%3f" } }

Create Transactions

Use the following endpoints to create transactions.

/accounts/{id}/locations/{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
/accounts/{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 field.
/accounts/{id}/locations/{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

{ "action":"sale", "authorization_amount": 1.00, "billing_address":{ "first_name": "Emmett", "last_name": "Brown" }, "card":{ "card_type": "visa", "account_number": "4111111111111111", "expire_month": 12, "expire_year": 2015, "card_verification_value": "123" } }

Response

{ "transaction_id": "trn_4bcfa57d-18e9-456e-8ce0-da7eb3a4f37d", "location_id": "loc_115161", "action": "sale", "authorization_amount": 1.0, "billing_address": { "first_name": "Emmett", "last_name": "Brown" }, "card": { "masked_account_number": "****1111", "expire_month": 12, "expire_year": 2015, "card_verification_value": "123", "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/accounts/act_300005/locations/loc_115161/transactions/trn_4bcfa57d-18e9 -456e-8ce0-da7eb3a4f37d", "settlements": "/v2/accounts/act_300005/locations/loc_115161/transactions/trn_4bcfa57d -18e9-456e-8ce0-da7eb3a4f37d/settlements" } }

 

POST

/accounts/act_300005/locations/loc_115161/transactions/

 

Request

{ "action":"sale", "customer_token":"cst_6cHpUhBG_02bIb4SXxOm5A", "paymethod_token":"mth_jSrW_4HsdEmo0J2oOZ36Uw", "customer_id": "456852", "reference_id": "000159", "authorization_amount": 1.00, "entered_by":"Griff Tannen", "sales_tax_amount": 0.25 }

Response

{ "transaction_id": "trn_f62b810c-bf7a-4069-98ac-2435c052ab4c", "location_id": "loc_115161", "customer_token": "cst_6cHpUhBG_02bIb4SXxOm5A", "paymethod_token": "mth_jSrW_4HsdEmo0J2oOZ36Uw", "customer_id": "456852", "reference_id": "000159", "action": "sale", "authorization_amount": 1.0, "sales_tax_amount": 0.25, "entered_by": "Griff Tannen", "response": { "authorization_code":"123456", "avs_result":"Y", "cvv_code":"M", "environment": "live", "response_type": "A", "response_code": "A01", "response_desc": "APPROVED" }, "links": { "self": "/v2/accounts/act_300005/locations/loc_115161/transactions/trn_f62b810c -bf7a-4069-98ac-2435c052ab4c", "settlements": "/v2/accounts/act_300005/locations/loc_115161/transactions/trn_f62b810c -bf7a-4069-98ac-2435c052ab4c/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-zsxgq689rew" } }

Response

{ "transaction_id": "trn_0836f440-f183-4ed1-9f79-395d3c2528ee", "location_id": "loc_115161", "action": "sale", "authorization_amount": 1.0, "billing_address": { "first_name": "Emmett", "last_name": "Brown" }, "card": { "one_time_token": "ott_tq0hemmmtf-zsxgq689rew" }, "response": { "authorization_code":"123456", "avs_result":"Y", "cvv_code":"M", "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 Transaction

Use the following endpoints to update a transaction.

/accounts/{id}/locations/{id}/transactions/{id}

Updates the Transaction and returns a new Transaction ID

/accounts/{id}/locations/{id}/transactions/{id}/{action}

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

  • Void
  • Capture

 

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

 

 

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" }

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

 

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_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. 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 a Settlement

Use the following endpoint to find a settlement.

/accounts/{id}/locations/{id}/settlements

This endpoint returns all the transaction settlements for a Location.

 

To narrow this data to a specific time frame, settlement type, response code, or settlement amount, use the following parameters to filter your results:

settle_date* /accounts/{id}/locations/{id}/settlements/?filter=start_settle_date+eq+'2002-01-08'+and+end_settle_date
+eq+'2013-12-08'
settle_response_code /accounts/{id}/locations/{id}/settlements/?filter=settle_response_code+eq+'R21'
method /accounts/{id}/locations/{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" } }

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

customer Object

 

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:
  1. active
  2. 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 The Paymethod Object Optional
addresses An array of Address Objects  

Find a Customer

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

/accounts/{id}/locations/{id}/customers This endpoint returns all the Customers for a Location.
/accounts/{id}/locations/{id}/customers/{id} This endpoint returns all the default information of a Customer object.

 

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 a Customer

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

/accounts/{id}/locations/{id}/customers

This endpoint can perform the following tasks while returning a new Customer ID/token:

  • 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/{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 field.

 

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", "customer_id": "036598",
"addresses": [
{
"label": "Brown Shipping",
"first_name": "Emmett",
"last_name": "Brown",
"company_name": "Brown Associates",
"phone_number": "444-444-4444",
"fax_number": "444-444-4445",
"email_address": "e.brown@brown.net",
"shipping_address_type": "residential",
"address_type": "default_shipping",
"addresses": {
"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_number": "444-444-4444",
"fax_number": "444-444-4446",
"email_address": "e.brown@forte.net",
"shipping_address_type": "commercial",
"address_type": "default_billing",
"addresses": {
"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",
"partial_auth_allowed": "No",
"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", "customer_id": "036598", "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", "label": "Brown Billing", "address_type": "default_billing", "shipping_address_type": "commercial", "physical_address": {}, "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", "label": "Brown Shipping", "address_type": "default_shipping", "shipping_address_type": "residential", "physical_address": {}, "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" } }, "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" } }

Update a Customer

Use the following endpoint to update a customer.

/accounts/{id}/locations/{id}/customers/{id}

This endpoint can perform the following tasks while returning the Customer ID:

  • 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 a Customer

Use the following endpoint to delete a customer.

/accounts/{id}/locations/{id}/customers/{id} This endpoint deletes a Customer object

 

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" }

 

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

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] Optional
last_name The last name of the user associated with this billing or shipping address [max length = 50] Optional
company_name The name of the company associated with this billing or shipping address [max length = 50] Optional
phone The phone number associated with this billing or shipping address [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:

  1. default_billing - the default billing address
  2. default_shipping - the default shipping address
  3. none - the address is not a default address
  4. 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.

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 [max length = 2] Optional
postal_code Postal Code [max length = 15] Optional

Find an Address

Use the following endpoints to find an address.

/accounts/{id}/locations/{id}/customers/{id}/addresses/ Returns all Address(es) for a Customer
/accounts/{id}/locations/{id}/customers/{id}/addresses/{id} Returns Address object detail

 

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 an Address

Use the following endpoint to create an address.

/accounts/{id}/locations/{id}/customers/{id}/addresses/ Creates a new Address for the Customer. Returns the Address ID.
/accounts/{id}/customers/{id}/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_number": "444-444-4444",
"fax_number": "444-444-4445",
"email_address": "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 an Address

Use the following endpoint to update an address.

/accounts/{id}/locations/{id}/customers/{id}/addresses/{id} Updates the Address and returns the Address ID.

 

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_number": "444-444-4444",
"fax_number": "555-555-5555",
"email_address": "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 an Address

Use the following endpoint to delete an address.

/accounts/{id}/locations/{id}/customers/{id}/addresses/{id} This endpoint deletes an Address object.

 

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"
}

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

paymethod Object

 

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.

/accounts/{id}/locations/{id}/paymethods/{id} Returns Paymethod object detail
/accounts/{id}/locations/{id}/paymethods Returns all Paymethods for a Location
/accounts/{id}/locations/{id}/customers/{id}/paymethods Returns all Paymethods for a Customer

 

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.

/accounts/{id}/locations/{id}/paymethods

This endpoint can perform the following tasks while returning a new Paymethod ID/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/{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/{id}/locations/{id}/customers/{id}/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", "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", "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", "partial_auth_allowed": "balance" } }

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.

/accounts/{id}/locations/{id}/paymethods/{id} Updates Paymethods while returning a Paymethods token

 

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

 

 

PUT

/accounts/act_300005/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": { "account_number": "4111111111111111", "expire_month": 12, "expire_year": 2015, "card_verification_value": "123", "card_type": "visa", "name_on_card": "Dr. Emmett Brown", "partial_auth_allowed": "balance" } }

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", "account_number": "4111111111111111", "expire_month": 12, "expire_year": 2015, "card_verification_value": "123", "card_type": "visa", "partial_auth_allowed": "balance" }, "response": { "environment": "live", "response_desc": "Update Successful." } }

Delete Paymethods

Use the following endpoint to delete paymethods.

/accounts/{id}/locations/{id}/paymethods/{id}?customerToken={id} Updates Paymethods while returning a Paymethods token

 

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"
}