Parameter

Description

Type

Req

organization_id

The identification number of the associated organization. For example, org_5551236.

string

R

location_id

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

string

R

action

The supported transaction types include the following values:

sale - Used to collect funds from a debit/credit card or bank account. This action is the same as an authorization + capture operation in just one step, and should be the preferred option if the intent of the merchant is to capture the funds immediately upon authorization.
authorize - Used to verify the specified account information (bank account or debit/credit card account) and balance (for credit cards). This transaction should be used when the capture of the funds will be initiated at a later time. For example, after the shipping or the delivery of goods subject to the transaction. If the intent is to authorize the transaction and capture the funds immediately a sale transaction call should be sent instead of authorization and capture calls.
credit - Used to send fund 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 were previously authorized. See authorize.
inquiry - Requests the available balance from a card. NOTE: This action is only for merchant organizations 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. NOTE: For credit cards, this action is only supported for merchants enrolled with Vantiv.
authenticate - used to verify the ownership of a bank account. This service verifies if the given person/business (identified by the First & Last name or Business Name) is the owner of a given bank account.
force - Used to capture funds by bypassing verification or authorization functionality. Merchants should verify or authorize a force operation prior to performing it.
reverse - Used to reverse a previous sale (action=sale) transaction if it's too late to void that transaction. NOTE: Action = credit or force cannot be reversed.

string

R

status

The current dispositon of the transaction. For a list of transaction status values, click here

string

--

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 paymethods object or a paymethod_token) if the customer has defined a default_paymethod_token in the customer object. [max length = 26]

string

R

customer_id

A merchant-defined string used to identify the customer. [max length = 15]

string

O

paymethod_token

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

string

O

reference_id

A merchant-defined string that identifies the transaction.[max length = 15]

string

O

authorization_amount

The amount to be charged/credited to the customer.

decimal

R

order_number

A merchant-assigned ID code that is returned with the transaction response. [max length = 36]

string

O

original_transaction_id

The trace number returned by the original transaction. [max length = 36]

string

O

transaction_id

A 36-character code that uniquely identifies the transaction.

string

O

authorization_code

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

object

R

entered_by

The name or the ID of the person entering the data. [max length = 20]

string

O

received_date

The date the merchant received the transaction. This parameter is return only.

datetime

--

origination_date

The date the funds of the transaction go to the originating depository financial institution. This parameter is return only.

datetime

--

sales_tax_amount

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

decimal

O

subtotal_amount

The base amount of the good or service. This parameter is auto-calculated and is not required for requests. Use this parameter when calculating service fees.

decimal

--

service_fee_amount

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

service_fee_amount - The percentage calculated (e.g., subtotal_amount * 2.45% for a service fee of 2.45%)
authorization_amount - The resulting sum of the subtotal_amount and the service_fee_amount.

decimal

O

recurring_indicator

A merchant-assigned flag used to indicate recurring credit card transactions for the following transaction types when set to true for POST-only requests:

sale
authorize
credit
force

NOTE: When set to true, this parameter could have an impact on a merchant's interchange rates depending on his or her credit card processor. Contact your processor for more information.

bool

O

customer_ip_address

The customer's originating IP address. This parameter is used for fraud prevention and does not echo back in the response. [max length = 80]

string

O

save_token

This parameter creates customer and/or paymethod tokens for any transaction POST request—whether passed via request parameters or via swipe data through the card.card_data parameter. Supported values include the following:

customer - Creates a new customer and paymethod tokens.
paymethod - Creates a clientless paymethod token.

string

O

attempt_number

The number of times Forte has presented an ACH transaction for settlement. Values for this field can only be positive, whole numbers (e.g., attempt_number=1). This field is return only. [max length = 80]

string

--

cof_transaction_type

Indicates whether the credential on file (COF) transaction is recurring (0) or customer initiated (1). NOTE: If you are performing a zero-dollar authorization and only storing the payment method for future use, then the pg_cof_transaction_type should be 1.

int

--

cof_initial_transaction_id

The processor’s transaction ID of the first transaction for a stored credential on file. This field is required for non-tokenized, credential-on-file subsequent transactions. [max length = 20]

string

C

billing_address

The Address Object

object

R

billing_address.address_token

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

string

R

billing_address.customer_token

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

string

R

billing_address.organization_id

The identification number of the associated organization. For example, org_5551236.

string

R

billing_address.location_id

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

string

R

billing_address.first_name

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

string

R

billing_address.last_name

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

string

R

billing_address.company_name

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

string

R

billing_address.phone

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

string

O

billing_address.email

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

string

O

billing_address.label

A label that succinctly identifies the address. For example, "Work" or "Home." [max length = 50]

string

O

billing_address.address_type

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

default_billing - The default billing address
none - The address is not a default address
both - The address is both a default shipping and default billing address

string

O

billing_address.shipping_address_type

Indicates whether the address is a residential or commercial address (if the address is both a billing and shipping address).

string

R

billing_addreess.physical_address

The Physical Address Object.

object

O

billing_address.physical_address.street_line1

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

string

O

billing_address.physical_address.street_line2

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

string

O

billing_address.physical_address.locality

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

string

O

billing_address.physical_address.region

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

string

O

billing_address.physical_address.country

The ISO 3166-1 alpha-2 country abbreviation. [max length = 2]

string

O

billing_address.physical_address.postal_code

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

string

O

shipping_address

The Address Object

object

O

shipping_address.address_token

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

string

R

shipping_address.customer_token

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

string

R

shipping_address.organization_id

The identification number of the associated organization. For example, org_5551236.

string

R

shipping_address.location_id

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

string

R

shipping_address.first_name

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

string

R

shipping_address.last_name

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

string

R

shipping_address.company_name

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

string

R

shipping_address.phone

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

string

O

shipping_address.email

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

string

O

shipping_address.label

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

string

O

shipping_address.address_type

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

default_shipping - The default shipping address
none - The address is not a default address
both - The address is both a default shipping address and a default billing address

string

O

shipping_address.shipping_address_type

Indicates whether the address is a residential or commercial address.

string

R

shipping_address.physical_address

The Physical Address Object.

object

O

shipping_address.physical_address.street_line1

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

string

O

shipping_address.physical_address.street_line2

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

string

O

shipping_address.physical_address.locality

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

string

O

shipping_address.physical_address.region

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

string

O

shipping_address.physical_address.country

The ISO 3166-1 alpha-2 country abbreviation. [max length = 2]

string

O

shipping_address.physical_address.postal_code

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

string

O

card

The Card Object

object

R

card.card_type

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

visa
mast
amex
disc
dine
jcb

string

R

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

string

R

card.last_4_account_number

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

string

--

card.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].
For Digital wallet transactions this device-specific identifier (DPAN - Device Primary Account Number) replaces the card number to securely conduct transactions.
Note: Device Primary Account Number is used for alternative method of payments.

string

R

card.expire_month

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

string

R

card.expire_year

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

string

R

card.card_verification_value

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

string

R

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

bool

O

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

string

O

card.one_time_token

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

string

O

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

string

O

card.card_data

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

string

O

card.card_emv_data

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

string

O

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

bool

O

card.wallet_cryptogram

This one-time encrypted string represents the transaction and merchant information

string

R

card.wallet_type

This field will indicate the wallet used to obtain the cryptogram. Supported values: “ApplePay”

string

R

card.wallet_source

This will indicate the platform on which the payment request was received. Web: integrations capturing payments on browser Mobile: Data values describing an InApp Transaction

string

R

echeck

The eCheck Object

object

R

echeck.account_holder

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

string

R

echeck.last_4_account_number

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

string

--

echeck.account_number

The DDA or eCheck account number. This field is required when creating or updating a new record and can only contain digits. Forte echoes this parameter in the echeck.masked_account_number response parameter.

string

R

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

string

R

echeck.account_type

>Use one of the following values for this parameter:

Checking
Savings

string

O

echeck.item_description

Check number or other description of item to be processed. NOTE: This field is only available for POST transactions and is not included in the paymethods object.

string

O

echeck.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 eCheck transactions, it is only required for action= "sale", "authorize", "credit" and "force". Otherwise (e.g. "verify", "authenticate") it should be null. For more information on SEC codes, see the ACH Standard Entry Class (SEC) Codes Tutorial. This parameter is required to conform with 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.

string

C

echeck.one_time_token

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

string

O

line_items

The Line Items Object.

object

O

line_items.line_item_header

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

string

O

line_items.line_item_1-10000

Contents of the line item formatted according to the line_item_header.

string

O

xdata

The Xdata Object

object

O

xdata.xdata_1-9

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.

string

O

vendor

The vendor Object

object

O

vendor.vendor_type

The supported vendor types include the following.

PayPal

string

R

vendor.vendor_order_number

The ID of the order

**Note:**The vendor_order_number is required for vendor when creating transaction without PayPal tokens

string

R

vendor.vendor_billing_agreement_id

The ID of PayPal billing agreement

NOTE:The vendor_billing_agreement_id is required for vendor when creating transaction with PayPal tokens.

string