Single Transaction API (TxHandler)
Last updated
PayShield - Transaction Processing / TxProcess
Last updated
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 https://uat.txshield.payshield.ai/secure/txHandler.php
| Name | Type | Description |
|---|---|---|
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.
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.
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.
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.
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