Single Transaction API (TxHandler)

TxHandler is the most common integration method. It is also the most flexible integration method for collecting payments.

TxHandler expects Form Data to be sent via POST calls. Typically this would be after a customer clicks on the "Pay Now" button on the merchants website. But can be doing via an API call.

POST data to TxHandler

POST https://uat.txshield.payshield.ai/secure/txHandler.php

Request Body

Name	Type	Description
sid*	String	Site id (unique identifier for the web site)
tid	String	Merchant Reference
postback_url*	String	The URL of the page used to receive the TxHandler postback. The response can be read from $_POST array.
redirect_url	String	The URL of the page TxHandler will redirect to after processing. The response can be read as GET parameters. If there is no redirect_url, the result will be a json string
hash*	String	md5 hash of sid+timestamp+amounttotal+currency+rcode ie: md5('22'.'1234568995265421'.'17.00'.'USD'.'222b6c') For more details see the hash section. Field Definitions
timestamp*	String	Timestamp value used in the hash ie: 1234568995265421
card_type*	String	Please ask your support contact for your complete list. Each pay method will require different fields and currencies to be entered.
card_name*	String	Card holders name as is on the card.
card_no*	String	Card Number / PAN. No spaces or separators allowed
card_ccv*	String	Card CCV/CVV/CVC
card_exp_month*	String	2 digits
card_exp_year*	String	4 digits
institution_number	String	The institution number, used for bank transfers
routing_no	String	The routing or transit number, used for bank transfers
account_no	String	The account number, used for bank transfers
firstname	String	First name of the customer
lastname	String	Last name of the customer
phone	String	Customer phone number
email*	String	Customer email
mobile	String	Customer mobile number
address	String	Customer address
suburb_city	String	Customer suburb or city
state	String	Customer state, 2 digit code for US/Canada
postcode	String	Customer postcode/zipcode
country*	String	Customer country, ISO 3166 2 digit code
shipping_firstname	String	First name of the customer
shipping_lastname	String	Last name of the customer
shipping_address	String	Customer address
shipping_suburb_city	String	Customer suburb or city
shipping_state	String	Customer state, 2 digit code for US/Canada
shipping_postcode	String	Customer postcode/zipcode
shipping_country	String	Customer country, ISO 3166 2 digit code
currency*	String	Transaction currency [currency in which the gateway is setup], ISO 3 letter code
amount_shipping*	String	Transaction shipping amount
amount_coupon*	String	Coupon amount
amount_tax*	String	Transaction tax amount
item_quantity*	Object	An array with the quantity of each cart item
item_name*	Object	An array of article names for each cart item
item_no*	Object	An array of article numbers for each cart item
item_desc*	Object	An array with descriptions for each cart item
item_amount_unit*	Object	An array that defines the price per unit for each cart item
threeDSecure	String	json string of the 3d2.0 params eg, {"eci":"05", "cavv":"MPUAANABhSD54fFQJTIm+Vq+zPY=", "xid":"1b5705e7-70da-4a63-9693-bba49da82066", "status":"Y", "protocolVersion":"2.1.0", "authenticationValue":"MPUAANABhSD54fFQJTIm+Vq+zPY=", "dsTransactionId":"1b5705e7-70da-4a63-9693-bba49da82066"}
campaignid	String	This is a campaign code as provided by the associated affiliate system. please only use if information is provided.
affiliateid	String	The affiliate id provided by the affiliate system
tx_action*	String	PAYMENT/PREAUTH/AUTH
ref4	String	Merchant reference field
ref3	String	Merchant reference field
ref2	String	Merchant reference field
ref1	String	Merchant reference field

Name

Type

Description

sid*

String

Site id (unique identifier for the web site)

tid

String

Merchant Reference

postback_url*

String

The URL of the page used to receive the TxHandler postback. The response can be read from $_POST array.

redirect_url

String

The URL of the page TxHandler will redirect to after processing. The response can be read as GET parameters. If there is no redirect_url, the result will be a json string

hash*

String

md5 hash of sid+timestamp+amounttotal+currency+rcode ie: md5('22'.'1234568995265421'.'17.00'.'USD'.'222b6c') For more details see the hash section.

Field Definitions

timestamp*

String

Timestamp value used in the hash ie: 1234568995265421

card_type*

String

Please ask your support contact for your complete list. Each pay method will require different fields and currencies to be entered.

card_name*

String

Card holders name as is on the card.

card_no*

String

Card Number / PAN. No spaces or separators allowed

card_ccv*

String

Card CCV/CVV/CVC

card_exp_month*

String

2 digits

card_exp_year*

String

4 digits

institution_number

String

The institution number, used for bank transfers

routing_no

String

The routing or transit number, used for bank transfers

account_no

String

The account number, used for bank transfers

firstname

String

First name of the customer

lastname

String

Last name of the customer

phone

String

Customer phone number

email*

String

Customer email

mobile

String

Customer mobile number

address

String

Customer address

suburb_city

String

Customer suburb or city

state

String

Customer state, 2 digit code for US/Canada

postcode

String

Customer postcode/zipcode

country*

String

Customer country, ISO 3166 2 digit code

shipping_firstname

String

First name of the customer

shipping_lastname

String

Last name of the customer

shipping_address

String

Customer address

shipping_suburb_city

String

Customer suburb or city

shipping_state

String

Customer state, 2 digit code for US/Canada

shipping_postcode

String

Customer postcode/zipcode

shipping_country

String

Customer country, ISO 3166 2 digit code

currency*

String

Transaction currency [currency in which the gateway is setup], ISO 3 letter code

amount_shipping*

String

Transaction shipping amount

amount_coupon*

String

Coupon amount

amount_tax*

String

Transaction tax amount

item_quantity*

Object

An array with the quantity of each cart item

item_name*

Object

An array of article names for each cart item

item_no*

Object

An array of article numbers for each cart item

item_desc*

Object

An array with descriptions for each cart item

item_amount_unit*

Object

An array that defines the price per unit for each cart item

threeDSecure

String

json string of the 3d2.0 params eg, {"eci":"05", "cavv":"MPUAANABhSD54fFQJTIm+Vq+zPY=", "xid":"1b5705e7-70da-4a63-9693-bba49da82066", "status":"Y", "protocolVersion":"2.1.0", "authenticationValue":"MPUAANABhSD54fFQJTIm+Vq+zPY=", "dsTransactionId":"1b5705e7-70da-4a63-9693-bba49da82066"}

campaignid

String

This is a campaign code as provided by the associated affiliate system. please only use if information is provided.

affiliateid

String

The affiliate id provided by the affiliate system

tx_action*

String

PAYMENT/PREAUTH/AUTH

ref4

String

Merchant reference field

ref3

String

Merchant reference field

ref2

String

Merchant reference field

ref1

String

Merchant reference field

sid=xxx&status=OK&parent_txid=xx&txid=xxx&tx_action=xxx&amount=xxx&currency=xxx&comment=xxx&rebillkey=xxx&descriptor=xxx&tid=xxx&ref1=xxx&ref2=xxx&ref3=xxx&ref4=xxx&vrfy=xxx

sid=xxx&status=EXC&parent_txid=xx&txid=xxx&tx_action=xxx&amount=xxx&currency=xxx&comment=xxx&rebillkey=xxx&descriptor=xxx&tid=xxx&ref1=xxx&ref2=xxx&ref3=xxx&ref4=xxx&vrfy=xxx&error_type=xxx&error_sys=xxx&error_info=xxx&error_msg=xxx&error_code=xxx

Redirect URL

After the transaction, the customer can be redirected to a merchant defined location and also the result of the transaction can be received as postback to a merchant defined script/page.

In case of no redirect URL, the response will be a JSON string of the above data (see example response in above). This will be useful if you are doing an cURL post instead of FORM post.

For more information click the following link: Make Payment using TxHandler.

Postback URL

For every transaction type, and status combination, a postback will be sent to the postback URL.

A postback will contain the same data as that contained in the return of a redirect, except to a dedicated endpoint you specify. For synchronous transactions this may not seem important, as you may be redirecting the user back to your main CRM. For asynchronous transactions this is very important, if this is not used correctly, you will never get the final status of the second part of the transaction.

Status

The status field will have one of the following values:

OK The transaction was successful.

PEND The transaction is pending and there will be a follow-up message.

EXC The transaction is declined. The response should include information about the reason or exception encountered.

PAYG_ERROR This is a rare response, indicating a problem with communicating with the processor.

<form action="{endpoint_url}/secure/txHandler.php" method="post">
    sid: <input type="text" name="sid" value="19"><br>
    tid: <input type="text" name="tid" value="5678"><br>
    postback_url: <input type="text" name="postback_url" value="http://mysite.com/postback.php"><br>
    redirect_url: <input type="text" name="redirect_url" value="http://mysite.com/redirect.php"><br>
    timestamp: <input type="text" name="timestamp" value="1234568995265421"><br>
    hash: <input type="text" name="hash" value="08ff1b1b14a09acfd67560baae229c4e"><br>
    firstname: <input type="text" name="firstname" value="Jack"><br>
    lastname: <input type="text" name="lastname" value="Tester"><br>
    phone: <input type="text" name="phone" value="1234567"><br>
    email: <input type="text" name="email" value="test@example.com"><br>
    address: <input type="text" name="address" value="12 Test Lane"><br>
    suburb_city: <input type="text" name="suburb_city" value="TestCity"><br>
    state: <input type="text" name="state" value="CA-ON"><br>
    postcode: <input type="text" name="postcode" value="41010"><br>
    country: <input type="text" name="country" value="CA"><br>
    ship_firstname: <input type="text" name="ship_firstname" value="Julie"><br>
    ship_lastname: <input type="text" name="ship_lastname" value="Tester"><br>
    ship_address: <input type="text" name="ship_address" value="13 Test Lane"><br>
    ship_suburb_city: <input type="text" name="ship_suburb_city" value="TestCity"><br>
    ship_state: <input type="text" name="ship_state" value="CA-ON"><br>
    ship_postcode: <input type="text" name="ship_postcode" value="41010"><br>
    ship_country: <input type="text" name="ship_country" value="CA"><br>
    currency_code: <input type="text" name="currency" value="USD"><br>
    amount_shipping: <input type="text" name="amount_shipping" value="0.30"><br>
    amount_tax: <input type="text" name="amount_tax" value="0.00"><br>
    amount_coupon: <input type="text" name="amount_coupon" value="0.00"><br>
    card_type: <input type="text" name="card_type" value="visa"><br>
    card_no: <input type="text" name="card_no" value="41111111111111"><br>
    card_name: <input type="text" name="card_name" value="J Citizen"><br>
    card_cvv: <input type="text" name="card_cvv" value="123"><br>
    card_exp_month: <input type="text" name="card_exp_month" value="2014"><br>
    card_exp_year: <input type="text" name="card_exp_year" value="09"><br>
    tx_action: <input type="text" name="tx_action" value="FRAUDCHECK"><br>
    ref1: <input type="text" name="ref1" value=""><br>
    ref2: <input type="text" name="ref2" value=""><br>
    ref3: <input type="text" name="ref3" value=""><br>
    ref4: <input type="text" name="ref4" value=""><br>
    <table>
        <tr>
            <td>
                item_quantity: <input type="text" name="item_quantity[]" value="2">
                item_name: <input type="text" name="item_name[]" value="apple">
                item_no: <input type="text" name="item_no[]" value="a234">
                item_desc: <input type="text" name="item_desc[]" value="juicy green apple">
                item_amount_unit: <input type="text" name="item_amount_unit[]" value="0.59">
            </td>
        </tr>
        <tr>
            <td>
                item_quantity: <input type="text" name="item_quantity[]" value="1">
                item_name: <input type="text" name="item_name[]" value="pear">
                item_no: <input type="text" name="item_no[]" value="p567">
                item_desc: <input type="text" name="item_desc[]" value="fresh green pear">
                item_amount_unit: <input type="text" name="item_amount_unit[]" value="0.68">
            </td>
        </tr>
    </table>
    <input type="submit" value="Submit">
</form>

PreviousTransaction Lifecyle / Workflow NextREST API

Last updated 2 years ago