# Overview

<img src="/files/qFas3OWaegGkhYb8nJg5" alt="" width="375">

**Note:** TxShield is the core framework on which the PayShield system is built. All referenced APIs will use txshield in the domain URL.&#x20;

PayShield is a fraud/chargeback prevention, handling & response system, with capabilities of payment processing. Along with over 300+ payment processor integrations to processors all over the world, it has a heavy emphasis on fraud/chargeback prevention (active and passive), handling & response. Systems have been designed to mitigate the potential for fraudulent transactions to be processed and chargebacks to be lodged by customers.&#x20;

### PayShield Documentation

[Dispute Alerts](https://docs.payshield.ai/txalerts-dispute-alerts/)

[3D Secure](https://docs.payshield.ai/3dsecure2+/)

[Order Insight / TxFind](https://docs.payshield.ai/txfind-payreveal-order-insight-ican/)

[Transaction Processing / TxProcess](https://docs.payshield.ai/transaction-processing/)

[Fraud Check](https://docs.payshield.ai/payshield-fraudcheck/)

[Merchant Monitoring API](https://docs.payshield.ai/transaction-processing/)

### Fraud/chargeback mitigation

PayShield's fraud/chargeback modules include:

**Dispute Alerts**\
The alert module receives notifications that a dispute is about to be raised against your account by a cardholder, and lets you respond to the dispute before it becomes a chargeback. The alerts can be managed from our dashboard, or integrated into your CRM.

**3DS SDK**\
Native 3DS SDK that allows merchants to perform simple 3DS integrations on their payment page, taking the complexity out of the integration, and only having to handle the result. Compatible with any payment processor who will accept 3DS data.

**Risk-Based Assessment**\
With integrations to many fraud detection and risk-based assessment platforms, TxShield can return to you a fraud score for the transaction, allowing you to setup automated rules based on the result.

**PayReveal**\
PayReveal allows merchants to store a copy of their transaction and cart details which are then available to customers direct from their banks web/mobile app. There is no special onboarding for issuing banks as the integration is direct to the card platforms.

**Fraud Check**\
TxShield's Fraud Management system evaluates transactions for risk using a configurable set of local rules and third-party scoring providers. Fraud checks can run in two modes: embedded within a payment transaction or as a standalone check independent of any payment.

#### Transaction Processing

TxShield can process transactions for every major card platform:

* Visa
* Mastercard
* JCB
* CUP
* Amex
* Diners

PayShield is built to hand every variety of transaction workflow:

* Synchronous
* Asynchronous
* Redirect


# Overview

<figure><img src="/files/NNMwIxsFUEzaqdlsjnU7" alt="" width="375"><figcaption></figcaption></figure>

PayShield is focused on payment dispute resolution & chargeback prevention. The objective of the system is to accelerate dispute resolution and significantly reduce chargebacks by notifying merchants of disputes that have been raised by card programs (Visa / Mastercard), and allowing the merchants to respond to and mitigate the disputes before they become chargebacks. \
\
There are several options available for merchants on how to handle the alert:

1. Implementing tight integration into the merchants payment system, which will empower merchants to respond more efficiently and effectively to alerts raised by card programs (Visa / Mastercard) within the mandated timeframes.
2. Responding to alerts through the PayShield Dashboard and managing them directly from there.
3. Using PayShield's Dispute Intelligence to automatically resolve the alerts with custom rules around the volume, amount, and types of dispute to handle automatically, and the rest to notify the merchant about.
4. Receive the alert notifications via email.


# Notification of a New Alert

The notification of a new alert will notify the merchant that a new alert has been received, and the details for the alert.\
\
The merchant must provide TxShield with the URL that they want the new alert notifications sent to. This must be a https URL.\
The merchant can also, and it's also strongly recommended, that they protect the endpoint with a long lived bearer token that they provide to TxAlert.\
\
If post to the url fails, the system reties every 12hr, 0th minute of the hour (UTC time). \
Post retry stops when\
a) If the time is more than 72hrs from the time we received the alert\
b) if alerts outcome gets updated.&#x20;

## Notification of a new alert

<mark style="color:green;">`POST`</mark> `https://{merchant_supplied_url}`

The data in this call is sent as x-www-form-urlencoded data.

#### Headers

| Name          | Type   | Description  |
| ------------- | ------ | ------------ |
| Authorization | String | Bearer Token |

#### Request Body

| Name                                         | Type     | Description                                                                                                                                                                                                                                                                                                                                     |
| -------------------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| card                                         | string   | Masked or unmasked card number                                                                                                                                                                                                                                                                                                                  |
| transaction\_timestamp                       | DateTime | Authentication date/time for the transaction                                                                                                                                                                                                                                                                                                    |
| descriptor                                   | String   | The merchant descriptor is the description as seen on the card holders’ statement                                                                                                                                                                                                                                                               |
| amount                                       | String   | Transaction amount                                                                                                                                                                                                                                                                                                                              |
| currency                                     | String   | Transaction currency                                                                                                                                                                                                                                                                                                                            |
| arn                                          | String   | Acquirer Reference Number (ARN) is a unique 23-digit number that tags a card transaction when it goes from the merchant bank (acquiring bank) through the card scheme to the cardholders’ bank                                                                                                                                                  |
| alert\_id                                    | String   | Alert ID from TxShield. This ID should be used when sending status updates                                                                                                                                                                                                                                                                      |
| alert\_type                                  | String   | Type of the alert or event - DISPUTE - DISPUTE\_RDR - DISPUTE\_NOTICE - CANCEL - FRAUD\_NOTICE - FRAUD                                                                                                                                                                                                                                          |
| alert\_action                                | String   | Action to be taken on the merchant system - REFUND - CANCEL - REVIEW - MATCHED - RESOLVED - DECLINED The action required by the merchant to take, for this alert. Or in the case of an alert\_type of DISPUTE\_RDR, the action that has already been taken.                                                                                     |
| auth\_code                                   | String   | auth\_code is sent by the alert provider. TxShield will send the same auth\_code to the merchant. In some cases, the auth\_code can be empty.                                                                                                                                                                                                   |
| descriptor\_id                               | String   | descriptor\_id is a code given by the merchant for each descriptor. TxShield will send this descriptor code with every alert sent to the merchant. The idea of this code is to make the merchant system search its transactions faster. This ID is not used in TxShield for any of its processes. This is treated as a merchant reference code. |
| matched\_enrolled\_descriptor                | String   | enrolled descriptor which was matched to the alert descriptor                                                                                                                                                                                                                                                                                   |
| mid                                          | Number   | Mid from TxShield that the alert belongs to.                                                                                                                                                                                                                                                                                                    |
| rid                                          | Number   | Rid from Txshield that the alert belongs to.                                                                                                                                                                                                                                                                                                    |
| sid                                          | Number   | Sid from Txshield that the alert belongs to.                                                                                                                                                                                                                                                                                                    |
| provider                                     | String   | The name of the provider the alert originated from.                                                                                                                                                                                                                                                                                             |
| txdetails                                    | String   | JSON array                                                                                                                                                                                                                                                                                                                                      |
| txdetails\[].alert\_transaction              | String   | <p>JSON Object that represents the original transaction the alert is raised for, with the payment processors details . The 4 fields inside the object are from the payment gateway. If null, no direct match could be found<br><em>\* only available for dispute intelligence matches</em></p>                                                  |
| txdetails\[].transaction\_action             | String   | <p>JSON Object that represents the action performed by dispute intelligence.<br><em>\* only available for dispute intelligence matches</em></p>                                                                                                                                                                                                 |
| txdetails\[].transaction\_potential\_matches | String   | <p>JSON array of all the potential matches that could be found in the payment gateway. If empty, no matches are found<br><em>\* only available for dispute intelligence matches</em></p>                                                                                                                                                        |
| dispute\_condition\_code\_reason             | String   | If we have a text based explanation for the condition\_code we will forward that here. This will not always be filled even if there is a condition\_code                                                                                                                                                                                        |
| condition\_code                              | String   | If the Alert Provider sent a Condition Code for why the alert was raised, we will forward the code in this field.                                                                                                                                                                                                                               |
| site                                         | String   | The TxShield Site name that the alert belongs to.                                                                                                                                                                                                                                                                                               |
| retailer                                     | String   | The TxShield Retailer name that this alert belongs to                                                                                                                                                                                                                                                                                           |
| issuer\_name                                 | String   | The credit card issuers name. Either a string or  empty.                                                                                                                                                                                                                                                                                        |
| provider\_case\_id                           | String   | The alert providers identifier for the alert                                                                                                                                                                                                                                                                                                    |
| alert\_age                                   | String   | The alert age as sent in by the alert provider                                                                                                                                                                                                                                                                                                  |
| alert\_transactionid                         | String   | The transaction id that this alert is for, as sent in by the alert provider.                                                                                                                                                                                                                                                                    |
| dispute\_amount                              | String   | Case amount                                                                                                                                                                                                                                                                                                                                     |
| dispute\_currency                            | String   | Case amount currency                                                                                                                                                                                                                                                                                                                            |
| tier                                         | String   | The billing tier for the alert                                                                                                                                                                                                                                                                                                                  |
| alert\_date                                  | DateTime | Received date/time for the alert                                                                                                                                                                                                                                                                                                                |
| is\_duplicate                                | String   | if alert is a duplicate, the value will be 'yes' and txdetails\[].duplicate\_alertid and txdetails\[].comment will have details                                                                                                                                                                                                                 |
| txdetails\[].duplicate\_alertid              | String   | If alert is a duplicate of another alert, this field will have alertid of the duplicate                                                                                                                                                                                                                                                         |
| txdetails\[].comment                         | String   | <p>If alert is a duplicate of another alert, the comment will have the details<br>In case of DECLINED DISPUTE\_RDR, this field will have the status code of the decline</p>                                                                                                                                                                     |
| bin                                          | String   | if alert is DISPUTE\_RDR, Acquirer BIN info                                                                                                                                                                                                                                                                                                     |
| caid                                         | String   | CAID info                                                                                                                                                                                                                                                                                                                                       |
| rdr\_reason\_code                            | String   | In case of DECLINED DISPUTE\_RDR, this field will have the status code of the decline                                                                                                                                                                                                                                                           |

### Example

**Headers**

```
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: {BEARER_TOKEN_VALUE_TO_BE_GIVEN_BY_THE_MERCHANT}
```

#### Data -full&#x20;

This is an example of the full data sent with a new alert call. The data in this call is sent as x-www-form-urlencoded data.

```
card=411111%2A%2A%2A%2A%2A%2A1111&transaction_timestamp=2024-01-17+00%3A00%3A00&descriptor=Payshield&amount=123.0&currency=USD&alert_id=340739&alert_type=FRAUD&alert_action=REFUND&alert_date=2024-01-17+22%3A54%3A42&arn=65678998765&auth_code=rtv451&descriptor_id=Test&retailer=Test+Retailer&site=Test+Site&condition_code=10.1&dispute_condition_code_reason=EMV+Liability+Shift+Counterfeit+Fraud&issuer_name=National+Bank&provider_case_id=687c4760-9f05-4105-90ad-0d6cca087128&alert_age=009&alert_transactionid=GUI898789876JKYHNJ&tier=T2provider=ethoca
```

#### Data - txdetails: no match found, no refund processed

example of the JSON data that will be contained in the txdetails field. This is not the full data set, just the txdetails field.

```json
[{
        "alert_transaction": null,
        "transaction_action": null,
        "transaction_potential_matches": null
    }
]
```

#### Data - txdetails: match found, no refund processed

example of the JSON data that will be contained in the txdetails field. This is not the full data set, just the txdetails field.

```json
[{
        "alert_transaction": {
            "payment_gateway_reference": "1233778452",
            "payment_gateway_reference2": "order_123456",
            "payment_gateway_tx_type": "sale",
            "payment_gateway_transaction_date": ""
        },
        "transaction_action": null,
        "transaction_potential_matches": null
    }
]
```

#### Data - txdetails: match found, refund processed

example of the JSON data that will be contained in the txdetails field. This is not the full data set, just the txdetails field.

```json
[{
        "alert_transaction": {
            "payment_gateway_reference": "1233778452",
            "payment_gateway_reference2": "order_123456",
            "payment_gateway_tx_type": "sale",
            "payment_gateway_transaction_date": ""
        },
        "transaction_action": {
            "payment_gateway_reference": "1233778453",
            "payment_gateway_reference2": "order_123456",
            "payment_gateway_tx_type": "refund",
            "payment_gateway_transaction_date": ""
        },
        "transaction_potential_matches": null
    }
]json
```

#### Data - txdetails: no exact match found / unable to determine exact match, potential matches found

example of the JSON data that will be contained in the txdetails field. This is not the full data set, just the txdetails field.

```json
[{
        "alert_transaction": null,
        "transaction_action": null,
        "transaction_potential_matches": [{
                "payment_gateway_reference": "1233778452",
                "payment_gateway_reference2": "order_123456",
                "payment_gateway_tx_type": "sale",
                "payment_gateway_transaction_date": ""
            }, {
                "payment_gateway_reference": "1233778454",
                "payment_gateway_reference2": "order_123457",
                "payment_gateway_tx_type": "sale",
                "payment_gateway_transaction_date": ""
            }, {
                "payment_gateway_reference": "1233778455",
                "payment_gateway_reference2": "order_123458",
                "payment_gateway_tx_type": "sale",
                "payment_gateway_transaction_date": ""
            }
        ]
    }
]
```

### Payment Processor Field Mapping

When a new alert is pushed to the merchant, *and the merchant is using dispute intelligence*, TxAlert will map several of the txdetails fields directly to values from the payment processor.\
\
A list of the fields and their mappings can be found in the [Appendix here](/txalerts-dispute-alerts/appendix/dispute-intelligence-payment-processor-field-mappings)


# Notification of an Alert Status Update

The notification of an Alert's status update will push a notification to the merchants system that an alert has had its status updated. The merchant must opt in to receive these notifications\
\
This will happen when the status field of an alert has changed, if any other field is updated and the status remains the same, it will not send a notification.

The merchant must provide TxShield with the URL that they want the status update notifications sent to. This must be a https URL.\
The merchant can also, and it's also strongly recommended, that they protect the endpoint with a long lived bearer token that they provide to TxAlert.

<mark style="color:green;">`POST`</mark> `https://{merchant_supplied_url}`

The data in this call is sent as x-www-form-urlencoded data.

#### Request Body

<table><thead><tr><th width="253">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>action</td><td>Sting</td><td>"statusupdate"</td></tr><tr><td>alert_id</td><td>String</td><td>Alert ID from TxShield.</td></tr><tr><td>status</td><td>String</td><td>Status of the transaction. - RESOLVED - DECLINED - RDR_DELETE. See <a href="/pages/mlmKsJz63WaqHyWRqlPT">status page </a>for details.</td></tr><tr><td>reason_code</td><td>String</td><td>reason code that was updated. In case of RDR_DELETE, the reason_code will be empty Refer table below</td></tr><tr><td>merchant_update_on</td><td>String</td><td>Date when the update was received from merchant(not available for RDR Delete)</td></tr><tr><td>outcome_updated_on</td><td>String</td><td>Date when provider was updated successfully(not available for RDR Delete)</td></tr><tr><td>alert_outcome_amount</td><td>String</td><td>amount refunded.  available if present in the status update </td></tr><tr><td>alert_outcome_currency</td><td>String</td><td>currency of the amount refunded. available if present in the status update</td></tr><tr><td>alert_outcome_action_date</td><td>String</td><td>outcome action date. available if present in the status update</td></tr><tr><td>tx_details[]</td><td>Array</td><td>variable information, available only if present in status update</td></tr><tr><td>merchant_notes</td><td>String</td><td>available only if present in the status update</td></tr><tr><td>comments</td><td>String</td><td>available only if present in the status update</td></tr></tbody></table>

### Example

#### **Headers**

```
Accept: application/json
Content-Type: application/x-www-form-urlencoded
Authorization: {BEARER_TOKEN_VALUE_TO_BE_GIVEN_BY_THE_MERCHANT}
```

#### **Data - full**

The full data set being sent. The data in this call is sent as x-www-form-urlencoded data.

```
action=statusupdate&alert_id=1000&status=wip&reason_code=000.001
```


# Notification of Enrollment Status Update

When a merchant updates their **enrollment status**, the system sends the updated enrollment data to the configured **webhook endpoint** in **JSON format**.

This webhook allows downstream systems to stay in sync with enrollment progress across supported products (e.g., Ethoca, RDR).

### Payload Field Descriptions

#### Top-Level Fields

| Field                       | Type   | Description                                                       |
| --------------------------- | ------ | ----------------------------------------------------------------- |
| `action`                    | string | Event type. Always `enrollment_request_status_update`             |
| `request_id`                | number | Unique enrollment request identifier                              |
| `request_date`              | string | Original enrollment request creation timestamp                    |
| `merchant_name`             | string | Merchant name                                                     |
| `site_name`                 | string | Merchant site name                                                |
| `products`                  | string | Comma-separated list of enrolled products                         |
| `enrollment_request_status` | string | Overall enrollment status (e.g. `ENROLLED`, `PARTIALLY ENROLLED`) |
| `enrollment_request_items`  | object | Product-specific enrollment details                               |
| `updated_at`                | string | Timestamp of the latest update                                    |

***

#### Enrollment Request Items

The `enrollment_request_items` object is grouped by product name (e.g. `ethoca`, `rdr`). Each product contains an array of enrollment entries.

**Common Fields**

| Field           | Type   | Description                            |
| --------------- | ------ | -------------------------------------- |
| `descriptor`    | string | Descriptor submitted for enrollment    |
| `status`        | string | Current enrollment status for the item |
| `last_activity` | string | Last update timestamp for the item     |

**Ethoca-Specific Fields**

| Field        | Type   | Description                                            |
| ------------ | ------ | ------------------------------------------------------ |
| `match_type` | string | Descriptor matching rule (e.g. `Exact`, `Starts with`) |

**RDR-Specific Fields**

| Field         | Type           | Description            |
| ------------- | -------------- | ---------------------- |
| `mcc`         | string \| null | Merchant Category Code |
| `visa_bin`    | string \| null | Visa BIN               |
| `visa_caid`   | string \| null | Visa CAID              |
| `visa_arn`    | string \| null | Visa ARN               |
| `rdr_ruleset` | string \| null | Applied RDR ruleset    |

***

### Webhook Retry Behavior

If a webhook delivery attempt **fails**, the system will:

* Automatically retry posting the webhook
* Continue retrying until the webhook **expires after 72 hours**
* Stop retries once the expiration window is reached

This ensures reliable delivery even during temporary endpoint outages.\ <br>

### Webhook Payload

Below is an example of the JSON payload sent to the webhook endpoint:

```json
{
  "action": "enrollment_request_status_update",
  "request_id": 2451,
  "request_date": "2026-01-15 10:42:11",
  "merchant_name": "Acme Online Retail Ltd",
  "site_name": "Acme Online Store",
  "products": "ethoca,rdr",
  "enrollment_request_status": "PARTIALLY ENROLLED",
  "enrollment_request_items": {
    "ethoca": [
      {
        "descriptor": "ACME*ONLINE",
        "status": "ENROLLED",
        "last_activity": "2026-01-15 11:05:32",
        "match_type": "Starts with"
      },
      {
        "descriptor": "ACME SUBSCRIPTION",
        "status": "WAITING FOR ACTION",
        "last_activity": "2026-01-16 02:18:09",
        "match_type": "Exact"
      }
    ],
    "rdr": [
      {
        "descriptor": "ACME*ONLINE",
        "status": "ENROLLED",
        "last_activity": "2026-01-15 11:05:32",
        "mcc": "5732",
        "visa_bin": "411111",
        "visa_caid": "ACME12345",
        "visa_arn": "745903821649201234",
        "rdr_ruleset": "STANDARD_ECOMMERCE"
      }
    ]
  },
  "updated_at": "2026-01-16 02:18:09"
}
```


# Alert Status Update

Notify TxAlert of actions taken and status updates on the alert by a merchant.

\
Status updates are initiated from the merchant system to inform TxShield about the status of a previous alert raised by TxShield. Updates can be synchronous, returning to the alert notification/webhook, or asynchronous when calling this endpoint.

<mark style="color:green;">`POST`</mark>`      ``/secure/alert/update/v2/`

#### Request Body

| Name                              | Type   | Description                                                                                                                                                                                                                                                                                       |
| --------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| alert\_outcome\_currency          | String | The currency for the alert\_outcome\_amount                                                                                                                                                                                                                                                       |
| alert\_outcome\_amount            | String | The amount that was cancelled / refunded. Can be partial or full amount of the alert.                                                                                                                                                                                                             |
| alert\_outcome\_action\_date      | String | <p>The date & time that the outcome was reached on, e.g. the time and date that the refund was processed. ISO 8601 date format <br>e.g. 2025-02-27T04:33:04.328Z or<br>2020-11-09T05:00:00+02:00</p>                                                                                              |
| reason\_code                      | String | Reason code will explain the reason for each “status” parameter. It should be in the format xxx.yyy where xxx is the [reason code](/txalerts-dispute-alerts/appendix/reason-code) and yyyy is the [result code](/txalerts-dispute-alerts/appendix/result-code). This is a **mandatory parameter** |
| comments                          | String | Reason for not refunding when 900.002 is used as reason code                                                                                                                                                                                                                                      |
| status                            | String | Status of the transaction. - RESOLVED - DECLINED - WIP - OTHER. See [status page](/txalerts-dispute-alerts/appendix/status) for details. This is a **mandatory parameter**                                                                                                                        |
| alert\_id                         | String | Alert ID from the original alert sent by TxShield. This is a **mandatory parameter** to map the status update of the initial alert                                                                                                                                                                |
| tx\_details\[].duplicate\_alertid | String | alertid of the duplicate alert This is a **mandatory parameter** when using reason\_code 940                                                                                                                                                                                                      |
| tx\_details\[].userid             | String | Merchant can pass the userid of the user who did the action in this field                                                                                                                                                                                                                         |
| tx\_details\[].username           | String | Merchant can pass the user name of the user who did the action in this field                                                                                                                                                                                                                      |
| txdetails\[]                      | String | Merchant can use json structure to send the details of the user or the duplicates in this field                                                                                                                                                                                                   |
| merchant\_notes                   | String | Merchant can use this field for their reference. This will be stored in the alert record                                                                                                                                                                                                          |

### Example

**JSON : Header**

```
"rcode: xxxxxxxxxxx ",
"Content-Type: application/json"
```

**JSON : Format**

```
Postdata
{
"alert_id": 10001,
"status": "resolved",
"reason_code": "100.001",
"tx_details": {"duplicate_alertid":"12323" },
"alert_outcome_action_date": "2020-11-09T05:00:00+02:00",
"alert_outcome_amount": "10",
"alert_outcome_currency": "USD"
}
```


# Test Alert Endpoint

The test alert endpoint allows you to create alerts with different values in the system. This will then trigger the full alert workflow for those alerts. If configured, you should receive new webhook calls, alerts in the front end, or emails notification.\
\
Please note, this will only be available to you once you have completed on boarding. <br>

<mark style="color:green;">`POST`</mark>  `/secure/alerts/txshield_dummy`

#### Request Body

| Name                     | Type     | Description                                                                                                                      |
| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| auth\_code               | String   | auth\_code of the transaction if known                                                                                           |
| arn                      | String   | arn of the transaction if known                                                                                                  |
| alert\_type              | String   | Type of alert eg,Dispute                                                                                                         |
| currency                 | String   | ISO 4217 3 character Currency Code. e.g. "USD"                                                                                   |
| amount                   | String   | Value of the transaction as a string, including decimals. e.g. "10.00"                                                           |
| descriptor               | String   | descriptor the transaction was processed under. This will be supplied.                                                           |
| transaction\_timestamp   | Datetime | ISO 8601 timestamp of the transaction. You can find the time stamp on <https://www.utctime.net/> as UTC. See example for format. |
| card                     | String   | Card number used in the transaction. Should be masked. e.g. "411111\*\*\*\*\*\*1111"                                             |
| issuername               | String   | Issuer name                                                                                                                      |
| dispute\_condition\_code | Number   |                                                                                                                                  |

### Example

**JSON**

<pre><code><strong>{
</strong>"card" : "411111******1111",
"transaction_timestamp" :  "2021-10-11T00:00:23.000Z",
"descriptor" : "shoes",
"amount" : "10.00",
"currency" : "USD",
"alert_type" : "Dispute",
"arn" : "",
"auth_code" : ""
}
</code></pre>


# Create Descriptor Enrollment

API to create descriptor enrollment request

## POST /txalerts/descriptor\_enrollment/create

>

```json
{"openapi":"3.0.1","info":{"title":"TxShield api V3.0","version":"3.0"},"tags":[{"name":"Alerts","description":"Call related to alerts in txshield core."}],"servers":[{"url":"<?=PROTOCOL?>://<?=SITE_DOMAIN?>/api/v3"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"Error":{"type":"object","properties":{"msg":{"type":"string"},"details":{"type":"string"}}}}},"paths":{"/txalerts/descriptor_enrollment/create":{"post":{"tags":["Alerts"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"sid":{"type":"integer","description":"Site ID"},"email_cc_list":{"type":"string","description":"List of email as receiver for descriptor enrollment. Multiple email should be seperate by (,)"},"enrollment_items":{"type":"array","items":{"type":"object","properties":{"provider":{"type":"array","description":"Allowed provider values are the following Ethoca, CDRN and RDR","items":{"type":"string"}},"descriptor":{"type":"string","description":"Descriptor name"},"match_type":{"type":"string","description":"match_type is only required if provider is Ethoca or CDRN. Only allowed values are Starts with and Exact"},"mcc":{"type":"string","description":"Descriptor MCC. this field is optional"},"visa_bin":{"type":"string","description":"Descriptor Visa Bin. Visa BIN and CAID are only required as a pair if Visa ARN is null and provider is RDR"},"visa_caid":{"type":"string","description":"Descriptor Visa Caid. Visa BIN and CAID are only required as a pair if Visa ARN is null and provider is RDR"},"visa_arn":{"type":"string","description":"Descriptor Visa ARN. this field is only required if Visa CAID or Visa BIN are null and provider is RDR"},"rdr_ruleset":{"type":"string","description":"Descriptor RDR ruleset. this field is optional"}}}}}}}}},"responses":{"200":{"description":"Successfully returned enrollment request id","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"msg":{"type":"string"},"enrollment_request_id":{"type":"integer"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


# Descriptor Enrollment Status

API to get  descriptor enrollment request status with enrollment request id

## POST /txalerts/enrollment/status/{id}

>

```json
{"openapi":"3.0.1","info":{"title":"TxShield api V3.0","version":"3.0"},"tags":[{"name":"Alerts","description":"Call related to alerts in txshield core."}],"servers":[{"url":"<?=PROTOCOL?>://<?=SITE_DOMAIN?>/api/v3"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"EnrollmentStatus":{"type":"object","properties":{"enrollment_request_id":{"type":"integer"},"request_date":{"type":"string","format":"date-time"},"merchant_name":{"type":"string"},"site_name":{"type":"string"},"products":{"type":"string"},"enrollment_request_status":{"type":"string"},"enrollment_request_items":{"$ref":"#/components/schemas/EnrollmentRequestItems"}}},"EnrollmentRequestItems":{"type":"object","properties":{"cdrn":{"type":"array","items":{"$ref":"#/components/schemas/CDRN_Ethoca_Item"}},"rdr":{"type":"array","items":{"$ref":"#/components/schemas/RDRItem"}}}},"CDRN_Ethoca_Item":{"type":"object","properties":{"descriptor":{"type":"string"},"status":{"type":"string"},"last_activity":{"type":"string","format":"date-time"},"match_type":{"type":"string"}}},"RDRItem":{"type":"object","properties":{"descriptor":{"type":"string"},"status":{"type":"string"},"last_activity":{"type":"string","nullable":true},"mcc":{"type":"string","nullable":true},"visa_bin":{"type":"string","nullable":true},"visa_caid":{"type":"string","nullable":true},"visa_arn":{"type":"string"},"rdr_ruleset":{"type":"string"}}},"Error":{"type":"object","properties":{"msg":{"type":"string"},"details":{"type":"string"}}}}},"paths":{"/txalerts/enrollment/status/{id}":{"post":{"tags":["Alerts"],"parameters":[{"name":"id","in":"path","description":"Enrollment id for get enrollment details","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Successfully returned enrollment details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrollmentStatus"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


# Descriptor Enrollment List

This endpoint will return the descriptor that are requested for enrollment and their status

## POST /txalerts/descriptor\_enrollments

>

```json
{"openapi":"3.0.1","info":{"title":"TxShield api V3.0","version":"3.0"},"tags":[{"name":"Alerts","description":"Call related to alerts in txshield core."}],"servers":[{"url":"<?=PROTOCOL?>://<?=SITE_DOMAIN?>/api/v3"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"AlertDescriptorEnrollmentsList":{"type":"object","properties":{"list":{"type":"array","items":{"$ref":"#/components/schemas/AlertDescriptorEnrollmentsListItem"}},"totalResult":{"type":"integer"}}},"AlertDescriptorEnrollmentsListItem":{"type":"object","properties":{"enrollment_request_id":{"type":"integer"},"merchant_name":{"type":"string"},"site_name":{"type":"string"},"products":{"type":"string"},"status":{"type":"string"},"request_date":{"type":"string"},"last_activity":{"type":"string"},"completed_at":{"type":"string"},"enrollment_items":{"type":"array","items":{"type":"object","properties":{"descriptor":{"type":"string"},"provider":{"type":"string"},"status":{"type":"string"},"last_activity":{"type":"string"},"match_type":{"type":"string","description":"match_type only exist if provider has Ethoca or CDRN"},"mcc":{"type":"string","description":"mcc only exist if provider has RDR"},"visa_bin":{"type":"string","description":"visa_bin only exist if provider has RDR"},"visa_caid":{"type":"string","description":"visa_caid only exist if provider has RDR"},"visa_arn":{"type":"string","description":"visa_arn only exist if provider has RDR"},"rdr_ruleset":{"type":"string","description":"rdr_ruleset only exist if provider has RDR"}}}}}},"Error":{"type":"object","properties":{"msg":{"type":"string"},"details":{"type":"string"}}}}},"paths":{"/txalerts/descriptor_enrollments":{"post":{"tags":["Alerts"],"requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"type":"object","properties":{"status":{"type":"array","description":"Descriptor enrollment status. Values can be any of the following PENDING, FAILED, ENROLLED, UNENROLLED, WAITING FOR ACTION and WAITING FOR PROVIDER","items":{"type":"string"}},"sid":{"type":"array","description":"Site IDs. This field is optional.","items":{"type":"string"}},"rid":{"type":"array","description":"Retailers IDs. This field is optional.","items":{"type":"string"}},"mid":{"type":"array","description":"Merchants IDs. This field is optional","items":{"type":"string"}},"date_to":{"type":"string","description":"this filter will be applied to request_date. This field is optional"},"date_from":{"type":"string","description":"this filter will be applied to request_date. This field is optional"},"size":{"type":"string","description":"Prefered number of result per request. This field is optional"},"offset":{"type":"string","description":"Prefered number of offset per request. This field is optional"},"order":{"type":"string","description":"default value is DESC. This field is optional"},"sort_field":{"type":"string","description":"Determine what field will to apply the order by. This field is optional"}}}},"application/json":{"schema":{"type":"object","properties":{"status":{"type":"array","description":"Descriptor enrollment status. Values can be any of the following PENDING, FAILED, ENROLLED, UNENROLLED, WAITING FOR ACTION and WAITING FOR PROVIDER","items":{"type":"string"}},"sid":{"type":"array","description":"Site IDs. This field is optional.","items":{"type":"string"}},"rid":{"type":"array","description":"Retailers IDs. This field is optional.","items":{"type":"string"}},"mid":{"type":"array","description":"Merchants IDs. This field is optional","items":{"type":"string"}},"date_to":{"type":"string","description":"this filter will be applied to request_date. This field is optional"},"date_from":{"type":"string","description":"this filter will be applied to request_date. This field is optional"},"size":{"type":"string","description":"Prefered number of result per request. This field is required"},"offset":{"type":"string","description":"Prefered number of offset per request. This field is required"},"order":{"type":"string","description":"default value is DESC. This field is optional"},"sort_field":{"type":"string","description":"Determine what field will to apply the order by. This field is optional"}}}}}},"responses":{"200":{"description":"Successfully returned enrollment request id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AlertDescriptorEnrollmentsList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


# Inform Alerts

This endpoint will return the inform alerts

## POST /txalerts/informalerts

> Returns inform alerts only (FRAUD\_NOTICE, DISPUTE\_NOTICE).<br>

```json
{"openapi":"3.0.1","info":{"title":"TxShield api V3.0","version":"3.0"},"tags":[{"name":"Alerts","description":"Call related to alerts in txshield core."}],"servers":[{"url":"<?=PROTOCOL?>://<?=SITE_DOMAIN?>/api/v3"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"InformAlertRequest":{"type":"object","properties":{"field":{"type":"string","description":"one of the value from [alert_id, descriptor, card_number, transaction_amount, alert_type]"},"keyword":{"type":"string","description":"value of the field"},"mid":{"type":"array","items":{"type":"integer"}},"rid":{"type":"array","items":{"type":"integer"}},"sid":{"type":"array","items":{"type":"integer"}},"reseller":{"type":"array","items":{"type":"integer"}},"date_from":{"type":"string","description":"format YYYY-MM-DD"},"date_to":{"type":"string","description":"format YYYY-MM-DD"},"order":{"type":"string","description":"one of the value from [ASC, DESC]"},"size":{"type":"integer"},"page":{"type":"integer"}}},"InformAlertList":{"type":"object","properties":{"list":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"alertdate":{"type":"string","description":"Timestamp when alert was received in system"},"descriptor":{"type":"string"},"transaction_date":{"type":"string"},"transaction_currency":{"type":"string"},"transaction_amount":{"type":"string"},"cardnumber":{"type":"string"},"providername":{"type":"string"},"provider_caseid":{"type":"string"},"arn":{"type":"string"},"authcode":{"type":"string"},"alert_type":{"type":"string"},"partnerid":{"type":"string"},"retailername":{"type":"string"},"sitename":{"type":"string"},"issuername":{"type":"string"},"source":{"type":"string"},"chargeback_proceeded":{"type":"string"},"is_duplicate":{"type":"string"},"duplicate_alertid":{"type":"integer","nullable":true},"matched_descriptor":{"type":"string"},"merchantname":{"type":"string"}}}},"totalResult":{"type":"integer"}}},"Error":{"type":"object","properties":{"msg":{"type":"string"},"details":{"type":"string"}}}}},"paths":{"/txalerts/informalerts":{"post":{"tags":["Alerts"],"description":"Returns inform alerts only (FRAUD_NOTICE, DISPUTE_NOTICE).\n","requestBody":{"required":true,"content":{"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/InformAlertRequest"}},"application/json":{"schema":{"$ref":"#/components/schemas/InformAlertRequest"}}}},"responses":{"200":{"description":"Successfully returned inform alert list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InformAlertList"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```


# Merchant Enrollment

`POST /api/v3/merchant/retailer-site-enrollment`

Creates a new retailer and retailer site under an existing merchant, provisions shield settings for the new site, and notifies operations by email.

***

### &#x20;Authorization

<table><thead><tr><th width="180">Requirement</th><th>Detail</th></tr></thead><tbody><tr><td>Authorization</td><td>Bearer authentication header of the form Bearer &#x3C;token></td></tr></tbody></table>

***

### Request

Content-Type: `application/json`

<table><thead><tr><th width="159">Field</th><th width="162">Required</th><th width="139">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>mid</code></td><td><strong>Yes</strong></td><td>int</td><td>Merchant ID. Provided by payshield</td></tr><tr><td><code>retailer_name</code></td><td><strong>Yes</strong></td><td>string</td><td>New retailer name</td></tr><tr><td><code>site_name</code></td><td><strong>Yes</strong></td><td>string</td><td>New retailer site name. </td></tr><tr><td><code>contact_email</code></td><td>No</td><td>string</td><td>Retailer contact email. </td></tr><tr><td><code>country</code></td><td>No</td><td>string</td><td>Two-letter country code (e.g. <code>US</code>). </td></tr><tr><td><code>site_url</code></td><td>No</td><td>string</td><td>Site URL</td></tr><tr><td><code>mcc</code></td><td>No</td><td>string</td><td>Merchant Category Code</td></tr><tr><td><code>remarks</code></td><td>No</td><td>string</td><td>Remarks</td></tr><tr><td><code>alert_notification_url</code></td><td>No</td><td>string</td><td>Url to receive webhook for new alert</td></tr><tr><td><code>token</code></td><td>No</td><td>string</td><td>Bearer token to be used in webhook</td></tr><tr><td><code>alert_status_update_url</code></td><td>No</td><td>string</td><td>Url to receive webhook for alert status update</td></tr><tr><td><code>email_for_alert_notification</code></td><td>No</td><td>string</td><td>Email to receive alert notification. Comma separated if there are more than one.</td></tr></tbody></table>

#### Example

```json
{
  "mid": 10234,
  "retailer_name": "Acme West Retail",
  "site_name": "Acme West Online",
  "contact_email": "ops@acmewest.com",
  "country": "US",
  "site_url": "https://shop.acmewest.com",
  "mcc": "5411",
  "alert_notification_url": "https://acmewest.com/webhooks/alerts",
  "token": "s3cr3t-token",
  "email_for_alert_notification": "alerts@acmewest.com"
}
```

### Response

#### Success — `200`

```json
{
  "status": "ok",
  "rid": 5821,
  "sid": 9043,
  "msg": "Retailer and Site Created"
}
```

#### Error — `401`

```json
{
  "status": "EXC",
  "code": 401,
  "error_msg": {
    "msg": "retailer_name already exists."
  }
}
```

***


# Status

Status of the alert

The status represents the current status of the alert.

<table data-header-hidden><thead><tr><th width="204.68358370778884"></th><th></th></tr></thead><tbody><tr><td><strong>Status</strong></td><td>Explanation</td></tr><tr><td>RESOLVED</td><td>The alert may have been resolved under many different conditions. the exact detail of the resolved alert can be sent via the <a href="/pages/TDS5B4ufGvvehX8dpfFi">reason_code </a>parameter</td></tr><tr><td>DECLINED</td><td>The alert may have been declined for many reasons. Details of the reason can be sent via the <a href="/pages/TDS5B4ufGvvehX8dpfFi">reason_code </a>parameter</td></tr><tr><td>WIP</td><td>The merchant system may respond to an alert as WIP (Work-In-Progress). This will inform TxShield that the merchant system will need more time to respond. The <a href="/pages/TDS5B4ufGvvehX8dpfFi">reason_code </a>parameter can hold the details.</td></tr><tr><td>RDR_DELETE</td><td>When an RDR Delete is received for an RDR alert</td></tr></tbody></table>


# Reason Code

For provider specific reason listing please check the links below.

\
[Ethoca Alert Reason Code](/txalerts-dispute-alerts/appendix/ethoca-alert-reason-code-new-mapping-from-jun18th-2024)

[Verifi Alert Reason Code](/txalerts-dispute-alerts/appendix/verifi-alert-reason-code-new-mapping-from-jun18th-2024)<br>


# Result Code

| Result Code | Description   |
| ----------- | ------------- |
| 001         | refunded      |
| 002         | not\_refunded |
| 003         | not\_settled  |


# Dispute Intelligence Payment Processor field mappings

Mappings from TxAlert names to the Payment Processors Field name.

## **NMI**

Mappings for the tx\_details values for transactions processed through NMI.

| TxShield                            | NMI             |
| ----------------------------------- | --------------- |
| payment\_gateway\_reference         | transaction\_id |
| payment\_gateway\_reference2        | order\_id       |
| payment\_gateway\_tx\_type          | action\_type    |
| payment\_gateway\_transaction\_date | date            |


# Ethoca Alert Reason Code- New Mapping (from Jun18th, 2024)

{% hint style="info" %}
This table scrolls horizontally. Make sure to check all columns.
{% endhint %}

The first two columns show the reason code, with a description. \
The last three columns show the valid reason code & result code combinations in their xxx.yyy format.

{% tabs %}
{% tab title="Confimed Fraud " %}

<table data-full-width="true"><thead><tr><th width="96">Reason Code</th><th width="141">Description</th><th>Outcome</th><th>Refunded</th><th width="135">Not Refunded</th><th>Not Settled</th></tr></thead><tbody><tr><td>100</td><td>Alert allowed you to stop the fraud</td><td>Resolved</td><td>100.001</td><td>invalid</td><td>100.003</td></tr><tr><td>101</td><td>Resolved with partial refund</td><td>Resolved</td><td>101.001<mark style="color:red;">*</mark></td><td>101.002</td><td>101.003</td></tr><tr><td>102</td><td>Transaction failed authorization</td><td>Resolved</td><td>invalid</td><td>invalid</td><td>102.003</td></tr><tr><td>103</td><td>Account suspended from placing future orders</td><td>Resolved</td><td>103.001</td><td>103.002</td><td>103.003</td></tr><tr><td>900</td><td>Not refunded for other reasons</td><td>Declined</td><td>invalid</td><td>900.002</td><td>invalid</td></tr><tr><td>901</td><td>Descriptor does not belong to Merchant</td><td>Declined</td><td>invalid</td><td>901.002</td><td>invalid</td></tr><tr><td>902</td><td>Transaction could not be found</td><td>Declined</td><td>invalid</td><td>902.002</td><td>invalid</td></tr><tr><td>940</td><td>Duplicate Alert</td><td>Declined</td><td>940.001</td><td>940.002</td><td>940.003</td></tr><tr><td>950</td><td>Unable to process refund</td><td>Declined</td><td>invalid</td><td>950.002</td><td>invalid</td></tr><tr><td>951</td><td>Transaction refunded or cancelled before the alert</td><td>Resolved</td><td>951.001</td><td>invalid</td><td>951.003</td></tr><tr><td>952</td><td>Transaction previously received a chargeback</td><td>Declined</td><td>952.001</td><td>952.002</td><td>invalid</td></tr><tr><td>953</td><td>Transaction older than 120 days</td><td>Declined</td><td>953.001</td><td>953.002</td><td>invalid</td></tr><tr><td>954</td><td>Transaction 3D secure authenticated successfully</td><td>Declined</td><td>954.001</td><td>954.002</td><td>invalid</td></tr><tr><td>956</td><td>Unable to stop order fulfillment</td><td>Declined</td><td>956.001</td><td>956.002</td><td>956.003</td></tr><tr><td>998</td><td>Shipper has been contacted/intercept in progress</td><td>Resolved</td><td>998.001</td><td>998.002</td><td>998.003</td></tr><tr><td>999</td><td>Work in progress</td><td>WIP</td><td>invalid</td><td>999.002</td><td>invalid</td></tr></tbody></table>
{% endtab %}

{% tab title="Customer Dispute" %}

<table data-full-width="true"><thead><tr><th width="119">Reason Code</th><th>Description</th><th>Outcome</th><th>Refunded</th><th>Not Refunded</th><th>Not Settled</th></tr></thead><tbody><tr><td>100</td><td>Case resolved with customer</td><td>Resolved</td><td>100.001</td><td>100.002</td><td>100.003</td></tr><tr><td>101</td><td>Resolved with partial refund</td><td>Resolved</td><td>101.001<mark style="color:red;">*</mark></td><td>invalid</td><td>invalid</td></tr><tr><td>102</td><td>Transaction failed authorization</td><td>Resolved</td><td>invalid</td><td>invalid</td><td>102.003</td></tr><tr><td>900</td><td>Not refunded for other reasons</td><td>Declined</td><td>invalid</td><td>900.002</td><td>invalid</td></tr><tr><td>901</td><td>Descriptor does not belong to Merchant</td><td>Declined</td><td>invalid</td><td>901.002</td><td>invalid</td></tr><tr><td>902</td><td>Transaction could not be found</td><td>Declined</td><td>invalid</td><td>902.002</td><td>invalid</td></tr><tr><td>940</td><td>Duplicate Alert</td><td>Declined</td><td>940.001</td><td>940.002</td><td>940.003</td></tr><tr><td>950</td><td>Unable to process refund</td><td>Declined</td><td>invalid</td><td>950.002</td><td>invalid</td></tr><tr><td>951</td><td>Transaction refunded or cancelled before the alert</td><td>Resolved</td><td>951.001</td><td>invalid</td><td>951.003</td></tr><tr><td>952</td><td>Transaction previously received a chargeback</td><td>Declined</td><td>952.001</td><td>952.002</td><td>invalid</td></tr><tr><td>953</td><td>Transaction older than 120 days</td><td>Declined</td><td>953.001</td><td>953.002</td><td>invalid</td></tr><tr><td>954</td><td>Transaction 3D secure authenticated successfully</td><td>Declined</td><td>954.001</td><td>954.002</td><td>invalid</td></tr><tr><td>957</td><td>Disagree with the reason, chargeback will be disputed</td><td>Declined</td><td>invalid</td><td>957.002</td><td>invalid</td></tr><tr><td>999</td><td>Work in progress</td><td>WIP</td><td>invalid</td><td>999.002</td><td>invalid</td></tr></tbody></table>
{% endtab %}
{% endtabs %}

#### <mark style="color:red;">\* mandatory -</mark> *alert\_outcome\_amount (=partial refund amount)*


# Verifi Alert Reason Code - New Mapping(from Jun18th, 2024)

{% hint style="info" %}
This table scrolls horizontally. Make sure to check all columns.<br>
{% endhint %}

The first two columns show the reason code, with a description. \
The last three columns show the valid reason code & result code combinations in their xxx.yyy format.

<table data-full-width="false"><thead><tr><th width="146">Reason Code</th><th width="156">Description</th><th>Outcome</th><th>Refund</th><th>Not Refunded</th><th>Not Settled</th></tr></thead><tbody><tr><td>100</td><td>Resolved with successful refund</td><td>Resolved</td><td>100.001</td><td>invalid</td><td>invalid</td></tr><tr><td>101</td><td>Resolved with partial credit</td><td>Resolved</td><td>101.001<mark style="color:red;">*</mark></td><td>invalid</td><td>invalid</td></tr><tr><td>102</td><td>Authorization failed transaction</td><td>Resolved</td><td>invalid</td><td>invalid</td><td>102.003</td></tr><tr><td>900</td><td>Not refunded for Other Reasons</td><td>Declined</td><td>invalid</td><td>900.002</td><td>invalid</td></tr><tr><td>901</td><td>Descriptor does not belong to Merchant</td><td>Declined</td><td>invalid</td><td>901.002</td><td>invalid</td></tr><tr><td>902</td><td>Transaction could not be found</td><td>Declined</td><td>invalid</td><td>902.002</td><td>invalid</td></tr><tr><td>940</td><td>Duplicate Alert</td><td>Declined</td><td>940.001</td><td>940.002</td><td>940.003</td></tr><tr><td>950</td><td>Unable to process refund</td><td>Declined</td><td>invalid</td><td>950.002</td><td>invalid</td></tr><tr><td>951</td><td>Transaction refunded or cancelled before the alert</td><td>Resolved</td><td>951.001</td><td>invalid</td><td>951.003</td></tr><tr><td>952</td><td>Transaction previously received a chargeback</td><td>Declined</td><td>952.001</td><td>952.002</td><td>invalid</td></tr><tr><td>953</td><td>Transaction older than 120 days</td><td>Declined</td><td>953.001</td><td>953.002</td><td>invalid</td></tr><tr><td>954</td><td>Transaction 3D secure authenticated successfully</td><td>Declined</td><td>954.001</td><td>954.002</td><td>invalid</td></tr><tr><td>956</td><td>Unable to stop order fulfillment</td><td>Declined</td><td>956.001</td><td>956.002</td><td>invalid</td></tr><tr><td>957</td><td>Disagree with dispute reason. Proceed with chargeback</td><td>Declined</td><td>invalid</td><td>957.002</td><td>invalid</td></tr><tr><td>999</td><td>Work in progress</td><td>WIP</td><td>invalid</td><td>999.002</td><td>invalid</td></tr></tbody></table>

#### <mark style="color:red;">\* mandatory -</mark> *alert\_outcome\_amount (=partial refund amount)*


# Overview

<figure><img src="/files/bHxb6wlTP4TNzfNpm4zc" alt="" width="375"><figcaption></figcaption></figure>

Integrate with PayShield for 3D Secure 2 (3DS2) authentication using PayShield's JavaScript-based 3DS SDK. The subsequent pages provide an overview of the [3DS DOM elements](/3dsecure2+/3ds-dom-elements) and describe how to connect to the [3DS SDK](/3dsecure2+/3ds-sdk-options) and the various options available.

We also have a demo payment page that shows how simple it is to integrate. Instructions for the demo payment page are in the [3DS Demo Payment Page](/3dsecure2+/3ds-demo-payment-page) section.


# Implementation Guidelines

### **Before you begin**

Before you begin, you will need to have the following settings which will be provided to you by PayShield during the onboarding process:

* txshield\_3ds\_url
* txshield\_3ds\_mid
* txshield\_3ds\_rcode

There are 7 steps to complete the 3DS SDK integration, the majority of which require updates to your current payment page/checkout page only.

1. [Add the 3DS SDK](#1.-add-the-3ds-sdk)
2. [Add data-threeds attributes](#2.-add-data-threeds-attributes-to-form-elements.)
3. [Initialise the 3DS SDK](#3.-initialise-the-3ds-sdk)
4. [Call the do3D() method](#4.-call-the-do3d-method.)
5. [Handle 3DS result](#5.-handle-3ds-result)
6. [Check the added input fields](#6.-added-input-fields)
7. [Submit for payment processing](#7.-submit-for-payment)

{% hint style="info" %}
*If your authorisation (payment) processing is done through a provider other than TxShield, you are only required to complete steps 1-5.*&#x20;
{% endhint %}

### 1. Add the 3DS SDK

Add the 3DS Javascript Library to the payment page `<script src="{txshield_3ds_url}/sdk/3d2integrator.v3.dist.js"></script>`&#x20;

*{txshield\_3ds\_url}* is the TxShield server URL that you are integrating with (Provided by PayShield at time of onboarding).

```
<html>
    <body>
        <div class="your-page-content">
        <form id="billing-form" action="" method="post">
        </form>
        </div> <!-- End of page -->
        <script src="{txshield_3ds_url}/sdk/3d2integrator.v3.dist.js"></script>
        <script>
            let options = {
                showChallenge: true,
                showChallengePopup: true
            }
            let threeD2 = new ThreeDS2( "<insert-form-id-here>", "<txshield_3ds_mid>", "<amounttotal>","<hash>","<txshield_3ds_url>","<merchantreference>","this", "<options>");
            document.getElementById('billing-form').addEventListener('submit', function (e) {
                threeD2.do3D(fnresponse);
            })
        </script>
    </body>
</html>
```

### 2. Add "data-threeds" attributes

Add the `data-threeds` attribute to all elements in the form that contain information relevant to 3DS authentication. The 3DS SDK will search for all elements marked with a `data-threeds` attribute. The value for the attribute tells the script what data this field contains.&#x20;

{% hint style="warning" %}
'pan', 'month' and 'year' elements are mandatory.
{% endhint %}

```
<input name='creditCardNumber' id='creditCardNumber' data-threeds='pan'>
<input name='cardMonth' id='cardMonth' data-threeds='month'>
<input name='cardYear' id='cardYear' data-threeds='year'>
```

### 3. Initialise the 3DS SDK

Initialise/instantiate the 3DS SDK. This should be done on page load, as there are several network calls that are performed. If done on page load, these network calls can run in the background while the customer is completing the payment form.

```
let my3ds2 = new ThreeDS2('{formId}',
    '{txshield_3ds_mid}',
    '{amounttotal}',
    '{hash}',
    '{txshield_3ds_url}',
    '{merchantreference}',
    '{global window scope}',
    '{options}'
)
```

* **formid**: The id attribute of your tag on your checkout page. This form should be your billing form that contains the data-threeds attributes detailed later. e.g. if the formid is 'billing-form' the form must have an id tag.
* **txshield\_3ds\_mid**: Provided to you at time of onboarding.
* **amounttotal**: Total amount to charge the customer in decimals. e.g. 10.00 12.34
* **hash**: sha256 of txshield\_3ds\_mid, amount using rcode as the key e.g. in php\
  &#x20;hash\_hmac('sha256', $hashString, $shield3dsRcode);
* **txshield\_3ds\_url**: The TxShield 3ds server url that you are integrating into. This will be provided to you at the time of onboarding.
* **merchantreference**: Merchants reference for this transaction. The reference here should be the same one for the payment transaction.&#x20;
* **global window scope**: The scope for the window in which the billing form is in. For most integrations, it will simply be **this**.
* **options**: Options should be a JavaScript object that contains the different options available to configure the SDK. A full list of options is available in the [3DS SDK Options](/3dsecure2+/3ds-sdk-options) section.

```
let options = {
    showChallenge: true,
    showChallengePopup: true,
    rebilling: true,
    rebillingData: {
        rebillingExpiry: "20231231",
        rebillingFrequency : 28
    }
}
```

### 4. Call the do3D() method

When the customer has finished entering their card details and filled all other `data-threeds` tagged fields with data, you should start the 3DS workflow by calling the `do3D()` method. This would commonly be done when the customer has submitted the payment form.

You should call the do3D() method after doing your initial data validation (making sure all fields are filled and are in the correct format etc). This should avoid extra 3DS transactions and costs by sending empty fields.

The `do3d()` function accepts one parameter, a callback function. The callback function is called when the authentication has been completed. There is one parameter sent to the callback function, it is a JavaScript object containing the result of the authentication.

The callback function is discussed more in [step 5.](#5.-handle-3ds-result)

```
my3ds2.do3D(function (data)) {
    //my callback
});
```

### 5. Handle 3DS result

In [step 4](#4.-call-the-do3d-method.), a callback function was provided to do3D(). When authentication is complete, the callback function is called.

Authentication is considered complete when the customer has ended their interaction with the 3DS servers. Refer to the [3DS Response](/3dsecure2+/3ds-response) section to learn more about the returned response and what it means.

Once the callback has been called, you can now submit your payment form for payment processing.

If you are doing your payment processing through TxShield, there is nothing further for you to do with this data, other than to decide if you want to continue based on the transStatus.

If your payment processing is done through another provider, you can use this callback to format the data for your provider.

### 6. Added input fields

If the above steps are done correctly, the form will contain up to two new input fields - threeDSecure and addinfo. *If payment processing is through TxShield, these fields must exist and must be included in the final form submission.* **Do not remove them.**

```
<input class="threeDSecure" type="hidden" name="threeDSecure" value="">
<input class="addinfo" type="hidden" name="addinfo" value="" data-threeds="id">
```

### 7. Submit for payment processing

Now that you have formatted the data for your payment provider, you can submit the payment for processing.


# 3DS SDK Options

3DS SDK Options

The below table provides a list of all possible options which are sent in when the 3DS SDK is initialised as documented in [**Step 3**](https://docs.payshield.ai/3dsecure2+/pages/GdUjgLso4DLAKsAq5r3i#3.-initialise-the-3ds-sdk) of the implementation guide.

<table><thead><tr><th>Option</th><th width="270">Description</th><th width="150">Format</th><th>Default</th><th>Required</th><th>Version</th></tr></thead><tbody><tr><td><code>showChallenge</code></td><td><p>If the 3DS authentication requires a challenge, this provides the option to show the challenge or not. </p><p>If set to false, and a challenge is requested, the authentication will result in a status of N or C. </p><p>The default value is set at signup time. </p><p>This can be sent in to override the default.</p></td><td>boolean</td><td>true</td><td><strong>v2:</strong> Y<br><strong>v3:</strong> N</td><td>2 , 3</td></tr><tr><td>showChallen<code>gePopup</code></td><td>Option to display the challenge at the bottom of the form, or in a popup window.</td><td>boolean</td><td>true</td><td>N</td><td>2</td></tr><tr><td><code>rebilling</code></td><td>If this is a recurring billing authentication. If set to true the rebillingData object must be set.</td><td>boolean</td><td>false</td><td>N</td><td>2</td></tr><tr><td><code>rebillingData</code></td><td>Contains the rebilling options.</td><td>object</td><td>-</td><td>only if rebilling is set to true</td><td>2</td></tr><tr><td><code>rebillingData. rebillingExpiry</code></td><td>The date that the recurring billing will expire. e.g. for a 12 month magazine subscriotion, it should be set to the last month that a transaction will occur.</td><td>string formatted Date. YYYYMMDD</td><td>-</td><td>only if rebilling is set to true</td><td>2</td></tr><tr><td><code>rebillingData. rebillingFrequency</code></td><td>The least number of days between a rebilling cycle. If the rebilling is monthly this should be 28 (for February). If a weekly rebill, 7 days.</td><td>integer</td><td>-</td><td>only if rebilling is set to true</td><td>2</td></tr><tr><td><code>rebillingData.amount</code></td><td>The amount for the rebilling transaction. The rebilling amount must be in the same currency as the amounttotal and for the same currency.</td><td>decimal</td><td>-</td><td>only if rebilling is set to true</td><td>2</td></tr><tr><td><code>addrMatch</code></td><td>Set to true, the shipping address matches the billing address, and does not need to be set.</td><td>boolean</td><td>false</td><td>N</td><td>3</td></tr><tr><td><code>autoStart</code></td><td>If set to true, the SDK will attempt to authorization as soon as the user finishes entering data into all the required fields (e.g. card number, CVV, Expiry).<br><br>This setting can cause many false transactions to be charged to your account, as a user may go back and edit their data, and every time they edit the data, a new transaction will start. <br><br>It is <strong>not recommended</strong> to use this feature.</td><td>boolean</td><td>false</td><td>N</td><td>2</td></tr><tr><td><code>formSeparateElements</code></td><td>If set to true, instead of adding the 3DS data to the form in one element as JSON data. It will print each field as a separate hidden <code>&#x3C;input> elements with the name being the JSON key and the data the JSON data.</code></td><td>boolean</td><td>false</td><td>N</td><td>3</td></tr><tr><td><code>threeDs1StyleReturn</code></td><td>Names all the returned data to use 3DS1 naming patterns.</td><td>boolean</td><td>false</td><td>N</td><td>3</td></tr><tr><td><code>convertResponseToMatchVersion</code></td><td>Converts all the returned data to use the corresponding 3DS versions naming patterns.</td><td>boolean</td><td>false</td><td>N</td><td>3</td></tr><tr><td><code>mcc</code></td><td><strong>ONLY TO BE USED IN TESTING</strong><br>This setting allows you to change the workflow while in testing mode. On live the MCC is set in the backend system and should never be passed in using this option.<br><br>3001 - Challenge Required<br>3002 - Frictionless<br>3003 - Decline</td><td>string</td><td>-</td><td>N</td><td>3</td></tr></tbody></table>


# 3DS Response

3DS response fields and their values/meanings

This section provides an overview of the 3DS response fields and their associated values/meanings.&#x20;

There is also a translation of the TxShield response to 3DS1 naming conventions (TxShield response matches naming conventions of 3DS2).

* [transStatus](#transstatus)
* [transStatusReason](#transstatusreason)
* [TxShield (3DS2) fields to 3DS1 translation](#txshield-3ds2-fields-to-3ds1-translation)

### Example Response

```
{
  threeDSIntegratorOid: 'string',
  threeDSRequestorOrderID: 'string',
  threeDSRequestorData: 'string',
  threeDSRequestorID: 'string',
  threeDSServerTransID: 'string',
  shieldReference: 'string',
  acsTransID: 'string',
  dsTransID: 'string',
  transStatus: 'string',
  transStatusReason: 'string',
  authenticationValue: 'string',
  authenticationAlgorithm: 'string',
  eci: 'string',
  version: 'string',
  errCode: 'string',
  errMsg: 'string'
}
```

### transStatus

The values in the transStatus field along with the eci field indicate whether a liability shift has occurred. If the value is **Y, U, A** you can attempt the authorisation (payment) transaction. If the value is **N, C, R** we recommend not attempting the authorisation transaction, however, it is at the merchant's discretion if they wish to proceed.

Only a status of **Y** guarantees a full liability shift.

A transStatus of **C** should only be returned by the 3DS SDK if challenges are turned off. This turns the 3DS SDK into a frictionless workflow. If you receive a transStatus of **C** the frictionless transaction has not been authenticated. The ACS server (the card issuer) requested the Challenge workflow, and in a forced frictionless scenario this means the authentication has failed. You should not proceed to payment. The 3DS SDK returns the transStatus of **C** so that the merchant can keep statistics and track how many potential authentications failed because the ACS requested a challenge. You can use this information to make a more informed decision as to whether you turn challenges on, or keep them turned off.

| transStatus Value | Description                                                                                                   | Continue to Payment |
| ----------------- | ------------------------------------------------------------------------------------------------------------- | ------------------- |
| Y                 | Authentication successful                                                                                     | Y                   |
| N                 | Not authenticated, transaction denied                                                                         | N                   |
| U                 | Authentication/account verification could not be performed                                                    | Y                   |
| A                 | Not authenticated, but a proof of attempted authentication is provided                                        | Y                   |
| C                 | Challenge required; additional authentication is required. Only returned if challenge disabled (frictionless) | N                   |
| R                 | Authentication rejected; issuer is rejecting authentication and requesting authorisation not be attempted.    | N                   |

### transStatusReason

The values in the transStatusReason field can be mapped to the below meanings. The full text should already be in the msg field in the response data so you don't need to map this yourself.

| transStatusReason Value | Meaning                                 |
| ----------------------- | --------------------------------------- |
| 01                      | Card authentication failed              |
| 02                      | Unknown Device                          |
| 03                      | Unsupported Device                      |
| 04                      | Exceeds authentication frequency limit  |
| 05                      | Expired card                            |
| 06                      | Invalid card number                     |
| 07                      | Invalid transaction                     |
| 08                      | No card record                          |
| 09                      | Security failure                        |
| 10                      | Stolen card                             |
| 11                      | Suspected fraud                         |
| 12                      | Transaction not permitted to cardholder |
| 13                      | Cardholder not enrolled in service      |
| 14                      | Transaction timed out at the ACS        |
| 15                      | Low confidence                          |
| 16                      | Medium confidence                       |
| 17                      | High confidence                         |
| 18                      | Very High confidence                    |
| 19                      | Exceeds ACS maximum challenges          |
| 20                      | Non-Payment transaction not supported   |
| 21                      | 3RI transaction not supported           |

### TxShield (3DS2) fields to 3DS1 translation

| TxShield Field (3DS2)   | 3DS1 Name               | Description                                    |
| ----------------------- | ----------------------- | ---------------------------------------------- |
| acsTransId              | -                       | ACS servers reference                          |
| authenticationValue     | cavv                    | -                                              |
| dsTransId               | xid                     | Director servers reference                     |
| eci                     | eci                     | Ecommer Indiciator                             |
| protocolVersion         | -                       | -                                              |
| transStatus             | transStatus / status    | Depends on the processor as to which they use. |
| authenticationAlgorithm | authenticationAlgorithm | Alorithm Identifier. 3DS1 Only                 |


# 3DS DOM elements

Below is a list of all DOM elements you can tag with `data-threeds` attributes so the 3DS SDK can find it.&#x20;

An example and more details are available in [**Step 2**](https://docs.payshield.ai/3dsecure2+/pages/GdUjgLso4DLAKsAq5r3i#2.-add-data-threeds-attributes) of the integration guide.

| Element           | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Format                           | Required                              | Version |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ------------------------------------- | ------- |
| pan               | Credit card number                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | String                           | Y                                     | 2.3     |
| month             | Expiration month                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | String - Two digits only         | Y                                     | 2.3     |
| year              | Expiration year                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | String - Two digits only         | Y                                     | 2.3     |
| shippingLine1     | First line of cardholder street address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | String (max 50 characters)       | Amex only (recommended if applicable) | 2.3     |
| shippingLine2     | Second line of cardholder street address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | String (max 50 characters)       | Amex only (recommended if applicable) | 2.3     |
| shippingLine3     | Third line of cardholder street address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | String (max 50 characters)       | Amex only (recommended if applicable) | 2.3     |
| shippingPostCode  | Zip code / Postal code                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | String (max 16 characters)       | Amex only (recommended if applicable) | 2.3     |
| shippingCity      | City of cardholder address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | String (max 50 characters)       | Amex only (recommended if applicable) | 2.3     |
| shippingState     | State of cardholder address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | String  (max 3 characters)       | Amex only (recommended if applicable) | 2.3     |
| shippingCountry   | Country of cardholder address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | String  (max 3 characters)       | Amex only (recommended if applicable) | 2.3     |
| billingLine1      | First line of cardholder street address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | String (max 50 characters)       | No (strongly recommended)             | 2.3     |
| billingLine2      | Second line of cardholder street address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | String (max 50 characters)       | No (strongly recommended)             | 2.3     |
| billingLine3      | Third line of cardholder street address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | String (max 50 characters)       | No (strongly recommended)             | 2.3     |
| billingPostCode   | Zip code / Postal code                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | String (max 16 characters)       | No (strongly recommended)             | 2.3     |
| billingCity       | City of cardholder address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | String (max 50 characters)       | No (strongly recommended)             | 2.3     |
| billingState      | State of cardholder address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | String  (max 3 characters)       | No (strongly recommended)             | 2.3     |
| billingCountry    | Country of cardholder address                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | String (max 3 char)              | No (strongly recommended)             | 2.3     |
| email             | E-mail                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | String  (max 254 characters)     | No (strongly recommended)             | 2.3     |
| cardHolderName    | First name + Last name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | String (min 2 max 45 characters) | Discover only (strongly recommended)  | 2.3     |
| currency          | ISO 4217 three-digit currency code. Must be one of the values set in 3ds merchant setting                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | String                           | No                                    | 2       |
| transType         | <p>Type of product being transacted:<br><strong>01</strong> = Goods / Service Purchase (default)<br><strong>03</strong> = Check Acceptance<br><strong>10</strong> = Account Funding<br><strong>11</strong> = Quasi-Cash Transaction<br><strong>28</strong> = Prepaid Activation and Load</p>                                                                                                                                                                                                                                                                                                                                                                                                                                          | String                           | No                                    | 2       |
| shipIndicator     | <p>Shipping method used to deliver goods:<br><strong>01</strong> = Ship to cardholder’s billing address</p><p><strong>02</strong> = Ship to another verified address on file with merchant</p><p><strong>03</strong> = Ship to address that is different than the cardholder’s billing address</p><p><strong>04</strong> = “Ship to Store” / Pick-up at local store (Store address shall be populated in shipping address fields)</p><p><strong>05</strong> = Digital goods (includes online services, electronic gift cards and redemption codes)<br><strong>06</strong> = Travel and Event tickets, not shipped<br><strong>07</strong> = Other (for example, Gaming, digital services not shipped, e-media subscriptions, etc.)</p> | String                           | Amex only                             | 2       |
| deliveryTimeFrame | <p>When would the goods be delivered:<br><strong>01</strong> = Electronic Delivery<br><strong>02</strong> = Same day shipping<br><strong>03</strong> = Overnight shipping<br><strong>04</strong> = Two-day or more shipping</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | String                           | Amex only                             | 2       |
| reorderItemsInd   | <p>Is the order new for the customer or it has been ordered before:<br><strong>01</strong> = First time ordered<br><strong>02</strong> = Reordered</p>                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | String                           | Amex only                             | 2       |


# 3DS Demo Payment Page

### Installation

The demo payment page file can be downloaded here.

{% file src="/files/IpzaVT0eXb4C9b3MSqvQ" %}

| File                     | Detail                                                                                                                            |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| 3ds2DemoPaymentPage.html | Example payment page integrated with TxShield 3DS SDK. Do not use in production environments as it exposes sensitive information. |

These files are intended for you to copy into the same directory on your webserver and run directly from there.

### Configuration

Once on the webserver all you have to do is update the `3ds2DemoPaymentPage.html` file with the configuration values supplied by PayShield. The variables in the demo payment page are surrounded by {{ variable }}. Both the name and `{{}}` should be replaced as per below.

#### 3DS Server URL Updates

`{{txshield_3ds_url}}`: the URL of the server to connect to for 3ds2 authorisation. It needs to be updated in 2 places. Assuming the URL we provide is `https://myauthserver.com`.

| Default Values                                                                |                                                                                                                                               |
| ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| \<script src="{{txshield\_3ds\_url}}/sdk/3d2integrator.v3.dist.js">\</script> | \<script src="[https://myauthserver.com/sdk/3d2integrator.v3.dist.js">\\](https://myauthserver.com/sdk/3d2integrator.v3.dist.js">\\)</script> |
| let shieldUrl = '{{txshield\_3ds\_url}}';                                     | let shieldUrl = '<https://myauthserver.com>';                                                                                                 |

#### Authentication Updates

Two further updates need to be made to the MID and Rcode. This will allow authorisation to connect to the TxShield 3DS SDK.

`{{txshield_3ds_mid}}` is the MID provided to you by PayShield and is equivalent to a username. For example, if a mid of 808 is provided, then:

| Default Value                                | Updated Value             |
| -------------------------------------------- | ------------------------- |
| let shield3dsMid = '{{txshield\_3ds\_mid}}'; | let shield3dsMid = '808'; |

`{{txshield_3ds_rcode}}` is the rcode provided to you by PayShield and is equivalent to a password. For example, if an rcode of '598950057acc2dd9df729a5ed4b9750a7c03bbec' is provided, then:

| Default Value                                    | Updated Value                                                    |
| ------------------------------------------------ | ---------------------------------------------------------------- |
| let shield3dsRcode = '{{txshield\_3ds\_rcode}}'; | let shield3dsRcode = '598950057acc2dd9df729a5ed4b9750a7c03bbec'; |

{% hint style="warning" %}

#### Do not expose your production MID or Rcode publicly

A MID and RCode are equivalent to your username and password, or API authorisation key.
{% endhint %}

You should now be able to run the demo payment page file. For test card details please contact [PayShield Support.](mailto:support@payshield.ai)


# 3DS Test Credentials

Test Credentials for 3DS

| Company    | Card Number      | Expiry |
| ---------- | ---------------- | ------ |
| Visa       | 4850235256199618 | 2810   |
| Mastercard | 5379580432276056 | 2810   |
| JCB        | 3579523973277151 | 2810   |
| CUP        | 6222029736972074 | 2810   |

*<mark style="color:orange;">\*To test the 3DS process, use the mobile option from Purchase Authentication options. Use 123456 as the code. This is the only option that can be used in the test.</mark>*\
\
*<mark style="color:orange;">You can test 3 types of workflow that the cards should follow ie, Frictionless, Challenge Required, Decline- by choosing the option and clicking the 'Update Config'</mark>*


# Overview

<figure><img src="/files/zrVMKUw3989hYhpXk4ZP" alt="" width="375"><figcaption></figcaption></figure>

TxFind stores transaction and cart data from the merchant, making it available to Card Schemes (e.g. Visa, Mastercard) or other select providers.

Card Schemes use this data to allow customers and issuing banks to look up unique details for a transaction, helping to resolve cardholder billing confusion and disputes in near real-time.

For customers, enhanced order details are made available to them through their banks' online banking platform or phone app. If a customer chooses to contact their issuing bank, the issuer's call centre or back-office personnel will have access to the same detailed order information.

Access to comprehensive transaction information helps cardholders recognise transactions immediately and empowers issuers to help resolve confusion by validating purchases, or flag as true or first-party fraud, reducing the instance of unwarranted chargebacks.\
\
It is important that Merchants maintain a minimum of 365 days of prior orders available to maximize match rates and service benefits.

{% hint style="info" %}

#### Solution Highlights

* Eliminate unwarranted chargebacks
* Confirm buying decisions and reduce billing confusion
* Identify fraud and stop first-party / “friendly” fraud
  {% endhint %}

In this documentation, `{baseUrl}` is used as a placeholder for the base domain of your environment.

Please replace `{baseUrl}` with the appropriate domain:

* **Staging/UAT**: `uat-txfind.payshield.ai`


# Integration Overview

There are 2 different paths to integrate with TxFind depending on how you're interacting with the system.

### Merchant

Merchants will use TxFind to store a copy of cart / transaction data to be made available to customers via search at a later stage.

### Provider

Providers provide the interface between the stored cart / transaction data and the customer, allowing them to initiate a search for their data.\ <br>


# Merchant Integration

## Overview

TxFind allows Merchants to store a copy of their cart/transaction data. You can update the cart data with relevant information over the lifetime of a transaction if you wish, or you can just leave it as the uploaded data.

The data that you may want to update could be the settlement data for an asynchronous transaction, where the settlement only happened hours / days later. Or updated parcel tracking information if available.

## Integration Steps

### Merchant signup

When a merchant signs up you will be provided a merchantId and a JWT Bearer token. Keep these safe and private. They are used for authentication into the merchant endpoints and all costs for use are raised against those credentials.

### Store cart/transaction details

For every transaction that you do, you should store the full details of the cart/ transaction into TxFind. This is done by calling the[ /transactionDetails](/txfind-payreveal-order-insight-ican/merchant/store-transaction-details). This accepts a strict JSON string representing the details of the transaction.

Upon a successful store, the return data from the transactionDetails call will have a `txShieldOICartReference` , you should keep a record of this reference against the transaction in your system. You will need this reference if you want to update the cart later.

To help during integration there is the [/cartValidation](/txfind-payreveal-order-insight-ican/merchant/validate-cart-details) endpoint. This allows you to test your JSON data during integration with out storing a lot of test transactions in the database. You can also use this later for debugging transactions that failed.

### Update alert & chargeback status

There are two important transaction lifecycle events that should be updated for the transaction. [/alert](/txfind-payreveal-order-insight-ican/transaction/flag-alert-received) and [/chargeback](/txfind-payreveal-order-insight-ican/transaction/flag-chargeback-received) . In particular, **recording that a chargeback was done against a transaction is important for billing information.**

Both endpoints accept a reference that can be used to find the details about an alert / chargeback in your system later, and will flag the transaction as having received an alert / chargeback.

**Alert**\
[/alert](/txfind-payreveal-order-insight-ican/transaction/flag-alert-received)\
An alert is a notification that is sent after a customer initiates a chargeback, but before it is finalized by the issuing bank. For more information about how to receive these talk to the TxShield team and see the documentation [here.](https://docs.payshield.ai/txalerts-dispute-alerts/)

**Chargeback**\
[/chargeback](/txfind-payreveal-order-insight-ican/transaction/flag-chargeback-received)\
When a chargeback is completed for a transaction, it should be recorded against the transaction in TxFind. This is in particular very important for transactions that are being exposed to Card Provider networks (Visa, Mastercard etc.) as this can significantly impact your billing.

### Update cart / transaction details

The [/updateTransactionDetails](/txfind-payreveal-order-insight-ican/merchant/update-transaction-details) endpoint allows you to update details about the transaction. You may want to update the Settlement data for an asynchronous transaction that you did not have available to you at the time the cart / transaction was stored in TxFind. You may want to update parcel tracking information if available.

The information stored in TxFind will be available to the customer and their Issuing Bank prior to raising a Chargeback. So keeping as much relevant information available to search by (Settlement data) so the transaction can be found, along with as much up-to date cart / transaction information which can assist the customer or their Issuing Bank in making decisions about chargebacks.

### Finished

That is all there is to the TxFind integration, you have now finished the Merchant Integration.


# Provider Integration

## Overview

Provider integrations are for companies that will be providing customers with a way to search for their transactions which may be stored in TxFind.

Merchants will not have to complete this integration, and will **not** be provided with credentials to do so.

## Integration

## Provider signup

To signup, you will need to make contact with the TxFind team. When signup is completed you will be provided with a key that can be used to sign JWT Bearer tokens.

## Authentication

Authentication is completed by sending a JWT Bearer token that has been created using the private key sent during registration.

At a minimum, the JWT Bearer token must contain the `iat` and `exp` fields.

If authentication fails TxFind will return a 401 Unauthorized status code and terminate the call.

For more information on how JWT Bearer tokens work please [see here](https://jwt.io/)

### JWT Bearer Token

Please note that when you were given access to the system as a provider you would have been provided your JWT Signature Key. To generate a Bearer token to test your call, you will need to use that key to encode your Bearer Token, [JWT.io](https://jwt.io/#debugger-io) will let you build one to test with. Make sure that you have set the following:

* Algorithm: HS256
* Leave the header as is
* Payload: `{ "iat": 1632265844560, "exp": 1632266144560 }`
* verify signature: in the box provided enter your JWT Signature Key

Note that the `iat` can be generated from your browsers console by typing `Date.now()`. The `exp` is 5 minutes later, this can be calculated by adding 300,000 to the `iat` (the `iat` is in milliseconds, not seconds).

## Search

Call the search endpoint that is relevant to you. During the onboarding process, the TxFind team will discuss with you your needs and point you at the correct search endpoint. In many cases, this may require a custom search endpoint with search fields and results tailored to your use case.

It should be noted that you will not have access to all search endpoints with your credentials, just the ones relevant to your needs.


# Verifi Provider Order Search

<mark style="color:green;">`POST`</mark> `https://{baseUrl}/api/v2/provider/verifi/orders`

#### Request Body

## Verifi V3 Provider Search

> Search for an Verifi V3 enabled merchant's transaction details.

```json
{"openapi":"3.0.1","info":{"title":"TxFind API's Version 2 Endpoints","version":"2.0.0"},"tags":[{"name":"Provider","description":"Call related to transaction details."}],"servers":[{"url":"https://{baseUrl}","description":"Current server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/api/v2/provider/verifi/orders":{"post":{"tags":["Provider"],"summary":"Verifi V3 Provider Search","description":"Search for an Verifi V3 enabled merchant's transaction details.","operationId":"verifi/Orders","requestBody":{"description":"The supplied JSON payload from Verifi.","content":{"application/json":{"schema":{"type":"object","required":["insightId","verifiEntityInfo","source","paymentType","paymentDescriptor","transactionDate","transactionAmount","transactionRequestId"],"properties":{"insightId":{"maxLength":36,"type":"string","description":"Verifi's unique identifier for the Order Insight request to the network Format = UUID version 3."},"verifiEntityInfo":{"type":"object","properties":{"partnerId":{"type":"number","maxLength":10,"description":"Unique ID for partner in Verifi system."},"clientId":{"type":"number","maxLength":10,"description":"Unique ID for client in Verifi system."}},"required":["partnerId"],"description":"Information related to partners and clients in the Verifi system."},"source":{"maxLength":3,"type":"string","description":"Identifies the source of the Order Lookup Request."},"cardBin":{"maxLength":8,"type":"string","description":"The six or eight-digit card Issuer BIN associated with the purchase."},"cardLast4":{"maxLength":4,"type":"string","description":"The six or eight-digit card Issuer BIN associated with the purchase."},"paymentType":{"maxLength":20,"type":"string","description":"Indicates the payment type of the original purchase."},"paymentDescriptor":{"maxLength":25,"type":"string","description":"The Merchant name component of the billing descriptor which appears on the customer's transaction statement."},"transactionDate":{"maxLength":20,"type":"string","format":"date","description":"ISO 8601 string format without milliseconds (Example = YYYY-MM-DDThh:mm:ssZ)."},"transactionAmount":{"type":"object","properties":{"amount":{"type":"number","maxLength":10,"description":"The amount value, represented as multiples of 0.01"},"currency":{"type":"string","maxLength":3,"description":"Currency of the amount. ISO 4217 3-letter currency code."}},"required":["amount"],"description":"Transaction Amount Object."},"transactionRequestId":{"maxLength":36,"type":"string","description":"Not a unique value, this is a hashed value based on key input fields used to locate a previous request with the same key input fields."}}}}}},"responses":{"200":{"description":"Response","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"404":{"description":"Order for the given lookup not found","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"default":{"description":"Error Payload","content":{"application/json":{"schema":{"type":"object"}}}}}}}}}
```

<table><thead><tr><th width="270">Name</th><th>Type</th><th>Description</th></tr></thead><tbody><tr><td>insightId</td><td>String</td><td>"Please add the description here"</td></tr><tr><td>verifiEntityInfo</td><td>JSON </td><td>"Please add the description here"</td></tr><tr><td>verifiEntityInfo.partnerId</td><td>Number</td><td>"Please add the description here"<br><br>NOTE: This field is inside the verifiEntityInfo JSON</td></tr><tr><td>verifiEntityInfo.clientId</td><td>Number</td><td>"Please add the description here"<br><br>NOTE: This field is inside the verifiEntityInfo JSON</td></tr><tr><td>paymentType</td><td>String</td><td>"Please add the description here"</td></tr><tr><td>paymentDescriptor</td><td>String</td><td>"Please add the description here"</td></tr><tr><td>transactionDate</td><td>Datetime</td><td>"Please add the description here"<br><br>NOTE: Format should be in ISO 8601</td></tr><tr><td>transactionAmount</td><td>JSON</td><td>"Please add the description here"</td></tr><tr><td>transactionAmount.amount</td><td>Number</td><td>"Please add the description here"<br><br>NOTE: This field is inside the transactionAmount JSON</td></tr><tr><td>transactionAmount.currency</td><td>String</td><td>"Please add the description here"<br><br>NOTE: This field is inside the transactionAmount JSON</td></tr><tr><td>cardLast4</td><td>String</td><td>The last 4 digits of the card number associated with the purchase.</td></tr><tr><td>cardBin</td><td>String</td><td>The six-digit card Issuer BIN associated with the purchase.</td></tr><tr><td>transactionRequestId</td><td>String</td><td>The hash value based on key input fields used to locate a previous request with the same key input fields. Format: UUID version 3</td></tr><tr><td>source</td><td>String</td><td>Identifies the source of the Order Request: Order Insight request from an Issuer via a Portal or API request (OrderInsight OIP), Order Insight request from a Cardholder via an Issuer Mobile Application or Digital Channel (Order Insight Digital OIM). Enumerated values: OIP, OIM</td></tr></tbody></table>


# EMS Provider Search

Search from EMS

## EMS Provider Search

> Search for an EMS enabled merchant's transaction details.

```json
{"openapi":"3.0.1","info":{"title":"TxFind API's Version 2 Endpoints","version":"2.0.0"},"tags":[{"name":"Provider","description":"Call related to transaction details."}],"servers":[{"url":"https://{baseUrl}","description":"Current server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"getTransactionDetailsReturn":{"type":"array","items":{"type":"object","properties":{"merchantInformation":{"type":"object","properties":{"merchantContactPhone":{"type":"string"},"storeDetails":{"type":"object","properties":{"storeName":{"type":"string"}}},"merchantUrl":{"type":"string"},"merchantName":{"type":"string"}}},"receipt":{"type":"object","required":["productsPurchasedList"],"properties":{"orderDate":{"type":"string","format":"date-time"},"orderNumber":{"type":"string"},"purchaseCategory":{"type":"string"},"invoiceNumber":{"type":"string"},"downloadDateTime":{"type":"string","format":"date-time"},"subTotalAmount":{"type":"object","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string"}}},"taxAmount":{"type":"object","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string"}}},"taxDescription":{"type":"string"},"shippingAndHandlingAmount":{"type":"object","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string"}}},"orderTotalAmount":{"type":"object","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string"}}},"paymentInformation":{"type":"object","properties":{"paymentTotalAmount":{"type":"object","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string"}}}}},"productsPurchasedList":{"type":"array","items":{"type":"object","required":["productDescription"],"properties":{"quantity":{"type":"integer"},"creditReimbursementSequenceNumber":{"type":"integer"},"unitPriceAmount":{"type":"object","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string"}}},"productUrl":{"type":"string","format":"uri"},"productType":{"type":"string"},"productDescription":{"type":"string"},"artistOrSeller":{"type":"string"},"deliveryDetails":{"type":"object","properties":{"shippingCarrier":{"type":"string"},"trackingNumber":{"type":"string"},"dateOfShipment":{"type":"string","format":"date-time"},"dateOfDelivery":{"type":"string","format":"date-time"},"deliveryStatus":{"type":"string"},"otherStatusDescription":{"type":"string"}}}}}}}},"customerInformation":{"type":"object","properties":{"accountId":{"type":"string"}}},"device":{"type":"object","properties":{"ipAddress":{"type":"string"},"deviceFingerprint":{"type":"string"},"deviceId":{"type":"string"}}},"deliveryAddress":{"type":"object","properties":{"address1":{"type":"string"}}}}}}}},"paths":{"/api/v2/provider/ems/getTransactionDetails":{"post":{"tags":["Provider"],"summary":"EMS Provider Search","description":"Search for an EMS enabled merchant's transaction details.","operationId":"emsGetTransactionDetails","requestBody":{"description":"the JSON payload","content":{"application/json":{"schema":{"type":"object","required":["txShieldOICartReference","source","cardBin","cardLast4","transactionDate"],"properties":{"txShieldOICartReference":{"type":"string","description":"TxShield OI Reference number"},"source":{"type":"string","description":"Source of the transaction. Must be \"EMS\"."},"cardBin":{"maxLength":8,"type":"string","description":"The first 6-8 digits card number."},"cardLast4":{"maxLength":4,"type":"string","description":"The last 4 digits card number."},"transactionAmount":{"type":"object","properties":{"amount":{"description":"Amout of purchase transactions.","type":"number"},"currency":{"description":"ISO 4217 currency code.","type":"string","maxLength":3}}},"transactionDate":{"maxLength":20,"type":"string","description":"Transaction Date formatted in ISO 8601 20 charactor long without milliseconds (Example = YYYY-MM-DDThh:mm:ssZ)"}}}}},"required":true},"responses":{"200":{"description":"Response","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/getTransactionDetailsReturn"},{"type":"object","properties":{"merchantId":{"type":"string","description":"The merchant's unique identifier."},"txShieldOICartReference":{"type":"string","description":"The TxShield OI Cart Reference for the transaction."},"paymentType":{"type":"string","description":"Payment type used in the transaction."},"paymentDescriptor":{"type":"string","description":"Payment descriptor for the transaction."}}}]}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"403":{"description":"Forbidden - Merchant not enrolled with EMS service","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}}}}}}}
```


# Verifi RDR Decision

When an Issuer submits a dispute and the Merchant is enrolled for Rapid Dispute Resolution (RDR) decisioning via the Verifi API, Verifi sends the pre-dispute to the Merchant via HTTP POST call.

## RDR Decision Evaluation

> Evaluates transaction data against merchant RDR rules and returns accept/decline decision for Rapid Dispute Resolution.

```json
{"openapi":"3.0.1","info":{"title":"TxFind API's Version 2 Endpoints","version":"2.0.0"},"tags":[{"name":"RDR","description":"Call related to Rapid Dispute Resolution (RDR) decisions."}],"servers":[{"url":"https://{baseUrl}","description":"Current server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"RdrDecisionRequest":{"type":"object","required":["decisionId","verifiEntityInfo","caseType","source","caseDate","paymentDescriptor","paymentDescriptorContact","acquirerBin","cardAcceptorId","transactionId","paymentType","authCode","transactionDate","transactionAmount","arn","mcc","caseAmount","transactionType","reasonCode"],"properties":{"decisionId":{"type":"string","maxLength":36,"description":"ID number generated by Verifi and used for case reference (UUID version 4)"},"verifiEntityInfo":{"type":"object","description":"Collection of system identifiers the request is associated with on the Verifi system","required":["partnerId","clientId"],"properties":{"partnerId":{"type":"integer","description":"Partner ID in Verifi system"},"clientId":{"type":"integer","description":"Client ID in Verifi system"}}},"caseType":{"type":"string","maxLength":20,"description":"Case type for RDR Decision Requests","enum":["DISPUTE"]},"source":{"type":"string","maxLength":20,"description":"Source for RDR Decision Requests","enum":["VMPI"]},"caseDate":{"type":"string","format":"date-time","maxLength":20,"description":"Date the case was recorded by the system"},"paymentDescriptor":{"type":"string","maxLength":25,"description":"The Merchant name component of the billing descriptor which appeared on the customer's transaction statement"},"paymentDescriptorContact":{"type":"string","maxLength":13,"description":"The Merchant phone number which appeared on the Cardholder's transaction statement"},"acquirerBin":{"type":"string","maxLength":6,"description":"Acquiring Bank identifier assigned by Visa"},"cardAcceptorId":{"type":"string","maxLength":15,"description":"Acquirer-assigned identifier of the Merchant account to VisaNet"},"transactionId":{"type":"string","maxLength":15,"description":"Visa-generated identifier that is unique for each original transaction"},"cardBin":{"type":"string","maxLength":8,"description":"The six or eight-digit card Issuer BIN that is associated with the purchase (conditionally required)"},"cardLast4":{"type":"string","maxLength":4,"description":"The last four digits of the card number associated with the purchase (conditionally required)"},"token":{"type":"string","maxLength":19,"description":"Token associated with the transaction when a token was used instead of a PAN for payment"},"paymentType":{"type":"string","maxLength":20,"description":"Indicates the payment type of the original purchase"},"authCode":{"type":"string","maxLength":6,"description":"The Issuer authorization code for the transaction"},"eci":{"type":"string","maxLength":1,"description":"The mail/phone/electronic commerce indicator (Values 1-9)"},"mcsn":{"type":"string","maxLength":2,"description":"Multiple Clearing Sequence Number contains a sequence number that distinguishes a specific clearing message"},"installmentNumber":{"type":"integer","maximum":9999999999,"description":"Specific installment number of the transaction (for Parcelado installment transactions)"},"transactionDate":{"type":"string","format":"date-time","maxLength":20,"description":"Purchase transaction date in UTC format"},"transactionAmount":{"type":"object","description":"The transaction amount of the payment processed by Merchant","required":["amount","currency"],"properties":{"amount":{"type":"number","description":"Transaction amount value"},"currency":{"type":"string","maxLength":3,"description":"Currency code (ISO 4217)"}}},"destinationAmount":{"type":"object","description":"Cardholder billing amount if a currency conversion took place at settlement","properties":{"amount":{"type":"number","description":"Destination amount value"},"currency":{"type":"string","maxLength":3,"description":"Currency code (ISO 4217)"}}},"arn":{"type":"string","maxLength":24,"description":"Acquirer reference number"},"mcc":{"type":"string","maxLength":4,"pattern":"^[0-9]{4}$","description":"The four-digit number listed in ISO 18245 for retail financial services"},"terminalId":{"type":"string","maxLength":8,"description":"Code that identifies a terminal at the card acceptor location"},"caseAmount":{"type":"object","description":"Amount of the dispute","required":["amount","currency"],"properties":{"amount":{"type":"number","description":"Case amount value"},"currency":{"type":"string","maxLength":3,"description":"Currency code (ISO 4217)"}}},"purchaseIdentifier":{"type":"string","maxLength":25,"description":"Unique identifier for the order defined by the Merchant"},"transactionType":{"type":"string","maxLength":20,"description":"Type of transaction"},"reasonCode":{"type":"string","maxLength":4,"description":"Code indicating both Dispute Category and Dispute Condition Code"},"posEntryModeCode":{"type":"string","maxLength":2,"description":"Identifies the terminal type and terminal entry capability"}}},"RdrDecisionResponseAccepted":{"type":"object","required":["outcome","statusCode","reason","refundAmount"],"properties":{"outcome":{"type":"string","maxLength":8,"description":"The decision result for accepted cases","enum":["ACCEPTED"]},"statusCode":{"type":"string","maxLength":3,"description":"Status code for accepted RDR pre-dispute","enum":["103"]},"reason":{"type":"string","maxLength":255,"description":"Merchant provided reason the case was accepted (for informational purposes only)"},"refundAmount":{"type":"object","description":"Amount to be refunded (conditionally required when result = ACCEPTED). For RDR processing, the refund amount MUST always be the case amount from the request.","required":["amount","currency"],"properties":{"amount":{"type":"number","description":"Refund amount value"},"currency":{"type":"string","maxLength":3,"description":"Currency code (ISO 4217)"}}}}},"RdrDecisionResponseDeclined":{"type":"object","required":["outcome","statusCode","reason"],"properties":{"outcome":{"type":"string","maxLength":8,"description":"The decision result for declined cases","enum":["DECLINED"]},"statusCode":{"type":"string","maxLength":3,"description":"Status code indicating the reason for decline","enum":["957","950","951"]},"reason":{"type":"string","maxLength":255,"description":"Merchant provided reason the case was declined (for informational purposes only)"}}},"ErrorResponse":{"type":"object","properties":{"msg":{"type":"string","description":"Error message"}}}}},"paths":{"/api/v2/provider/verifi/decisions":{"post":{"tags":["RDR"],"summary":"RDR Decision Evaluation","description":"Evaluates transaction data against merchant RDR rules and returns accept/decline decision for Rapid Dispute Resolution.","operationId":"rdrDecisions","requestBody":{"description":"RDR decision request containing transaction details","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RdrDecisionRequest"}}}},"responses":{"200":{"description":"Decision evaluation completed successfully","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/RdrDecisionResponseAccepted"},{"$ref":"#/components/schemas/RdrDecisionResponseDeclined"}]}}}},"400":{"description":"Bad Request - Missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Authentication failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```


# Store Transaction Details

<mark style="color:green;">`POST`</mark> `https://{baseUrl}/api/v2/merchant/{merchantId}/transactionDetails`

The **Authorization Header** is required if JWT (JSON Web Token) authentication is enabled in the application configuration (`config.server.jwt_enable` is `true`). This header must contain a valid JWT token prefixed with the word "Bearer". The token is used to authenticate the request and verify that the sender is authorized to perform the requested operation

The **Request Body** must be an array containing exactly one object. This object includes the details of the transaction and payment information.

This endpoint is used to store transaction details for a merchant identified by `merchantId`. The endpoint validates the request body, checks the merchant's enrollment, and stores the transaction data in both MongoDB and optionally in AWS DynamoDB.

### **Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

### Path Parameters

<table><thead><tr><th width="374">Name</th><th>Description</th></tr></thead><tbody><tr><td><code>merchantId</code></td><td>Merchant Id for create transaction</td></tr></tbody></table>

### **Body**

<table data-full-width="true"><thead><tr><th>Name</th><th width="191">Type</th><th width="158">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>transactionReference</code></td><td>String</td><td>True</td><td>Merchant-supplied reference identifying this transaction</td></tr><tr><td><code>cardBin</code></td><td>String</td><td>True</td><td>The six or eight-digit card Issuer BIN that is
<br>associated with the purchase.</td></tr><tr><td><code>cardLast4</code></td><td>String</td><td>True</td><td>The last four digits of the card number
<br>associated with the purchase.</td></tr><tr><td><code>transactionDate</code></td><td>String</td><td>True</td><td>Purchase transaction date in UTC format.</td></tr><tr><td><code>paymentDescriptor</code></td><td>String</td><td>True</td><td>The Merchant name component of the
<br>billing descriptor which appears on the
<br>customer's transaction statement.</td></tr><tr><td><code>receipt</code></td><td>Object</td><td>True</td><td>Object containing transaction details like payment information and purchased products.</td></tr><tr><td><code>receipt.paymentInformation</code></td><td>Object</td><td>True</td><td>Object containing payment details.</td></tr><tr><td><code>receipt.paymentInformation.paymentTotalAmount</code></td><td>Object</td><td>True</td><td>Object containing the total amount and currency.</td></tr><tr><td><code>receipt.paymentInformation.paymentTotalAmount.amount</code></td><td>Number</td><td>True</td><td>The total payment amount.</td></tr><tr><td><code>receipt.paymentInformation.paymentTotalAmount.currency</code></td><td>String</td><td>True</td><td>The currency of the payment.</td></tr><tr><td><code>receipt.productsPurchasedList</code></td><td>Array</td><td>True</td><td>List of products purchased in the transaction.</td></tr><tr><td><code>receipt.productsPurchasedList[].productDescription</code></td><td>String</td><td>True</td><td>Detailed description of the product
<br>(merchandise or service) purchased.</td></tr><tr><td><code>merchantInformation</code></td><td>Object</td><td>True</td><td>Object containing information about the merchant.</td></tr><tr><td><code>merchantInformation.merchantName</code></td><td>String</td><td>True</td><td>Corporate or Parent company name of the
<br>Merchant, may or may not be recognizable
<br>to the consumer. May be the name on file
<br>with your Acquirer/Merchant Account
<br>provider.
</td></tr><tr><td><code>merchantInformation.merchantUrl</code></td><td>String</td><td>True</td><td>Merchant corporate business URL.
<br>May or may NOT be different from the
<br>URL the purchase was made from.</td></tr><tr><td><code>merchantInformation.merchantContactPhone</code></td><td>String</td><td>True</td><td>Merchant’s customer service phone
<br>number. Should be the number you would
<br>want a consumer to contact you to discuss
<br>any questions they may have about the
<br>purchase.
<br>Must be in E.164 format (“+” , 3-digit country
<br>code, 12-digit telephone number).</td></tr><tr><td><code>merchantInformation.storeDetails</code></td><td>Object</td><td>True</td><td>Object containing details about the merchant's store.</td></tr><tr><td><code>merchantInformation.storeDetails.storeName</code></td><td>String</td><td>True</td><td>Store/Webstore name where purchase
<br>was made. Should be recognizable to the
<br>consumer</td></tr><tr><td><code>customerInformation</code></td><td>Object</td><td>True (Conditionally)</td><td>Object containing information about the customer, required for "CE" merchants.</td></tr><tr><td><code>customerInformation.accountId</code></td><td>String</td><td>True (Conditionally)</td><td>Cardholder registered identifier to
<br>uniquely identify their account with the
<br>Merchant. This should be recognizable
<br>to the Cardholder (not an internal system
<br>identifier) and something they provided the
<br>Merchant during account creation.
<br>Examples are a unique username, email,
<br>phone number or other similar value.
<br>If a “guest” checkout option was used or the
<br>Cardholder has NOT established/registered
<br>an account with the Merchant this field
<br>is not to be used.<br>Required for "CE" merchants if <code>deliveryAddress</code> is not provided.</td></tr><tr><td><code>deliveryAddress</code></td><td>Object</td><td>True (Conditionally)</td><td>Required for "CE" merchants if <code>accountId</code> is not provided.</td></tr><tr><td><code>deliveryAddress.address1</code></td><td>String</td><td>True (Conditionally)</td><td>Street address plus additional address lines
<br>such as suite number, apartment, etc.<br>Required if the merchant enrollment is "CE" or based on specific conditions.</td></tr><tr><td><code>device</code></td><td>Object</td><td>True (Conditionally)</td><td>Required for "CE" merchants or if additional security checks are needed.</td></tr><tr><td><code>device.deviceId</code></td><td>String</td><td>True (Conditionally)</td><td>Device ID of the device used to submit
<br>order. 
<br>Example values from device:
<br>• IMEI
<br>• MEID<br>Required if other device fields are not provided.</td></tr><tr><td><code>device.ipAddress</code></td><td>String</td><td>True (Conditionally)</td><td>IP Address associated with the device. Only
<br>Public IP Addresses should be provided<br>Required if other device fields are not provided.</td></tr><tr><td><code>device.deviceFingerprint</code></td><td>String</td><td>True (Conditionally)</td><td>Device fingerprint information is generated
<br>by a third-party service provider or the
<br>Merchant’s own algorithm to combine
<br>browser or device attributes to form a
<br>unique fingerprint to identify the device.<br>Required if other device fields are not provided.</td></tr></tbody></table>

## Store Transaction Details

> Storing Merchant Transaction

```json
{"openapi":"3.0.1","info":{"title":"TxFind API's Version 2 Endpoints","version":"2.0.0"},"tags":[{"name":"Merchant","description":"Call related to merchant transaction."}],"servers":[{"url":"https://{baseUrl}","description":"Current server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/api/v2/merchant/{merchantId}/transactionDetails":{"post":{"tags":["Merchant"],"summary":"Store Transaction Details","description":"Storing Merchant Transaction","operationId":"merchantTransactionDetails","parameters":[{"name":"merchantId","in":"path","description":"Merchant Id for create transaction","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["transactionReference","cardBin","cardLast4","transactionDate","paymentDescriptor","receipt","merchantInformation"],"properties":{"transactionReference":{"type":"string","description":"Merchant-supplied reference identifying this transaction. Leading/trailing whitespace is trimmed before storage. Must be unique per merchant - duplicates are rejected (single endpoint returns 409; batch endpoints mark the row as error). Echoed back (trimmed) in the response so the merchant can map their reference to the txShieldOICartReference.","maxLength":100},"cardBin":{"type":"string","description":"First 6 or 8 digits of the card used in the transaction. Must be numeric.","minLength":6,"maxLength":8,"pattern":"^[0-9]+$"},"cardLast4":{"type":"string","description":"Last 4 digits of the card used in the transaction. Must be numeric.","minLength":4,"maxLength":4,"pattern":"^[0-9]+$"},"transactionDate":{"type":"string","format":"date-time","description":"The date and time of the transaction in ISO 8601 format. Must be earlier than today."},"paymentDescriptor":{"type":"string","description":"Payment descriptor identifying the transaction.","maxLength":25},"arn":{"type":"string","description":"Acquirer Reference Number.","maxLength":24},"authCode":{"type":"string","description":"Authorization code for the transaction.","maxLength":6},"receipt":{"type":"object","required":["productsPurchasedList"],"properties":{"orderDate":{"type":"string","format":"date-time","description":"The date and time when the order was placed."},"orderNumber":{"type":"string","maxLength":25,"description":"The unique identifier for the order defined by the Merchant."},"purchaseCategory":{"type":"string","maxLength":20,"description":"The type of purchase made (MERCHANDISE or SERVICE)."},"invoiceNumber":{"type":"string","maxLength":25,"description":"The invoice number related to the order."},"downloadDateTime":{"type":"string","format":"date-time","description":"The date and time when a digital download was completed, if applicable."},"subTotalAmount":{"type":"object","description":"The subtotal before tax and shipping fees.","properties":{"amount":{"type":"number","format":"float","description":"The subtotal amount."},"currency":{"type":"string","maxLength":3,"description":"Currency in ISO 4217 3-letter format."}}},"taxAmount":{"type":"object","description":"The tax amount applied to the purchase.","properties":{"amount":{"type":"number","format":"float","description":"The total tax amount."},"currency":{"type":"string","maxLength":3,"description":"Currency in ISO 4217 3-letter format."}}},"taxDescription":{"type":"string","maxLength":100,"description":"Description of the tax applied."},"shippingAndHandlingAmount":{"type":"object","description":"The shipping and handling fee amount.","properties":{"amount":{"type":"number","format":"float","description":"Shipping and handling cost."},"currency":{"type":"string","maxLength":3,"description":"Currency in ISO 4217 3-letter format."}}},"orderTotalAmount":{"type":"object","description":"The total order amount including all charges.","properties":{"amount":{"type":"number","format":"float","description":"The final total amount."},"currency":{"type":"string","maxLength":3,"description":"Currency in ISO 4217 3-letter format."}}},"paymentInformation":{"type":"object","description":"Payment information for the order.","properties":{"paymentMethod":{"type":"string","maxLength":45,"description":"Masked representation of the payment card, showing last 4 digits."},"billingName":{"type":"string","maxLength":50,"description":"Full name of the cardholder used for billing."},"billingAddressDetails":{"type":"object","description":"Billing address details of the cardholder.","properties":{"address1":{"type":"string","maxLength":50,"description":"Primary address line."},"address2":{"type":"string","maxLength":50,"description":"Secondary address line (optional)."},"city":{"type":"string","maxLength":50,"description":"City name."},"region":{"type":"string","maxLength":3,"description":"State, province, or region (e.g., CA, ON)."},"postalCode":{"type":"string","maxLength":9,"description":"Postal or ZIP code."},"country":{"type":"string","maxLength":3,"description":"Country in ISO 3166-1 alpha-3 format."}}},"paymentSubTotalAmount":{"type":"object","description":"Subtotal of the payment amount.","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string","maxLength":3}}},"paymentTotalBeforeTax":{"type":"object","description":"Total before tax applied.","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string","maxLength":3}}},"paymentTaxAmount":{"type":"object","description":"Tax amount applied to the payment.","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string","maxLength":3}}},"paymentTaxDescription":{"type":"string","maxLength":100,"description":"Description of the tax applied."},"paymentTotalAmount":{"type":"object","description":"Total amount charged.","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string","maxLength":3}}},"cvvChecked":{"type":"boolean","description":"Indicates whether CVV check was performed during the transaction."}}},"productsPurchasedList":{"type":"array","description":"A list of products or services purchased in the order.","minItems":1,"items":{"type":"object","required":["productDescription"],"properties":{"productType":{"type":"string","maxLength":20,"description":"Category or type of product."},"productDescription":{"type":"string","description":"Description of the product.","maxLength":1000},"productUrl":{"type":"string","format":"uri","maxLength":1000,"description":"URL to the product detail page."},"artistOrSeller":{"type":"string","maxLength":100,"description":"Name of the artist or seller of the product."},"unitPriceAmount":{"type":"object","description":"Price per unit of the item.","properties":{"amount":{"type":"number","format":"float","description":"Price for a single unit."},"currency":{"type":"string","maxLength":3,"description":"Currency in ISO 4217 3-letter format."}}},"quantity":{"type":"integer","description":"Number of units purchased."},"deliveryDetails":{"type":"object","description":"Delivery details for the item.","properties":{"shippingCarrier":{"type":"string","maxLength":45,"description":"Carrier used for shipping the product."},"trackingNumber":{"type":"string","maxLength":255,"description":"Tracking number provided by the carrier."},"dateOfShipment":{"type":"string","format":"date-time","description":"Date the item was shipped."},"dateOfDelivery":{"type":"string","format":"date-time","description":"Date the item was delivered."},"deliveryStatus":{"type":"string","maxLength":25,"description":"Current status of the delivery."},"otherStatusDescription":{"type":"string","maxLength":25,"description":"Additional description if deliveryStatus is \"OTHER\"."}}}}}}}},"merchantInformation":{"type":"object","required":["merchantName","merchantUrl","merchantContactPhone","storeDetails"],"properties":{"merchantName":{"type":"string","description":"Name of the merchant.","maxLength":100},"merchantUrl":{"type":"string","description":"URL of the merchant.","format":"uri","maxLength":1000},"websiteUrl":{"type":"string","format":"uri","maxLength":1000,"description":"The website where the consumer made the online purchase."},"merchantContactPhone":{"type":"string","description":"Contact phone number in E.164 format (e.g., +12345678901).","pattern":"^\\+[1-9]\\d{10,14}$"},"merchantAddress":{"type":"object","description":"Merchant's business mailing address.","properties":{"address1":{"type":"string","maxLength":50,"description":"Primary address line."},"address2":{"type":"string","maxLength":50,"description":"Additional address line."},"city":{"type":"string","maxLength":50,"description":"City name."},"region":{"type":"string","maxLength":3,"description":"State, province, or region (ISO 3166-2)."},"postalCode":{"type":"string","maxLength":9,"description":"ZIP or postal code."},"country":{"type":"string","maxLength":3,"description":"Country in ISO 3166-1 alpha-3 format."}}},"termsAndConditions":{"type":"string","format":"uri","maxLength":2000,"description":"URL pointing to terms and conditions."},"storeDetails":{"type":"object","required":["storeName"],"properties":{"storeName":{"type":"string","description":"Name of the store.","maxLength":100},"storeContactPhone":{"type":"string","pattern":"^\\+[1-9]\\d{10,14}$","description":"Customer service phone number for the store, in E.164 format."},"storeLocation":{"type":"object","description":"Physical store location (for card-present transactions).","properties":{"geoLocation":{"type":"object","description":"Geographic location of the store.","properties":{"latitude":{"type":"string","maxLength":10,"description":"Latitude in signed decimal degrees (DDD.dddd)."},"longitude":{"type":"string","maxLength":10,"description":"Longitude in signed decimal degrees (DDD.dddd)."}}},"locationAddress":{"type":"object","description":"Address of the store.","properties":{"address1":{"type":"string","maxLength":50,"description":"Primary address line."},"address2":{"type":"string","maxLength":50,"description":"Secondary address line."},"city":{"type":"string","maxLength":50,"description":"City name."},"region":{"type":"string","maxLength":3,"description":"State/province/region."},"postalCode":{"type":"string","maxLength":9,"description":"ZIP or postal code."},"country":{"type":"string","maxLength":3,"description":"Country in ISO 3166-1 alpha-3 format."}}}}}}}}},"customerInformation":{"type":"object","description":"Customer information.","properties":{"accountId":{"type":"string","description":"Customer account identifier. Required for Compelling Evidence(CE).","maxLength":50},"emailAddress":{"type":"string","format":"email","description":"Customer email address."},"firstName":{"type":"string","description":"Customer's first name."},"lastName":{"type":"string","description":"Customer's last name."},"lengthOfRelationship":{"type":"string","description":"Length of relationship with the Merchant in number of months."}}},"deliveryAddress":{"type":"object","description":"Delivery Address. Required for Compelling Evidence(CE).","properties":{"address1":{"type":"string","description":"Primary address line. Required for Compelling Evidence(CE).","maxLength":50},"address2":{"type":"string","maxLength":50,"description":"Secondary address line."},"city":{"type":"string","maxLength":50,"description":"City name. Required for Compelling Evidence(CE)."},"region":{"type":"string","maxLength":3,"description":"State/province/region. Required for Compelling Evidence(CE)."},"postalCode":{"type":"string","maxLength":9,"description":"ZIP or postal code. Required for Compelling Evidence(CE)."},"country":{"type":"string","maxLength":3,"description":"Country in ISO 3166-1 alpha-3 format. Required for Compelling Evidence(CE)."}}},"recipientCustomerName":{"type":"string","description":"Name of the recipient customer.","maxLength":20},"device":{"type":"object","description":"Device details. Required for Compelling Evidence(CE).","properties":{"deviceId":{"type":"string","description":"Device identifier. Required for Compelling Evidence(CE).","minLength":15,"maxLength":32},"devicename":{"type":"string","description":"Name of the device.","maxLength":50},"deviceType":{"type":"string","description":"Type of device (e.g., mobile, desktop).","maxLength":20},"ipAddress":{"type":"string","format":"ipv4","description":"IP address of the device. Required for Compelling Evidence(CE).","maxLength":45},"deviceFingerprint":{"type":"string","description":"Fingerprint of the device. Required for Compelling Evidence(CE).","maxLength":45},"deviceLocation":{"type":"object","description":"Location of the device.","properties":{"geoLocation":{"type":"object","description":"Geographic location of the device.","properties":{"latitude":{"type":"string","maxLength":10,"description":"Latitude in signed decimal degrees (DDD.dddd)."},"longitude":{"type":"string","maxLength":10,"description":"Longitude in signed decimal degrees (DDD.dddd)."}}}}}}},"flightDetails":{"description":"Information about flight(s) associated with the purchase.","type":"object","properties":{"reservationNumber":{"type":"string","maxLength":50},"reservationDate":{"type":"string","format":"date-time"},"memberRewardsNumber":{"type":"string","maxLength":20},"memberRewardsName":{"type":"string","maxLength":50},"passengerName1":{"type":"string","maxLength":50},"passengerName2":{"type":"string","maxLength":50},"passengerName3":{"type":"string","maxLength":50},"passengerName4":{"type":"string","maxLength":50},"passengerName5":{"type":"string","maxLength":50},"itinerary":{"type":"string","description":"Flight itinerary details.","maxLength":2000},"additionalRelatedPurchases":{"type":"integer"},"flightManifestName":{"type":"string","maxLength":50},"flightManifestDateOfBirth":{"type":"string","format":"date-time"},"travelUtilizationIndicator":{"type":"boolean"},"travelInsurance":{"type":"string","format":"uri","maxLength":2000},"reservationReceivedFrom":{"type":"string","maxLength":50},"termsAndConditions":{"type":"string","format":"uri","maxLength":2000}}},"hotelDetails":{"type":"object","properties":{"reservationNumber":{"type":"string","maxLength":50},"reservationDate":{"type":"string","format":"date-time"},"memberRewardsNumber":{"type":"string","maxLength":20},"memberRewardsNameRegistered":{"type":"string","maxLength":50},"checkInDate":{"type":"string","format":"date-time"},"checkOutDate":{"type":"string","format":"date-time"},"lengthOfStay":{"type":"integer"},"hotelRoomType":{"type":"string","maxLength":20},"travelInsurance":{"type":"string","maxLength":2000},"reservationReceivedFrom":{"type":"string","maxLength":50},"termsAndConditions":{"type":"string","format":"uri","maxLength":2000}}},"carRentalDetails":{"type":"object","properties":{"reservationNumber":{"type":"string","maxLength":50},"reservationDate":{"type":"string","format":"date-time"},"memberRewardsNumber":{"type":"string","maxLength":20},"memberRewardsName":{"type":"string","maxLength":50},"carRentalVehicleDescription":{"type":"string","maxLength":50},"carRentalPickupDate":{"type":"string","format":"date-time"},"carRentalPickupLocation":{"type":"object","properties":{"geoLocation":{"type":"object","properties":{"latitude":{"type":"string","maxLength":10},"longitude":{"type":"string","maxLength":10}}},"locationAddress":{"type":"object","properties":{"address1":{"type":"string","maxLength":50},"address2":{"type":"string","maxLength":50},"city":{"type":"string","maxLength":50},"region":{"type":"string","maxLength":3},"postalCode":{"type":"string","maxLength":9},"country":{"type":"string","maxLength":3}}}}},"carRentalDropOffDate":{"type":"string","format":"date-time"},"carRentalDropOffLocation":{"type":"object","properties":{"geoLocation":{"type":"object","properties":{"latitude":{"type":"string","maxLength":10},"longitude":{"type":"string","maxLength":10}}},"locationAddress":{"type":"object","properties":{"address1":{"type":"string","maxLength":50},"address2":{"type":"string","maxLength":50},"city":{"type":"string","maxLength":50},"region":{"type":"string","maxLength":3},"postalCode":{"type":"string","maxLength":9},"country":{"type":"string","maxLength":3}}}}},"travelInsurance":{"type":"string","maxLength":2000},"reservationReceivedFrom":{"type":"string","maxLength":50},"termsAndConditions":{"type":"string","format":"uri","maxLength":2000}}},"rideShareDetails":{"type":"object","properties":{"pickupLocation":{"type":"object","properties":{"geoLocation":{"type":"object","properties":{"latitude":{"type":"string","maxLength":10},"longitude":{"type":"string","maxLength":10}}},"locationAddress":{"type":"object","properties":{"address1":{"type":"string","maxLength":50},"address2":{"type":"string","maxLength":50},"city":{"type":"string","maxLength":50},"region":{"type":"string","maxLength":3},"postalCode":{"type":"string","maxLength":9},"country":{"type":"string","maxLength":3}}}}},"dropOffLocation":{"type":"object","properties":{"geoLocation":{"type":"object","properties":{"latitude":{"type":"string","maxLength":10},"longitude":{"type":"string","maxLength":10}}},"locationAddress":{"type":"object","properties":{"address1":{"type":"string","maxLength":50},"address2":{"type":"string","maxLength":50},"city":{"type":"string","maxLength":50},"region":{"type":"string","maxLength":3},"postalCode":{"type":"string","maxLength":9},"country":{"type":"string","maxLength":3}}}}},"dateOfTrip":{"type":"string","format":"date-time"},"totalAmount":{"type":"object","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string","maxLength":3}}},"vehicleDescription":{"type":"string","maxLength":50},"termsAndConditions":{"type":"string","format":"uri","maxLength":2000}}}}}}}}},"responses":{"200":{"description":"Response","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"},"txShieldOICartReference":{"type":"string"},"transactionReference":{"type":"string","description":"The merchant-supplied reference echoed back from the request."}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"403":{"description":"Forbidden - Token not authorized for this merchant","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"404":{"description":"Merchant not found","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"409":{"description":"Duplicate transactionReference for this merchant","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"msg":{"type":"string"}}}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"},"error":{"type":"string"}}}}}}}}}}}
```


# Update Transaction Details

<mark style="color:green;">`POST`</mark> `https://{baseUrl}/api/v2/merchant/{merchantId}/updateTransactionDetails`

The **Authorization Header** is required if JWT (JSON Web Token) authentication is enabled in the application configuration (`config.server.jwt_enable` is `true`). This header must contain a valid JWT token prefixed with the word "Bearer". The token is used to authenticate the request and verify that the sender is authorized to perform the requested operation.

The **Request Body** must be an array containing exactly one object. This object includes the details for updating a transaction.

This endpoint is used to update the transaction details for a specific merchant identified by `merchantId`. The update is performed on the transaction record based on the provided `txShieldOICartReference`. The updated transaction details are stored in MongoDB and, if applicable, in AWS DynamoDB.

### **Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

### Path Parameters&#x20;

| Name         | Description                        |
| ------------ | ---------------------------------- |
| `merchantId` | Merchant Id for update transaction |

### **Body**

<table data-full-width="true"><thead><tr><th>Name</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>txShieldOICartReference</code></td><td>String</td><td>True</td><td>A unique reference for the transaction that needs to be updated. This is a mandatory field.</td></tr></tbody></table>

## Update Transaction Details

> Update Merchant Transaction based on the txShieldOICartReference

```json
{"openapi":"3.0.1","info":{"title":"TxFind API's Version 2 Endpoints","version":"2.0.0"},"tags":[{"name":"Merchant","description":"Call related to merchant transaction."}],"servers":[{"url":"https://{baseUrl}","description":"Current server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/api/v2/merchant/{merchantId}/updateTransactionDetails":{"post":{"tags":["Merchant"],"summary":"Update Transaction Details","description":"Update Merchant Transaction based on the txShieldOICartReference","operationId":"merchantUpdateTransactionDetails","parameters":[{"name":"merchantId","in":"path","description":"Merchant Id for update transaction","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["txShieldOICartReference"],"properties":{"txShieldOICartReference":{"type":"string","description":"The unique reference for the transaction to be updated."},"cardBin":{"type":"string","description":"First 6 or 8 digits of the card used in the transaction."},"cardLast4":{"type":"string","description":"Last 4 digits of the card used in the transaction."},"receipt":{"type":"object","properties":{"productsPurchasedList":{"type":"array","items":{"type":"object","properties":{"productDescription":{"type":"string","description":"Updated description of the product."},"deliveryDetails":{"type":"object","properties":{"deliveryStatus":{"type":"string","description":"Updated status of the delivery."},"dateOfShipment":{"type":"string","format":"date-time","description":"Updated date the item was shipped."}}}}}}}},"customerInformation":{"type":"object","properties":{"emailAddress":{"type":"string","format":"email","description":"Updated customer email address."}}}}}}}}},"responses":{"200":{"description":"Successful update","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"msg":{"type":"string"},"txShieldOICartReference":{"type":"string"}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"500":{"description":"Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"},"error":{"type":"string"}}}}}}}}}}}
```


# Validate Cart Details

<mark style="color:green;">`POST`</mark> `https://{baseUrl}/api/v2/merchant/cartValidation`

The **Request Body** must be an array containing exactly one object. This object includes the details of the transaction and payment information.

This endpoint is used to validate the transaction details provided in a cart. It performs both general validation and mandatory field checks on the transaction data. The endpoint returns a success message if all validations pass, or detailed error messages if any validations fail.

### **Headers**

| Name         | Value              |
| ------------ | ------------------ |
| Content-Type | `application/json` |

### **Body**

<table data-full-width="true"><thead><tr><th>Name</th><th>Type</th><th>Required</th><th>Description</th></tr></thead><tbody><tr><td><code>transactionReference</code></td><td>String</td><td>True</td><td>Merchant-supplied reference identifying this transaction</td></tr><tr><td><code>arn</code></td><td>String</td><td>False</td><td>Alphanumeric string with a maximum length of 24 characters.</td></tr><tr><td><code>orderId</code></td><td>String</td><td>False</td><td>Order ID with a maximum length of 25 characters.</td></tr><tr><td><code>orderDate</code></td><td>String</td><td>False</td><td>The date of the order in ISO 8601 format. Must be a string and cannot exceed 20 characters.</td></tr><tr><td><code>paymentDescriptor</code></td><td>String</td><td>False</td><td>Descriptor for the payment, with a maximum length of 25 characters.</td></tr><tr><td><code>authorizationCode</code></td><td>String</td><td>False</td><td>Alphanumeric code with a maximum length of 6 characters.</td></tr><tr><td><code>authorizationDate</code></td><td>String</td><td>False</td><td>The date of authorization in ISO 8601 format. Must be a string and cannot exceed 25 characters.</td></tr><tr><td><code>authorizationCurrency</code></td><td>String</td><td>False</td><td>The currency of the authorization. Must be a string and cannot exceed 3 characters.</td></tr><tr><td><code>authorizationAmount</code></td><td>Number</td><td>False</td><td>The amount of the authorization. Must be a decimal value with up to 2 decimal places, and cannot exceed 13 characters.</td></tr><tr><td><code>settlementDate</code></td><td>String</td><td>False</td><td>The date of settlement in ISO 8601 format. Must be a string and cannot exceed 25 characters.</td></tr><tr><td><code>settlementCurrency</code></td><td>String</td><td>False</td><td>The currency of the settlement. Must be a string and cannot exceed 3 characters.</td></tr><tr><td><code>settleAmount</code></td><td>Number</td><td>False</td><td>The amount of the settlement. Must be a decimal value with up to 2 decimal places, and cannot exceed 13 characters.</td></tr><tr><td><code>cardBin</code></td><td>String</td><td>False</td><td>The first 6 digits of the credit card number. Must be exactly 6 characters.</td></tr><tr><td><code>cardLast4</code></td><td>String</td><td>False</td><td>The last 4 digits of the credit card number. Must be exactly 4 characters.</td></tr><tr><td><code>details</code></td><td>Object</td><td>False</td><td>Additional details related to the transaction.</td></tr><tr><td><code>details.transactionDetail</code></td><td>Object</td><td>False</td><td>Specific transaction details.</td></tr><tr><td><code>details.transactionDetail.taxAmount</code></td><td>Array</td><td>False</td><td>Array containing tax amounts.</td></tr><tr><td><code>details.transactionDetail.taxAmountCurrency</code></td><td>Array</td><td>False</td><td>Array containing tax amount currencies.</td></tr><tr><td><code>details.transactionDetail.shippingAndHandlingAmount</code></td><td>Array</td><td>False</td><td>Array containing shipping and handling amounts.</td></tr><tr><td><code>details.transactionDetail.shippingAndHandlingCurrency</code></td><td>Array</td><td>False</td><td>Array containing shipping and handling amount currencies.</td></tr><tr><td><code>details.transactionDetail.totalAmount</code></td><td>Number</td><td>False</td><td>The total amount of the transaction.</td></tr><tr><td><code>details.transactionDetail.totalAmountCurrency</code></td><td>String</td><td>False</td><td>The currency of the total amount.</td></tr><tr><td><code>details.transactionDetail.billingAddressDetails</code></td><td>Object</td><td>False</td><td>Object containing billing address details.</td></tr><tr><td><code>details.transactionDetail.billingAddressDetails.address</code></td><td>Array</td><td>False</td><td>Array containing billing address lines.</td></tr><tr><td><code>details.transactionDetail.billingAddressDetails.city</code></td><td>String</td><td>False</td><td>The city of the billing address.</td></tr><tr><td><code>details.transactionDetail.billingAddressDetails.state</code></td><td>String</td><td>False</td><td>The state of the billing address.</td></tr><tr><td><code>details.transactionDetail.billingAddressDetails.zip</code></td><td>String</td><td>False</td><td>The ZIP code of the billing address.</td></tr><tr><td><code>details.transactionDetail.billingAddressDetails.country</code></td><td>String</td><td>False</td><td>The country of the billing address.</td></tr><tr><td><code>details.transactionDetail.shippingAddressDetails</code></td><td>Array</td><td>False</td><td>Array containing shipping address details.</td></tr><tr><td><code>details.transactionDetail.avsChecked</code></td><td>Boolean</td><td>False</td><td>Whether AVS was checked or not.</td></tr><tr><td><code>details.transactionDetail.cvvChecked</code></td><td>Boolean</td><td>False</td><td>Whether CVV was checked or not.</td></tr><tr><td><code>details.transactionDetail.refundAmount</code></td><td>Number</td><td>False</td><td>The amount refunded.</td></tr><tr><td><code>details.transactionDetail.refundCurrency</code></td><td>String</td><td>False</td><td>The currency of the refund amount.</td></tr><tr><td><code>details.transactionDetail.dateOfRefund</code></td><td>String</td><td>False</td><td>The date of the refund in ISO 8601 format.</td></tr><tr><td><code>details.transactionDetail.deviceName</code></td><td>String</td><td>False</td><td>The name of the device used for the transaction.</td></tr><tr><td><code>details.transactionDetail.deviceId</code></td><td>String</td><td>False</td><td>The ID of the device used for the transaction.</td></tr><tr><td><code>details.transactionDetail.ipAddress</code></td><td>String</td><td>False</td><td>The IP address of the device used for the transaction.</td></tr><tr><td><code>details.transactionDetail.termsAndConditions</code></td><td>String</td><td>False</td><td>URL to the terms and conditions.</td></tr><tr><td><code>details.customerInformation</code></td><td>Object</td><td>False</td><td>Object containing customer information.</td></tr><tr><td><code>details.customerInformation.firstName</code></td><td>String</td><td>False</td><td>The first name of the customer.</td></tr><tr><td><code>details.customerInformation.lastName</code></td><td>String</td><td>False</td><td>The last name of the customer.</td></tr><tr><td><code>details.customerInformation.lengthOfRelationship</code></td><td>String</td><td>False</td><td>The length of the relationship with the customer.</td></tr><tr><td><code>details.customerInformation.emailAddress</code></td><td>String</td><td>False</td><td>The email address of the customer.</td></tr><tr><td><code>details.productPurchased</code></td><td>Array</td><td>False</td><td>Array containing information about the products purchased.</td></tr><tr><td><code>details.productPurchased[].productName</code></td><td>String</td><td>False</td><td>The name of the product purchased.</td></tr><tr><td><code>details.productPurchased[].productUrl</code></td><td>String</td><td>False</td><td>The URL of the product purchased.</td></tr><tr><td><code>details.productPurchased[].unitPriceCurrency</code></td><td>String</td><td>False</td><td>The currency of the unit price.</td></tr><tr><td><code>details.productPurchased[].unitPriceAmount</code></td><td>Object</td><td>False</td><td>Object containing the unit price amount and currency.</td></tr><tr><td><code>details.productPurchased[].unitPriceAmount.amount</code></td><td>Number</td><td>False</td><td>The unit price amount of the product.</td></tr><tr><td><code>details.productPurchased[].unitPriceAmount.currency</code></td><td>String</td><td>False</td><td>The currency of the unit price.</td></tr><tr><td><code>details.productPurchased[].quantity</code></td><td>String</td><td>False</td><td>The quantity of the product purchased.</td></tr><tr><td><code>details.productPurchased[].industryDetails</code></td><td>Object</td><td>False</td><td>Object containing industry-specific details such as flight or hotel details.</td></tr><tr><td><code>details.productPurchased[].industryDetails.flightDetails</code></td><td>Array</td><td>False</td><td>Array containing flight-related details.</td></tr><tr><td><code>details.productPurchased[].industryDetails.hotelDetails</code></td><td>Array</td><td>False</td><td>Array containing hotel-related details.</td></tr><tr><td><code>details.deliveryDetails</code></td><td>Object</td><td>False</td><td>Object containing delivery-related details.</td></tr><tr><td><code>details.deliveryDetails.physicalFulfillment</code></td><td>Array</td><td>False</td><td>Array containing physical fulfillment details, such as shipment and delivery information.</td></tr><tr><td><code>details.deliveryDetails.physicalFulfillment[].shippingCarrierUrl</code></td><td>String</td><td>False</td><td>The URL of the shipping carrier's tracking page.</td></tr><tr><td><code>details.deliveryDetails.physicalFulfillment[].trackingNumber</code></td><td>String</td><td>False</td><td>The tracking number provided by the shipping carrier.</td></tr><tr><td><code>details.deliveryDetails.physicalFulfillment[].dateOfShipment</code></td><td>String</td><td>False</td><td>The date the item was shipped.</td></tr><tr><td><code>details.deliveryDetails.physicalFulfillment[].dateOfDelivery</code></td><td>String</td><td>False</td><td>The date the item was delivered.</td></tr><tr><td><code>details.crmDetails</code></td><td>Array</td><td>False</td><td>Array containing customer relationship management (CRM) details.</td></tr><tr><td><code>details.crmDetails[].notes</code></td><td>String</td><td>False</td><td>Notes about the interaction.</td></tr><tr><td><code>details.attachments</code></td><td>Array</td><td>False</td><td>Array containing attachments related to the transaction.</td></tr><tr><td><code>details.attachments[].id</code></td><td>String</td><td>False</td><td>The ID of the attachment.</td></tr><tr><td><code>details.attachments[].fileName</code></td><td>String</td><td>False</td><td>The file name of the attachment.</td></tr><tr><td><code>details.attachments[].friendlyFileName</code></td><td>String</td><td>False</td><td>The friendly name of the attachment.</td></tr><tr><td><code>details.attachments[].mimeType</code></td><td>String</td><td>False</td><td>The MIME type of the attachment.</td></tr><tr><td><code>details.attachments[].receivedDate</code></td><td>String</td><td>False</td><td>The date the attachment was received.</td></tr><tr><td><code>details.attachments[].fileSource</code></td><td>String</td><td>False</td><td>The source of the file.</td></tr><tr><td><code>details.attachments[].data</code></td><td>String</td><td>False</td><td>The base64 encoded data of the attachment</td></tr></tbody></table>

## Validate Transaction Details

> Merchant Cart Validation

```json
{"openapi":"3.0.1","info":{"title":"TxFind API's Version 2 Endpoints","version":"2.0.0"},"tags":[{"name":"Merchant","description":"Call related to merchant transaction."}],"servers":[{"url":"https://{baseUrl}","description":"Current server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/api/v2/merchant/cartValidation":{"post":{"tags":["Merchant"],"summary":"Validate Transaction Details","description":"Merchant Cart Validation","operationId":"cartValidation","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","minItems":1,"maxItems":1,"items":{"type":"object","required":["transactionReference","cardBin","cardLast4","transactionDate","paymentDescriptor","receipt","merchantInformation"],"properties":{"transactionReference":{"type":"string","description":"Merchant-supplied reference identifying this transaction. Leading/trailing whitespace is trimmed before storage. Must be unique per merchant - duplicates are rejected (single endpoint returns 409; batch endpoints mark the row as error). Echoed back (trimmed) in the response so the merchant can map their reference to the txShieldOICartReference.","maxLength":100},"cardBin":{"type":"string","description":"First 6 or 8 digits of the card used in the transaction. Must be numeric.","minLength":6,"maxLength":8,"pattern":"^[0-9]+$"},"cardLast4":{"type":"string","description":"Last 4 digits of the card used in the transaction. Must be numeric.","minLength":4,"maxLength":4,"pattern":"^[0-9]+$"},"transactionDate":{"type":"string","format":"date-time","description":"The date and time of the transaction in ISO 8601 format. Must be earlier than today."},"paymentDescriptor":{"type":"string","description":"Payment descriptor identifying the transaction.","maxLength":25},"arn":{"type":"string","description":"Acquirer Reference Number.","maxLength":24},"authCode":{"type":"string","description":"Authorization code for the transaction.","maxLength":6},"receipt":{"type":"object","required":["productsPurchasedList"],"properties":{"orderDate":{"type":"string","format":"date-time","description":"The date and time when the order was placed."},"orderNumber":{"type":"string","maxLength":25,"description":"The unique identifier for the order defined by the Merchant."},"purchaseCategory":{"type":"string","maxLength":20,"description":"The type of purchase made (MERCHANDISE or SERVICE)."},"invoiceNumber":{"type":"string","maxLength":25,"description":"The invoice number related to the order."},"downloadDateTime":{"type":"string","format":"date-time","description":"The date and time when a digital download was completed, if applicable."},"subTotalAmount":{"type":"object","description":"The subtotal before tax and shipping fees.","properties":{"amount":{"type":"number","format":"float","description":"The subtotal amount."},"currency":{"type":"string","maxLength":3,"description":"Currency in ISO 4217 3-letter format."}}},"taxAmount":{"type":"object","description":"The tax amount applied to the purchase.","properties":{"amount":{"type":"number","format":"float","description":"The total tax amount."},"currency":{"type":"string","maxLength":3,"description":"Currency in ISO 4217 3-letter format."}}},"taxDescription":{"type":"string","maxLength":100,"description":"Description of the tax applied."},"shippingAndHandlingAmount":{"type":"object","description":"The shipping and handling fee amount.","properties":{"amount":{"type":"number","format":"float","description":"Shipping and handling cost."},"currency":{"type":"string","maxLength":3,"description":"Currency in ISO 4217 3-letter format."}}},"orderTotalAmount":{"type":"object","description":"The total order amount including all charges.","properties":{"amount":{"type":"number","format":"float","description":"The final total amount."},"currency":{"type":"string","maxLength":3,"description":"Currency in ISO 4217 3-letter format."}}},"paymentInformation":{"type":"object","description":"Payment information for the order.","properties":{"paymentMethod":{"type":"string","maxLength":45,"description":"Masked representation of the payment card, showing last 4 digits."},"billingName":{"type":"string","maxLength":50,"description":"Full name of the cardholder used for billing."},"billingAddressDetails":{"type":"object","description":"Billing address details of the cardholder.","properties":{"address1":{"type":"string","maxLength":50,"description":"Primary address line."},"address2":{"type":"string","maxLength":50,"description":"Secondary address line (optional)."},"city":{"type":"string","maxLength":50,"description":"City name."},"region":{"type":"string","maxLength":3,"description":"State, province, or region (e.g., CA, ON)."},"postalCode":{"type":"string","maxLength":9,"description":"Postal or ZIP code."},"country":{"type":"string","maxLength":3,"description":"Country in ISO 3166-1 alpha-3 format."}}},"paymentSubTotalAmount":{"type":"object","description":"Subtotal of the payment amount.","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string","maxLength":3}}},"paymentTotalBeforeTax":{"type":"object","description":"Total before tax applied.","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string","maxLength":3}}},"paymentTaxAmount":{"type":"object","description":"Tax amount applied to the payment.","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string","maxLength":3}}},"paymentTaxDescription":{"type":"string","maxLength":100,"description":"Description of the tax applied."},"paymentTotalAmount":{"type":"object","description":"Total amount charged.","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string","maxLength":3}}},"cvvChecked":{"type":"boolean","description":"Indicates whether CVV check was performed during the transaction."}}},"productsPurchasedList":{"type":"array","description":"A list of products or services purchased in the order.","minItems":1,"items":{"type":"object","required":["productDescription"],"properties":{"productType":{"type":"string","maxLength":20,"description":"Category or type of product."},"productDescription":{"type":"string","description":"Description of the product.","maxLength":1000},"productUrl":{"type":"string","format":"uri","maxLength":1000,"description":"URL to the product detail page."},"artistOrSeller":{"type":"string","maxLength":100,"description":"Name of the artist or seller of the product."},"unitPriceAmount":{"type":"object","description":"Price per unit of the item.","properties":{"amount":{"type":"number","format":"float","description":"Price for a single unit."},"currency":{"type":"string","maxLength":3,"description":"Currency in ISO 4217 3-letter format."}}},"quantity":{"type":"integer","description":"Number of units purchased."},"deliveryDetails":{"type":"object","description":"Delivery details for the item.","properties":{"shippingCarrier":{"type":"string","maxLength":45,"description":"Carrier used for shipping the product."},"trackingNumber":{"type":"string","maxLength":255,"description":"Tracking number provided by the carrier."},"dateOfShipment":{"type":"string","format":"date-time","description":"Date the item was shipped."},"dateOfDelivery":{"type":"string","format":"date-time","description":"Date the item was delivered."},"deliveryStatus":{"type":"string","maxLength":25,"description":"Current status of the delivery."},"otherStatusDescription":{"type":"string","maxLength":25,"description":"Additional description if deliveryStatus is \"OTHER\"."}}}}}}}},"merchantInformation":{"type":"object","required":["merchantName","merchantUrl","merchantContactPhone","storeDetails"],"properties":{"merchantName":{"type":"string","description":"Name of the merchant.","maxLength":100},"merchantUrl":{"type":"string","description":"URL of the merchant.","format":"uri","maxLength":1000},"websiteUrl":{"type":"string","format":"uri","maxLength":1000,"description":"The website where the consumer made the online purchase."},"merchantContactPhone":{"type":"string","description":"Contact phone number in E.164 format (e.g., +12345678901).","pattern":"^\\+[1-9]\\d{10,14}$"},"merchantAddress":{"type":"object","description":"Merchant's business mailing address.","properties":{"address1":{"type":"string","maxLength":50,"description":"Primary address line."},"address2":{"type":"string","maxLength":50,"description":"Additional address line."},"city":{"type":"string","maxLength":50,"description":"City name."},"region":{"type":"string","maxLength":3,"description":"State, province, or region (ISO 3166-2)."},"postalCode":{"type":"string","maxLength":9,"description":"ZIP or postal code."},"country":{"type":"string","maxLength":3,"description":"Country in ISO 3166-1 alpha-3 format."}}},"termsAndConditions":{"type":"string","format":"uri","maxLength":2000,"description":"URL pointing to terms and conditions."},"storeDetails":{"type":"object","required":["storeName"],"properties":{"storeName":{"type":"string","description":"Name of the store.","maxLength":100},"storeContactPhone":{"type":"string","pattern":"^\\+[1-9]\\d{10,14}$","description":"Customer service phone number for the store, in E.164 format."},"storeLocation":{"type":"object","description":"Physical store location (for card-present transactions).","properties":{"geoLocation":{"type":"object","description":"Geographic location of the store.","properties":{"latitude":{"type":"string","maxLength":10,"description":"Latitude in signed decimal degrees (DDD.dddd)."},"longitude":{"type":"string","maxLength":10,"description":"Longitude in signed decimal degrees (DDD.dddd)."}}},"locationAddress":{"type":"object","description":"Address of the store.","properties":{"address1":{"type":"string","maxLength":50,"description":"Primary address line."},"address2":{"type":"string","maxLength":50,"description":"Secondary address line."},"city":{"type":"string","maxLength":50,"description":"City name."},"region":{"type":"string","maxLength":3,"description":"State/province/region."},"postalCode":{"type":"string","maxLength":9,"description":"ZIP or postal code."},"country":{"type":"string","maxLength":3,"description":"Country in ISO 3166-1 alpha-3 format."}}}}}}}}},"customerInformation":{"type":"object","description":"Customer information.","properties":{"accountId":{"type":"string","description":"Customer account identifier. Required for Compelling Evidence(CE).","maxLength":50},"emailAddress":{"type":"string","format":"email","description":"Customer email address."},"firstName":{"type":"string","description":"Customer's first name."},"lastName":{"type":"string","description":"Customer's last name."},"lengthOfRelationship":{"type":"string","description":"Length of relationship with the Merchant in number of months."}}},"deliveryAddress":{"type":"object","description":"Delivery Address. Required for Compelling Evidence(CE).","properties":{"address1":{"type":"string","description":"Primary address line. Required for Compelling Evidence(CE).","maxLength":50},"address2":{"type":"string","maxLength":50,"description":"Secondary address line."},"city":{"type":"string","maxLength":50,"description":"City name. Required for Compelling Evidence(CE)."},"region":{"type":"string","maxLength":3,"description":"State/province/region. Required for Compelling Evidence(CE)."},"postalCode":{"type":"string","maxLength":9,"description":"ZIP or postal code. Required for Compelling Evidence(CE)."},"country":{"type":"string","maxLength":3,"description":"Country in ISO 3166-1 alpha-3 format. Required for Compelling Evidence(CE)."}}},"recipientCustomerName":{"type":"string","description":"Name of the recipient customer.","maxLength":20},"device":{"type":"object","description":"Device details. Required for Compelling Evidence(CE).","properties":{"deviceId":{"type":"string","description":"Device identifier. Required for Compelling Evidence(CE).","minLength":15,"maxLength":32},"devicename":{"type":"string","description":"Name of the device.","maxLength":50},"deviceType":{"type":"string","description":"Type of device (e.g., mobile, desktop).","maxLength":20},"ipAddress":{"type":"string","format":"ipv4","description":"IP address of the device. Required for Compelling Evidence(CE).","maxLength":45},"deviceFingerprint":{"type":"string","description":"Fingerprint of the device. Required for Compelling Evidence(CE).","maxLength":45},"deviceLocation":{"type":"object","description":"Location of the device.","properties":{"geoLocation":{"type":"object","description":"Geographic location of the device.","properties":{"latitude":{"type":"string","maxLength":10,"description":"Latitude in signed decimal degrees (DDD.dddd)."},"longitude":{"type":"string","maxLength":10,"description":"Longitude in signed decimal degrees (DDD.dddd)."}}}}}}},"flightDetails":{"description":"Information about flight(s) associated with the purchase.","type":"object","properties":{"reservationNumber":{"type":"string","maxLength":50},"reservationDate":{"type":"string","format":"date-time"},"memberRewardsNumber":{"type":"string","maxLength":20},"memberRewardsName":{"type":"string","maxLength":50},"passengerName1":{"type":"string","maxLength":50},"passengerName2":{"type":"string","maxLength":50},"passengerName3":{"type":"string","maxLength":50},"passengerName4":{"type":"string","maxLength":50},"passengerName5":{"type":"string","maxLength":50},"itinerary":{"type":"string","description":"Flight itinerary details.","maxLength":2000},"additionalRelatedPurchases":{"type":"integer"},"flightManifestName":{"type":"string","maxLength":50},"flightManifestDateOfBirth":{"type":"string","format":"date-time"},"travelUtilizationIndicator":{"type":"boolean"},"travelInsurance":{"type":"string","format":"uri","maxLength":2000},"reservationReceivedFrom":{"type":"string","maxLength":50},"termsAndConditions":{"type":"string","format":"uri","maxLength":2000}}},"hotelDetails":{"type":"object","properties":{"reservationNumber":{"type":"string","maxLength":50},"reservationDate":{"type":"string","format":"date-time"},"memberRewardsNumber":{"type":"string","maxLength":20},"memberRewardsNameRegistered":{"type":"string","maxLength":50},"checkInDate":{"type":"string","format":"date-time"},"checkOutDate":{"type":"string","format":"date-time"},"lengthOfStay":{"type":"integer"},"hotelRoomType":{"type":"string","maxLength":20},"travelInsurance":{"type":"string","maxLength":2000},"reservationReceivedFrom":{"type":"string","maxLength":50},"termsAndConditions":{"type":"string","format":"uri","maxLength":2000}}},"carRentalDetails":{"type":"object","properties":{"reservationNumber":{"type":"string","maxLength":50},"reservationDate":{"type":"string","format":"date-time"},"memberRewardsNumber":{"type":"string","maxLength":20},"memberRewardsName":{"type":"string","maxLength":50},"carRentalVehicleDescription":{"type":"string","maxLength":50},"carRentalPickupDate":{"type":"string","format":"date-time"},"carRentalPickupLocation":{"type":"object","properties":{"geoLocation":{"type":"object","properties":{"latitude":{"type":"string","maxLength":10},"longitude":{"type":"string","maxLength":10}}},"locationAddress":{"type":"object","properties":{"address1":{"type":"string","maxLength":50},"address2":{"type":"string","maxLength":50},"city":{"type":"string","maxLength":50},"region":{"type":"string","maxLength":3},"postalCode":{"type":"string","maxLength":9},"country":{"type":"string","maxLength":3}}}}},"carRentalDropOffDate":{"type":"string","format":"date-time"},"carRentalDropOffLocation":{"type":"object","properties":{"geoLocation":{"type":"object","properties":{"latitude":{"type":"string","maxLength":10},"longitude":{"type":"string","maxLength":10}}},"locationAddress":{"type":"object","properties":{"address1":{"type":"string","maxLength":50},"address2":{"type":"string","maxLength":50},"city":{"type":"string","maxLength":50},"region":{"type":"string","maxLength":3},"postalCode":{"type":"string","maxLength":9},"country":{"type":"string","maxLength":3}}}}},"travelInsurance":{"type":"string","maxLength":2000},"reservationReceivedFrom":{"type":"string","maxLength":50},"termsAndConditions":{"type":"string","format":"uri","maxLength":2000}}},"rideShareDetails":{"type":"object","properties":{"pickupLocation":{"type":"object","properties":{"geoLocation":{"type":"object","properties":{"latitude":{"type":"string","maxLength":10},"longitude":{"type":"string","maxLength":10}}},"locationAddress":{"type":"object","properties":{"address1":{"type":"string","maxLength":50},"address2":{"type":"string","maxLength":50},"city":{"type":"string","maxLength":50},"region":{"type":"string","maxLength":3},"postalCode":{"type":"string","maxLength":9},"country":{"type":"string","maxLength":3}}}}},"dropOffLocation":{"type":"object","properties":{"geoLocation":{"type":"object","properties":{"latitude":{"type":"string","maxLength":10},"longitude":{"type":"string","maxLength":10}}},"locationAddress":{"type":"object","properties":{"address1":{"type":"string","maxLength":50},"address2":{"type":"string","maxLength":50},"city":{"type":"string","maxLength":50},"region":{"type":"string","maxLength":3},"postalCode":{"type":"string","maxLength":9},"country":{"type":"string","maxLength":3}}}}},"dateOfTrip":{"type":"string","format":"date-time"},"totalAmount":{"type":"object","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string","maxLength":3}}},"vehicleDescription":{"type":"string","maxLength":50},"termsAndConditions":{"type":"string","format":"uri","maxLength":2000}}}}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string"},"msg":{"type":"string"}}}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"default":{"description":"Error Payload","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}}}}}}}
```


# Upload Transaction Batch

<mark style="color:green;">`POST`</mark> `https://{baseUrl}/api/v2/merchant/{merchantId}/uploadTransactionBatch`

This endpoint is used to upload and validate a batch of transactions for a specified merchant. The **Request Body** must include a json array. Each array item should contain a single transaction object.

&#x20;It performs general validation and mandatory field checks on the transaction data. If all validations pass, a success message is returned. Otherwise, detailed error messages are provided for any validation failures.

### **Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

### Path Parameters

| Name         | Description                              |
| ------------ | ---------------------------------------- |
| `merchantId` | Merchant Id for transaction batch upload |

### **Body**

<table data-full-width="true"><thead><tr><th>Name</th><th>Type</th><th width="227">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>transactionReference</code></td><td>String</td><td>True</td><td>Merchant-supplied reference identifying this transaction</td></tr><tr><td><code>transactionDate</code></td><td>Datetime (ISO 8601 format)</td><td>True</td><td>Date and time when the order was placed.</td></tr><tr><td><code>paymentDescriptor</code></td><td>String</td><td>True</td><td>Payment descriptor as it appears on the customer's statement.</td></tr><tr><td><code>cardBin</code></td><td>String</td><td>True</td><td>First six digits of the credit card used for the transaction.</td></tr><tr><td><code>cardLast4</code></td><td>String</td><td>True</td><td>Last four digits of the credit card used for the transaction.</td></tr><tr><td><code>receipt</code></td><td>Object</td><td>True</td><td>Contains detailed information about the receipt</td></tr><tr><td><code>receipt.paymentInformation</code></td><td>Object</td><td>True</td><td>Contains detailed information about the payment information</td></tr><tr><td><code>receipt.paymentInformation.paymentTotalAmount</code></td><td>Object</td><td>True</td><td>Contains detailed information about the payment total amount</td></tr><tr><td><code>receipt.paymentInformation.paymentTotalAmount.amount</code></td><td>Number</td><td>True</td><td>The payment amount</td></tr><tr><td><code>receipt.paymentInformation.paymentTotalAmount.currency</code></td><td>String</td><td>True</td><td>The payment currency</td></tr><tr><td><code>merchantInformation</code></td><td>Object</td><td>True</td><td>Contains detailed information about the merchant information</td></tr><tr><td><code>merchantInformation.merchantName</code></td><td>String</td><td>True</td><td>The merchant name</td></tr><tr><td><code>merchantInformation.merchantUrl</code></td><td>String</td><td>True</td><td>The merchant url</td></tr><tr><td><code>merchantInformation.merchantContactPhone</code></td><td>String</td><td>True</td><td>The merchant contact phone</td></tr><tr><td><code>merchantInformation.storeDetails.storeName</code></td><td>String</td><td>True</td><td>The store name</td></tr><tr><td><code>deliveryAddress</code></td><td>Object</td><td>True</td><td>Contains detailed information about the delivery address</td></tr><tr><td><code>deliveryAddress.address1</code></td><td>String</td><td>True</td><td>The delivery address</td></tr><tr><td><code>deliveryAddress.city</code></td><td>String</td><td>True</td><td>The delivery city</td></tr><tr><td><code>deliveryAddress.region</code></td><td>String</td><td>True</td><td>The delivery region</td></tr><tr><td><code>deliveryAddress.postalCode</code></td><td>String</td><td>True</td><td>The delivery postal code</td></tr><tr><td><code>deliveryAddress.country</code></td><td>String</td><td>True</td><td>The delivery country</td></tr><tr><td><code>device</code></td><td>Object</td><td>True</td><td>Contains detailed information about the device</td></tr><tr><td><code>device.deviceId</code></td><td>String</td><td>True</td><td>The device id</td></tr><tr><td><code>device.ipAddress</code></td><td>String</td><td>True</td><td>The device ip address</td></tr><tr><td><code>device.deviceFingerprint</code></td><td>String</td><td>True (Conditionally)</td><td>The device fingerprint</td></tr></tbody></table>

## Upload Transaction Batch

> Upload a batch of merchant transactions as JSON.

```json
{"openapi":"3.0.1","info":{"title":"TxFind API's Version 2 Endpoints","version":"2.0.0"},"tags":[{"name":"Merchant","description":"Call related to merchant transaction."}],"servers":[{"url":"https://{baseUrl}","description":"Current server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/api/v2/merchant/{merchantId}/uploadTransactionBatch":{"post":{"tags":["Merchant"],"summary":"Upload Transaction Batch","description":"Upload a batch of merchant transactions as JSON.","operationId":"merchantUploadTransactionBatch","parameters":[{"name":"merchantId","in":"path","description":"Merchant Id for transaction batch upload","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"array","minItems":1,"items":{"type":"object","required":["transactionReference","cardBin","cardLast4","transactionDate","paymentDescriptor","receipt","merchantInformation"],"properties":{"transactionReference":{"type":"string","description":"Merchant-supplied reference identifying this transaction. Leading/trailing whitespace is trimmed before storage. Must be unique per merchant - duplicates are rejected (single endpoint returns 409; batch endpoints mark the row as error). Echoed back (trimmed) in the response so the merchant can map their reference to the txShieldOICartReference.","maxLength":100},"cardBin":{"type":"string","description":"First 6 or 8 digits of the card used in the transaction. Must be numeric.","minLength":6,"maxLength":8,"pattern":"^[0-9]+$"},"cardLast4":{"type":"string","description":"Last 4 digits of the card used in the transaction. Must be numeric.","minLength":4,"maxLength":4,"pattern":"^[0-9]+$"},"transactionDate":{"type":"string","format":"date-time","description":"The date and time of the transaction in ISO 8601 format. Must be earlier than today."},"paymentDescriptor":{"type":"string","description":"Payment descriptor identifying the transaction.","maxLength":25},"arn":{"type":"string","description":"Acquirer Reference Number.","maxLength":24},"authCode":{"type":"string","description":"Authorization code for the transaction.","maxLength":6},"receipt":{"type":"object","required":["productsPurchasedList"],"properties":{"orderDate":{"type":"string","format":"date-time","description":"The date and time when the order was placed."},"orderNumber":{"type":"string","maxLength":25,"description":"The unique identifier for the order defined by the Merchant."},"purchaseCategory":{"type":"string","maxLength":20,"description":"The type of purchase made (MERCHANDISE or SERVICE)."},"invoiceNumber":{"type":"string","maxLength":25,"description":"The invoice number related to the order."},"downloadDateTime":{"type":"string","format":"date-time","description":"The date and time when a digital download was completed, if applicable."},"subTotalAmount":{"type":"object","description":"The subtotal before tax and shipping fees.","properties":{"amount":{"type":"number","format":"float","description":"The subtotal amount."},"currency":{"type":"string","maxLength":3,"description":"Currency in ISO 4217 3-letter format."}}},"taxAmount":{"type":"object","description":"The tax amount applied to the purchase.","properties":{"amount":{"type":"number","format":"float","description":"The total tax amount."},"currency":{"type":"string","maxLength":3,"description":"Currency in ISO 4217 3-letter format."}}},"taxDescription":{"type":"string","maxLength":100,"description":"Description of the tax applied."},"shippingAndHandlingAmount":{"type":"object","description":"The shipping and handling fee amount.","properties":{"amount":{"type":"number","format":"float","description":"Shipping and handling cost."},"currency":{"type":"string","maxLength":3,"description":"Currency in ISO 4217 3-letter format."}}},"orderTotalAmount":{"type":"object","description":"The total order amount including all charges.","properties":{"amount":{"type":"number","format":"float","description":"The final total amount."},"currency":{"type":"string","maxLength":3,"description":"Currency in ISO 4217 3-letter format."}}},"paymentInformation":{"type":"object","description":"Payment information for the order.","properties":{"paymentMethod":{"type":"string","maxLength":45,"description":"Masked representation of the payment card, showing last 4 digits."},"billingName":{"type":"string","maxLength":50,"description":"Full name of the cardholder used for billing."},"billingAddressDetails":{"type":"object","description":"Billing address details of the cardholder.","properties":{"address1":{"type":"string","maxLength":50,"description":"Primary address line."},"address2":{"type":"string","maxLength":50,"description":"Secondary address line (optional)."},"city":{"type":"string","maxLength":50,"description":"City name."},"region":{"type":"string","maxLength":3,"description":"State, province, or region (e.g., CA, ON)."},"postalCode":{"type":"string","maxLength":9,"description":"Postal or ZIP code."},"country":{"type":"string","maxLength":3,"description":"Country in ISO 3166-1 alpha-3 format."}}},"paymentSubTotalAmount":{"type":"object","description":"Subtotal of the payment amount.","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string","maxLength":3}}},"paymentTotalBeforeTax":{"type":"object","description":"Total before tax applied.","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string","maxLength":3}}},"paymentTaxAmount":{"type":"object","description":"Tax amount applied to the payment.","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string","maxLength":3}}},"paymentTaxDescription":{"type":"string","maxLength":100,"description":"Description of the tax applied."},"paymentTotalAmount":{"type":"object","description":"Total amount charged.","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string","maxLength":3}}},"cvvChecked":{"type":"boolean","description":"Indicates whether CVV check was performed during the transaction."}}},"productsPurchasedList":{"type":"array","description":"A list of products or services purchased in the order.","minItems":1,"items":{"type":"object","required":["productDescription"],"properties":{"productType":{"type":"string","maxLength":20,"description":"Category or type of product."},"productDescription":{"type":"string","description":"Description of the product.","maxLength":1000},"productUrl":{"type":"string","format":"uri","maxLength":1000,"description":"URL to the product detail page."},"artistOrSeller":{"type":"string","maxLength":100,"description":"Name of the artist or seller of the product."},"unitPriceAmount":{"type":"object","description":"Price per unit of the item.","properties":{"amount":{"type":"number","format":"float","description":"Price for a single unit."},"currency":{"type":"string","maxLength":3,"description":"Currency in ISO 4217 3-letter format."}}},"quantity":{"type":"integer","description":"Number of units purchased."},"deliveryDetails":{"type":"object","description":"Delivery details for the item.","properties":{"shippingCarrier":{"type":"string","maxLength":45,"description":"Carrier used for shipping the product."},"trackingNumber":{"type":"string","maxLength":255,"description":"Tracking number provided by the carrier."},"dateOfShipment":{"type":"string","format":"date-time","description":"Date the item was shipped."},"dateOfDelivery":{"type":"string","format":"date-time","description":"Date the item was delivered."},"deliveryStatus":{"type":"string","maxLength":25,"description":"Current status of the delivery."},"otherStatusDescription":{"type":"string","maxLength":25,"description":"Additional description if deliveryStatus is \"OTHER\"."}}}}}}}},"merchantInformation":{"type":"object","required":["merchantName","merchantUrl","merchantContactPhone","storeDetails"],"properties":{"merchantName":{"type":"string","description":"Name of the merchant.","maxLength":100},"merchantUrl":{"type":"string","description":"URL of the merchant.","format":"uri","maxLength":1000},"websiteUrl":{"type":"string","format":"uri","maxLength":1000,"description":"The website where the consumer made the online purchase."},"merchantContactPhone":{"type":"string","description":"Contact phone number in E.164 format (e.g., +12345678901).","pattern":"^\\+[1-9]\\d{10,14}$"},"merchantAddress":{"type":"object","description":"Merchant's business mailing address.","properties":{"address1":{"type":"string","maxLength":50,"description":"Primary address line."},"address2":{"type":"string","maxLength":50,"description":"Additional address line."},"city":{"type":"string","maxLength":50,"description":"City name."},"region":{"type":"string","maxLength":3,"description":"State, province, or region (ISO 3166-2)."},"postalCode":{"type":"string","maxLength":9,"description":"ZIP or postal code."},"country":{"type":"string","maxLength":3,"description":"Country in ISO 3166-1 alpha-3 format."}}},"termsAndConditions":{"type":"string","format":"uri","maxLength":2000,"description":"URL pointing to terms and conditions."},"storeDetails":{"type":"object","required":["storeName"],"properties":{"storeName":{"type":"string","description":"Name of the store.","maxLength":100},"storeContactPhone":{"type":"string","pattern":"^\\+[1-9]\\d{10,14}$","description":"Customer service phone number for the store, in E.164 format."},"storeLocation":{"type":"object","description":"Physical store location (for card-present transactions).","properties":{"geoLocation":{"type":"object","description":"Geographic location of the store.","properties":{"latitude":{"type":"string","maxLength":10,"description":"Latitude in signed decimal degrees (DDD.dddd)."},"longitude":{"type":"string","maxLength":10,"description":"Longitude in signed decimal degrees (DDD.dddd)."}}},"locationAddress":{"type":"object","description":"Address of the store.","properties":{"address1":{"type":"string","maxLength":50,"description":"Primary address line."},"address2":{"type":"string","maxLength":50,"description":"Secondary address line."},"city":{"type":"string","maxLength":50,"description":"City name."},"region":{"type":"string","maxLength":3,"description":"State/province/region."},"postalCode":{"type":"string","maxLength":9,"description":"ZIP or postal code."},"country":{"type":"string","maxLength":3,"description":"Country in ISO 3166-1 alpha-3 format."}}}}}}}}},"customerInformation":{"type":"object","description":"Customer information.","properties":{"accountId":{"type":"string","description":"Customer account identifier. Required for Compelling Evidence(CE).","maxLength":50},"emailAddress":{"type":"string","format":"email","description":"Customer email address."},"firstName":{"type":"string","description":"Customer's first name."},"lastName":{"type":"string","description":"Customer's last name."},"lengthOfRelationship":{"type":"string","description":"Length of relationship with the Merchant in number of months."}}},"deliveryAddress":{"type":"object","description":"Delivery Address. Required for Compelling Evidence(CE).","properties":{"address1":{"type":"string","description":"Primary address line. Required for Compelling Evidence(CE).","maxLength":50},"address2":{"type":"string","maxLength":50,"description":"Secondary address line."},"city":{"type":"string","maxLength":50,"description":"City name. Required for Compelling Evidence(CE)."},"region":{"type":"string","maxLength":3,"description":"State/province/region. Required for Compelling Evidence(CE)."},"postalCode":{"type":"string","maxLength":9,"description":"ZIP or postal code. Required for Compelling Evidence(CE)."},"country":{"type":"string","maxLength":3,"description":"Country in ISO 3166-1 alpha-3 format. Required for Compelling Evidence(CE)."}}},"recipientCustomerName":{"type":"string","description":"Name of the recipient customer.","maxLength":20},"device":{"type":"object","description":"Device details. Required for Compelling Evidence(CE).","properties":{"deviceId":{"type":"string","description":"Device identifier. Required for Compelling Evidence(CE).","minLength":15,"maxLength":32},"devicename":{"type":"string","description":"Name of the device.","maxLength":50},"deviceType":{"type":"string","description":"Type of device (e.g., mobile, desktop).","maxLength":20},"ipAddress":{"type":"string","format":"ipv4","description":"IP address of the device. Required for Compelling Evidence(CE).","maxLength":45},"deviceFingerprint":{"type":"string","description":"Fingerprint of the device. Required for Compelling Evidence(CE).","maxLength":45},"deviceLocation":{"type":"object","description":"Location of the device.","properties":{"geoLocation":{"type":"object","description":"Geographic location of the device.","properties":{"latitude":{"type":"string","maxLength":10,"description":"Latitude in signed decimal degrees (DDD.dddd)."},"longitude":{"type":"string","maxLength":10,"description":"Longitude in signed decimal degrees (DDD.dddd)."}}}}}}},"flightDetails":{"description":"Information about flight(s) associated with the purchase.","type":"object","properties":{"reservationNumber":{"type":"string","maxLength":50},"reservationDate":{"type":"string","format":"date-time"},"memberRewardsNumber":{"type":"string","maxLength":20},"memberRewardsName":{"type":"string","maxLength":50},"passengerName1":{"type":"string","maxLength":50},"passengerName2":{"type":"string","maxLength":50},"passengerName3":{"type":"string","maxLength":50},"passengerName4":{"type":"string","maxLength":50},"passengerName5":{"type":"string","maxLength":50},"itinerary":{"type":"string","description":"Flight itinerary details.","maxLength":2000},"additionalRelatedPurchases":{"type":"integer"},"flightManifestName":{"type":"string","maxLength":50},"flightManifestDateOfBirth":{"type":"string","format":"date-time"},"travelUtilizationIndicator":{"type":"boolean"},"travelInsurance":{"type":"string","format":"uri","maxLength":2000},"reservationReceivedFrom":{"type":"string","maxLength":50},"termsAndConditions":{"type":"string","format":"uri","maxLength":2000}}},"hotelDetails":{"type":"object","properties":{"reservationNumber":{"type":"string","maxLength":50},"reservationDate":{"type":"string","format":"date-time"},"memberRewardsNumber":{"type":"string","maxLength":20},"memberRewardsNameRegistered":{"type":"string","maxLength":50},"checkInDate":{"type":"string","format":"date-time"},"checkOutDate":{"type":"string","format":"date-time"},"lengthOfStay":{"type":"integer"},"hotelRoomType":{"type":"string","maxLength":20},"travelInsurance":{"type":"string","maxLength":2000},"reservationReceivedFrom":{"type":"string","maxLength":50},"termsAndConditions":{"type":"string","format":"uri","maxLength":2000}}},"carRentalDetails":{"type":"object","properties":{"reservationNumber":{"type":"string","maxLength":50},"reservationDate":{"type":"string","format":"date-time"},"memberRewardsNumber":{"type":"string","maxLength":20},"memberRewardsName":{"type":"string","maxLength":50},"carRentalVehicleDescription":{"type":"string","maxLength":50},"carRentalPickupDate":{"type":"string","format":"date-time"},"carRentalPickupLocation":{"type":"object","properties":{"geoLocation":{"type":"object","properties":{"latitude":{"type":"string","maxLength":10},"longitude":{"type":"string","maxLength":10}}},"locationAddress":{"type":"object","properties":{"address1":{"type":"string","maxLength":50},"address2":{"type":"string","maxLength":50},"city":{"type":"string","maxLength":50},"region":{"type":"string","maxLength":3},"postalCode":{"type":"string","maxLength":9},"country":{"type":"string","maxLength":3}}}}},"carRentalDropOffDate":{"type":"string","format":"date-time"},"carRentalDropOffLocation":{"type":"object","properties":{"geoLocation":{"type":"object","properties":{"latitude":{"type":"string","maxLength":10},"longitude":{"type":"string","maxLength":10}}},"locationAddress":{"type":"object","properties":{"address1":{"type":"string","maxLength":50},"address2":{"type":"string","maxLength":50},"city":{"type":"string","maxLength":50},"region":{"type":"string","maxLength":3},"postalCode":{"type":"string","maxLength":9},"country":{"type":"string","maxLength":3}}}}},"travelInsurance":{"type":"string","maxLength":2000},"reservationReceivedFrom":{"type":"string","maxLength":50},"termsAndConditions":{"type":"string","format":"uri","maxLength":2000}}},"rideShareDetails":{"type":"object","properties":{"pickupLocation":{"type":"object","properties":{"geoLocation":{"type":"object","properties":{"latitude":{"type":"string","maxLength":10},"longitude":{"type":"string","maxLength":10}}},"locationAddress":{"type":"object","properties":{"address1":{"type":"string","maxLength":50},"address2":{"type":"string","maxLength":50},"city":{"type":"string","maxLength":50},"region":{"type":"string","maxLength":3},"postalCode":{"type":"string","maxLength":9},"country":{"type":"string","maxLength":3}}}}},"dropOffLocation":{"type":"object","properties":{"geoLocation":{"type":"object","properties":{"latitude":{"type":"string","maxLength":10},"longitude":{"type":"string","maxLength":10}}},"locationAddress":{"type":"object","properties":{"address1":{"type":"string","maxLength":50},"address2":{"type":"string","maxLength":50},"city":{"type":"string","maxLength":50},"region":{"type":"string","maxLength":3},"postalCode":{"type":"string","maxLength":9},"country":{"type":"string","maxLength":3}}}}},"dateOfTrip":{"type":"string","format":"date-time"},"totalAmount":{"type":"object","properties":{"amount":{"type":"number","format":"float"},"currency":{"type":"string","maxLength":3}}},"vehicleDescription":{"type":"string","maxLength":50},"termsAndConditions":{"type":"string","format":"uri","maxLength":2000}}}}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","enum":["success","error"]},"index":{"type":"integer","description":"Zero-based position of the transaction in the submitted array."},"transactionReference":{"type":"string","nullable":true,"description":"The merchant-supplied reference echoed back so each result row can be mapped to the submitted transaction."},"txShieldOICartReference":{"type":"string"},"msg":{"type":"string"}}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"},"error":{"type":"string"}}}}}}}}}}}
```


# Upload Transaction Batch File

<mark style="color:green;">`POST`</mark> `https://{base_url}/api/v2/merchant/{merchantId}/transactionBatch`

The **Request Body** must include a file named`transactionsFile`, which contains a batch of transaction details. The file should be in JSON format, with each entry representing a single transaction.

This endpoint is used to upload and validate a batch of transactions for a specified merchant. It performs general validation and mandatory field checks on the transaction data. If all validations pass, a success message is returned. Otherwise, detailed error messages are provided for any validation failures.

### **Headers**

| Name          | Value                 |
| ------------- | --------------------- |
| Content-Type  | `multipart/form-data` |
| Authorization | `Bearer <token>`      |

### Path Parameters

| Name         | Description                                   |
| ------------ | --------------------------------------------- |
| `merchantId` | Merchant Id for transaction batch file upload |

### **Body**

<table data-full-width="true"><thead><tr><th>Name</th><th>Type</th><th width="227">Required</th><th>Description</th></tr></thead><tbody><tr><td><code>transactionsFile</code></td><td>File</td><td>True</td><td>A file that contains transactions</td></tr></tbody></table>

**NOTE: The JSON file data structure inside will be the same as Upload Transaction Batch**

## Upload Transaction Batch File

> Upload a file containing a batch of merchant transactions

```json
{"openapi":"3.0.1","info":{"title":"TxFind API's Version 2 Endpoints","version":"2.0.0"},"tags":[{"name":"Merchant","description":"Call related to merchant transaction."}],"servers":[{"url":"https://{baseUrl}","description":"Current server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/api/v2/merchant/{merchantId}/transactionBatch":{"post":{"tags":["Merchant"],"summary":"Upload Transaction Batch File","description":"Upload a file containing a batch of merchant transactions","operationId":"merchantTransactionBatchFileUpload","parameters":[{"name":"merchantId","in":"path","description":"Merchant Id for transaction batch file upload","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"transactionsFile":{"type":"string","format":"binary"}}}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"},"results":{"type":"array","items":{"type":"object","properties":{"status":{"type":"string","enum":["success","error"]},"index":{"type":"integer","description":"Zero-based position of the transaction in the submitted batch"},"transactionReference":{"type":"string","nullable":true,"description":"Merchant-supplied transaction reference from the submitted record"},"txShieldOICartReference":{"type":"string","description":"PayShield-assigned UUID for the stored record (present on success)"},"msg":{"type":"string","description":"Error description (present on error)"},"reference":{"type":"string","description":"Generated UUID returned on certain error paths (e.g. DynamoDB failure after reference was assigned)"}}}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"},"error":{"type":"string"}}}}}}}}}}}
```


# Get Merchant Descriptors

<mark style="color:green;">`GET`</mark>`https://{baseUrl}/api/v2/merchant/{merchantId}/descriptors`

This endpoint retrieves all unique payment descriptors associated with a specific merchant. It first validates the presence of a merchant ID and performs an authorization check if JWT is enabled. Upon successful validation, it queries the database to find and return all descriptors for the given merchant. If no descriptors are found, a 404 error is returned. Otherwise, the endpoint returns a list of descriptors sorted by creation date. If any errors occur during execution, an appropriate error message is returned.

### **Headers**

| Name          | Value              |
| ------------- | ------------------ |
| Content-Type  | `application/json` |
| Authorization | `Bearer <token>`   |

### Path Parameters

| Name         | Description                      |
| ------------ | -------------------------------- |
| `merchantId` | Merchant Id to fetch descriptors |

## Get Merchant Descriptors

> Retrieve all unique descriptors for a specific merchant

```json
{"openapi":"3.0.1","info":{"title":"TxFind API's Version 2 Endpoints","version":"2.0.0"},"tags":[{"name":"Merchant","description":"Call related to merchant transaction."}],"servers":[{"url":"https://{baseUrl}","description":"Current server"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}}},"paths":{"/api/v2/merchant/{merchantId}/descriptors":{"get":{"tags":["Merchant"],"summary":"Get Merchant Descriptors","description":"Retrieve all unique descriptors for a specific merchant","operationId":"getMerchantDescriptors","parameters":[{"name":"merchantId","in":"path","description":"Merchant Id to fetch descriptors for","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"descriptorId":{"type":"string"},"title":{"type":"string"},"merchantId":{"type":"string"},"merchantName":{"type":"string"},"active":{"type":"boolean"},"dateCreated":{"type":"string","format":"date-time"}}}}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"403":{"description":"Forbidden - Token not authorized for this merchant","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"}}}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"type":"object","properties":{"msg":{"type":"string"},"error":{"type":"string"}}}}}}}}}}}
```


# Flag alert received

This endpoint can be used by the merchant to notify payshield that an alert was received for a transaction.

<mark style="color:green;">`POST`</mark> `https://{baseUrl}/api/v1/cart/{merchantId}/alert`

#### Path Parameters

| Name                                         | Type   | Description                                                  |
| -------------------------------------------- | ------ | ------------------------------------------------------------ |
| merchantId<mark style="color:red;">\*</mark> | String | <p>Merchant Id to check access to transaction</p><p><br></p> |

#### Request Body

| Name                    | Type   | Description                               |
| ----------------------- | ------ | ----------------------------------------- |
| txShieldOICartReference | String | Reference to cart record in order insight |
| alertReference          | String | Alert reference from merchant             |


# Flag chargeback received

This endpoint can be used by the merchant to notify payshield that a chargeback occured for a transaction.

<mark style="color:green;">`POST`</mark> `https://{baseUrl}/api/v1/cart/{merchantId}/chargeback`

#### Path Parameters

| Name                                         | Type   | Description                                                  |
| -------------------------------------------- | ------ | ------------------------------------------------------------ |
| merchantId<mark style="color:red;">\*</mark> | String | <p>Merchant Id to check access to transaction</p><p><br></p> |

#### Request Body

| Name                    | Type   | Description                               |
| ----------------------- | ------ | ----------------------------------------- |
| txShieldOICartReference | String | Reference to cart record in order insight |
| chargebackReference     | String | Chargeback reference from merchant        |


# Recommended Fields

The following is a list of recommended fields for specific Merchant categories.

x – recommended field<br>

<table data-first-column-sticky data-search="false"><thead><tr><th>API Response Fields</th><th align="center">Airline</th><th align="center">Hotel</th><th align="center">Rideshare</th><th align="center">Car Rental</th><th align="center">Digital Goods</th><th align="center">Delivery Goods</th></tr></thead><tbody><tr><td><code>billingAddressDetails.address1</code></td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr><tr><td><code>billingAddressDetails.city</code></td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr><tr><td><code>creditReimbursement.creditAmount</code></td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr><tr><td><code>orderDate</code></td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr><tr><td><code>orderNumber</code></td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr><tr><td><code>orderTotalAmount</code></td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr><tr><td><code>firstName</code></td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr><tr><td><code>lastName</code></td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr><tr><td><code>productDescription</code></td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr><tr><td><code>unitPriceAmount</code></td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td></tr><tr><td><code>quantity</code></td><td align="center">X</td><td align="center"></td><td align="center"></td><td align="center"></td><td align="center">X</td><td align="center">X</td></tr><tr><td><code>trackingNumber</code></td><td align="center"></td><td align="center"></td><td align="center"></td><td align="center"></td><td align="center"></td><td align="center">X</td></tr><tr><td><code>dateOfShipment</code></td><td align="center"></td><td align="center"></td><td align="center"></td><td align="center"></td><td align="center"></td><td align="center">X</td></tr><tr><td><code>dateOfDelivery</code></td><td align="center"></td><td align="center"></td><td align="center"></td><td align="center"></td><td align="center"></td><td align="center">X</td></tr><tr><td><code>itinerary</code></td><td align="center">X</td><td align="center"></td><td align="center"></td><td align="center"></td><td align="center"></td><td align="center"></td></tr><tr><td><code>flightDetails.memberRewardsNumber</code></td><td align="center">X</td><td align="center"></td><td align="center"></td><td align="center"></td><td align="center"></td><td align="center"></td></tr><tr><td><code>hotelDetails.reservationNumber</code></td><td align="center"></td><td align="center">X</td><td align="center"></td><td align="center"></td><td align="center"></td><td align="center"></td></tr><tr><td><code>carRentalDetails.reservationNumber</code></td><td align="center"></td><td align="center"></td><td align="center"></td><td align="center">X</td><td align="center"></td><td align="center"></td></tr><tr><td><code>hotelDetails.memberRewardsNumber</code></td><td align="center"></td><td align="center">X</td><td align="center"></td><td align="center"></td><td align="center"></td><td align="center"></td></tr><tr><td><code>reservationDate</code></td><td align="center"></td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center"></td><td align="center"></td></tr><tr><td><code>termsAndConditions</code></td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center">X</td><td align="center"></td><td align="center"></td></tr></tbody></table>


# Overview

<figure><img src="/files/cAn6Mgwk6OLB2yXq8g7S" alt="" width="375"><figcaption></figcaption></figure>

PayShield's transaction processing (also known as "TxProcess") facilitates the online processing of Credit Card, Bank Transfer, wallet and many other payment options, while supporting the many different Transaction Types associated with the payment method.\
\
PayShield's transaction processing uses the 3 main different transaction workflows / lifecycles for an online transaction.  <br>

The combination of the different transaction types, payment methods and workflows makes PayShield's transaction processing able to handle any payment integration. Currently PayShield's transaction processing has over 400 integrations to different payment processors around the globe.\
\
PayShield's transaction processing can facilitate the Authorization transaction (the transaction collecting payment) for 3D Secure transactions.\
\
Along with supporting 3D Secure Authorizations, PayShield's transaction processing has the ability for rule based processing to limit exposure to fraud, and adhere to limits enforced by payment processors, to help maintain good merchant relationships with the processor.

###

##


# Transaction Types

**PAYMENT Transactions**\
Are instant & synchronous and are typically associated with a credit card transaction such as Visa or Mastercard.

**PREAUTH/SETTLEMENT**\
Are asynchronous transactions. They are used to authorise a transaction that doesn't immediately get settled (PREAUTH). These transactions can be settled either manually or using a postback from the gateway side (SETTLEMENT). Examples are ACH, Bank deposits, wire transfers.

**AUTH/CAPTURE**\
Are the same as a PREAUTH/SETTLEMENT but updated to avoid using the phrase SETTLEMENT, which can cause confusion about the payment status.

**CREDIT Transactions**\
Are transactions in which funds are credited to a recipient's credit card. They are asynchronous transactions

**VOID Transactions**\
Are used to void a transaction. If the transaction amount has not been settled /transferred to the merchant's account, there is a chance the transaction can be voided. This typically has lower processing fees than a REFUND. Not all gateways support VOID transactions.

**REFUND Transactions**\
Once a transaction has been settled / transferred to the merchant account, the transaction can no longer be VOID, so any reversals must be done via a REFUND transaction.

Each Transaction Type has a matching set of of workflow and Integration methods. They are mapped out below.

| Transaction Type     | Synchronous / Asynchronous / Redirect | Integration Methods                |
| -------------------- | ------------------------------------- | ---------------------------------- |
| Payment              | Synchronous / Redirect                | Rest, Soap, Form Redirect / Submit |
| Preauth / Settlement | Asynchronous / Redirect               | Rest, Soap, Form Redirect / Submit |
| Auth / Capture       | Asynchronous / Redirect               | Rest, Soap, Form Redirect / Submit |
| Credit               | Asynchronous                          | Rest, Soap                         |
| Void                 | Synchronous                           | Soap                               |
| Refund               | Synchronous                           | Soap                               |


# Payment Methods

TxProcess has an extensive list of available Payment Methods. The Payment Method is a guide for which fields TxProcess will be expecting / looking at. A single Integration can have several Payment Methods available, and to distinguish between which one is being used, it is sent in in the `payby`/<mark style="background-color:blue;">`card_type`</mark> parameters.

Common current Payment Methods are

* Mastercard
* Visa
* VMC (combined Visa / Mastercard)
* CUP
* JCB
* UPOP
* AMEX
* DINERS
* DISCOVER
* REDIRECT
* ONLINEPAYMENTS
* BANK
* ACH
* WIRE


# Transaction Lifecyle / Workflow

### Synchronous

![](/files/9efWKilpLv4pJJjOhEaB)

1. Customer completes a purchase on merchant site.
2. Merchant sends all required purchase data to TxProcess&#x20;
3. TxProcess processes the purchase and sends a payment request to the Customers Issuing Bank
4. The Issuing Bank sends back whether the payment was successful or not.
5. TxProcess returns the completed payment details to the merchant's system.

Synchronous Transactions are instant payment transactions where the whole transaction life cycle is completed in one call. They are typically associated with credit card transactions such as Visa / Mastercard / CUP / JCB.

Synchronous payments are typically associated with the PAYMENT transaction type. VOID and REFUND are also synchronous calls.

### Asynchronous

![](/files/42yCV1CFWTL2NFBqKphj)

1. Customer completes a purchase on merchant site.
2. Merchant sends all required purchase data to TxProcess&#x20;
3. TxProcess processes the purchase and sends a payment request to the Customers Issuing Bank
4. The Issuing Bank sends back an acknowledgment that they have received the payment request. This does not indicate if payment is successful. Just that they have received the request.
5. TxProcess returns whether the bank has acknowledged the payment request.
6. The Issuing Bank sends a notification that the payment is now complete and whether it was successful or not.
7. TxProcess processed the payment notification and sends a notification to the merchant's system that payment is now complete, and whether it was successful or not.

Asynchronous transactions are more complex than synchronous transactions integrations but offer a lot more flexibility and integration types.

Common use cases are for Bank / Wire transfers where a transaction Id is generated and the customer has to manually transfer the money with that transaction Id as a reference, or go to a physical payments office to complete the payment.

When the payment has been confirmed, the Issuing Bank / Payment processor can automatically trigger a call at step 6 confirming payment is complete. In the case of a local Bank Transfer, you may even need to manually acknowledge the settlement in the TxProcess system and mark the transaction as complete, and TxProcess will complete step 7.

### Redirect

![](/files/QLAIDNcuXknjQ5lXbxci)

1. Customer completes a purchase on merchant site.
2. Merchant sends all required purchase data to TxProcess via either a form submit, or a form redirect. Sending the user's browser to the TxProcess server.
3. TxProcess processes the purchase data and forwards the user's browser to the Intermediary Hosted Form. This could be a different payment processors' hosted form allowing the user to enter credit card details, or an online wallet system that requires the user to validate the purchase request by logging in and confirming payment.
4. If required, after submitting the intermediary form the payment will be sent to the issuing bank.
5. The issuing bank will send back the status of the payment request. To the Intermediary
6. The Intermediary will forward the status of the payment to TxProcess&#x20;
7. TxProcess will return the status of the payment, along with the browsers window, to the Merchants system.

The redirect workflow requires that the user's browser window is redirected to the TxProcess server, and will be redirected again to some intermediate form before the transaction is complete. Redirect transactions can either by Synchronous or Asynchronous in nature. Meaning that you could have the final transaction status at the completion of the redirect flow, or you could be waiting for a SETTLEMENT/CAPTURE to come in later. It will depend on the type of integration and payment methods being used.

Common use cases for the Redirect workflow can be for using third-party wallets, where the user has an online balance that they wish to use to complete payment. Redirecting the user to another payment provider online payment form etc.


# 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="/pages/uKsJ0weFqOpYoSs7uR5U">/pages/uKsJ0weFqOpYoSs7uR5U</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>
```


# REST API

The REST API endpoints are broken into functional groups.

Some common tasks

* [create a transaction ](/transaction-processing/integrations-and-apis/rest-api/site-sid-payments#sid-singletx)
* [get list of payment options](/transaction-processing/integrations-and-apis/rest-api/site-sid-payments#payment-options)
* [check available payout balance](/transaction-processing/integrations-and-apis/rest-api/site-sid-payments#sid-payout)


# Site - SID - Payments

## Payment Options

### soap/feeapi

FeeAPI provides a way to get a list of payment methods and information for a given sid. These request should only be used server-to-server as they use the rcode.

FeeAPI will give you the cart converted to the currency of the payment method and the list of payment methods and the fields. Fields section in the response will have the input requirement for sending the transaction to the gateway.

FeeAPI differs from RawFeeAPI in that it requires the cart details. This can be very useful if you want to display the cart details to the customer in the currency that they will be paying.

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

#### Request Body

| Name                                                | Type    | Description                                                                                                  |
| --------------------------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------ |
| amount\_coupon<mark style="color:red;">\*</mark>    | String  | Coupon amount                                                                                                |
| (numerical index)<mark style="color:red;">\*</mark> | Array   | Contains information about one item in the cart (Repeat until all cart items are listed)                     |
| addfee                                              | Boolean | This will add the processing fees on top of the amount.                                                      |
| amount\_shipping<mark style="color:red;">\*</mark>  | String  | Shipping amount                                                                                              |
| country<mark style="color:red;">\*</mark>           | String  | Country of the user - will provide the list of payments available for that country                           |
| items<mark style="color:red;">\*</mark>             | Array   | Contains the cart items                                                                                      |
| amount\_purchase<mark style="color:red;">\*</mark>  | String  | Total amount of purchase                                                                                     |
| summary<mark style="color:red;">\*</mark>           | Array   | Contains a summary of cart contents                                                                          |
| fxrate\_posted<mark style="color:red;">\*</mark>    | String  | Rate used for conversion of cart currency to gw currency. Enter Buy cart currency Sell Gw currency           |
| sid<mark style="color:red;">\*</mark>               | String  | Site id (unique identifier for the web site)                                                                 |
| currency\_code<mark style="color:red;">\*</mark>    | String  | 3 digit currency code of the cart currency                                                                   |
| rcode<mark style="color:red;">\*</mark>             | String  | Site RCODE                                                                                                   |
| cart<mark style="color:red;">\*</mark>              | Array   | Information about the purchase items. This is only compulsory for feeapi, do not sent the cart to rawfeeapi. |
| amount\_tax<mark style="color:red;">\*</mark>       | String  | tax amount                                                                                                   |
| item\_desc<mark style="color:red;">\*</mark>        | String  | Item description                                                                                             |
| item\_no<mark style="color:red;">\*</mark>          | String  | Article number                                                                                               |
| amount\_unit<mark style="color:red;">\*</mark>      | String  | Unit price amount (without commas and only 2 decimals places)                                                |
| quantity<mark style="color:red;">\*</mark>          | String  | Quantity of the item                                                                                         |
| name<mark style="color:red;">\*</mark>              | String  | Category, can be used freely                                                                                 |

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

```javascript
[{
    "mxsid":"188",
    "payby":"visa",
    "title":"Visa",
    "display_title":"Test",
    "description":"\u00a0",
    "transfertime":null,
    "transferlimit":null,
    "currency_code":"USD",
    "currency_symbol":"$",
    "image":"https://txprocess.uat.ipayoptions.com/secure/dbfile.php?type=pmimg&id=1&nocache=575a36bb51db4",
    "fee":12.63,
    "cart": {
        "summary": {
            "quantity":"1",
            "amount_purchase":16.36,
            "amount_shipping":0,
            "amount_tax":0,
            "currency_code":"USD",
            "amount_shipping_posted":null,
            "amount_tax_posted":null,
            "amount_coupon_posted":null,
            "amount_coupon":0,
            "currency_symbol":"$",
            "fxrate":0.85846649
        },
        "items": [{
            "quantity":"1",
            "name":"Economy single",
            "item_no":"e1234",
            "item_desc":"Single Economy ticket LHR - ZAR",
            "amount_unit":3.73,
            "amount_unit_posted":"3.20"
        },
        {
            "name":"Processing Fees",
            "quantity":1,
            "amount_unit_posted":10.84,
            "amount_unit":12.63,
            "item_no":"",
            "item_desc":"Processing Fees"
        }]
    },
    "fields":
    {
        "card_name":
        {
            "description":"",
            "type":"text",
            "title":"Card Holder Name",
            "required":1
        },
        "card_no":
        {
            "description":"No spaces or dashes allowed",
            "type":"text",
            "title":"Card Number",
            "required":1,
            "pattern":"[0-9] { 13,19 }"
        },
        "card_cvv":
        {
            "description":"CVV",
            "type":"text",
            "title":"CVV",
            "required":1,
            "pattern":"[0-9]{3,4}"
        },
        "card_exp_month":
        {
            "description":"",
            "type":"select",
            "options":["01","02","03","04","05","06","07","08","09","10","11","12"],
            "title":"Card Expiry Month"
        },
        "card_exp_year":
        {
            "description":"",
            "type":"select",
            "options":[2016,2017,2018,2019,2020,2021,2022,2023,2024,2025,2026,2027],
            "title":"Card Expiry Year"
        }
    }
}]
```

{% endtab %}
{% endtabs %}

### soap/rawfeeapi.php

RawFeeAPI provides a way to get a list of payment methods and information for a given sid. These request should only be used server-to-server as they use the rcode.

RawFeeAPI will give you the list of payment methods and the fields. Fields section in the response will have the input requirement for sending the transaction to the gateway.

RawFeeAPI differs from FeeAPI in that it does not need the cart details.

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

#### Request Body

| Name                                       | Type   | Description                                                                        |
| ------------------------------------------ | ------ | ---------------------------------------------------------------------------------- |
| sid<mark style="color:red;">\*</mark>      | String | Site id (unique identifier for the web site)                                       |
| currency<mark style="color:red;">\*</mark> | String | 3 digit currency code. cart currency                                               |
| country<mark style="color:red;">\*</mark>  | String | Country of the user - will provide the list of payments available for that country |
| rcode<mark style="color:red;">\*</mark>    | String | Site RCODE                                                                         |

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

```javascript
[
  {
    "mxsid": "10146",
    "payby": "bpay",
    "title": "BPay",
    "display_title": null,
    "description": null,
    "transfertime": null,
    "transferlimit": null,
    "currency_code": "AUD",
    "currency_symbol": "$",
    "image": "--Logo URL--",
    "fee": {
      "srccode": "AUD",
      "destcode": "USD",
      "rate": 0.96801106010318,
      "effectivedate": "2011-04-04",   
      "flatfee": 3,
      "mdr": 1
    },
    "fields": {
      "card_no": {
        "description": "",
        "type": "hidden",
        "value": "70720297711",
        "title": ""
      },
      "description": {
        "description": "",
        "type": "span",
        "value": "--HTML String--"
      },
    }
  }
]
```

{% endtab %}
{% endtabs %}

### {sid}/getpaymentoptions

retrieves a collection of payment options that are available for this sid.

### {sid}/getpaymentoptionsfrombin

{% openapi src="/files/1u9LF7bPvfCrr8hfmbfx" path="/{sid}/getpaymentoptionfrombin" method="post" %}
[TxProcessV1.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fs4d4ErTmJJRKIfdGk2bV%2FTxProcessV1.yml?alt=media\&token=af4079fb-44fd-4acc-b178-10ee83c6802d)
{% endopenapi %}

### {sid}/getvendorpaymentoptions

{% openapi src="/files/1u9LF7bPvfCrr8hfmbfx" path="/{sid}/getvendorpaymentoptions" method="post" %}
[TxProcessV1.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fs4d4ErTmJJRKIfdGk2bV%2FTxProcessV1.yml?alt=media\&token=af4079fb-44fd-4acc-b178-10ee83c6802d)
{% endopenapi %}

## Transactions

### {sid}/singletx

{% openapi src="/files/8RoZPmGr12k3YC8LlrJs" path="/{sid}/singletx" method="post" %}
[swagger.yaml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2FquHscMMZrM9nAeU4MI91%2Fswagger.yaml?alt=media\&token=01c44baa-fa48-40f8-80fd-cbe7a9adc8e0)
{% endopenapi %}

### {sid}/flagcapture

<mark style="color:green;">`POST`</mark> `https://uat.txshield.payshield.ai/api/v1/index.php/{sid}/flagcapture`

Mark an AUTH transaction as finalised and ready to be captured.

#### Path Parameters

| Name                                  | Type    | Description |
| ------------------------------------- | ------- | ----------- |
| sid<mark style="color:red;">\*</mark> | Integer | Site ID     |

#### Request Body

| Name                                           | Type    | Description                                                                               |
| ---------------------------------------------- | ------- | ----------------------------------------------------------------------------------------- |
| parent\_txid<mark style="color:red;">\*</mark> | String  | The parent txid from the Auth transaction.                                                |
| amount<mark style="color:red;">\*</mark>       | Decimal | The amount to capture. Should be the same as the original amount in the Auth transaction. |
| hash<mark style="color:red;">\*</mark>         | String  | The md5 hash of sid+amount+rcode                                                          |

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

```javascript
{
    // Response
}
```

{% endtab %}

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

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

### {sid}/convertnpay

{% openapi src="/files/1u9LF7bPvfCrr8hfmbfx" path="/{sid}/convertnpay" method="post" %}
[TxProcessV1.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fs4d4ErTmJJRKIfdGk2bV%2FTxProcessV1.yml?alt=media\&token=af4079fb-44fd-4acc-b178-10ee83c6802d)
{% endopenapi %}

## Other

### {sid}/payout

{% openapi src="/files/1u9LF7bPvfCrr8hfmbfx" path="/{sid}/payout" method="post" %}
[TxProcessV1.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fs4d4ErTmJJRKIfdGk2bV%2FTxProcessV1.yml?alt=media\&token=af4079fb-44fd-4acc-b178-10ee83c6802d)
{% endopenapi %}

### /cardtransactions

Will search for all transactions done for the given card number either in the last 3 months, or in the month specified.

{% openapi src="/files/86gbQmJG1cyYGi3hzAv8" path="/cardtransactions" method="post" %}
[TxProcessV2.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2F4htBNt54qGKkmxdrR9WY%2FTxProcessV2.yml?alt=media\&token=3af94572-79dc-489b-8c2c-3fc0143b6be8)
{% endopenapi %}

### /cardsearchandemail

Functionally the same as /cardtransactions except that it will email a list of the transactions found to the email address stored against the transaction.

{% openapi src="/files/86gbQmJG1cyYGi3hzAv8" path="/cardsearchandemail" method="post" %}
[TxProcessV2.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2F4htBNt54qGKkmxdrR9WY%2FTxProcessV2.yml?alt=media\&token=3af94572-79dc-489b-8c2c-3fc0143b6be8)
{% endopenapi %}

### v3/{sid}/balance

Returns the available funds that the merchant can request to withdraw / have settled to them. Does not do the withdrawal, just the balance.

## Returns available balance for the sid

<mark style="color:green;">`POST`</mark> `https://uat.txshield.payshield.ai/api/v3/{sid}/balance`

Returns the available funds that the merchant can request to withdraw / have settled to them. Does not do the withdrawal, just the balance.

#### Path Parameters

| Name                                  | Type   | Description                                    |
| ------------------------------------- | ------ | ---------------------------------------------- |
| sid<mark style="color:red;">\*</mark> | String | The sid that you want to check the balance of. |

#### Request Body

| Name                                     | Type   | Description            |
| ---------------------------------------- | ------ | ---------------------- |
| object<mark style="color:red;">\*</mark> | String | The root json object.  |
| rcode                                    | String | the rcode for the sid. |

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

```javascript
{"status":"ok","sid":"18","balance":"95.76","currency":"USD"}

```

{% endtab %}
{% endtabs %}

#### Example

example json body for the call

```
{
    “rcode”: “1239ff1a10f0a0567388b5664f2dc10088848c5b999"
}
```


# Transaction - ptxid

Most of the following API's will require a PTXID(Parent Transaction ID) and are based around handling transactions once they have been created.\
\
For information on how to create a transaction via a REST call, see the [SID Section](/transaction-processing/integrations-and-apis/rest-api/site-sid-payments)

{% openapi src="/files/1u9LF7bPvfCrr8hfmbfx" path="/{ptxid}/getstatus" method="get" %}
[TxProcessV1.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fs4d4ErTmJJRKIfdGk2bV%2FTxProcessV1.yml?alt=media\&token=af4079fb-44fd-4acc-b178-10ee83c6802d)
{% endopenapi %}

{% openapi src="/files/1u9LF7bPvfCrr8hfmbfx" path="/{ptxid}/requery" method="post" %}
[TxProcessV1.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fs4d4ErTmJJRKIfdGk2bV%2FTxProcessV1.yml?alt=media\&token=af4079fb-44fd-4acc-b178-10ee83c6802d)
{% endopenapi %}

{% openapi src="/files/1u9LF7bPvfCrr8hfmbfx" path="/{ptxid}/sendauth" method="post" %}
[TxProcessV1.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fs4d4ErTmJJRKIfdGk2bV%2FTxProcessV1.yml?alt=media\&token=af4079fb-44fd-4acc-b178-10ee83c6802d)
{% endopenapi %}

{% openapi src="/files/1u9LF7bPvfCrr8hfmbfx" path="/{ptxid}/resendauth" method="get" %}
[TxProcessV1.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fs4d4ErTmJJRKIfdGk2bV%2FTxProcessV1.yml?alt=media\&token=af4079fb-44fd-4acc-b178-10ee83c6802d)
{% endopenapi %}

{% openapi src="/files/86gbQmJG1cyYGi3hzAv8" path="/gettoken" method="post" %}
[TxProcessV2.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2F4htBNt54qGKkmxdrR9WY%2FTxProcessV2.yml?alt=media\&token=3af94572-79dc-489b-8c2c-3fc0143b6be8)
{% endopenapi %}

#### processrefund

processrefund uses your Bearer token for Authentication and takes in JSON data.\
\
If the transaction is still a PREAUTH that hasn't been settled, the transaction will be VOID instead.\
\
It should be noted that you can't do a partial VOID, a VOID is for the full transaction amount. You can however do a partial refund.

{% openapi src="/files/bbtMQfp0iOHaYDgUEtJA" path="/txprocess/transaction/{parentxid}/processrefund" method="post" %}
[txprocessv3.yaml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2FJV0JC2MV9SRiqas9EKWb%2Ftxprocessv3.yaml?alt=media\&token=3e2d553a-d20b-4300-ac8f-7914764f144a)
{% endopenapi %}


# Merchant Management

API's to create and manage merchants

### Introduction

Merchants (mid) in TxShield are treated as the parent node of a Tree. The layer underneath the Merchant is the Retailer (rid) and the lowest node is a Site (sid).

Merchant --> Retailer --> Site&#x20;

A Site is the object that actions / transactions are done on, in the system.\
If I wanted to process cred card transaction, i would create a payment Site, and use the credentials for that site to [process payments.](/transaction-processing/integrations-and-apis/single-transaction-api-txhandler)\
If I wanted to 3ds Authentications, I would create a 3ds Site and use those credentials to do 3ds Authentications with the [3ds SDK.](https://docs.payshield.ai/3dsecure2+/)

To create a Merchant, you will need to call the merchant create endpoint. This will return a Merchant id (mid). \
You can then use this mid to create a Retailer by call the retailer create endpoint. This will return a Retailer Id (rid).\
Using the rid you can then create a Site by calling the site create endpoint. This will return a Site Id (sid).

### Authentication

Every call on this page requires a Bearer token to be sent in the Authorization header.\
\
You can obtain a Bearer token from the System Administrator.

## Merchant, Retailer, Site.

### Merchant Create

{% openapi src="<https://uat.txshield.payshield.ai/api/swaggerV3.php>" path="/merchant/create" method="post" %}
<https://uat.txshield.payshield.ai/api/swaggerV3.php>
{% endopenapi %}

Create a new merchant in the system. This call will return a MID that can be used to create Retailers.\
\
list of available themes can be retrieved from the [themes endpoint.](#theme-list)

\
Example JSON data.

```json
{
  "name": "New Merchant",
  "payments": true,
  "threeDS": true,
  "alerts": true,
  "cbm": true,
  "order_insights": true,
  "oi_merchant_id": "",
  "remarks": "My New Merchant",
  "themeid": 0
}
```

### Merchant Details

{% openapi src="<https://uat.txshield.payshield.ai/api/swaggerV3.php>" path="/merchant/{mid}/details" method="post" %}
<https://uat.txshield.payshield.ai/api/swaggerV3.php>
{% endopenapi %}

Returns the details of a Merchant, doesn't have any body parameters.

### Retailer Create

{% openapi src="/files/PrmllFwFzP9Cqml9ymtz" path="/retailer/mid/{mid}/create" method="post" %}
[TxProcess.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fle2FnrchW87BHp7CpriZ%2FTxProcess.yml?alt=media\&token=1665a1c4-33be-43bc-8b35-1e7c8c1bcc56)
{% endopenapi %}

Creates a new Retailer, you will need the mid of the Merchant that you want to attach the retailer too.\
\
A list of available currencies can be found at the [currency endpoint.](#currency-list)\
\
Example JSON data

```json
{
  "name": "New Retailer",
  "currency": "USD",
  "margin_percentage": 0,
  "contact_email": "myemail@contact.com",
  "remarks": "Created At xx",
  "description": "For my USD Sites"
}
```

### Retailer Details

{% openapi src="<https://uat.txshield.payshield.ai/api/swaggerV3.php>" path="/retailer/{rid}/details" method="post" %}
<https://uat.txshield.payshield.ai/api/swaggerV3.php>
{% endopenapi %}

Returns the details of a Retailer

### Site Create

{% openapi src="<https://uat.txshield.payshield.ai/api/swaggerV3.php>" path="/site/mid/{mid}/rid/{rid}/create" method="post" %}
<https://uat.txshield.payshield.ai/api/swaggerV3.php>
{% endopenapi %}

Create a new Site,  You will need the mid and rid of the merchant/retailer you want this site attached too.\
\
A list of available resellers can be found at the [reseller endpoint.](#reseller-list)\
A list of available support groups can be found at the [support group endpoint.](#support-group-list)\
A list of available categories can be found at the [categories endpoint.](#category-list)\
\
Example JSON data:

```json
{
  "name": "string",
  "reseller_id": 0,
  "url": "string",
  "remarks": "string",
  "description": "string",
  "currency": "string",
  "support_group": 0,
  "cat_id": 0
}
```

### Site Details

{% openapi src="/files/PrmllFwFzP9Cqml9ymtz" path="/site/{sid}/details" method="post" %}
[TxProcess.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fle2FnrchW87BHp7CpriZ%2FTxProcess.yml?alt=media\&token=1665a1c4-33be-43bc-8b35-1e7c8c1bcc56)
{% endopenapi %}

Returns the details of a site. Doesn't have any body params.

### Site List

{% openapi src="/files/PrmllFwFzP9Cqml9ymtz" path="/site/list" method="post" %}
[TxProcess.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fle2FnrchW87BHp7CpriZ%2FTxProcess.yml?alt=media\&token=1665a1c4-33be-43bc-8b35-1e7c8c1bcc56)
{% endopenapi %}

Returns a list of sites. Doesn't have any body params.

### Site Payment

{% openapi src="<https://uat.txshield.payshield.ai/api/swaggerV3.php>" path="/site/mid/{mid}/rid/{rid}/sid/{sid}/payment" method="post" %}
<https://uat.txshield.payshield.ai/api/swaggerV3.php>
{% endopenapi %}

Marks a site as a Payment site. Once set to payment, the site can never be changed to 3ds or Alert.\
\
A list of available fraud templates can be retrieved from the [fraud template endpoint.](#fraud-template-list)\
\
Example JSON data.

```json
{
  "stop_send_email": 0,
  "cbreportemail": "string",
  "ftid": 0,
  "skip_ccv": 0,
  "bin_currency": 0,
  "allow_rebilling": 0,
  "proceedeveniffail": 0,
  "margin_percentage": "string",
  "first_transaction_alert": 0,
  "notify_email": "string",
  "allow_refund": 0,
  "allow_refund_time": 0,
  "emaildomain": "string",
  "shipping_n_tracking": 0
}
```

### Site 3ds

{% openapi src="<https://uat.txshield.payshield.ai/api/swaggerV3.php>" path="/site/mid/{mid}/rid/{rid}/sid/{sid}/3ds" method="post" %}
<https://uat.txshield.payshield.ai/api/swaggerV3.php>
{% endopenapi %}

Mark a site as a 3ds site. Once set to 3ds, the site can never be changed to Payment or Alert.\
\
Example JSON data

```json
{
  "settings": {
    "clientMode": "string",
    "enableResult": "string",
    "disableChallenge": "string",
    "enable3ds1Frictionless": "string",
    "enable3DS1Only": "string",
    "requestorName": "string",
    "requestorURL": "string",
    "authenticationInd": "string",
    "challengeInd": "string",
    "acctType": "string",
    "acquirerMerchantPwd": "string",
    "mcc": "string",
    "merchantCountryCode": "string",
    "merchantName": "string",
    "messageCategory": "string",
    "purchaseCurrency": "string",
    "transType": "string",
    "verbose": 0,
    "acquirerBin": "string",
    "acquirerMid": "string",
    "masterAcquirerBin": "string",
    "masterAcquirerMid": "string",
    "JCBAcquirerBin": "string",
    "JCBAcquirerMid": "string",
    "CUPAcquirerBin": "string",
    "CUPAcquirerMid": "string",
    "AMEXAcquirerBin": "string",
    "AMEXAcquirerMid": "string"
  },
  "shieldsettings": {
    "skip3d2": 0,
    "three_ds_provider": "string",
    "threedsprotocolversion": "string",
    "paayauth3d2": "string",
    "gpay_merchant_token": "string",
    "gpay_merchant_id": "string",
    "gpay_base_url": "string",
    "hitrust_account_id": "string",
    "hitrust_password": "string",
    "hitrust_base_url": "string",
    "hitrust_mastercard_prefix": "string"
  }
}
```

### Site Alert

{% openapi src="<https://uat.txshield.payshield.ai/api/swaggerV3.php>" path="/site/mid/{mid}/rid/{rid}/sid/{sid}/alert" method="post" %}
<https://uat.txshield.payshield.ai/api/swaggerV3.php>
{% endopenapi %}

Set a site as an Alert site. Once set to Alert it can never be changed to Payment or 3ds.\
\
Example JSON data

```json
{
  "alertapiurl": "string",
  "descriptorid": "string",
  "username": "string",
  "token": "string",
  "default_dispute_action": "string",
  "max_refund_amount": 0,
  "alert_triggeremail": 0,
  "alert_email": "string",
  "shieldrdr_review_email": "string",
  "statusupdate_url": "string"
}
```

## Supporting Data

### County List

{% openapi src="/files/PrmllFwFzP9Cqml9ymtz" path="/datasource/country" method="post" %}
[TxProcess.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fle2FnrchW87BHp7CpriZ%2FTxProcess.yml?alt=media\&token=1665a1c4-33be-43bc-8b35-1e7c8c1bcc56)
{% endopenapi %}

List of countries and their country codes.

### Currency List

{% openapi src="/files/PrmllFwFzP9Cqml9ymtz" path="/datasource/defaultcurrency" method="post" %}
[TxProcess.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fle2FnrchW87BHp7CpriZ%2FTxProcess.yml?alt=media\&token=1665a1c4-33be-43bc-8b35-1e7c8c1bcc56)
{% endopenapi %}

A list of supported currency and their currency codes.

### Fraud Template List

{% openapi src="/files/PrmllFwFzP9Cqml9ymtz" path="/datasource/fraudtemplate" method="post" %}
[TxProcess.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fle2FnrchW87BHp7CpriZ%2FTxProcess.yml?alt=media\&token=1665a1c4-33be-43bc-8b35-1e7c8c1bcc56)
{% endopenapi %}

A list of currently setup Fraud Templates.

### Reseller List

{% openapi src="/files/PrmllFwFzP9Cqml9ymtz" path="/datasource/reseller" method="post" %}
[TxProcess.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fle2FnrchW87BHp7CpriZ%2FTxProcess.yml?alt=media\&token=1665a1c4-33be-43bc-8b35-1e7c8c1bcc56)
{% endopenapi %}

A list of available resellers.

### Support Group List

{% openapi src="/files/PrmllFwFzP9Cqml9ymtz" path="/datasource/supportgroup" method="post" %}
[TxProcess.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fle2FnrchW87BHp7CpriZ%2FTxProcess.yml?alt=media\&token=1665a1c4-33be-43bc-8b35-1e7c8c1bcc56)
{% endopenapi %}

A list of support groups.

### Theme List

{% openapi src="/files/PrmllFwFzP9Cqml9ymtz" path="/datasource/theme" method="post" %}
[TxProcess.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fle2FnrchW87BHp7CpriZ%2FTxProcess.yml?alt=media\&token=1665a1c4-33be-43bc-8b35-1e7c8c1bcc56)
{% endopenapi %}

A list of available themes.

### Site Category List

{% openapi src="/files/PrmllFwFzP9Cqml9ymtz" path="/datasource/sitecategory" method="post" %}
[TxProcess.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fle2FnrchW87BHp7CpriZ%2FTxProcess.yml?alt=media\&token=1665a1c4-33be-43bc-8b35-1e7c8c1bcc56)
{% endopenapi %}

A list of available site categories.

### Payment Method List

{% openapi src="/files/PrmllFwFzP9Cqml9ymtz" path="/datasource/paymentmethods" method="post" %}
[TxProcess.yml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2Fle2FnrchW87BHp7CpriZ%2FTxProcess.yml?alt=media\&token=1665a1c4-33be-43bc-8b35-1e7c8c1bcc56)
{% endopenapi %}

A list of supported Payment Methods.


# Fraud Check

## POST /{sid}/fraudcheck

> Create a fraudcheck

```json
{"openapi":"3.0.0","info":{"title":"Txshield Api Version 1","version":"1.0"},"servers":[{"url":"/api/v1/index.php"}],"paths":{"/{sid}/fraudcheck":{"post":{"tags":["transaction"],"description":"Create a fraudcheck","parameters":[{"name":"sid","in":"path","description":"ID of site","required":true,"schema":{"type":"integer"}}],"requestBody":{"$ref":"#/components/requestBodies/post_sid_fraudcheck"},"responses":{"200":{"description":"Fraudcheck result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/fraudcheckResponse"}}}},"default":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorModel"}}}}}}}},"components":{"requestBodies":{"post_sid_fraudcheck":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"hash":{"description":"md5 hash of sid+timestamp+amounttotal+currency+rcode e.g. md5('22'.'1234568995265421'.'17.00'.'USD'.'222b6c')","type":"string"},"timestamp":{"description":"timestamp value used in the hash e.g. 1234568995265421","type":"string"},"tid":{"description":"Merchant reference","type":"string"},"card_type":{"description":"type of card(visa/mastercard)","type":"string"},"card_no":{"description":"The card number or the bin","type":"integer","format":"int64"},"card_exp_month":{"description":"2 digit for the month. Please have leading zeroes e.g. 05","type":"string"},"card_exp_year":{"description":"4 digit year i.e. 2016","type":"string"},"card_name":{"description":"The name printed on the card","type":"string"},"card_ccv":{"description":"Card CCV","type":"number"},"bank_name":{"description":"The name of the bank","type":"string"},"bank_phone":{"description":"Bank phone number","type":"string"},"routing_no":{"description":"Bank routing number","type":"string"},"mobile":{"description":"Mobile number","type":"string"},"useragent":{"description":"string identifying the software acting on behalf of a user to interact with web servers","type":"string"},"browseragent":{"description":"string helps identify which browser is being used, what version, and on which operating system","type":"string"},"dynamic_descriptor":{"description":"Business name as it appears on the customer's bank statement","type":"string"},"fingerprintsession":{"description":"device fingerprint (Unique identifier for the session)","type":"string"},"threeDSecure":{"description":"json string containing 3ds2 check values","type":"string"},"device_info":{"description":"json string containing device information check values","type":"string"},"firstname":{"description":"First name of the customer.","type":"string"},"lastname":{"description":"Last name of the customer.","type":"string"},"email":{"description":"Email of the customer.","type":"string"},"phone":{"description":"Phone of the customer.","type":"string"},"address":{"description":"Billing street address","type":"string"},"suburb_city":{"description":"Billing suburb or city","type":"string"},"state":{"description":"Billing state, 2 letter code for US/Canada. Australia should use 2/3 letter codes.","type":"string"},"country":{"description":"Billing country, ISO 3166 2 digit code.","type":"string"},"postcode":{"description":"Billing postcode/zipcode.","type":"string"},"ship_address":{"description":"Shipping street address","type":"string"},"ship_suburb_city":{"description":"Shipping suburb or city","type":"string"},"ship_state":{"description":"Shipping state, 2 letter code for US/Canada. Australia should use 2/3 letter codes.","type":"string"},"ship_country":{"description":"Shipping country, ISO 3166 2 letter code.","type":"string"},"ship_postcode":{"description":"Shipping postcode/zipcode.","type":"string"},"amount":{"description":"Amount"},"currency":{"description":"Transaction currency, ISO 3 letter code","type":"string"},"items":{"description":"Array of items in the transaction","type":"array","items":{"type":"object"}},"addinfo":{"description":"Additional information","type":"string"},"uip":{"description":"users ip address","type":"string"}},"required":["hash","card_type","card_no","card_ccv","card_exp_month","card_exp_year","card_name","timestamp","firstname","lastname","email","amount","currency"]}}}}},"schemas":{"fraudcheckResponse":{"properties":{"sid":{"type":"integer","format":"int64","description":"sid of site"},"comment":{"type":"string","description":"comment"},"tid":{"type":"string","description":"Merchant reference"},"card_issuer":{"type":"string","description":"Name of the card issuer"},"txid":{"type":"integer","format":"int64","description":"Fraud check transaction id"},"status":{"type":"string","description":"Has the value \"OK\" for a successful transaction, \"EXC\" for a failed transaction, \"PEND\" for a transaction in progress."},"tx_action":{"type":"string","description":"FRAUDCHECK"},"amount":{"type":"number","description":"The amount specified in the request"},"currency":{"type":"string","description":"The currency specified in the request"},"pay_method":{"description":"Payment method specified in request","type":"string"},"error":{"type":"object","items":{"properties":{"type":{"type":"string"},"sys":{"type":"string"},"info":{"type":"string"},"status":{"type":"string"},"response":{"type":"string"},"logext":{"type":"string"},"msgcode":{"type":"string"},"details":{"type":"string"},"code":{"type":"string","description":"The error code, if status value equal \"EXC\"."},"msg":{"type":"string","description":"The error message, if status value equal \"EXC\"."}}}},"cardbindata":{"type":"object","items":{"properties":{"bin":{"type":"string"},"card_type":{"type":"string"},"bank_name":{"type":"string"},"country":{"type":"string"},"phone":{"type":"string"},"type":{"type":"string"},"level":{"type":"string"},"www":{"type":"string"},"date_added":{"type":"string"}}}},"fraud_checks":{"type":"string","description":"Json string with the details of fraudcheck"}}},"errorModel":{"required":["code","message"],"properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"}}}}}}
```


# Payment Refund

{% openapi src="/files/QERJ9a4jbRGeNken57Kt" path="/{ptxid}/refund" method="post" %}
[paymentrefund.yaml](https://2711531294-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FS2zmC5IQEnyETw2Wkawl%2Fuploads%2FTFkqzK6YOFngPD2AxPyY%2Fpaymentrefund.yaml?alt=media\&token=321b1762-9fb4-4126-b415-7dddd76a6739)
{% endopenapi %}


# Field Definitions

Common Field and their definitions

## account\_no

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | -          |

The account number, used for bank transfers.

## address

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 255        |

The customers address. e.g. 123 Customer Street.

## affiliateid

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 30         |

Used in special cases.&#x20;

## amount

| data type | min length | max length |
| --------- | ---------- | ---------- |
| decimal   | 0          | 9          |

The amount processed in the system for this transaction against this sid.

## amount\_coupon

| data type | min length | max length |
| --------- | ---------- | ---------- |
| decimal   | 0          | 9          |

Any discounts that you want recorded in the system, this . This will be deducted from the total of the transaction. Refer to [amounttotal ](#amounttotal)for calculation details.

## amount\_shipping

| data type | min length | max length |
| --------- | ---------- | ---------- |
| decimal   | 0          | 9          |

Any amount being charged for shipping, that you want recorded in the system. This will be added to the total of the transaction. Refer to [amounttotal ](#amounttotal)for calculation details.

## amount\_tax

| data type | min length | max length |
| --------- | ---------- | ---------- |
| decimal   | 0          | 9          |

Any amount of tax being charged that you want recorded in the system. This will be added to the transaction. Refer to [amounttotal ](#amounttotal)for calculation details.

## Amounttotal

| data type | min length | max length |
| --------- | ---------- | ---------- |
| decimal   | 0          | -          |

The amounttotal field is the calculated total of the transaction based on all information sent in, the total value of the cart items, shipping, tax minus any coupon amount.

The amounttotal is always used displaying any all minor units. \
e.g.\
USD$17  is used as 17.00 \
JPY¥17 is used as 17&#x20;

Calculating the amounttotal follows this pseudocode:&#x20;

```
amounttotal = 0;

for each item in the cart {
    amounttotal = amounttotal + ( item.quantity * item.amount_unit);
}

amounttotal = amounttotal + (amount_shipping + amount_tax - amount_coupon);
```

## campaignid

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | -          |

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

## card\_ccv

| data type | min length | max length |
| --------- | ---------- | ---------- |
| integer   | 3          | 6          |

The  security code on the customers cards. Also known as, CCV, CVV, CVC and CSC. This is not the Card PIN.&#x20;

## card\_exp\_month

| data type | min length | max length |
| --------- | ---------- | ---------- |
| integer   | 2          | 2          |

The expiry month for the customers card. Should be 0 filled. \
e.g. 1 (January) should be sent as 01. 2 should be sent as 02.

## card\_exp\_year

| data type | min length | max length |
| --------- | ---------- | ---------- |
| integer   | 2          | 2          |

The expiry year for the customers card. Should be 0 filled.  And is only 2 digits long.\
e.g. 2001 should be 01. 2022 should be 22..

## card\_no

| data type | min length | max length |
| --------- | ---------- | ---------- |
| integer   | 13         | 20         |

Also known as the PAN. This is the full credit card number. It should **not** have any punctuation or separators when sent. The system will not filter for any punctuation or separators and will just fail the transaction.

## card\_type

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 255        |

This is the payment method. It should be indicative of the payment type.&#x20;

e.g.&#x20;

* visa
* &#x20;mastercard
* bank

They paymethod should be provided to you at onboarding time. The payment methods available for your sid can also be retrieved using the [rawfee ](https://docs.payshield.ai/transaction-processing/integrations-and-apis/pages/wmh1GXQn8uR3ulN7v7eM#soap-rawfeeapi.php)API.&#x20;

## country

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 3          | 3          |

The country code that belongs to the customers credit card. This should be the [Alpha 3 ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) country code.&#x20;

## currency

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 3          | 3          |

The 3 Alpha character [ISO 4217 code ](https://en.wikipedia.org/wiki/ISO_4217)for the currency.

## descriptor

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 1          | 50         |

The name of the payment descriptor that was used on the SID to complete the payment.  This should be indicative of the Name / Title that will appear on the customers Bank Statement.

## email

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 150        |

The customers email address.

## error\_code

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | -          |

If the error is generated by TxProcess this is a 3 character integer number corresponding to our internal error code list.\
\
If created by an external system this can be of any length.

## error\_info

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | -          |

Where possible, an extended explanation of what caused the error / details about it.

## error\_msg

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | -          |

The raw error message generated.

## error\_sys

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | -          |

Where possible, the module that generated the error.

## error\_type

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | -          |

## firstname

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 100        |

The customers first name.

## Hash

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 32         | 32         |

The hash is a secure signature that is generated when you communicate with TxProcess.\
\
Every time you communicate with TxProcess and will create a Payment Record / Transaction in the system you will be required to create a hash to verify the contents of the transaction it self, and to complete your authentication with the system.

### Generating the Hash

The hash is the md5 of

* sid
* [timestamp](#timestamp)
* [amounttotal](#amounttotal)
* [currency](#currency)
* [rcode](#rcode)

i.e. `md5('22'.'1234568995265421'.'17.00'.'USD'.'222b6c')`

## institution\_number

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 3          | 3          |

Required for ACH transactions.

## item\_desc

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 255        |

A short text description of the item being purchase. \
e.g. A shiny Red Delicious

## item\_amount\_unit

| data type | min length | max length |
| --------- | ---------- | ---------- |
| decimal   | 0          | 9          |

The cost of the item, per each unit. This is used in the [amounttotal ](#amounttotal)calculation.\
If you are selling 1 bag of apples, then it's the price per bag.\
If you are charging for each individual apple, it's the price per apple.

## item\_name

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 255        |

The item name. E.g. Apple\_Red

## item\_no

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 255        |

The identification number  / stock number for the item.

## item\_quantity

| data type | min length | max length |
| --------- | ---------- | ---------- |
| integer   | 0          | 10         |

How many of the item was bought.  This is used in the [amounttotal ](#amounttotal)calculation.

## lastname

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 100        |

The customers lastname.

## mobile

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 25         |

The customers mobile number.

## parent\_txid

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 16         | 16         |

The parent transaction id of the transaction. If this transaction is part of a series of transactions (Asynchronous transactions for e.g.) this is the parent transaction id that can be used to link all transactions together.

## phone

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 25         |

The customers land line phone number. Not their mobile phone number. For mobile phone number see [mobile](#mobile).

## postcode

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 16         |

The postcode / zip code of the customer.

## postback\_url

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 255        |

The URL to POST data to, when a transaction type has finished, or receives an update. \
\
For e.g. if an transaction has a status of PENDING and a final status is determined, you should receive a postback notification of both states. First the PENDING state, and then when a final status is determined a second notification.\
\
Handling this endpoint on the merchants end is very important, particularly for Asynchronous transactions that will have no other way to communicate the final result to the merchant.

## rcode

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 40         |

The rcode will be provided to you at onboarding. The rcode should never be sent in as plain text with the payment data. It is the equivalent to your password and should never be accessible / viewable online.

## redirect\_url

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 255        |

A complete URL of the page that you want the customer redirected too, after the transaction has completed processing. They will be redirected with the data from the corresponding responses section.

## ref1

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 255        |

An extra reference field on top of the [tid ](#tid)field that the merchant can use to store a reference. Note, that this does not replace the tid.

## ref2

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 255        |

An extra reference field on top of the [tid ](#tid)field that the merchant can use to store a reference. Note, that this does not replace the tid.

## ref3

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 255        |

An extra reference field on top of the [tid ](#tid)field that the merchant can use to store a reference. Note, that this does not replace the tid.

## ref4

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 2048       |

An extra reference field on top of the [tid ](#tid)field that the merchant can use to store a reference. Note, that this does not replace the tid.

## routing\_no

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 14         |

The routing or transit number, used for bank transfers.

## shipping\_address

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 255        |

The shipping address. e.g. 123 Customer Street.

## shipping\_country

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 3          | 3          |

The shipping country code. This should be the [Alpha 3 ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) country code.&#x20;

## shipping\_firstname

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 100        |

The first name of the person receiving the parcel.

## shipping\_lastname

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 100        |

The first name of the person receiving the parcel.

## shipping\_postcode

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 16         |

The shipping postcode / zip code of the customer.

## shipping\_state

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 32         |

The shipping state for the transaction.

## shipping\_suburb\_city

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 60         |

The shipping suburb or city of the transaction.

## sid

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 11         |

The sid (Site ID) will be provided to you at onboarding.

## state

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 32         |

The customers billing state.

## status

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 10         |

The result of the transaction

## suburb\_city

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 60         |

The billing suburb or city of the customer.

## threeDSecure

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | -          |

Expects be a JSON object with a collection of ThreeDSecure(3DS) fields and their values. This is for the Authorization transaction, after a 3DS Authentication transaction has already occurred. To complete a 3DS Authentication, please contact support and they will help guide you for your specific integration. The particular fields and their naming can be different depending on how the Authentication is done, and the payment processor being used.

## tid

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 255        |

The txid (transaction id) that the system generated for this transaction.

## timestamp

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 10         | 10         |

The timestamp is to be a Unix timestamp&#x20;

## tx\_action

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 15         |

the transaction type. e.g. `PAYMENT` or `SETTLEMENT`

## txid

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 16         | 16         |

The transaction id for this transaction. If this is the first in a series of transactions, this could be the same as the [parent\_txid ](#parent_txid). If it is not the first, there will be a parent\_txid that will be used to group all of the series together.

## Vrfy

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 256        | 256        |

Some response form TxProcess, in particular in response to a call that generated a transaction, will return a vrfy field, so that you can validate the response hasn't been tampered with before receiving it. All the values except the rcode will be in the response returned. \
\
Note that the vrfy string in contrast to the hash string has a separator(;) in between the values.<br>

The vrfy is the sha256 of

* sid
* [rcode](#rcode)
* [txid](#txid)
* [status](#status)
* [amount](#amount)
* [currency](#currency)
* [tx\_action](#tx_action)\
  `sha256(sid;rcode;txid;status;amount;currency;txaction)`


# Responses

#### To Redirect Page and to Postback Url

The response from the server is an array. If the status has the value "**OK**" the transaction has been successfully processed.

The response array has the following structure:

| Name         | Data Type | Description                                                                                                                                     |
| ------------ | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| sid          | String    | Has the sid where transaction was processed                                                                                                     |
| status       | String    | Has the value "OK" for a successful transaction, or "EXC" for a failed transaction                                                              |
| parent\_txid | String    | Parent transaction id                                                                                                                           |
| txid         | String    | The transaction ID                                                                                                                              |
| tx\_action   | String    | The state change txaction, e.g. "PAYMENT"                                                                                                       |
| amount       | String    | The amount processed. The gateway currency amount                                                                                               |
| currency     | String    | The currency in which the transaction was processed                                                                                             |
| comment      | String    | Response from the gateway                                                                                                                       |
| rebillkey    | String    | rebillkey for the transaction, if rebill is allowed                                                                                             |
| descriptor   | String    | Gateway descriptor name                                                                                                                         |
| tid          | String    | From the original transaction                                                                                                                   |
| ref1         | String    | From the original transaction                                                                                                                   |
| ref2         | String    | From the original transaction                                                                                                                   |
| ref3         | String    | From the original transaction                                                                                                                   |
| ref4         | String    | From the original transaction                                                                                                                   |
| vrfy         | String    | This is a sha 256 hash so the data can be verified. To generate hash with sha256 the string of *sid;rcode;txid;status;amount;currency;txaction* |
|              |           |                                                                                                                                                 |
| **error**    |           | **f an error has occurred, then the status value will equal "EXC" and these parameters will be sent as well**                                   |
| error\_type  | String    | The error type                                                                                                                                  |
| error\_sys   | String    | The system that caused the error (client or server)                                                                                             |
| error\_msg   | String    | The error message                                                                                                                               |
| error\_info  | String    | Error information that contains the bank message and bank code                                                                                  |
| error\_code  | String    | Txprocess UAT error code                                                                                                                        |


# Testing Data

Not all gateways provide a testing environment but we will be able to setup a test gateway for testing.

To test your integration, please contact support and you will be provided with a testing SID. Any transaction processed on the testing SID will only be checked syntactically and semantically by TxProcess UAT. This way you can test if you have sent sufficient and correct data.

The information given below is for testing using our test gateway only. No amount will be deducted from the account. Test responses are simulated based on the amount sent.

When performing credit card type transaction testing with your testing SID, the following card details can be used:

| Field       | Value #1         | Value #2         |
| ----------- | ---------------- | ---------------- |
| Card Number | 4111111111111111 | 5555555555554444 |
| Card Type   | visa             | mastercard       |
| CVV         | 123              | 1234             |
| Expiry Date | 01/2022          | 01/2022          |
| Card name   | Tester           | Tester           |

The following transaction amounts can be used to test different transaction results with your testing SID.

| Total Amount                       | Description                                         |
| ---------------------------------- | --------------------------------------------------- |
| $\*.01                             | Non 3D Secure transactions with Gateway error       |
| $\*.03                             | PENDING transaction                                 |
| $\*.12                             | Non 3D Secure transactions with Decline message     |
| $\*.13                             | 3D Secure transaction with a Decline message        |
| $\*.15                             | 3D Secure transaction with a Gateway Failed message |
| any amount between $*.15 and $*.20 | Approved 3D Secure transaction                      |

{% hint style="info" %}
Stands for any dollar value. eg, $\*.12 = $1.12, $2.12 etc
{% endhint %}

You will be able to view the results of your testing transactions in TxProcess UAT by searching for them on the **Browse Transactions :** *{endpoint\_url}/transactions.php* page with your testing SID as a search item.


# NMI - API

The NMI API emulator can be located at: secure/apidirecthandlernmi.php

This will take a normal POST API call and return the status of the transaction and the transaction details.\
\
The response will be in TxProcess formatting, but the original call, can be formatted using NMI naming schemes.\
\
It currently only handles sale transactions.

## Post NMI Emulator

<mark style="color:green;">`POST`</mark> `secure/apidirecthandlernmi.php`

#### Request Body

| Name                        | Type   | Description                                                                                                         |
| --------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------- |
| type                        | String | Type of transaction. Currently only accepts sale.                                                                   |
| security\_key               | String | API Security Key assigned to a merchant account.                                                                    |
| ccnumber                    | String | Credit card number.                                                                                                 |
| ccexp                       | String | Credit card expiration date. Format: MMYY                                                                           |
| cvv                         | String | The card security code.                                                                                             |
| checkname                   | String | The name on the customer's ACH account.                                                                             |
| checkaba                    | String | The customer's bank routing number.                                                                                 |
| checkaccount                | String | The customer's bank account number.                                                                                 |
| account\_holder\_type       | String | The type of ACH account the customer has.                                                                           |
| account\_type               | String | The ACH account entity of the customer.                                                                             |
| sec\_code                   | String | The Standard Entry Class code of the ACH transaction.                                                               |
| amount                      | String | Total amount to be charged. For validate, the amount must be omitted or set to 0.00.                                |
| tax                         | String | The sales tax, included in the transaction amount, associated with the purchase.                                    |
| cash\_discount              | String | How much less a customer paid due to a cash discount.                                                               |
| surcharge                   | String | Surcharge amount.                                                                                                   |
| shipping                    | String | Total shipping amount.                                                                                              |
| currency                    | String | The transaction currency. Format: ISO 4217                                                                          |
| orderdescription            | String | Order description                                                                                                   |
| orderid                     | String | Order Id                                                                                                            |
| ipaddress                   | String | IP address of cardholder, this field is recommended.                                                                |
| ponumber                    | String | Original purchase order.                                                                                            |
| lastname                    | String | Cardholder's last name                                                                                              |
| address1                    | String | Card billing address                                                                                                |
| address2                    | String | Card billing address, line 2                                                                                        |
| city                        | String | Card billing city                                                                                                   |
| state                       | String | Card billing state.                                                                                                 |
| zip                         | String | Card billing zip code                                                                                               |
| country                     | String | Card billing country.                                                                                               |
| phone                       | String | Billing phone number                                                                                                |
| fax                         | String | Billing fax number                                                                                                  |
| email                       | String | Billing email address                                                                                               |
| social\_security\_number    | String | Customer's social security number, checked against bad check writers database if check verification is enabled.     |
| merchant\_defined\_field\_# | String | Merchant defined fields that can be used to store any information the merchant wants to track with the transaction. |
| firstname                   | String | Cardholder's first name.                                                                                            |
| version                     | String | 3DSecure version.                                                                                                   |
| cardholder\_auth            | String | Set 3D Secure condition. Value used to determine E-commerce indicator (ECI).                                        |
| xid                         | String | Cardholder authentication transaction id.                                                                           |
| cavv                        | String | Cardholder authentication verification value.                                                                       |
| shipping\_country           | String | Shipping country Country codes are as shown in ISO 3166. Format: CC                                                 |
| shipping\_zip               | String | Shipping zip code                                                                                                   |
| shipping\_state             | String | Shipping state                                                                                                      |
| shipping\_city              | String | Shipping city                                                                                                       |
| shipping\_address2          | String | Shipping address, line 2                                                                                            |
| shipping\_address1          | String | Shipping address                                                                                                    |
| shipping\_lastname          | String | Shipping last name                                                                                                  |
| shipping\_firstname         | String | Shipping first name                                                                                                 |
| drivers\_license\_dob       | String | Driver's license date of birth.                                                                                     |
| drivers\_license\_number    | String | Driver's license number.                                                                                            |


# Overview

The Merchant Monitoring API allows you to monitor merchant domains and their business web presence, assess trustworthiness and receive ongoing alerts when meaningful changes are detected.

It is designed for platforms and merchants that need reliable, provider-backed intelligence to support onboarding, risk assessment, compliance workflows, or ongoing monitoring.

### What Merchant Monitor Does

Merchant Monitoring provides two core capabilities:

* **Ongoing Monitoring** (notifications via webhook) of domains on a scheduled basis
* **Web Presence Check** that evaluates trust signals and returns a recommendation

**IMPORTANT:** Once a domain is registered, monitoring begins immediately. An initial Web Presence Check is attempted asynchronously. In some cases, this check may not complete successfully (for example, due to provider timeouts or incomplete data). When this occurs, the verification can be retried using the Manually Trigger Domain Verification Check endpoint.

### High-Level Lifecycle

*Below is a diagram that explains, at a high-level, how the Merchant Monitoring API works*

{% @mermaid/diagram content="flowchart TD
A\[Domain Registered] --> B\[Monitoring Starts Immediately]
B --> C\[Initial Web Presence Check Triggered]
C --> D\[Verification Processing]
D -->|Completed| E\[Recommendation Available]
D -->|Failed or Timed Out| F\[Recommendation Pending]
F --> G\[Manual Verification Retry]
G --> E
B --> H\[Scheduled Monitoring Continues]
H --> I\[Notifications Emitted on Changes]" %}

### Consuming Results

Domain Monitor supports two complementary integration patterns:<br>

#### Pull-Based (API)

Use the API to retrieve the current state of a domain, including its latest recommendation and timestamps.

{% content-ref url="/pages/xSQJOlI5zM6FyqaQbvS9" %}
[Retrieving Domain Data](/merchant-monitoring-api/retrieving-domain-data)
{% endcontent-ref %}

#### Push-Based (Webhooks)

Request a webhook endpoint to receive alerts when monitoring detects meaningful changes or events.

{% content-ref url="/pages/2fUaGzo0uNthr7ABf6zE" %}
[Webhook - Monitoring Notifications](/merchant-monitoring-api/webhook-monitoring-notifications)
{% endcontent-ref %}

### Getting Started

To begin integrating with Merchant Monitoring, start by registering your first domain and reviewing the implementation guidelines.

{% content-ref url="/pages/GdUjgLso4DLAKsAq5r3i" %}
[Implementation Guidelines](/merchant-monitoring-api/implementation-guidelines)
{% endcontent-ref %}


# Implementation Guidelines

## Merchant Monitoring API Integration Guide

### Overview

The Merchant Monitoring API enables you to monitor merchant web presence and receive real-time notifications about domain trustworthiness. This guide covers everything you need to integrate the API into your application.

#### Base URLs

| Environment | URL                                |
| ----------- | ---------------------------------- |
| UAT         | `https://uat-monitor.payshield.ai` |
| Production  | `https://monitor.payshield.ai`     |

#### API Version

All endpoints are versioned under `/api/v1/`.

***

### Authentication

The API uses JWT (JSON Web Token) bearer authentication. All protected endpoints require the `Authorization` header.

**Using the Access Token**

Include the token in all authenticated requests:

```bash
curl -X GET {baseurl}/api/v1/domains \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."
```


# Adding a Domain

Add a single domain or business for monitoring.

## Add a new domain

> Register a new domain and start monitoring immediately. \
> An initial web presence verification is attempted asynchronously. Verification may fail, timeout, or return incomplete data and does not affect the monitoring status of the domain.<br>

```json
{"openapi":"3.0.3","info":{"title":"Domain Monitor API - Merchant Portal","version":"1.0.0"},"tags":[{"name":"Domains","description":"Domain monitoring and management"}],"servers":[{"url":"https://uat-monitor.payshield.ai","description":"Uat server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT access token obtained from login endpoint"}},"schemas":{"Domain":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid","description":"ID of the user (merchant) who owns this domain."},"domain":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","inactive"]},"recommendation":{"type":"string","enum":["pass","fail","review"],"nullable":true,"description":"Verification recommendation from the most recent web presence check. A null value indicates that verification has not completed or failed. Monitoring may still be active when this value is null.\n"},"provider":{"type":"string"},"checkFrequency":{"type":"string","enum":["7","30","90"],"description":"Monitoring frequency in days:\n- '7': Weekly monitoring (every 7 days)\n- '30': Monthly monitoring (every 30 days)\n- '90': Quarterly monitoring (every 90 days)\n\nThis value is sent to the monitoring provider (e.g., TrueBiz) to configure the monitoring package frequency.\n"},"lastCheckedAt":{"type":"string","format":"date-time","nullable":true},"nextCheckAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"details":{"type":"object"}}}},"responses":{"ValidationError":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnauthorizedError":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/domains":{"post":{"tags":["Domains"],"summary":"Add a new domain","description":"Register a new domain and start monitoring immediately. \nAn initial web presence verification is attempted asynchronously. Verification may fail, timeout, or return incomplete data and does not affect the monitoring status of the domain.\n","operationId":"createDomain","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"domain":{"type":"string","maxLength":255,"description":"Domain name (required if name not provided)"},"name":{"type":"string","maxLength":255,"description":"Business name (required if domain not provided)"},"description":{"type":"string","maxLength":1000,"description":"Business description"},"website":{"type":"string","format":"uri","maxLength":500,"description":"Full website URL"},"addressLine1":{"type":"string","maxLength":255,"description":"Street address line 1"},"addressLine2":{"type":"string","maxLength":255,"description":"Street address line 2"},"city":{"type":"string","maxLength":100,"description":"City"},"stateProvince":{"type":"string","maxLength":100,"description":"State or province"},"postalCode":{"type":"string","maxLength":20,"description":"Postal/ZIP code"},"country":{"type":"string","maxLength":100,"description":"Country"},"email":{"type":"string","format":"email","maxLength":255,"description":"Contact email"},"phone":{"type":"string","maxLength":50,"description":"Contact phone number"},"fullName":{"type":"string","maxLength":255,"description":"Contact person full name"},"externalTrackingRef":{"type":"string","maxLength":255,"description":"External tracking reference ID"},"checkFrequency":{"type":"string","enum":["7","30","90"],"nullable":true,"description":"Monitoring frequency in days:\n- '7': Weekly monitoring (every 7 days)\n- '30': Monthly monitoring (every 30 days)\n- '90': Quarterly monitoring (every 90 days)\n\nIf not provided (null/empty), no ongoing monitoring will be started - only a one-time domain/company check is performed.\nThis value is sent to the monitoring provider to configure the monitoring package frequency.\n"}}}}}},"responses":{"201":{"description":"Domain created successfully and initial verification attempted","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Domain"}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"},"409":{"description":"Domain already exists","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```

Since web presence verification is processed asynchronously, the initial `POST /domains` response may return with `recommendation: null`.

A Web Presence Check attempt is automatically triggered when the domain is created. If this attempt fails, times out, or returns incomplete data, you may manually retry verification using the **Manually trigger Web Presence Check** endpoint (see below).

Monitoring continues regardless of verification outcome.<br>

## Manually trigger Web Presence Check

> Manually retry the web presence verification for an existing domain.\
> \
> This endpoint is intended for cases where the initial verification failed,\
> timed out, or returned incomplete data. It re-attempts verification only and\
> does not affect monitoring status.\
> \
> This operation may take up to 30–40 seconds depending on provider response times.<br>

```json
{"openapi":"3.0.3","info":{"title":"Domain Monitor API - Merchant Portal","version":"1.0.0"},"tags":[{"name":"Domains","description":"Domain monitoring and management"}],"servers":[{"url":"https://uat-monitor.payshield.ai","description":"Uat server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT access token obtained from login endpoint"}},"schemas":{"Domain":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"userId":{"type":"string","format":"uuid","description":"ID of the user (merchant) who owns this domain."},"domain":{"type":"string"},"name":{"type":"string"},"status":{"type":"string","enum":["active","inactive"]},"recommendation":{"type":"string","enum":["pass","fail","review"],"nullable":true,"description":"Verification recommendation from the most recent web presence check. A null value indicates that verification has not completed or failed. Monitoring may still be active when this value is null.\n"},"provider":{"type":"string"},"checkFrequency":{"type":"string","enum":["7","30","90"],"description":"Monitoring frequency in days:\n- '7': Weekly monitoring (every 7 days)\n- '30': Monthly monitoring (every 30 days)\n- '90': Quarterly monitoring (every 90 days)\n\nThis value is sent to the monitoring provider (e.g., TrueBiz) to configure the monitoring package frequency.\n"},"lastCheckedAt":{"type":"string","format":"date-time","nullable":true},"nextCheckAt":{"type":"string","format":"date-time","nullable":true},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"details":{"type":"object"}}}},"responses":{"UnauthorizedError":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFoundError":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/domains/{id}/check":{"post":{"tags":["Domains"],"summary":"Manually trigger Web Presence Check","description":"Manually retry the web presence verification for an existing domain.\n\nThis endpoint is intended for cases where the initial verification failed,\ntimed out, or returned incomplete data. It re-attempts verification only and\ndoes not affect monitoring status.\n\nThis operation may take up to 30–40 seconds depending on provider response times.\n","operationId":"recheckDomain","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Domain ID"}],"responses":{"200":{"description":"Web presence check completed successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"data":{"$ref":"#/components/schemas/Domain"}}}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"404":{"$ref":"#/components/responses/NotFoundError"}}}}}}
```

#### Recommended Integration Pattern

```
1. POST /domains → Returns domain with recommendation: null
2. Poll GET /domains/{id}/check until recommendation is not null
3. Process the result (pass/fail/review)
```

#### Typical Processing Times

| Scenario                  | Typical Time     |
| ------------------------- | ---------------- |
| Domain with existing data | 2-5 seconds      |
| New domain lookup         | 5-15 seconds     |
| Business name search      | 5-20 seconds     |
| Provider timeout/retry    | Up to 30 seconds |


# Webhook - Monitoring Notifications

Webhooks allow you to receive real-time notifications when domain monitoring events occur, eliminating the need for polling. The API will automatically push events to your registered webhook.

#### Managing Webhook Endpoints

* Webhook endpoints are created and deleted by PayShield **upon request** (contact your PayShield Account Manager)
* Only **one** webhook endpoint is supported per account

**Get Webhook Details**

```bash
curl -X GET {baseurl}/api/v1/user-webhooks/{id} \
  -H "Authorization: Bearer <token>"
```

**Update Webhook**

```bash
curl -X PATCH {baseurl}/api/v1/user-webhooks/{id} \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/new-endpoint",
    "enabled": true
  }'
```

**Regenerate Secret**

If your webhook secret is compromised, regenerate it immediately:

```bash
curl -X POST {baseurl}/api/v1/user-webhooks/{id}/regenerate-secret \
  -H "Authorization: Bearer <token>"
```

**Response:**

```json
{
  "message": "Webhook secret regenerated successfully",
  "warning": "Store the new secret securely. It will not be shown again.",
  "data": {
    "secret": "whsec_new123..."
  }
}
```

#### Webhook Payload Format

All webhook events follow this structure:

```json
{
  "event": "business-closed",
  "description": "Business appears to be closed based on verification data",
  "timestamp": "2024-01-15T10:30:00.000Z",
  "data": {
    "domainId": "550e8400-e29b-41d4-a716-446655440000",
    "domain": "example.com",
    "status": "active",
    "provider": "truebiz"
  }
}
```

**Payload Fields**

| Field           | Type          | Required | Description                                                                                                      |
| --------------- | ------------- | -------- | ---------------------------------------------------------------------------------------------------------------- |
| `event`         | string        | Yes      | The event type that triggered this webhook (e.g., `business-closed`, `sentiment`, `website`, `business-profile`) |
| `description`   | string        | No       | Human-readable description of the event (may be `null`)                                                          |
| `timestamp`     | string        | Yes      | ISO 8601 timestamp when the event occurred                                                                       |
| `data`          | object        | Yes      | Event-specific data                                                                                              |
| `data.domainId` | string (UUID) | Yes      | UUID of the domain associated with this event                                                                    |
| `data.domain`   | string        | Yes      | The domain name                                                                                                  |
| `data.status`   | string        | Yes      | Current domain status (`active` or `inactive`)                                                                   |
| `data.provider` | string        | Yes      | The provider that triggered this event (e.g., `truebiz`)                                                         |

#### Webhook Delivery Logs

Monitor webhook deliveries to debug issues and track reliability.

**View Deliveries for Specific Endpoint**

```bash
curl -X GET "{baseurl}/api/v1/user-webhooks/{id}/deliveries?limit=50" \
  -H "Authorization: Bearer <token>"
```

**List All Delivery Logs**

View deliveries across all webhook endpoints:

```bash
curl -X GET "{baseurl}/api/v1/user-webhooks/deliveries?status=failed&limit=100" \
  -H "Authorization: Bearer <token>"
```

**Query Parameters:**

| Parameter  | Type              | Default | Description                                                                     |
| ---------- | ----------------- | ------- | ------------------------------------------------------------------------------- |
| `page`     | integer           | 1       | Page number (min: 1)                                                            |
| `limit`    | integer           | 100     | Items per page (min: 1, max: 1000)                                              |
| `status`   | string            | -       | Filter by status: `pending`, `success`, `failed`, `retrying`                    |
| `userId`   | string (UUID)     | -       | Filter by user ID (superadmin/reseller only)                                    |
| `domainId` | string (UUID)     | -       | Filter by domain ID                                                             |
| `dateFrom` | string (ISO 8601) | -       | Filter deliveries from this date (e.g., `2025-01-01` or `2025-01-01T00:00:00Z`) |
| `dateTo`   | string (ISO 8601) | -       | Filter deliveries until this date (must be >= `dateFrom`)                       |

**Delivery Status Values**

| Status     | Description                           |
| ---------- | ------------------------------------- |
| `pending`  | Delivery queued but not yet sent      |
| `success`  | Delivered successfully (2xx response) |
| `failed`   | All retry attempts failed             |
| `retrying` | Delivery failed, will retry           |

***

#### Webhook Retry Policy

Failed webhook deliveries are automatically retried:

* **Retry attempts:** 3 attempts total
* **Retry schedule:**
  * 1st retry: After 1 minute
  * 2nd retry: After 5 minutes
  * 3rd retry: After 15 minutes
* **Timeout:** 10 seconds per delivery attempt
* **Success criteria:** Any 2xx HTTP response code

***

#### Webhook Security

All webhook requests include a cryptographic signature that you **must verify** to ensure authenticity.

**Webhook Request Headers**

Each webhook delivery includes these headers:

| Header                  | Description              | Example                     |
| ----------------------- | ------------------------ | --------------------------- |
| `X-Webhook-Signature`   | HMAC-SHA256 signature    | `sha256=a1b2c3d4...`        |
| `X-Webhook-Event`       | Event type               | `business-closed`           |
| `X-Webhook-Delivery-Id` | Unique delivery ID       | `550e8400-e29b-41d4...`     |
| `User-Agent`            | Always set to this value | `DomainMonitor-Webhook/1.0` |

**Signature Verification**

To verify the webhook signature:

1. Get your webhook signing secret (from creation or regeneration)
2. Retrieve the raw request body as received (don't parse it first)
3. Compute HMAC-SHA256 hash using your secret as the key
4. Format as `sha256={hex_digest}`
5. Compare with `X-Webhook-Signature` header using timing-safe comparison

function to verify signature

```
function verifyWebhookSignature(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(JSON.stringify(payload));
  const expectedSignature = `sha256=${hmac.digest('hex')}`;

  // Use timing-safe comparison to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

```


# Retrieving Domain Data

#### Get Single Domain

```bash
curl -X GET {baseurl}/api/v1/domains/{id} \
  -H "Authorization: Bearer <token>"
```

#### Get Domain with Full Details

Includes raw provider response data:

```bash
curl -X GET {baseurl}/api/v1/domains/{id}/details \
  -H "Authorization: Bearer <token>"
```

#### List All Domains

```bash
curl -X GET "{baseurl}/api/v1/domains?page=1&limit=20" \
  -H "Authorization: Bearer <token>"
```

**Query Parameters**

| Parameter        | Type    | Default      | Description                                  |
| ---------------- | ------- | ------------ | -------------------------------------------- |
| `page`           | integer | 1            | Page number                                  |
| `limit`          | integer | 20           | Items per page (max 100)                     |
| `status`         | string  | -            | Filter: `active` or `inactive`               |
| `recommendation` | string  | -            | Filter: `pass`, `fail`, or `review`          |
| `search`         | string  | -            | Search in domain and name (max 255 chars)    |
| `industry`       | string  | -            | Filter by industry (max 255 chars)           |
| `businessType`   | string  | -            | Filter by business type (max 255 chars)      |
| `foundedYear`    | integer | -            | Filter by founded year (1800 - current year) |
| `sortBy`         | string  | `created_at` | Sort field                                   |
| `sortOrder`      | string  | `desc`       | `asc` or `desc`                              |

**Available sort fields:** `created_at`, `updated_at`, `domain`, `name`, `recommendation`, `last_checked_at`, `industry`, `business_type`, `founded_year`

### Recommendations

The API returns one of three recommendation values:

<table><thead><tr><th width="132">Value</th><th>Description</th></tr></thead><tbody><tr><td><code>pass</code></td><td>Domain/business is verified and trustworthy</td></tr><tr><td><code>review</code></td><td>Requires manual review</td></tr><tr><td><code>fail</code></td><td>Domain/business failed verification</td></tr></tbody></table>


# Manage Monitoring

### Managing Monitoring

#### Stop Monitoring

```bash
curl -X PATCH {baseurl}/api/v1/domains/{id}/stop \
  -H "Authorization: Bearer <token>"
```

#### Start/Restart Monitoring

```bash
curl -X PATCH {baseurl}/api/v1/domains/{id}/start \
  -H "Authorization: Bearer <token>"
```

## Get monitoring alerts

> Retrieve monitoring alerts list.\
> \
> Returns alerts list, even if you don't have webhooks configured.\
> This allows you to see all monitoring events for your domains in a consistent format.\
> You can filter by provider, domain, and date range to analyze monitoring activity.\
> \
> Note: This is different from \`/api/v1/user-webhooks/deliveries\` which shows the delivery logs of outbound webhooks sent to your registered endpoints.<br>

```json
{"openapi":"3.0.3","info":{"title":"Domain Monitor API - Merchant Portal","version":"1.0.0"},"tags":[],"servers":[{"url":"https://uat-monitor.payshield.ai","description":"Uat server"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT access token obtained from login endpoint"}},"schemas":{"Pagination":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}}},"Error":{"type":"object","properties":{"message":{"type":"string"},"code":{"type":"string"},"details":{"type":"object"}}}},"responses":{"ValidationError":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"UnauthorizedError":{"description":"Authentication required or token invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/api/v1/monitoring-alerts":{"get":{"tags":["Monitoring Alerts"],"summary":"Get monitoring alerts","description":"Retrieve monitoring alerts list.\n\nReturns alerts list, even if you don't have webhooks configured.\nThis allows you to see all monitoring events for your domains in a consistent format.\nYou can filter by provider, domain, and date range to analyze monitoring activity.\n\nNote: This is different from `/api/v1/user-webhooks/deliveries` which shows the delivery logs of outbound webhooks sent to your registered endpoints.\n","operationId":"getMonitoringAlerts","parameters":[{"name":"domainId","in":"query","schema":{"type":"string","format":"uuid"},"description":"Filter by domain ID"},{"name":"dateFrom","in":"query","schema":{"type":"string","format":"date-time"},"description":"Filter events from this date (ISO 8601 format, e.g., 2025-01-01 or 2025-01-01T00:00:00Z)"},{"name":"dateTo","in":"query","schema":{"type":"string","format":"date-time"},"description":"Filter events until this date (ISO 8601 format, e.g., 2025-01-31 or 2025-01-31T23:59:59Z)"},{"name":"page","in":"query","schema":{"type":"integer","default":1,"minimum":1},"description":"Page number"},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":100},"description":"Number of items per page"},{"name":"sortBy","in":"query","schema":{"type":"string","enum":["timestamp","domain","event","description"],"default":"created_at"},"description":"Field to sort by"},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["asc","desc"],"default":"desc"},"description":"Sort order"}],"responses":{"200":{"description":"Monitoring alerts retrieved successfully","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string"},"data":{"type":"array","items":{"type":"object","properties":{"event":{"type":"string","description":"Event category/type"},"description":{"type":"string","description":"Human-readable event description"},"timestamp":{"type":"string","format":"date-time","description":"When the event was received"},"data":{"type":"object","properties":{"domainId":{"type":"string","format":"uuid","nullable":true,"description":"Associated domain ID"},"domain":{"type":"string","nullable":true,"description":"Domain name"},"status":{"type":"string","nullable":true,"description":"Current domain status"},"provider":{"type":"string","description":"Provider name"}}}}}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/UnauthorizedError"}}}}}}
```


# Error Handling

### Error Handling

#### Error Response Format

```json
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      {
        "field": "domain",
        "message": "Please provide a valid domain name"
      }
    ]
  }
}
```

#### Common Error Codes

| HTTP Status | Code                   | Description                    |
| ----------- | ---------------------- | ------------------------------ |
| 400         | `VALIDATION_ERROR`     | Invalid request body           |
| 401         | `UNAUTHORIZED`         | Missing or invalid token       |
| 403         | `FORBIDDEN`            | Insufficient permissions       |
| 404         | `DOMAIN_NOT_FOUND`     | Domain does not exist          |
| 409         | `DOMAIN_EXISTS`        | Domain already being monitored |
| 422         | `UNPROCESSABLE_ENTITY` | Business logic error           |
| 429         | `RATE_LIMITED`         | Too many requests              |
| 500         | `INTERNAL_ERROR`       | Server error                   |

#### Rate Limiting

The API implements rate limiting to ensure fair usage:

* **Standard limit:** 100 requests per minute per user
* **Bulk operations:** Count as single request
* **Rate limit headers:**
  * `X-RateLimit-Limit`: Maximum requests allowed
  * `X-RateLimit-Remaining`: Requests remaining
  * `X-RateLimit-Reset`: Unix timestamp when limit resets

***


# Overview

TxShield's Fraud Management system evaluates transactions for risk using a configurable set of local rules and third-party scoring providers. Fraud checks can run in two modes: embedded within a payment transaction or as a standalone check independent of any payment.\
\
Two Processing Modes\
1\. Embedded Fraud Check (Payment-Triggered)\
Fraud checks run automatically as part of processing a `PAYMENT`, `PREAUTH`, or `AUTH` transaction. If the transaction's threat score exceeds the configured threshold, the payment is declined before authorization is attempted. No separate API call is needed — the fraud evaluation is built into the transaction flow.\
2\. Standalone Fraud Check\
A fraud check can also be submitted on its own — without processing a payment — using the `FRAUDCHECK` action. This allows merchants to evaluate a cardholder's risk profile before committing to a transaction, or to use TxShield's fraud scoring as a decision layer in their own workflow.\
A standalone check accepts the same inputs as a payment (card details, billing/shipping address, email, IP, cart data) but produces only a risk result — no charge is made.\[8:05 PM]Fraud Checks: Built-in vs. External\
Built-in checks (processed locally and immediately):<br>

* Velocity — repeated identical transactions within a short window
* BIN validation and issuing country check
* GeoIP — IP location vs. billing/shipping address
* Transaction limits — daily/monthly caps by IP, email, or card
* Chargeback and decline history
* Card and IP whitelists/blacklists
* Repeat transaction detection across card, email, or phone

External risk provider checks (real-time third-party scoring):<br>

* IP reputation, proxy/VPN/TOR detection
* Email validity and disposable email detection
* Phone number intelligence and risk scoring
* Identity verification across name, address, phone, and email
* Device fingerprinting and behavioral signals
* Order-level fraud scoring


# Fraud Check API

## POST /{sid}/fraudcheck

> Create a fraudcheck

```json
{"openapi":"3.0.0","info":{"title":"Txshield Api Version 1","version":"1.0"},"servers":[{"url":"/api/v1/index.php"}],"paths":{"/{sid}/fraudcheck":{"post":{"tags":["transaction"],"description":"Create a fraudcheck","parameters":[{"name":"sid","in":"path","description":"ID of site","required":true,"schema":{"type":"integer"}}],"requestBody":{"$ref":"#/components/requestBodies/post_sid_fraudcheck"},"responses":{"200":{"description":"Fraudcheck result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/fraudcheckResponse"}}}},"default":{"description":"unexpected error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/errorModel"}}}}}}}},"components":{"requestBodies":{"post_sid_fraudcheck":{"content":{"multipart/form-data":{"schema":{"type":"object","properties":{"hash":{"description":"md5 hash of sid+timestamp+amounttotal+currency+rcode e.g. md5('22'.'1234568995265421'.'17.00'.'USD'.'222b6c')","type":"string"},"timestamp":{"description":"timestamp value used in the hash e.g. 1234568995265421","type":"string"},"tid":{"description":"Merchant reference","type":"string"},"card_type":{"description":"type of card(visa/mastercard)","type":"string"},"card_no":{"description":"The card number or the bin","type":"integer","format":"int64"},"card_exp_month":{"description":"2 digit for the month. Please have leading zeroes e.g. 05","type":"string"},"card_exp_year":{"description":"4 digit year i.e. 2016","type":"string"},"card_name":{"description":"The name printed on the card","type":"string"},"card_ccv":{"description":"Card CCV","type":"number"},"bank_name":{"description":"The name of the bank","type":"string"},"bank_phone":{"description":"Bank phone number","type":"string"},"routing_no":{"description":"Bank routing number","type":"string"},"mobile":{"description":"Mobile number","type":"string"},"useragent":{"description":"string identifying the software acting on behalf of a user to interact with web servers","type":"string"},"browseragent":{"description":"string helps identify which browser is being used, what version, and on which operating system","type":"string"},"dynamic_descriptor":{"description":"Business name as it appears on the customer's bank statement","type":"string"},"fingerprintsession":{"description":"device fingerprint (Unique identifier for the session)","type":"string"},"threeDSecure":{"description":"json string containing 3ds2 check values","type":"string"},"device_info":{"description":"json string containing device information check values","type":"string"},"firstname":{"description":"First name of the customer.","type":"string"},"lastname":{"description":"Last name of the customer.","type":"string"},"email":{"description":"Email of the customer.","type":"string"},"phone":{"description":"Phone of the customer.","type":"string"},"address":{"description":"Billing street address","type":"string"},"suburb_city":{"description":"Billing suburb or city","type":"string"},"state":{"description":"Billing state, 2 letter code for US/Canada. Australia should use 2/3 letter codes.","type":"string"},"country":{"description":"Billing country, ISO 3166 2 digit code.","type":"string"},"postcode":{"description":"Billing postcode/zipcode.","type":"string"},"ship_address":{"description":"Shipping street address","type":"string"},"ship_suburb_city":{"description":"Shipping suburb or city","type":"string"},"ship_state":{"description":"Shipping state, 2 letter code for US/Canada. Australia should use 2/3 letter codes.","type":"string"},"ship_country":{"description":"Shipping country, ISO 3166 2 letter code.","type":"string"},"ship_postcode":{"description":"Shipping postcode/zipcode.","type":"string"},"amount":{"description":"Amount"},"currency":{"description":"Transaction currency, ISO 3 letter code","type":"string"},"items":{"description":"Array of items in the transaction","type":"array","items":{"type":"object"}},"addinfo":{"description":"Additional information","type":"string"},"uip":{"description":"users ip address","type":"string"}},"required":["hash","card_type","card_no","card_ccv","card_exp_month","card_exp_year","card_name","timestamp","firstname","lastname","email","amount","currency"]}}}}},"schemas":{"fraudcheckResponse":{"properties":{"sid":{"type":"integer","format":"int64","description":"sid of site"},"comment":{"type":"string","description":"comment"},"tid":{"type":"string","description":"Merchant reference"},"card_issuer":{"type":"string","description":"Name of the card issuer"},"txid":{"type":"integer","format":"int64","description":"Fraud check transaction id"},"status":{"type":"string","description":"Has the value \"OK\" for a successful transaction, \"EXC\" for a failed transaction, \"PEND\" for a transaction in progress."},"tx_action":{"type":"string","description":"FRAUDCHECK"},"amount":{"type":"number","description":"The amount specified in the request"},"currency":{"type":"string","description":"The currency specified in the request"},"pay_method":{"description":"Payment method specified in request","type":"string"},"error":{"type":"object","items":{"properties":{"type":{"type":"string"},"sys":{"type":"string"},"info":{"type":"string"},"status":{"type":"string"},"response":{"type":"string"},"logext":{"type":"string"},"msgcode":{"type":"string"},"details":{"type":"string"},"code":{"type":"string","description":"The error code, if status value equal \"EXC\"."},"msg":{"type":"string","description":"The error message, if status value equal \"EXC\"."}}}},"cardbindata":{"type":"object","items":{"properties":{"bin":{"type":"string"},"card_type":{"type":"string"},"bank_name":{"type":"string"},"country":{"type":"string"},"phone":{"type":"string"},"type":{"type":"string"},"level":{"type":"string"},"www":{"type":"string"},"date_added":{"type":"string"}}}},"fraud_checks":{"type":"string","description":"Json string with the details of fraudcheck"}}},"errorModel":{"required":["code","message"],"properties":{"code":{"type":"integer","format":"int32"},"message":{"type":"string"}}}}}}
```


# Field Definitions

Common Field and their definitions

## address

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 255        |

The customers address. e.g. 123 Customer Street.

## amount

| data type | min length | max length |
| --------- | ---------- | ---------- |
| decimal   | 0          | 9          |

The amount processed in the system for this transaction against this sid.

## amounttotal

| data type | min length | max length |
| --------- | ---------- | ---------- |
| decimal   | 0          | -          |

The amounttotal field is the calculated total of the transaction based on all information sent in, the total value of the cart items, shipping, tax minus any coupon amount.

The amounttotal is always used displaying any all minor units. \
e.g.\
USD$17  is used as 17.00 \
JPY¥17 is used as 17&#x20;

Calculating the amounttotal follows this pseudocode:&#x20;

```
amounttotal = 0;

for each item in the cart {
    amounttotal = amounttotal + ( item.quantity * item.amount_unit);
}

amounttotal = amounttotal + (amount_shipping + amount_tax - amount_coupon);
```

## card\_ccv

| data type | min length | max length |
| --------- | ---------- | ---------- |
| integer   | 3          | 6          |

The  security code on the customers cards. Also known as, CCV, CVV, CVC and CSC. This is not the Card PIN.&#x20;

## card\_exp\_month

| data type | min length | max length |
| --------- | ---------- | ---------- |
| integer   | 2          | 2          |

The expiry month for the customers card. Should be 0 filled. \
e.g. 1 (January) should be sent as 01. 2 should be sent as 02.

## card\_exp\_year

| data type | min length | max length |
| --------- | ---------- | ---------- |
| integer   | 2          | 2          |

The expiry year for the customers card. Should be 0 filled.  And is only 2 digits long.\
e.g. 2001 should be 01. 2022 should be 22..

## card\_no

| data type | min length | max length |
| --------- | ---------- | ---------- |
| integer   | 13         | 20         |

Also known as the PAN. This is the full credit card number. It should **not** have any punctuation or separators when sent. The system will not filter for any punctuation or separators and will just fail the transaction.

## card\_type

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 255        |

This is the payment method. It should be indicative of the payment type.&#x20;

e.g.&#x20;

* visa
* &#x20;mastercard
* bank

They paymethod should be provided to you at onboarding time. The payment methods available for your sid can also be retrieved using the [rawfee ](https://docs.payshield.ai/payshield-fraudcheck/pages/wmh1GXQn8uR3ulN7v7eM#soap-rawfeeapi.php)API.&#x20;

## country

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 3          | 3          |

The country code that belongs to the customers credit card. This should be the [Alpha 3 ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) country code.&#x20;

## currency

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 3          | 3          |

The 3 Alpha character [ISO 4217 code ](https://en.wikipedia.org/wiki/ISO_4217)for the currency.

## email

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 150        |

The customers email address.

## firstname

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 100        |

The customers first name.

## hash

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 32         | 32         |

The hash is a secure signature that is generated when you communicate with TxProcess.\
\
Every time you communicate with TxProcess and will create a Payment Record / Transaction in the system you will be required to create a hash to verify the contents of the transaction it self, and to complete your authentication with the system.

### Generating the Hash

The hash is the md5 of

* sid
* [timestamp](#timestamp)
* [amounttotal](#amounttotal)
* [currency](#currency)
* [rcode](#rcode)

i.e. `md5('22'.'1234568995265421'.'17.00'.'USD'.'222b6c')`

## lastname

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 100        |

The customers lastname.

## mobile

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 25         |

The customers mobile number.

## phone

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 25         |

The customers land line phone number. Not their mobile phone number. For mobile phone number see [mobile](#mobile).

## postcode

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 16         |

The postcode / zip code of the customer.

## rcode

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 40         |

The rcode will be provided to you at onboarding. The rcode should never be sent in as plain text with the payment data. It is the equivalent to your password and should never be accessible / viewable online.

## routing\_no

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 14         |

The routing or transit number, used for bank transfers.

## ship\_address

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 255        |

The shipping address. e.g. 123 Customer Street.

## ship\_country

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 3          | 3          |

The shipping country code. This should be the [Alpha 3 ISO 3166](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) country code.&#x20;

## ship\_postcode

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 16         |

The shipping postcode / zip code of the customer.

## ship\_state

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 32         |

The shipping state for the transaction.

## ship\_suburb\_city

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 60         |

The shipping suburb or city of the transaction.

## sid

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 11         |

The sid (Site ID) will be provided to you at onboarding.

## state

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 32         |

The customers billing state.

## status

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 10         |

The result of the transaction

## suburb\_city

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 60         |

The billing suburb or city of the customer.

## threeDSecure

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | -          |

Expects be a JSON object with a collection of ThreeDSecure(3DS) fields and their values. This is for the Authorization transaction, after a 3DS Authentication transaction has already occurred. To complete a 3DS Authentication, please contact support and they will help guide you for your specific integration. The particular fields and their naming can be different depending on how the Authentication is done, and the payment processor being used.

## tid

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 255        |

The txid (transaction id) that the system generated for this transaction.

## timestamp

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 10         | 10         |

The timestamp is to be a Unix timestamp&#x20;

## tx\_action

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 0          | 15         |

the transaction type. e.g. `PAYMENT` or `SETTLEMENT`

## txid

| data type | min length | max length |
| --------- | ---------- | ---------- |
| string    | 16         | 16         |

The transaction id for this transaction. If this is the first in a series of transactions, this could be the same as the [parent\_txid ](#parent_txid). If it is not the first, there will be a parent\_txid that will be used to group all of the series together.