Process Transactions

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.

• Elavon Test Cards
• First Data Rapid Connect Test Cards
• Chase Paymentech Test Cards
• Bluefin Gateway Test Cards

Additional Resources

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

• POSTback Webhook
• Using Hashed Authentication
• Handling Partial Authorizations
• Restaurant Transaction Processing
• Level 2 Transaction Processing
• Account Balance Inquiries (Elavon Only)

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.

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.

📘

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.

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