Process Transactions

A guide for using the PayConex API to process payments.

The information in this article is intended to serve as a guide to help a developer begin integrating the PayConex API for payment processing.

The examples below are not a comprehensive guide to all that a developer can accomplish with the API; rather, they are examples of the most common uses.

This guide is designed to assist you in getting acclimated to the API. If you have questions about how to implement an example or how to use the API for a function not shown here, please contact [email protected] for assistance.

API URLs

For the certification test environment:

https://cert.payconex.net/api/qsapi/3.8

For the production environment:

https://secure.payconex.net/api/qsapi/3.8

Credit Card Processing

Developers can send transaction requests with credit cards in various formats. Below, you will see examples using unencrypted keyboard input, encrypted card readers, token, and eToken values generated using Bluefin's secure iFrame.

For a full list of request and response variables associated with the PayConex API, see the tables at the bottom of this article.

Processing a Sale

Processing a SALE transaction authorizes funds on the card and flags the transaction to be captured for settlement at the next settlement time.

📘

Did you know?

You can request a transaction_id value prior to processing a transaction using the Transaction Status API (TSAPI). This can help with mitigating communication errors and other potential complications. For more information, see our guide, Fetching a Transaction ID.

This is an example of a sale where keyboard input was used:

curl --request POST \
  --url https://cert.payconex.net/api/qsapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data tender_type=CARD \
  --data transaction_type=SALE \
  --data transaction_amount=1.00 \
  --data card_number=4124939999999990 \
  --data card_expiration=1230

This is an example of a sale where an ID Tech SREDKey was used to capture the card data:

curl --request POST \
  --url https://cert.payconex.net/api/qsapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data tender_type=CARD \
  --data transaction_type=SALE \
  --data transaction_amount=1.00 \
  --data 'card_tracks=029C01801F322400839B%*4124********9990^TEST/BLUEFIN^3012************?*;4124********9990=3012************?*B0220AF94559A86A5D739EF14C012A669225881E5D64DF0BA59F9409E831C4314A68CDED17449E1A1316544F2ED5DA5B9FE8A8EEC832764B366AF000A1E330F8075794AC0402294956C1B737351B247A9D2BC1F900CD741833A6024ABE6E5F7F0000000000000000000000000000000000000000000000000000000000000000000000000000000036313354353331313333629949960E00280000666C3403'

This is an example of a sale where an eToken was retrieved from a secure iFrame:

curl --request POST \
  --url https://cert.payconex.net/api/qsapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data tender_type=CARD \
  --data transaction_type=SALE \
  --data transaction_amount=1.00 \
  --data eToken=m9QDt0gDoFEjGr1wOgUygKFX1JKL--iwPet7isyF_23K-RFmveDdFw_jaIOYm7Z12cxbTBX5lHwSJxF69T3gYasZTFlKPl3LFkmShrFE6UwkZjrJFzX6Ab0AMsdZoveIyX7CMXxyHbbd3vt7tDE3IP_3k40eoYHsNfs9Tfk0c9P2OKZrKcpbQRK5HRE1ngE1BsmhInfr00EGfWwAp5KUC5rO1QNbs3aU

📘

For more information on retrieving an eToken using the PayConex Secure iFrame please see our iFrame guide.

Sending a Refund

Refund transactions send a refund to the card holder of a previous sale transaction. The refund transaction type requires the token_id parameter. The value of the token_id should be the transaction_id from a transaction response.

curl --request POST \
  --url https://cert.payconex.net/api/qsapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data transaction_type=REFUND \
  --data token_id=000000100561

Processing an Authorization

An authorization transaction authorizes (holds) the funds on the card but does not transfer them. A CAPTURE transaction must be made to collect the held funds. See the section, "Capturing a Previous Authorization," below.

This is an example of a sale where keyboard input was used:

curl --request POST \
  --url https://cert.payconex.net/api/qsapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data tender_type=CARD \
  --data transaction_type=AUTHORIZATION \
  --data transaction_amount=1.00 \
  --data card_number=4124939999999990 \
  --data card_expiration=1230

This is an example of a sale where an ID Tech SREDKey was used to capture the card data:

curl --request POST \
  --url https://cert.payconex.net/api/qsapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data tender_type=CARD \
  --data transaction_type=AUTHORIZATION \
  --data transaction_amount=1.00 \
  --data 'card_tracks=029C01801F322400839B%*4124********9990^TEST/BLUEFIN^3012************?*;4124********9990=3012************?*B0220AF94559A86A5D739EF14C012A669225881E5D64DF0BA59F9409E831C4314A68CDED17449E1A1316544F2ED5DA5B9FE8A8EEC832764B366AF000A1E330F8075794AC0402294956C1B737351B247A9D2BC1F900CD741833A6024ABE6E5F7F0000000000000000000000000000000000000000000000000000000000000000000000000000000036313354353331313333629949960E00280000666C3403'

This is an example of a sale where an eToken was retrieved from a secure iFrame:

curl --request POST \
  --url https://cert.payconex.net/api/qsapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data tender_type=CARD \
  --data transaction_type=AUTHORIZATION \
  --data transaction_amount=1.00 \
  --data eToken=m9QDt0gDoFEjGr1wOgUygKFX1JKL--iwPet7isyF_23K-RFmveDdFw_jaIOYm7Z12cxbTBX5lHwSJxF69T3gYasZTFlKPl3LFkmShrFE6UwkZjrJFzX6Ab0AMsdZoveIyX7CMXxyHbbd3vt7tDE3IP_3k40eoYHsNfs9Tfk0c9P2OKZrKcpbQRK5HRE1ngE1BsmhInfr00EGfWwAp5KUC5rO1QNbs3aU

Capturing a Previous Authorization

A CAPTURE transaction flags a previous authorization to be captured for settlement at the next settlement time. This requires token_id with the value of a previous authorization transaction's transaction_id.

curl --request POST \
  --url https://cert.payconex.net/api/qsapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data transaction_type=CAPTURE \
  --data transaction_amount=1.00 \
  --data token_id=000000100601

Reversing an Authorization

A REVERSAL transaction allows a developer to reverse a previous authorization. This is helpful in cases where a merchant would not want to be holding customer funds that they do not intend to capture.

curl --request POST \
  --url https://cert.payconex.net/api/qsapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data transaction_type=REVERSAL \
  --data token_id=000000100661

Storing Payment Information

A STORE transaction allows a developer to send a request to QSAPI that stores credit card/ACH account information for later use (using the reissue parameter, example below).

curl --request POST \
  --url https://cert.payconex.net/api/qsapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data tender_type=CARD \
  --data transaction_type=STORE \
  --data transaction_amount=1.00 \
  --data card_number=4124939999999990 \
  --data card_expiration=1230

ACH Processing

Developers can send transaction requests with ACH information in various formats. See examples below with unencrypted keyboard input and eToken values generated using Bluefin's secure iFrame.

🚧

Real-time ACH Account Verification required by NACHA

The National ACH Association (NACHA) has introduced a new rule that states payment originators must perform account validation for ACH transactions the first time an account number is used to make a WEB debit transaction.

Bluefin has worked to provide a flexible toolset that developers and merchants can utilize to meet or exceed these new requirements.

To learn more, please see our guide titled, Real-Time ACH Account Verification

Processing a Sale

An ACH SALE creates a new transaction that is batched for settlement with a bank.

This is an example of a sale where keyboard input was used:

curl --request POST \
  --url https://cert.payconex.net/api/qsapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data tender_type=ACH \
  --data transaction_type=SALE \
  --data transaction_amount=1.00 \
  --data bank_routing_number=123123123 \
  --data bank_account_number=123456789

Sending a Refund

a REFUND transaction sends a refund to the account holder of a previous sale transaction. The refund transaction type requires the token_id parameter. The value of the token_id should be the transaction_id from a transaction response.

🚧

Note on ACH refunds

ACH transactions can only be refunded before being submitted for settlement. After settlement they cannot be refunded.

curl --request POST \
  --url https://cert.payconex.net/api/qsapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data transaction_type=REFUND \
  --data transaction_amount=1.00 \
  --data token_id=000000100701

Storing Payment Information

A STORE transaction allows a developer to send a request to QSAPI that stores credit card/ACH account information for later use (using the reissue parameter, example below).

curl --request POST \
  --url https://cert.payconex.net/api/qsapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data tender_type=ACH \
  --data transaction_type=STORE \
  --data bank_routing_number=123123123 \
  --data bank_account_number=123456789

Reissuing Previous Transactions

PayConex transactions contain a transaction_id value that can be used to issue new transactions. This is helpful in cases where a developer may want to store payment details so a card may be charged against later.

To accomplish this you must have a transaction_id value in the token_id parameter and set the reissue parameter to 1.

This method can be used to perform reissue sale, authorization, and other transaction types.

This is an example of a reissued sale transaction:

curl --request POST \
  --url https://cert.payconex.net/api/qsapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data transaction_type=SALE \
  --data transaction_amount=1.00 \
  --data token_id=000000100601 \
  --data reissue=1

📘

A note on storing and reissuing transactions

Visa now mandates that transactions specify if they were customer or merchant initiated when storing or reissuing. As our back-end processors add additional paramaters to support complying with Visa's mandate our gateway is as well. Currently these parameters are supported for merchants using Chase Paymentech and Fiserv RapidConnect. Please see the guide on Customer and Merchant Initiated Transactions for more information.

Handling Transaction Responses

The PayConex API provides the response_format parameter to allow developers to specify a desired data format.

There are three supported data formats at this time:

  • FORM: A url-encoded HTTP form query string.
  • JSON: A string in JavaScript Object Notation format.
  • DEBUG: A simple, human readable array output. Intended only for use by a developer for testing.

This example sale transaction contains the response_format value as JSON:

curl --request POST \
  --url https://cert.payconex.net/api/qsapi/3.8 \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data account_id=220614966801 \
  --data api_accesskey=32d42f0f0b6c89616d42aed8c96801e6 \
  --data tender_type=CARD \
  --data transaction_type=SALE \
  --data transaction_amount=1.00 \
  --data response_format=JSON \
  --data card_number=4124939999999990 \
  --data card_expiration=1230 \
  --data card_verification=456

Here you can see the APIs response in JSON format:

{
  "transaction_id": "000000101161",
  "tender_type": "CARD",
  "transaction_timestamp": "2021-08-12 20:53:13",
  "card_brand": "VISA",
  "transaction_type": "SALE",
  "last4": "9990",
  "card_expiration": "1230",
  "authorization_code": "332363",
  "authorization_message": "APPROVED",
  "request_amount": 1,
  "transaction_amount": 1,
  "keyed": true,
  "swiped": false,
  "entry_mode": "keyed",
  "transaction_approved": true,
  "cvv2_response": "N",
  "currency": "USD",
  "error": false,
  "error_code": 0,
  "error_message": null,
  "error_msg": null
}

📘

Did you know?

In combination with the Reporting Service API, PayConex provides a webhook called POSTback. POSTback allows a developer to receive an HTTP POST containing transaction details after every transaction request. For more information see our POSTback guide.

Test Cards and Cases

Test card values in the sandbox environment are determined by the back-end processing networks' testing environments. Each processor will have their own set of allowable cards along with rules for triggering decline scenarios.

To see more information about these test cards and cases please follow the link below that corresponds to your processor.

Additional Resources

Use the links below to learn about more specialized or uncommon processing functions.

If you have more questions about your integration requirements or strategies please contact our Integrations team at [email protected].

QSAPI Request Format

Below are all of the variables that can be posted to QSAPI along with a brief description of their function.

Variable Name Max Type Req'd Description
account_id 12 Numeric Yes The Payconex account identification number that you are issued after your account has been set up.
ach_account_type n/a Enumerated No This is the type of bank account for ACH/electronic check transactions. It will default to checking if none is specified.

The allowed values are:
Checking: checking account
Savings: savings account
ach_opcode n/a Enumerated No For processor-specific ACH features.
01, 02, 03, S, R
ach_sec_code n/a Enumerated No The Standard Entry Class (SEC) code that is required for ACH/echeck transactions. If no SEC code is provided, the default that is set up for the account is used. Please note that if you provide an SEC Code here that the account is not underwritten for, the bank will decline the transaction.

Acceptable types are:
CCD: Cash Concentration or Disbursement. This is the default type for corporations. Requires a signature.
PPD: Prearranged Payment & Deposit. Requires a signature.
WEB: Web-originated, ecommerce transactions.
TEL: Telephone-initiated transactions. Voice recording required.
POP: Point-of-Purchase, in-person transaction.
ARC: Accounts Receivable. This is for converting a check into an electronic ACH transaction.
RCK: Re-presented Check. This is used to present a declined check an additional time.
DEF: This can be sent to tell PayConex to use the default ACH SEC code. Sending nothing will result in the same action.
allow_partial 1 Numeric No Allows for support of partial auths. By default, QSAPI assumes all transactions do not support partial auth unless specified.

Values for partial auth are:
0: declares no partial auths allowed. Unneeded declaration however since by default partial auths are not allowed.
1: partial auths allowed.

*only supported in QSAPI 3.7 or higher
api_accesskey 32 Alphanumeric Yes The secret key that you will be provided when your Payconex account is set up and when you have requested access to QSAPI.
authorization_code 6 Alphanumeric No For credit/debit cards, this is the 6-digit authorization code from a previously authorized transaction that is required to be provided with a Force transaction. It may also be obtained by calling the merchant account processor for a force code.

For EBT cards, this is the authorization code that is required along with the voucher number to capture a prior authorized transaction.
bank_account_number 17 Numeric No The bank account (DDA) number that is required for an ACH/electronic check.
bank_routing_number 9 Numeric No The bank routing (ABA) number that is required for an ACH/electronic check.
card_expiration 4 Numeric Yes The card expiration date in the format of MMYY. This does not include hyphens, dashes, spaces, or slashes. It is required if submitting a card. It is not required for ACH/electronic checks.
card_number 16 Numeric Yes/No The card number with no spaces, dashes, or hyphens. Required for card transactions using KEYED entry. It is not required for ACH/electronic checks.
card_track1 ? Character No Should use "card_tracks" parameter instead. The characters from Track 1 of the magnetic stripe on a card. Track 1 begins with “%” and ends with “?” and includes the cardholder name.

If you do NOT use "card_tracks", this is the primary choice in choosing which track to send. Track 1, Track 2, or both can be sent, but NOT with "card_tracks". Track data may not be stored for any reason.
card_track2 ? Character No Should use "card_tracks" parameter instead. The characters from Track 2 of the magnetic stripe on a card. Track 2 begins with “;” and ends with “?” and does not include the cardholder name. Track 1, Track 2, or both can be sent, but NOT with "card_tracks". Track data may not be stored for any reason.
card_tracks ? Character Yes/No The characters from the full, un-modified payload from the magnetic stripe on a card. This is now the preferred method to send card track data and replaces both "card_track1" and "card_track2" parameters, so do not send "card_tracks" in combination with those. Track data may not be stored for any reason. Required for card transactions using SWIPED entries (see page 55-56).
card_verification 4 Numeric No The CVV/CVC/CID value which is the 3 digits from the signature panel on the back of a Visa/MasterCard/Discover or the 4 digits from the front of an American Express.
cashback_amt 9 Numeric No Amount requested as cash back (cash returned to the customer)
cashier 100 Character No The name or ID of the cashier that is submitting the transaction. This is shown with PayConex transaction details as the originator of the transaction. You may use any designation you wish. Good choices are the user name of the POS clerk, email address, or the name of the application that is connecting.
check_number 15 Numeric No The number of the check used for electronic checks that are processed via ACH. It is optional.
city 100 Character No The city portion of the cardholder or account holder address. This is not sent to the processor. It is only stored for your reporting purposes.
company 50 Character No The company name for cardholder or account holder address. This is not sent to the processor. It is only stored for your reporting purposes.
country 3 Alphabetic No This is a 2- or 3-character country code value for the card/account holder: Country codes can be obtained at http://www.iso.org/iso/country_codes

Note: We do NOT validate the value.
custom_data 65K Character No An open variable. Many developers use this variable to transmit structured data formats or serialized variables. You can send through many variable=value pairs through this single variable.
custom_id 50 Character No This is a custom identifier that can be used for any purpose you wish. Often times this is a customer number, or some other foreign key used to match up reports and transactions lists with customer information on your database. For some processors, such as Paymentech, this ID is passed through to the processor and available in their reporting. This can ease syncing up reporting.
disable_avs 1 Boolean No Disable Address Verification.
disable_cvv 1 Boolean No Disable Card Verification such as CVV, CVC, CID.
disable_fraudfirewall 1 Boolean No Disable any Fraud Firewall controls.
disable_redirect 1 Boolean No Disabling redirect will override the success_url and decline_url settings and force the return of transaction response in the format specified by response_format. This setting is required for using AJAX API calls.
ebt_type n/a Enumerated Yes/No For EBT (Electronic Benefits Transfer), the type can be as follows:
FOOD: this is for a food sale
CASH: this is for a cash sale
VOUCHER: this is for a voucher

Required if tender_type=EBT
ebt_voucher 15 Numeric No The EBT Voucher number for prior (phone) authorized EBT transactions. Required if "ebt_type" is VOUCHER
email 100 Character No The email address of the cardholder/account holder. It does not expect any specific format, is not sent to the processor, and is stored only for your reporting use or sending email receipts.
etoken ??? Alphanumeric No eToken value of a previously ran Bluefin iFrame transaction. Typically used in a Sale transaction, with the eToken variable and value sent. No card or PAN needed when using eToken.
first_name 50 Character Yes/No Card: The first name of the cardholder as it appears on the front of the card. It is not required for cards.
ACH: The first name of the account holder as it appears on the front of the check or bank statement.

*NACHA requires the provision of a first and last name.
group 12 Alphanumeric No Groups are pre-configured flexible groups that can be used for various reasons, including: a) to direct transactions to separate back-end merchant accounts or depository accounts. Please work with your Bluefin Representative to configure any of these options. b) to assign transactions to a specific grouping that you wish.
input_group 10 Character No An open variable. Used to identify or group transactions together in some fashion.
installment_count ??? Numeric No Used exclusively for installment transactions. Total number of installments. Please note that the installment count value never decreases, only the installment number should increase.

*only supported in QSAPI 3.7 or higher
installment_number ??? Numeric No Used exclusively for installment transactions and is the current installment number.

*only supported in QSAPI 3.7 or higher
ip_address 15 NNN.NNN.NNN.NNN No IP address of the client which initiated the transaction.
ksn ? Alphanumeric No The Key Sequence Number (DUKPT) portion for PIN debit, PIN EBT, or EMV transactions. It must be obtained from a PCI PTS/PED Certified device that is injected by Bluefin’s Encryption Service Organization or Key Injection Facility (KIF). The KSN may never be stored for any reason.
last_name 50 Character Yes/No Card: The last name of the cardholder as it appears on the front of the card. It is not required for cards.
ACH: The last name of the account holder as it appears on the front of the check or bank statement.

*NACHA requires the provision of a first and last name.
level2_merchant_reference 17 Alphanumeric No Used exclusively for level 2 transactions. Required for level 2 transactions. Merchant determines any custom alphanumeric value.

*only supported in QSAPI 3.7 or higher
level2_order_id 17 Alphanumeric No Used exclusively for level 2 transactions. Merchant determines any custom alphanumeric value.

*only supported in QSAPI 3.7 or higher
level2_tax ??? Numeric with decimal No Used exclusively for level 2 transactions. Required for level 2 transactions. For Visa cards, value must be expressed as greater than 0.00, for MasterCard value may be expressed as 0.00 if desired.

*only supported in QSAPI 3.7 or higher
level2_zip 10 Numeric with hyphen No Used exclusively for level 2 transactions. REQUIRED for level 2 transactions and it is probably the same value as the "zip" variable value. This value is not validated like the "zip" variable value, so any alphanumeric value up to 10 digits is valid.

*only supported in QSAPI 3.7 or higher
merchant_reference_num 11 Numeric No An optional merchant reference number that can be passed to processor for reconciliation purposes.
payment_type 11 Enumerated No The type of payment for this transaction. Valid values can be:
ECOMMERCE
INSTALLMENT
RECURRING
MOTO (Mail & Telephone Order)
phone 20 Alphanumeric No The phone number of the cardholder/account holder. It does not expect any specific format, is not sent to the processor, and is stored only for your reporting use.
pin ? Alphanumeric No The encrypted PIN Block portion for PIN debit or PIN EBT transactions. It must be obtained from a PCI PTS/PED Certified device that is injected by Bluefin’s Encryption Service Organization or Key Injection Facility (KIF). This PIN Block may never be stored for any reason.
reissue 1 Boolean No Reissue a transaction. If included (set to 1), either a bfid (ShieldConex tokens) or a "token_id" with known existing transaction id must be included. Amount, name, description, expiration can be changed.
response_format 5 Enumerated No Desired response format. FORM: www-form-urlencoded string (default format) JSON: JavaScript Object Notation DEBUG: human readable array output
restaurant_gratuity 9 Numeric No Used exclusively for restaurant transactions. Value can be 0 ~ 999999.99. Value must contain decimal point with two decimal point values.

*only supported in QSAPI 3.7 or higher
restaurant_server_id 3 Numeric No Used exclusively for restaurant transactions. Value can be null, 0 ~999

*only supported in QSAPI 3.7 or higher
scx_token_bank_account_number 1 Numeric No ShieldConex tokenized version of bank_account_number parameter. See ShieldConex on PayConex section for more details.
scx_token_bank_routing_number 1 Numeric No ShieldConex tokenized version of bank_routing_number parameter. See ShieldConex on PayConex section for more details.
scx_token_card_expiration 1 Numeric No ShieldConex tokenized version of card_expiration parameter. See ShieldConex on PayConex section for more details.
scx_token_card_number 1 Numeric No ShieldConex tokenized version of card_number parameter. See ShieldConex on PayConex section for more details.
scx_token_card_verification 1 Numeric No ShieldConex tokenized version of card_verification parameter. See ShieldConex on PayConex section for more details.
scx_token_email 1 String No ShieldConex tokenized version of email parameter. See ShieldConex on PayConex section for more details.
scx_token_first_name 1 String No ShieldConex tokenized version of first_name parameter. See ShieldConex on PayConex section for more details.
scx_token_last_name 1 String No ShieldConex tokenized version of last_name parameter. See ShieldConex on PayConex section for more details.
scx_token_phone 1 Numeric No ShieldConex tokenized version of phone parameter. See ShieldConex on PayConex section for more details.
scx_token_street_address1 1 String No ShieldConex tokenized version of street_address1 parameter. See ShieldConex on PayConex section for more details.
scx_token_zip 1 Numeric No ShieldConex tokenized version of zip parameter. See ShieldConex on PayConex section for more details.
send_customer_receipt 1 Boolean No Use this to override the default setting to send or not send email receipts to the customer.
send_merchant_receipt 1 Boolean No Use this to override the default setting to send or not send email receipts to the merchant.
state 2 Alphabetic No The two-digit state code of the cardholder or account holder address. This is not sent to the processor. It is only stored for your reporting purposes.
street_address1 100 Character No Street address of the cardholder or bank account holder.
street_address2 - Character No Suite number or other qualifying part of the address. NOT sent to the processor. Total of address1 and 2 are 100 maximum and will be truncated.
surcharge_amt 9 Numeric No Amount charged for fees, etc.
tender_type n/a Enumerated Yes The payment tender type that you are submitting. The following enumerated values are allowed:
CARD: credit, debit, and check cards
ACH: ACH , EFT, or electronic check
EBT: Electronic Benefits Transfer (Elavon only)
DEBIT: PIN Debit card only (Elavon/Omaha/North)
timestamp 19 YYYY-MM-DD HH:MM:SS No If used, MUST be included in a hash for authenticated transactions. See "Appendix: Using HASH for Authenticated Transactions"
token_id 12 Numeric No 12-digit transaction_id of a previous transaction. The token_id is used for reissues, refunds, and recurring transaction creation. Please see the SLAPI documentation for more information.
transaction_amount 9 Numeric with decimal Yes This is the dollar (or other currency) amount of the transaction. Only numbers and a single decimal are allowed. Commas are not allowed. The maximum amount is 999999.99. That is 1 cent less than 1 million. This is because the decimal is counted in the max size. Values with no decimal and no cents are allowed. Values with only a single number after the decimal are allowed and will be assumed to have a trailing 0.
transaction_description 65K Character No A description of the payment. This is an open field. If emails are sent to the customer or merchant, this will show in the “Description:” field. You may use this to send any information that you wish. It can store up to 65,000 characters.
transaction_id 12 Numeric No The transaction_id returned from a TSAPI "GET_TRANSACTION_ID" request. It is used to create a new transaction with the specified transation_id. Please see the TSAPI documentation.
transaction_type n/a Enumerated Yes The type of transaction you are requesting, with these enumerated values allowed:
AUTHORIZATION: authorizes (holds) the funds on the card but does not transfer them. Most banks support a $0.00 authorization in order to validate the card number, expiration date, and account status. This does, however, incur an authorization charge on the merchant account and a transaction charge in Payconex.
SALE: authorizes the funds on the card and flags the transaction to be captured for settlement at the next settlement time.
REFUND: refunds a previous sale. If the transaction has not yet been settled, then this results in a void. Otherwise, for Cards only, it results in a credit back on the card. ACH transactions can't be refunded once they are submitted for settlement (NOTE: For actual transaction settlement times, contact Bluefin support). You can specify an amount less than the original sale amount. Requires token_id.
CREDIT: puts money onto a card or into a bank with no offsetting sale. Most operations can be managed via REFUND. Only allowed if account is configured to allow Credits.
CAPTURE: flags a previous authorization to be captured for settlement at the next settlement time. Requires token_id.
STORE: stores credit card/ach account info for later use.
COPY: copies a transaction from one account to a destination account (under same Agent). Copy is done as a Store transaction.
STORE: stores credit card/ach account info for later use.
SETTLEBATCH: settles all un-settled sales, refunds, credits, or authorizations that have been captured.
FORCE: forces through a transaction. A 6-digit authorization_code must also be provided.
REVERSAL: removes an authorization request on a credit card or debit/ebt. Requires token_id (Elavon, Chase Paymentech, FD RapidConnect only)
BALANCE: request account balance on an EBT/Debit card (Elavon only).
CANCEL: removes a refund request on a credit card or debit/ebt. Requires the refund token_id (RapidConnect only)
zip 10 Numeric with hyphen No The 5-digit format or 5+4 formatted zip code of the cardholder or accountholder. For example, 12345 or 12345-1234. Only numbers and a hyphen are allowed.

INTERNATIONAL: Can contain any combination of letters or numbers, and either a space or a hyphen.

QSAPI Response Format

Below are all the variables that can be received in response to posts made to QSAPI along with a brief description of their function.

Variable Name Max Type Description
account_balance_1 9 Numeric See Balance Chart below for more information
ONLY returned when transaction_type=BALANCE
account_balance_2 9 Numeric See Balance Chart below for more information
ONLY returned when transaction_type=BALANCE
account_balance_3 9 Numeric See Balance Chart below for more information
ONLY returned when transaction_type=BALANCE
authorization_code 6 Alphanumeric This is the auth code returned by the processor.
authorization_message 50 Alphanumeric APPROVED or the auth message from the processor (e.g. AUTH DECLINED 200).
avs_response 1 Enumerated A single letter address verification response:
DFJMQVXY - Address and ZIP code match
LWZ - ZIP code match, address is wrong
ABOP - Address match, ZIP code is wrong
KN - No match, address and ZIP is wrong
U - No data from issuer/banknet switch
R - AVS System unable to process
S - Issuing bank does not support AVS
E - Error, AVS not supported for your business
C - Invalid address and ZIP format (International)
I - Address not verifiable (International)
G - Global non-verifiable address (International)
? - Unrecognized codes (none of the above) (empty) - No AVS data (blank)
card_brand n/a Enumerated VISA, MASTERCARD, AMERICAN EXPRESS, DISCOVER, ACH, EBT
card_expiration 4 Numeric The month and year of the card expiration date in the format MMYY. For example, 0120 for January 2020.
custom_data 65K Character The same variable submitted in the request.
custom_id 50 Character The same variable submitted in the request.
cvv2_response 1 Enumerated A single letter card verification value response:
M - CVV match
N - CVV does not match
P - CVV not processed
S - Card has CVV, customer says it doesn't
U - No CVV data from issuer
? - Unrecognized codes (none of the above) (empty) - No CVV data (blank)
dest_account 12 Numeric The Payconex account identification number that a "copy" transaction was created in.
entry_mode 9 Enumerated Indicates the mode of entry of the transaction. Can be used instead of keyed and swipe variables with responses of:
Keyed
Swiped
EMV
Contactless
Fallback Swiped
NFC
error 1 Boolean True for error conditions or decline.
error_code 5 Numeric 0 for no error, > 0 for error number.
error_message ? Character DECLINED or textual description of other API errors (e.g., “Must send card_number” or “Invalid bank_account_number”).
error_msg ? Character Deprecated (Legacy), same as error_message
first_name 50 Character The same variable submitted in the request. *May be returned with last_name concatenated
ip_address 15 NNN.NNN.NNN.NNN IP address of the client which initiated the transaction.
keyed 1 Boolean True for keyed transaction.
last_name 50 Character The same variable submitted in the request. *May be returned concatenated in the first_name field.
last4 4 Numeric The last four digits of the card number or Primary Account Number (PAN). For ACH, it is the last four digits of the account number.
network ? Character This response could be returned if processing thru to RapidConnect or Elavon. It is their name for the network which the transaction was routed thru, used for EMV and MSR (non-EMV), CREDIT, DEBIT and EBT.
original_transaction_id 12 Numeric Will be returned for refunds. This is the original transaction_id of the Sale transaction that was refunded. It is provided for reference purposes.
request_amount 9 Numeric Used only in partial auth. Indicates the amount of money that the merchant attempted to authorize the card for.

*only supported in QSAPI 3.7 and higher
swiped 1 Boolean True for swiped transaction.
tender_type n/a Enumerated This will be the same as the tender_type provided in the request. It is provided for reference purposes. See Response Format for list.
transaction_amount 9 Numeric with decimal The same variable submitted in the request. If a partial auth is valid, this represents the actual amount authorized.
transaction_approved 1 Boolean True for approved.
transaction_description 65K Character The same variable submitted in the request.
transaction_id 12 Numeric The transaction id for the new transaction. When using tokenization, this is the transaction_id that you submit as the token_id.
transaction_timestamp 19 YYYY-MM-DD HH:MM:SS This is the timestamp of the newly created transaction.
transaction_type n/a Enumerated This is the transaction_type of the original transaction.

📘

Note

For Boolean responses, if the “response_format” variable was FORM, responses will return a 1 for True and NULL for False. Other response formats will return the native Boolean response of True or False.

Account Balance Inquiry (Elavon Only)

In the QSAPI request, if you use the transaction_type with a value of BALANCE, then the response is based on the table below.

Variable Name tender_type=CARD tender_type=DEBIT tender_type=EBT
account_balance_1 Pre-paid Pre-paid Food Stamp
account_balance_2 Gift Card Gift Card Cash Benefit
account_balance_3 Loyalty Loyalty N/A

Depending on the tender_type value (also in the QSAPI request), the variable that could be returned and the description of the balance is shown. Example if QSAPI request has:
transaction_type=BALANCE tender_type = DEBIT

If account_balance_1 is returned, the value is the actual balance of the pre-paid portion remaining on the debit card used, according to the end processor (Elavon).