# 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

<mark style="color:green;">`POST`</mark> `https://uat.txshield.payshield.ai/secure/txHandler.php`

#### Request Body

| Name                                                 | Type   | Description                                                                                                                                                                                                                                                                                    |
| ---------------------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| sid<mark style="color:red;">\*</mark>                | String | Site id (unique identifier for the web site)                                                                                                                                                                                                                                                   |
| tid                                                  | String | Merchant Reference                                                                                                                                                                                                                                                                             |
| postback\_url<mark style="color:red;">\*</mark>      | 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<mark style="color:red;">\*</mark>               | String | <p>md5 hash of sid+timestamp+amounttotal+currency+rcode ie: md5('22'.'1234568995265421'.'17.00'.'USD'.'222b6c') For more details see the hash section.</p><p><a data-mention href="field-definitions">field-definitions</a></p>                                                                |
| timestamp<mark style="color:red;">\*</mark>          | String | Timestamp value used in the hash ie: 1234568995265421                                                                                                                                                                                                                                          |
| card\_type<mark style="color:red;">\*</mark>         | String | Please ask your support contact for your complete list. Each pay method will require different fields and currencies to be entered.                                                                                                                                                            |
| card\_name<mark style="color:red;">\*</mark>         | String | Card holders name as is on the card.                                                                                                                                                                                                                                                           |
| card\_no<mark style="color:red;">\*</mark>           | String | Card Number / PAN. No spaces or separators allowed                                                                                                                                                                                                                                             |
| card\_ccv<mark style="color:red;">\*</mark>          | String | Card CCV/CVV/CVC                                                                                                                                                                                                                                                                               |
| card\_exp\_month<mark style="color:red;">\*</mark>   | String | 2 digits                                                                                                                                                                                                                                                                                       |
| card\_exp\_year<mark style="color:red;">\*</mark>    | 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<mark style="color:red;">\*</mark>              | 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<mark style="color:red;">\*</mark>            | 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<mark style="color:red;">\*</mark>           | String | Transaction currency \[currency in which the gateway is setup], ISO 3 letter code                                                                                                                                                                                                              |
| amount\_shipping<mark style="color:red;">\*</mark>   | String | Transaction shipping amount                                                                                                                                                                                                                                                                    |
| amount\_coupon<mark style="color:red;">\*</mark>     | String | Coupon amount                                                                                                                                                                                                                                                                                  |
| amount\_tax<mark style="color:red;">\*</mark>        | String | Transaction tax amount                                                                                                                                                                                                                                                                         |
| item\_quantity<mark style="color:red;">\*</mark>     | Object | An array with the quantity of each cart item                                                                                                                                                                                                                                                   |
| item\_name<mark style="color:red;">\*</mark>         | Object | An array of article names for each cart item                                                                                                                                                                                                                                                   |
| item\_no<mark style="color:red;">\*</mark>           | Object | An array of article numbers for each cart item                                                                                                                                                                                                                                                 |
| item\_desc<mark style="color:red;">\*</mark>         | Object | An array with descriptions for each cart item                                                                                                                                                                                                                                                  |
| item\_amount\_unit<mark style="color:red;">\*</mark> | 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<mark style="color:red;">\*</mark>         | String | PAYMENT/PREAUTH/AUTH                                                                                                                                                                                                                                                                           |
| ref4                                                 | String | Merchant reference field                                                                                                                                                                                                                                                                       |
| ref3                                                 | String | Merchant reference field                                                                                                                                                                                                                                                                       |
| ref2                                                 | String | Merchant reference field                                                                                                                                                                                                                                                                       |
| ref1                                                 | String | Merchant reference field                                                                                                                                                                                                                                                                       |
| device\_info                                         | String | JSON string containg the information of the device used                                                                                                                                                                                                                                        |

{% tabs %}
{% tab title="200: OK " %}

```javascript
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
```

{% endtab %}

{% tab title="400: Bad Request " %}

```javascript
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
```

{% endtab %}
{% endtabs %}

### 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.&#x20;

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.\
\
If the post to the url fails, the system retries the post 3 times with a 2 min gap. If the http response code is 200, the retry is stopped.

### **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>
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.payshield.ai/transaction-processing/integrations-and-apis/single-transaction-api-txhandler.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.