Methodology

Direct Post API

Transactions

Steps:
1. The customer sends their payment information to the merchant's web site.
2. The merchant web site posts the payment data to the Payment Gateway.
3. The Payment Gateway responds immediately with the results of the transactions.
4. The merchant web site displays the appropriate message to the customer.

The communication method used to send messages to the Payment Gateway's server is the standard HTTP
protocol over an SSL connection.

In the Direct Post method, the communications with the cardholder (Steps 1 and 4) are developed completely by
the merchant and therefore are not defined by the Payment Gateway. Step 1 should simply collect the payment
data from the cardholder and Step 4 should display the appropriate transaction receipt or declined message.

In Step 2, transaction details should be delivered to the Payment Gateway using the POST method with the
appropriate variables defined below posted along with the request.

In Step 3, the transaction responses are returned in the body of the HTTP response in a query string name/value
format delimited by ampersands. For example: variable1=value1&variable2=value2&variable3=value3

Customer Vault
The Customer Vault was designed specifically for businesses of any size to address concerns about handling
customer payment information. Visa and MasterCard have instituted the Payment Card Industry (PCI) Data
Security to protect cardholder data, wherever it resides, ensuring that members, merchants, and service
providers maintain the highest information security standards.

These associations have also deemed that merchants will be held liable for any breach of cardholder data. This
has become a major concern for merchants who handle credit card or electronic check payments. The Customer
Vault is designed for these merchants who desire to avoid the tremendous costs and resources involved in
becoming PCI compliant under these circumstances.

The Customer Vault does this by allowing merchants to transmit their payment information through a Secure
Sockets Layer (SSL) connection for storage in our Level 1 PCI certified data facility. Once the customer record
has been securely transmitted to the Customer Vault, the merchant can then initiate transactions remotely
without having to access cardholder information directly. This process is accomplished without the merchant
storing the customer's payment information in their local database or payment application.

Transaction Types
Direct Post API
Sale (sale)
Transaction sales are submitted and immediately flagged for settlement.

Authorization (auth)
Transaction authorizations are authorized immediately but are not flagged for settlement. These transactions
must be flagged for settlement using the capture transaction type.

Capture (capture)
Transaction captures flag existing authorizations for settlement. Only authorizations can be captured. Captures
can be submitted for an amount equal to or less than the original authorization.

Void (void)
Transaction voids will cancel an existing sale or captured authorization. In addition, non-captured authorizations
can be voided to prevent any future capture. Voids can only occur if the transaction has not been settled.

Refund (refund)
Transaction refunds will reverse a previously settled or pending settlement transaction. If the transaction has not
been settled, a transaction void can also reverse it.

Credit (credit)
Transaction credits apply an amount to the cardholder's card that was not originally processed through the
Gateway. In most situations credits are disabled as transaction refunds should be used instead.

Validate (validate)
This action is used for doing an "Account Verification" on the cardholder's credit card without actually doing an
authorization.

Update (update)
Transaction updates can be used to update previous transactions with specific order information, such as a
tracking number and shipping carrier.

Transaction Variables
Direct Post API
Sale/Authorization/Credit/Validate/Offline
Variable Name Description
The type of transaction to be processed.
type*
Values: 'sale', 'auth', 'credit', 'validate', or 'offline'
Username assigned to merchant account.
username* Also requires 'password'. Using the 'security_key' variable in the same
request will result in an error
Password for the specified username.
password* Also requires 'username'. Using the 'security_key' variable in the same
request will result in an error
API Security Key assigned to a merchant account.
security_key* Using the 'username' or 'password' variables in the same request will
result in an error
ccnumber** Credit card number.
Credit card expiration date.
ccexp**
Format: MMYY
The card security code. While this is not required, it is strongly
cvv
recommended.
checkname*** The name on the customer's ACH account.
checkaba*** The customer's bank routing number.
checkaccount*** The customer's bank account number.
The type of ACH account the customer has.
account_holder_type
Values: 'business' or 'personal'
The ACH account entity of the customer.
account_type
Values: 'checking' or 'savings'
The Standard Entry Class code of the ACH transaction.
sec_code
Values: 'PPD', 'WEB', 'TEL', or 'CCD'
Total amount to be charged. For validate, the amount must be omitted or
amount set to 0.00.
Format: x.xx
Surcharge amount.
surcharge
Format: x.xx
currency The transaction currency. Format: ISO 4217
The type of payment.
payment*** Default: 'creditcard'
Values: 'creditcard' or 'check'
If using Multiple MIDs, route to this processor (processor_id is obtained
processor_id
under Settings->Transaction Routing in the Control Panel).
authorization_code‡ Specify authorization code. For use with "offline" action only.
Sets the time in seconds for duplicate transaction checking on supported
dup_seconds
processors. Set to 0 to disable duplicate checking.
descriptor Set payment descriptor on supported processors.
descriptor_phone Set payment descriptor phone on supported processors.
descriptor_address Set payment descriptor address on supported processors.
descriptor_city Set payment descriptor city on supported processors.
descriptor_state Set payment descriptor state on supported processors.
descriptor_postal Set payment descriptor postal code on supported processors.
descriptor_country Set payment descriptor country on supported processors.
descriptor_mcc Set payment descriptor mcc on supported processors.
descriptor_merchant_id Set payment descriptor merchant id on supported processors.
descriptor_url Set payment descriptor url on supported processors.
Should be set to 'recurring' to mark payment as a recurring transaction or
billing_method 'installment' to mark payment as an installment transaction.
Values: 'recurring', 'installment'
Specify installment billing number, on supported processors. For use
billing_number when "billing_method" is set to installment.
Values: 0-99
Specify installment billing total on supported processors. For use when
billing_total
"billing_method" is set to installment.
order_template Order template ID.
Order description.
order_description
Legacy variable includes: orderdescription
orderid Order Id
 IP address of cardholder, this field is recommended.
ipaddress
Format: xxx.xxx.xxx.xxx
tax**** Total tax amount.
shipping**** Total shipping amount
ponumber**** Original purchase order
Cardholder's first name.
first_name
Legacy variable includes: firstname
Cardholder's last name
last_name
Legacy variable includes: lastname
company Cardholder's company
address1 Card billing address
address2 Card billing address, line 2
city Card billing city
Card billing state.
state
Format: CC
zip Card billing zip code
Card billing country.
country
Country codes are as shown in ISO 3166. Format: CC
phone Billing phone number
fax Billing fax number
email Billing email address
Customer's social security number, checked against bad check writers
social_security_number
database if check verification is enabled.
drivers_license_number Driver's license number.
drivers_license_dob Driver's license date of birth.
drivers_license_state The state that issued the customer's driver's license.
shipping_firstname Shipping first name
shipping_lastname Shipping last name
shipping_company Shipping company
shipping_address1 Shipping address
shipping_address2 Shipping address, line 2
shipping_city Shipping city
Shipping state
shipping_state
Format: CC
shipping_zip Shipping zip code
Shipping country
shipping_country
Country codes are as shown in ISO 3166. Format: CC
shipping_email Shipping email address
You can pass custom information in up to 20 fields.
merchant_defined_field_#
Format: merchant_defined_field_1=Value
If set to true, when the customer is charged, they will be sent a
customer_receipt transaction receipt.
Values: 'true' or 'false'
 Cardholder signature image. For use with "sale" and "auth" actions only.
signature_image
Format: base64 encoded raw PNG image. (16kiB maximum)
Set 3D Secure condition.
cardholder_auth‡‡
Values: 'verified' or 'attempted'
E-commerce indicator.
eci‡‡
Values: '0', '1', '2', '5', '6', or '7'
Cardholder authentication verification value.
cavv‡‡
Format: base64 encoded
Cardholder authentication transaction id.
xid‡‡
Format: base64 encoded
Specifies a payment gateway transaction id in order to associate payment
source_transaction_id information with a Subscription or Customer Vault record. Must be set
with a 'recurring' or 'customer_vault' action.
Recurring specific fields
Recurring action to be processed.
recurring
Values: add_subscription
Create a subscription tied to a Plan ID if the sale/auth transaction is
plan_id
successful.
The number of payments before the recurring plan is complete.
plan_payments
Note: Use '0' for 'until canceled'
The plan amount to be charged each billing cycle.
plan_amount
Format: x.xx
How often, in days, to charge the customer. Cannot be set with
day_frequency
'month_frequency' or 'day_of_month'.
How often, in months, to charge the customer. Cannot be set with
month_frequency 'day_frequency'. Must be set with 'day_of_month'.
Values: 1 through 24
The day that the customer will be charged. Cannot be set with
'day_frequency'. Must be set with 'month_frequency'.
day_of_month
Values: 1 through 31 - for months without 29, 30, or 31 days, the charge
will be on the last day
The first day that the customer will be charged.
start_date
Format: YYYYMMDD
Customer Vault specific fields
Associate payment information with a Customer Vault record if the
customer_vault transaction is successful.
Values: 'add_customer' or 'update_customer'
Specifies a customer vault id. If not set, the payment gateway will
customer_vault_id
randomly generate a customer vault id.
Stored Credentials (CIT/MIT)
Who initiated the transaction.
initiated_by
Values: 'customer' or 'merchant'
initial_transaction_id Original payment gateway transaction id.
 The indicator of the stored credential.
Values: 'stored' or 'used'
Use 'stored' when processing the initial transaction in which you are
storing a customer's payment details (customer credentials) in the
stored_credential_indicator
Customer Vault or other third-party payment storage system.
Use 'used' when processing a subsequent or follow-up transaction using
the customer payment details (customer credentials) you have already
stored to the Customer Vault or third-party payment storage method.
Level III specific order fields
Freight or shipping amount included in the transaction amount
shipping Default: '0.00'
Format: x.xx
The sales tax, included in the transaction amount, associated with the
purchase. Setting tax equal to '-1' indicates an order that is exempt from
tax sales tax.
Default: '0.00'
Format: x.xx
ponumber† Purchase order number supplied by cardholder
Identifier assigned by the merchant. This defaults to gateway transaction
orderid†
id.
Shipping country (e.g. US)
shipping_country†
Format: CC
Postal/ZIP code of the address where purchased goods will be delivered.
shipping_postal† This field can be identical to the 'ship_from_postal' if the customer is
present and takes immediate possession of the goods.
Postal/ZIP code of the address from where purchased goods are being
ship_from_postal†
shipped, defaults to merchant profile postal code.
4 character international description code of the overall goods or services
summary_commodity_code† being supplied. The acquirer or processor will provide a list of current
codes.
Amount included in the transaction amount associated with the import of
purchased goods.
duty_amount
Default: '0.00'
Format: x.xx
Amount included in the transaction amount of any discount applied to
complete order by the merchant.
discount_amount
Default: '0.00'
Format: x.xx
The national tax amount included in the transaction amount.
national_tax_amount Default: '0.00'
Format: x.xx
Second tax amount included in the transaction amount in countries where
more than one type of tax can be applied to the purchases.
alternate_tax_amount
Default: '0.00'
Format: x.xx
Tax identification number of the merchant that reported the alternate tax
alternate_tax_id
amount.
 Contains the amount of any value added taxes which can be associated
with the purchased item.
vat_tax_amount
Default: '0.00'
Format: x.xx
Contains the tax rate used to calculate the sales tax amount appearing.
Can contain up to 2 decimal places, e.g. 1% = 1.00.
vat_tax_rate
Default: '0.00'
Format: x.xx
vat_invoice_reference_number Invoice number that is associated with the VAT invoice.
customer_vat_registration Value added tax registration number supplied by the cardholder.
Government assigned tax identification number of the merchant for
merchant_vat_registration
whom the goods or services were purchased from.
Purchase order date, defaults to the date of the transaction.
order_date
Format: YYMMDD
Level III specific line item detail fields
item_product_code_#† Merchant defined description code of the item being purchased.
item_description_#† Description of the item(s) being supplied.
International description code of the individual good or service being
item_commodity_code_#†
supplied. The acquirer or processor will provide a list of current codes.
Code for units of measurement as used in international trade.
item_unit_of_measure_#†
Default: 'EACH'
item_unit_cost_#† Unit cost of item purchased, may contain up to 4 decimal places.
Quantity of the item(s) being purchased.
item_quantity_#†
Default: '1'
Purchase amount associated with the item. Defaults to: 'item_unit_cost_#'
item_total_amount_#†
x 'item_quantity_#' rounded to the nearest penny.
Amount of tax on specific item, amount should not be included in
item_tax_amount_# † 'total_amount_#'.
Default: '0.00'
Percentage representing the value-added tax applied.
item_tax_rate_#†
Default: '0.00'
Discount amount which can have been applied by the merchant on the
item_discount_amount_# sale of the specific item. Amount should not be included in
'total_amount_#'.
Discount rate for the line item. 1% = 1.00.
item_discount_rate_#
Default: '0.00'
item_tax_type_# Type of value-added taxes that are being used.
Tax identification number of the merchant that reported the alternate tax
item_alternate_tax_id_#
amount.
* Always required
** Required for credit card transactions
*** Required for ACH transactions
**** Required for Level 2 transactions
† Required for Level 3 transactions
‡ Required for offline transactions
‡‡ Required for 3D Secure transactions
Notes:
Level II fields are required for Level II processing.
Level II and Level III fields are required for Level III processing.
You can pass only credit card or e-check transaction variables in a request, not both in the same request.
Certain banks may require some optional fields.

Capture
Variable Name Description
Type of transaction.
type*
Values: 'capture'
Username assigned to merchant account.
username* Also requires 'password'. Using the 'security_key' variable in the same request
will result in an error
Password for the specified username.
password* Also requires 'username'. Using the 'security_key' variable in the same request
will result in an error
API Security Key assigned to a merchant account.
security_key* Using the 'username' or 'password' variables in the same request will result in an
error
transactionid* Original payment gateway transaction id
Total amount to be settled. This amount must be equal to or less than the original
amount* authorized amount.
Format: x.xx
tracking_number Shipping tracking number
Shipping carrier.
shipping_carrier
Values: 'ups', 'fedex', 'dhl', or 'usps'
orderid Order id.
Cardholder signature image.
signature_image
Format: base64 encoded raw PNG image. (16kiB maximum)
* Always required
Void
Variable Name Description
Type of transaction.
type*
Values: 'void'
Username assigned to merchant account.
username* Also requires 'password'. Using the 'security_key' variable in the same request will
result in an error
Password for the specified username.
password* Also requires 'username'. Using the 'security_key' variable in the same request will
result in an error
 API Security Key assigned to a merchant account.
security_key*
Using the 'username' or 'password' variables in the same request will result in an error
transactionid* Original payment gateway transaction id
Reason the EMV transaction is being voided.
void_reason** Values: 'fraud', 'user_cancel', 'icc_rejected', 'icc_card_removed', 'icc_no_confirmation',
or 'pos_timeout'
The type of payment.
payment*** Default: 'creditcard'
Values: 'creditcard' or 'check'
* Always required
** Conditionally required for EMV transactions
*** Required for ACH transactions

Refund
Variable Name Description
Type of transaction.
type*
Values: 'refund'
Username assigned to merchant account.
username* Also requires 'password'. Using the 'security_key' variable in the same request will result
in an error
Password for the specified username.
password* Also requires 'username'. Using the 'security_key' variable in the same request will
result in an error
API Security Key assigned to a merchant account.
security_key*
Using the 'username' or 'password' variables in the same request will result in an error
transactionid* Original payment gateway transaction id
Total amount to be refunded. This amount may be equal to or less than the settled
amount amount. Setting the amount to 0.00 will refund the entire amount.
Format: x.xx
The type of payment.
payment** Default: 'creditcard'
Values: 'creditcard' or 'check'
* Always required
** Required for ACH transactions
Update
Variable Name Description
Type of transactions.
type*
Values: 'update'
Username assigned to merchant account.
username* Also requires 'password'. Using the 'security_key' variable in the same
request will result in an error
 Password for the specified username.
password* Also requires 'username'. Using the 'security_key' variable in the same
request will result in an error
API Security Key assigned to a merchant account.
security_key* Using the 'username' or 'password' variables in the same request will
result in an error
transactionid* Original payment gateway transaction id
The type of payment.
payment** Default: 'creditcard'
Values: 'creditcard' or 'check'
tracking_number Shipping tracking number
Total shipping amount.
shipping
Format: x.xx
Postal/ZIP code of the address where purchased goods will be delivered.
shipping_postal This field can be identical to the 'ship_from_postal' if the customer is
present and takes immediate possession of the goods.
Postal/ZIP code of the address from where purchased goods are being
ship_from_postal
shipped, defaults to merchant profile postal code.
shipping_country Shipping Country Code.
Shipping carrier.
shipping_carrier
Values: 'ups', 'fedex', 'dhl', or 'usps'
Shipping date.
shipping_date
Format: YYYYMMDD
Order Description.
order_description
Legacy variable includes: orderdescription
Order date.
order_date
Format: YYYYMMDD
If set to true, when the customer is charged, they will be sent a
customer_receipt transaction receipt.
Values: 'true' or 'false'
Cardholder signature image.
signature_image
Format: base64 encoded raw PNG image. (16kiB maximum)
ponumber Cardholder's purchase order number.
4 character international description code of the overall goods or services
summary_commodity_code being supplied. The acquirer or processor will provide a list of current
codes.
Amount included in the transaction amount associated with the import of
duty_amount purchased goods.
Format: x.xx
Amount included in the transaction amount of any discount applied to
discount_amount complete order by the merchant.
Format: x.xx
Tax amount.
tax
Format: x.xx
The national tax amount included in the transaction amount.
national_tax_amount
Format: x.xx
 Second tax amount included in the transaction amount in countries where
alternate_tax_amount more than one type of tax can be applied to the purchases.
Format: x.xx
Tax identification number of the merchant that reported the alternate tax
alternate_tax_id
amount.
Contains the amount of any value added taxes which can be associated
vat_tax_amount
with the purchased item.
Contains the tax rate used to calculate the sales tax amount appearing.
vat_tax_rate
Can contain up to 2 decimal places, e.g. 1% = 1.00.
vat_invoice_reference_number Invoice number that is associated with the VAT invoice.
customer_vat_registration Value added tax registration number supplied by the cardholder.
Government assigned tax identification number of the merchant for
merchant_vat_registration
whom the goods or services were purchased from.
Merchant Defined Fields.
merchant_defined_field_#
Format: merchant_defined_field_1=Value
* Always required
** Required for ACH transactions

Transaction Variables
Direct Post API
Create Invoice
Variable Name Description
Create a new invoice and email it to the customer.
invoicing*
Values: 'add_invoice'
Username assigned to merchant account.
username* Also requires 'password'. Using the 'security_key' variable in the same
request will result in an error.
Password for the specified username.
password* Also requires 'username'. Using the 'security_key' variable in the same
request will result in an error.
API Security Key assigned to a merchant account.
security_key* Using the 'username' or 'password' variables in the same request will
result in an error.
Total amount to be invoiced. Must be greater than 0.00.
amount*
Format: x.xx
Billing email address
email*
An invoice will be sent to this address when it is created.
When the invoice should be paid
payment_terms Default: 'upon_receipt'
Values: 'upon_receipt', '30', '60', or '90'.
 What payment methods a customer may use when paying invoice.
Defaults to all available payment methods available in your merchant
payment_methods_allowed account
Values: 'cc', 'ck', and 'cs'. Multiple payment types can be selected by
comma-separating values.
The transaction currency.
currency
Format: ISO 4217
Order description.
order_description
Legacy variable includes: orderdescription
orderid Order ID.
customer_id Customer ID.
customer_tax_id Customer Tax ID.
tax Total tax amount.
shipping Total shipping amount.
ponumber Original purchase order.
Cardholder's first name.
first_name
Legacy variable includes: firstname
Cardholder's last name.
last_name
Legacy variable includes: lastname
company Cardholder's company.
address1 Card billing address.
address2 Card billing address, line 2.
city Card billing city.
Card billing state.
state
Format: CC
zip Card billing zip code.
Card billing country.
country
Country codes are as shown in ISO 3166. Format: CC
phone Billing phone number.
fax Billing fax number.
website Customer website.
shipping_firstname Shipping first name.
shipping_lastname Shipping last name.
shipping_company Shipping company.
shipping_address1 Shipping address.
shipping_address2 Shipping address, line 2.
shipping_city Shipping city.
Shipping state.
shipping_state
Format: CC
shipping_zip Shipping zip code.
Shipping country.
shipping_country
Country codes are as shown in ISO 3166. Format: CC
shipping_email Shipping email address.
 You can pass custom information in up to 20 fields.
merchant_defined_field_#
Format: merchant_defined_field_1=Value
Product Information
item_product_code_# Merchant defined description code of the item being purchased.
item_description_# Description of the item(s) being supplied.
International description code of the individual good or service being
item_commodity_code_#
supplied. The acquirer or processor will provide a list of current codes.
Code for units of measurement as used in international trade.
item_unit_of_measure_#
Default: 'EACH'
item_unit_cost_# Unit cost of item purchased, may contain up to 4 decimal places.
Quantity of the item(s) being purchased.
item_quantity_#
Default: '1'
Purchase amount associated with the item. Defaults to: 'item_unit_cost_#'
item_total_amount_#
x 'item_quantity_#' rounded to the nearest penny.
Amount of tax on specific item, amount should not be included in
item_tax_amount_# 'total_amount_#'.
Default: '0.00'
Percentage representing the value-added tax applied.
item_tax_rate_#
Default: '0.00'
Discount amount which can have been applied by the merchant on the sale
item_discount_amount_#
of the specific item. Amount should not be included in 'total_amount_#'.
Discount rate for the line item. 1% = 1.00.
item_discount_rate_#
Default: '0.00'
item_tax_type_# Type of value-added taxes that are being used.
Tax identification number of the merchant that reported the alternate tax
item_alternate_tax_id_#
amount.
* Always required

Update Invoice
Variable Name Description
Update an existing invoice.
invoicing*
Values: 'update_invoice'
Username assigned to merchant account.
username* Also requires 'password'. Using the 'security_key' variable in the same request will
result in an error.
Password for the specified username.
password* Also requires 'username'. Using the 'security_key' variable in the same request will
result in an error.
API Security Key assigned to a merchant account.
security_key* Using the 'username' or 'password' variables in the same request will result in an
error.
invoice_id* The invoice ID to be updated.
 * Always required
Notes:
All variables (besides currency) on an invoice may be updated. Updating an invoice will not result in a new
invoice being sent to the customer. To send the invoice after updating an invoice, use the send_invoice request
after making changes.

Send Invoice
Variable Name Description
Send an existing invoice to a customer.
invoicing*
Values: 'send_invoice'
Username assigned to merchant account.
username* Also requires 'password'. Using the 'security_key' variable in the same request will
result in an error.
Password for the specified username.
password* Also requires 'username'. Using the 'security_key' variable in the same request will
result in an error.
API Security Key assigned to a merchant account.
security_key* Using the 'username' or 'password' variables in the same request will result in an
error.
invoice_id* The invoice ID to be emailed.
* Always required
Notes:
The invoice will be sent to the billing email address assigned to the invoice.

Close Invoice
Variable Name Description
The invoice to be closed.
invoicing*
Values: 'close_invoice'
Username assigned to merchant account.
username* Also requires 'password'. Using the 'security_key' variable in the same request will
result in an error.
Password for the specified username.
password* Also requires 'username'. Using the 'security_key' variable in the same request will
result in an error.
API Security Key assigned to a merchant account.
security_key* Using the 'username' or 'password' variables in the same request will result in an
error.
invoice_id* The invoice ID to be closed.
* Always required
Retail Data
Direct Post API
Passing Unencrypted Retail Magnetic Stripe Data
Variable Name Description
track_1 Raw Magnetic Stripe Data
track_2 Raw Magnetic Stripe Data
track_3 Raw Magnetic Stripe Data
Passing MagTek Magensa Encrypted Magnetic Stripe Data
Variable Name Description
magnesafe_track_1 Raw MagTek Magensa Data
magnesafe_track_2 Raw MagTek Magensa Data
magnesafe_magneprint Raw MagTek Magensa Data
magnesafe_ksn Raw MagTek Magensa Data
magnesafe_magneprint_status Raw MagTek Magensa Data
Passing IDTech M130 Encrypted Swipe Data
Variable Name Description
encrypted_track_1 Raw encrypted data
encrypted_track_2 Raw encrypted data
encrypted_track_3 Raw encrypted data
encrypted_ksn Raw encrypted data
Passing IDTech M130 Encrypted Keyed Data
Variable Name Description
encrypted_data Raw encrypted data
Passing Ingenico Telium 2 Chip Card Data
Variable Name Description
The type of transaction data to be processed.
entry_mode
Value: 'emv_icc'
emv_auth_request_data EMV Data for the transaction as received from the EMV Chip Card SDK.
The EMV - capable card reader.
emv_device
Value: 'ingenico_rba'
Method used to verify the EMV transaction.
verification_method
Values: 'signature', 'offline_pin', 'offline_pin_signature', or 'none'
encrypted_ksn Raw encrypted data
encrypted_track_2 Raw encrypted data

Passing Ingenico Telium 2 Swipe Data

Variable Name Description
The type of transaction data to be processed.
entry_mode
Values: 'swiped' or 'swiped_emv_fallback'
The EMV - capable card reader.
emv_device
Value: 'ingenico_rba'
encrypted_ksn Raw encrypted data
encrypted_track_1 Raw encrypted data
encrypted_track_2 Raw encrypted data
Passing Ingenico Telium 2 NFC Data
Variable Name Description
The type of transaction data to be processed.
entry_mode
Value: 'nfc_msd'
The EMV - capable card reader.
emv_device
Value: 'ingenico_rba'
encrypted_ksn Raw encrypted data
encrypted_track_2 Raw encrypted data
Passing Ingenico Telium 2 Keyed Data
Variable Name Description
The type of transaction data to be processed.
entry_mode
Value: 'keyed'
The EMV - capable card reader.
emv_device
Value: 'ingenico_rba'
encrypted_ksn Raw encrypted data
encrypted_track_2 Raw encrypted data

Apple Pay
Direct Post API
Supported Processors
Currently Apple Pay is supported only on the TSYS - EMV platform.
Configuring Apple Pay
Creating an Apple Merchant ID
First, you must obtain an Apple Merchant ID before you can generate the Certificate Signing Request that
Apple requires. You will need to set up an Apple Merchant ID in your iOS Developer Account. Follow these
steps to complete the setup:

1. Go to Apple's Developer Portal and log in to the Member Center to create a new Merchant ID.
2. Navigate to the Certificates, Identifiers, and Profiles area of the Member Center, and then begin the
Register Merchant ID process.
3. You must then set the Apple Merchant ID within your gateway Control Panel under Settings -> Apple
Pay.

Generating the Certificate Signing Request

Next, you will need to associate a Certificate with the Merchant ID in Apple's Developer Portal. After
downloading the Certificate Signing Request from the gateway's options page, follow these steps.

1. In Apple's Developer Portal, click on the Merchant ID and then click "Edit".
2. Click "Create Certificate".
3. You are obtaining a CSR file from a Payment Provider so you will not have to create one. Click
"Continue" to proceed to the upload page.
4. Click "Choose File..." and select the Gateway.certSigningRequest file you downloaded from the
gateway's options page.

How to Obtain Apple Pay Payment Data

PassKit provides the payment data in the (PKPayment *)payment that is returned to your app's
paymentAuthorizationViewController:didAuthorizePayment:completion method. The Apple Pay encrypted
payment data is found in payment.token.paymentData.

payment.token.paymentData is a binary (NSData) object, so you must encode it as a hexadecimal string before
it can be passed to the Gateway.

Passing Apple Pay Payment Data

To submit a payment with Apple Pay, send the encrypted token data into the applepay_payment_data variable.
There is no need to decrypt the data in your app. Only the Gateway will have access to the private key that can
decrypt the token.

Notes
When passing in applepay_payment_data, you should not include the variables ccnumber or ccexp; they are
extracted from the token data.

Important Note: The authorization amount must match the amount the customer approves in the app. If you
pass in a currency, that must also match the currency approved in the app. If omitted, the currency from the app
is used.

For working example code, including how to obtain the PKPayment object and how to pass a simple transaction
to the Gateway, download the sample project.

Variables
Variable Name Description
The encrypted Apple Pay payment data (payment.token.paymentData) from
applepay_payment_data
PassKit encoded as a hexadecimal string

Troubleshooting
If you receive the error "Failed to decrypt Apple Pay data. Ensure that the Apple Pay Merchant ID is correct in
the Gateway Settings and that the certificate was generated from a Gateway Certificate Signing Request.", try
these steps:

1. Verify that the Merchant ID that Apple has in the developer portal exactly matches the Merchant ID in the
Gateway's settings.
2. Verify that your app's PKPaymentRequest's merchantIdentifier exactly matches the Merchant ID in the
Gateway's settings.
3. Ensure that the correct Merchant ID is checked in the Apple Pay section of the Capabilities tab in your
project's target settings.
4. Try creating a new Merchant ID. Reusing an existing Merchant ID with a new certificate may sometimes
cause issues with encryption.

Recurring Variables
Direct Post API
Add a Plan
Variable Name Description
Add a recurring plan that subscriptions can be added to in the future.
recurring*
Value: 'add_plan'
The number of payments before the recurring plan is complete.
plan_payments*
Notes: '0' for until canceled
The plan amount to be charged each billing cycle.
plan_amount*
Format: x.xx
plan_name* The display name of the plan.
plan_id* The unique plan ID that references only this recurring plan.
How often, in days, to charge the customer. Cannot be set with
day_frequency**
'month_frequency' or 'day_of_month'.
 How often, in months, to charge the customer. Cannot be set with
month_frequency*** 'day_frequency'. Must be set with 'day_of_month'.
Values: 1 through 24
The day that the customer will be charged. Cannot be set with 'day_frequency'.
Must be set with 'month_frequency'.
day_of_month***
Values: 1 through 31 - for months without 29, 30, or 31 days, the charge will be
on the last day
* Always required
** Required unless 'month_frequency' and 'day_of_month' is set.
*** Required unless 'day_frequency' is set.

Add a Subscription to an Existing Plan

Variable Name Description
Associate payment information with a recurring plan.
recurring*
Value: add_subscription
plan_id* The plan ID of the plan that the subscription will be associated with.
The first day that the customer will be charged.
start_date
Format: YYYYMMDD
ccnumber** Credit card number.
Credit card expiration.
ccexp**
Format: MMYY
The type of payment.
payment*** Default: 'creditcard'
Values: 'creditcard' or 'check'
checkname*** The name on the customer's ACH account.
checkaccount*** The customer's bank account number.
checkaba*** The customer's bank routing number.
The customer's ACH account type.
account_type
Values: 'checking' or 'savings'
currency Set transaction currency.
The customer's ACH account entity.
account_holder_type
Values: 'personal' or 'business'
ACH standard entry class codes.
sec_code
Values: 'PPD', 'WEB', 'TEL', or 'CCD'
Cardholder's first name.
first_name
Legacy variable includes: firstname
Cardholder's last name.
last_name
Legacy variable includes: lastname
address1 Card billing address.
city Card billing city
state Card billing state.
zip Card billing postal code.
country Card billing country code.
phone Billing phone number.
email Billing email address.
company Cardholder's company.
address2 Card billing address, line 2.
fax Billing fax number.
orderid Order ID
order_description Order Description
Can be set up in merchant control panel under 'Settings'->'Merchant
merchant_defined_field_#
Defined Fields'.
ponumber Cardholder's purchase order number.
If using Multiple MIDs, route to this processor (processor_id is obtained
processor_id
under Settings->Transaction Routing in the Control Panel).
If set to true, when the customer is charged, they will be sent a
customer_receipt transaction receipt.
Values: 'true' or 'false'
Specifies a payment gateway transaction id in order to associate payment
source_transaction_id
information with a Subscription record.
* Always required
** Required for credit card transactions
*** Required for ACH transactions

Adding a Custom Subscription

Variable Name Description
Add a custom recurring subscription that is NOT associated with an
recurring* existing plan
Value: 'add_subscription'
The number of payments before the recurring plan is complete.
plan_payments*
Notes: '0' for until canceled
The plan amount to be charged each billing cycle.
plan_amount*
Format: x.xx
How often, in days, to charge the customer. Cannot be set with
day_frequency**
'month_frequency' or 'day_of_month'.
How often, in months, to charge the customer. Cannot be set with
month_frequency*** 'day_frequency'. Must be set with 'day_of_month'.
Values: 1 through 24
The day that the customer will be charged. Cannot be set with
'day_frequency'. Must be set with 'month_frequency'.
day_of_month***
Values: 1 through 31 - for months without 29, 30, or 31 days, the charge
will be on the last day
The first day that the customer will be charged.
start_date
Format: YYYYMMDD
ccnumber**** Credit card number.
 Credit card expiration.
ccexp****
Format: MMYY
The type of payment.
payment† Default: 'creditcard'
Values: 'creditcard' or 'check'
checkname† The name on the customer's ACH account.
checkaccount† The customer's bank account number.
checkaba† The customer's bank routing number.
The customer's ACH account type.
account_type
Values: 'checking' or 'savings'
The customer's ACH account entity.
account_holder_type
Values: 'personal' or 'business'
ACH standard entry class codes.
sec_code
Values: 'PPD', 'WEB', 'TEL', or 'CCD'
Cardholder's first name.
first_name
Legacy variable includes: firstname
Cardholder's last name.
last_name
Legacy variable includes: lastname
address1 Card billing address.
city Card billing city
state Card billing state.
zip Card billing postal code.
country Card billing country code.
phone Billing phone number.
email Billing email address.
company Cardholder's company.
address2 Card billing address, line 2.
fax Billing fax number.
orderid Order ID
Order Description
order_description
Legacy variable includes: orderdescription
Can be set up in merchant control panel under 'Settings'->'Merchant
merchant_defined_field_#
Defined Fields'.
ponumber Cardholder's purchase order number.
If using Multiple MIDs, route to this processor (processor_id is obtained
processor_id
under Settings->Transaction Routing in the Control Panel).
If set to true, when the customer is charged, they will be sent a
customer_receipt transaction receipt.
Values: 'true' or 'false'
Specifies a payment gateway transaction id in order to associate payment
source_transaction_id
information with a Subscription record.
* Always required
** Required unless 'month_frequency' and 'day_of_month' is set.
*** Required unless 'day_frequency' is set.
**** Required for credit card transactions
† Required for ACH transactions

Update a Subscription's Billing Information

Variable Name Description
Update the subscription's billing information.
recurring*
Value: 'update_subscription'
subscription_id
* The subscription ID that will be updated.

* Always required
Delete a Subscription
Variable Name Description
Delete the subscription. Customer will no longer be charged.
recurring*
Value: 'delete_subscription'
subscription_id
* The subscription ID that will be deleted.

* Always required

Customer Vault Variables

Direct Post API
Add/Update Customer Record
Variables Description
Add/Update a secure customer vault record.
customer_vault*
Values: 'add_customer' or 'update_customer'
Specifies a customer vault id. If not set, the payment gateway will
customer_vault_id
randomly generate a customer vault id.
Billing id to be assigned or updated. If none is provided, one will be
billing_id
created or the billing id with priority '1' will be updated.
Username assigned to merchant account.
username* Also requires 'password'. Using the 'security_key' variable in the same
request will result in an error
Password for the specified username.
password* Also requires 'username'. Using the 'security_key' variable in the same
request will result in an error
API Security Key assigned to a merchant account.
security_key* Using the 'username' or 'password' variables in the same request will
result in an error
ccnumber** Credit card number.
Credit card expiration.
ccexp**
Format: MMYY
checkname*** The name on the customer's ACH account.
checkaba*** The customer's bank routing number.
checkaccount*** The customer's bank account number.
The customer's ACH account entity.
account_holder_type
Values: 'personal' or 'business'
The customer's ACH account type.
account_type
Values: 'checking' or 'savings'
ACH standard entry class codes.
sec_code
Values: 'PPD', 'WEB', 'TEL', or 'CCD'
currency Set transaction currency.
Set payment type to ACH or credit card.
payment
Values: 'creditcard' or 'check'
orderid Order id
Order Description
order_description
Legacy variable includes: orderdescription
Can be set up in merchant control panel under 'Settings'->'Merchant
merchant_defined_field_# Defined Fields'.
Format: merchant_defined_field_1=Value
Cardholder's first name.
first_name
Legacy variable includes: firstname
Cardholder's last name.
last_name
Legacy variable includes: lastname
address1 Card billing address.
city Card billing city
state Card billing state.
zip Card billing postal code.
country Card billing country code.
phone Billing phone number.
email Billing email address.
company Cardholder's company.
address2 Card billing address, line 2.
fax Billing fax number.
Shipping entry id. If none is provided, one will be created or the billing id
shipping_id
with priority '1' will be updated.
shipping_firstname Shipping first name.
shipping_lastname Shipping last name.
shipping_company Shipping company.
shipping_address1 Shipping address.
shipping_address2 Shipping address, line 2.
shipping_city Shipping city
shipping_state Shipping state.
shipping_zip Shipping postal code.
shipping_country Shipping country code.
shipping_phone Shipping phone number.
shipping_fax Shipping fax number.
shipping_email Shipping email address.
Specifies a payment gateway transaction id in order to associate payment
source_transaction_id
information with a Customer Vault record.
* Always required
** Required for credit card transactions
*** Required for ACH transactions

Customer Vault initiated Sale/Auth/Credit/Offline

Variable Description
Username assigned to merchant account.
username* Also requires 'password'. Using the 'security_key' variable in the same
request will result in an error
Password for the specified username.
password* Also requires 'username'. Using the 'security_key' variable in the same
request will result in an error
API Security Key assigned to a merchant account.
security_key* Using the 'username' or 'password' variables in the same request will result
in an error
customer_vault_id* Specifies a customer vault id.
Total amount to be charged. For validate, the amount must be omitted or
amount set to 0.00.
Format: x.xx
currency The transaction currency. Format: ISO 4217
If using Multiple MIDs, route to this processor (processor_id is obtained
processor_id
under Settings->Transaction Routing in the Control Panel).
descriptor Set payment descriptor on supported processors.
descriptor_phone Set payment descriptor phone on supported processors.
Order description.
order_description
Legacy variable includes: orderdescription
orderid Order ID
Stored Credentials (CIT/MIT)
Who initiated the transaction.
initiated_by
Values: 'customer' or 'merchant'
initial_transaction_id Original payment gateway transaction id.
 The indicator of the stored credential.
Values: 'stored' or 'used'
Use 'stored' when processing the initial transaction in which you are
storing a customer's payment details (customer credentials) in the Customer
stored_credential_indicator
Vault or other third-party payment storage system.
Use 'used' when processing a subsequent or follow-up transaction using
the customer payment details (customer credentials) you have already
stored to the Customer Vault or third-party payment storage method.
* Always required

Delete Customer Record

Variable Description
Deletes a secure customer vault record.
customer_vault*
Values: 'delete_customer'
customer_vault_id* Specifies a customer vault id.
Username assigned to merchant account.
username* Also requires 'password'. Using the 'security_key' variable in the same request
will result in an error
Password for the specified username.
password* Also requires 'username'. Using the 'security_key' variable in the same request
will result in an error
API Security Key assigned to a merchant account.
security_key* Using the 'username' or 'password' variables in the same request will result in
an error
* Always required
Notes:
If you do not pass a customer_vault_id, our system will randomly generate one. If you include a
customer_id and customer_vault_id, they must match.
You can only pass Credit Card or Electronic Check transaction variables.

Partial Payment Information

Direct Post API
Request Details
Variable Description
Unique identifier returned when making the original transaction. This should only be
partial_payment_id
used for secondary transactions.
This variable allows the following two values to be passed to it:
partial_payments settle_partial: Settles any amount of tender collected (captured partial auth's and
approved partial sales) at cut off.
payment_in_full:
Required that any split
tendered transaction is
collected in-full
before settlement gets
initiated.
This variable can be passed the value 'complete_partial_payment' which will complete
a payment_in_full transaction that has not been collected in full. This allows industries
type
that require payment_in_full but subsequently decide to still settle the transaction even
though it has not been collected in full.

Response Details
Variable Description
A numeric identifier which is used when submitting subsequent
partial_payment_id
transactions.
partial_payment_balance Returns the payment's remaining balance.
amount_authorized Provides the amount that was authorized.
Examples
Example 1: In this request, if nothing more was done, a transaction for 30.00 would settle at the next cut-off.

Request ...type=sale&partial_payments=settle_partial&ccnumber=4111111111111111&ccexp=1016&amount=100.00
Response ...response=1&partial_payment_id=123456789&partial_payment_balance=70.00&amount_authorized=30.00.
Example 2: In this request, payment_in_full was required and two transaction were collected - this transaction
would settle at the next cut-off.

Request
...type=sale&partial_payments=payment_in_full&ccnumber=4111111111111111&ccexp=1016&amount=100
1
Response
...response=1&partial_payment_id=123456789&partial_payment_balance=70.00&amount_authorized=30.00.
1
Request
...type=sale&partial_payment_id=123456789&partial_payments=payment_in_full&ccnumber=400000000000
2
Response
...response=1& partial_payment_id=123456789&partial_payment _balance=0.00&amount_authorized=70.00.
2
Example 3: In this example, payment_in_full was required and two transactions were attempted, but only one
collected. The merchant decided to force it out anyways - this transaction would settle at the next cut-off.

Request
...type=sale&partial_payments=payment_in_full&ccnumber=4111111111111111&ccexp=1016&amount=100
1
Response
...response=1&partial_payment_id=123456789&partial_payment_balance=70.00&amount_authorized=30.00.
1
Request
...type=sale&partial_payment_id=123456789&partial_payments=payment_in_full&ccnumber=400000000000
2
Response
...response=2&partial_payment_id=123456789&partial_payment_balance=70.00&amount_authorized=70.00.
2
Request
...type=complete_partial_payment& partial_payment_id=123456789&partial_payments=payment_in_full&am
3
Response
...response=1& partial_payment_id=123456789&partial_payment_balance=0.00&amount_authorized=70.00..
3

Transaction Response Variables

Direct Post API
Standard Response
Variable Name Description
1 = Transaction Approved
response 2 = Transaction Declined
3 = Error in transaction data or system error
responsetext Textual response
authcode Transaction authorization code.
transactionid Payment gateway transaction id.
avsresponse AVS response code (See Appendix 1).
cvvresponse CVV response code (See Appendix 2).
orderid The original order id passed in the transaction request.
response_code Numeric mapping of processor responses (See Appendix 3).
This will optionally come back when any chip card data is provided on the
emv_auth_response_data authorization. This data needs to be sent back to the SDK after an
authorization.

Testing Information
Direct Post API

Transaction testing credentials

Transactions can be tested using one of two methods. First, transactions can be submitted to any merchant
account that is in test mode. Keep in mind that if an account is in test mode, all valid credit cards will be
approved but no charges will actually be processed.

The Payment Gateway demo account can also be used for testing at any time. Please use the following username
and password for testing with this account:

username: demo
password: password
Transaction POST URL
Transaction details should be POST'ed to the following URL:

POST URL: https://integratepayments.transactiongateway.com/api/transact.php

Test Data
Transactions can be submitted using the following information:

Visa: 4111111111111111
MasterCard: 5431111111111111
Discover: 6011601160116611
American Express: 341111111111111
Credit Card Expiration: 10/25
account (ACH): 123123123
routing (ACH): 123123123

Triggering Errors in Test Mode

To cause a declined message, pass an amount less than 1.00.
To trigger a fatal error message, pass an invalid card number.
To simulate an AVS match, pass 888 in the address1 field, 77777 for zip.
To simulate a CVV match, pass 999 in the cvv field.

Appendix 1
Direct Post API
AVS Response Codes
X Exact match, 9-character numeric ZIP
Y Exact match, 5-character numeric ZIP
D Exact match, 5-character numeric ZIP
M Exact match, 5-character numeric ZIP
2 Exact match, 5-character numeric ZIP, customer name
6 Exact match, 5-character numeric ZIP, customer name
A Address match only
B Address match only
3 Address, customer name match only
7 Address, customer name match only
W 9-character numeric ZIP match only
Z 5-character ZIP match only
P 5-character ZIP match only
L 5-character ZIP match only
1 5-character ZIP, customer name match only
5 5-character ZIP, customer name match only
N No address or ZIP match only
C No address or ZIP match only
4 No address or ZIP or customer name match only
8 No address or ZIP or customer name match only
U Address unavailable
G Non-U.S. issuer does not participate
I Non-U.S. issuer does not participate
R Issuer system unavailable
E Not a mail/phone order
S Service not supported
0 AVS not available
O AVS not available
B AVS not available

Appendix 2
Direct Post API
CVV Response Codes
M CVV2/CVC2 match
N CVV2/CVC2 no match
P Not processed
S Merchant has indicated that CVV2/CVC2 is not present on card
U Issuer is not certified and/or has not provided Visa encryption keys

Appendix 3
Direct Post API
Result Code Table
100 Transaction was approved.
200 Transaction was declined by processor.
201 Do not honor.
202 Insufficient funds.
203 Over limit.
204 Transaction not allowed.
220 Incorrect payment information.
221 No such card issuer.
222 No card number on file with issuer.
223 Expired card.
224 Invalid expiration date.
225 Invalid card security code.
226 Invalid PIN.
240 Call issuer for further information.
250 Pick up card.
251 Lost card.
252 Stolen card.
253 Fraudulent card.
260 Declined with further instructions available. (See response text)
261 Declined-Stop all recurring payments.
262 Declined-Stop this recurring program.
263 Declined-Update cardholder data available.
264 Declined-Retry in a few days.
300 Transaction was rejected by gateway.
400 Transaction error returned by processor.
410 Invalid merchant configuration.
411 Merchant account is inactive.
420 Communication error.
421 Communication error with issuer.
430 Duplicate transaction at processor.
440 Processor format error.
441 Invalid transaction information.
460 Processor feature not available.
461 Unsupported card type.