> For the complete documentation index, see [llms.txt](https://docs.payengine.co/payengine-api-v2.5/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.payengine.co/payengine-api-v2.5/transaction-monitoring/pre-auth.md).

# Pre Auth

## Perform a pre-auth

<mark style="color:green;">`POST`</mark> `https://<Platform-host>/transaction-monitoring/pre-auth`

This endpoints accepts the payload similar to auth and sale endpoints and responds with a decision and list of rules that were applied to allow or decline the transaction.

**Body**

| Name                                                       | Type   | Description                                                                                                                                                                                            |
| ---------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| transaction\_type<mark style="color:red;">\*</mark>        | string | The type of payment request you want to perform. `sale \|auth\|capture\|refund`                                                                                                                        |
| merchant\_id<mark style="color:red;">\*</mark>             | string | Platform merchant ID                                                                                                                                                                                  |
| data.card\_token                                           | string | <p>Platform secure vault token. Only used if card is tokenized with Platform secure vault.<br><br>If using <code>cardToken</code> then account holder information is optional</p>                    |
| data.cardholder\_name                                      | string | Card holder name                                                                                                                                                                                       |
| data.card\_exp                                             | string | `MM/YY` card expiration data                                                                                                                                                                           |
| data.card\_number                                          | string | Primary account number (PAN)                                                                                                                                                                           |
| data.currency<mark style="color:red;">\*</mark>            | string | Currency code (USD\|CAD etc.)                                                                                                                                                                          |
| data.transaction\_amount<mark style="color:red;">\*</mark> | string | <p>Max Length=12 Allowed characters: 0-9 and .(dot)</p><p>Note: this value always reflects the total dollar amount for example 1.00 and 1 both will be considered $1.00 and 0.10 will be 10 cents.</p> |
| data.ip\_address                                           | string | Client IP address                                                                                                                                                                                      |

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

| Field Name                                            | Type   | Description                                                                                                                                                     |
| ----------------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| processing\_status<mark style="color:red;">\*</mark>  | string | Overall processing status `allow\|decline`                                                                                                                      |
| transaction\_status<mark style="color:red;">\*</mark> | string | The transaction status. If all rules are passed it will be `preauth` otherwise `failed`                                                                         |
| roc\_text\_data<mark style="color:red;">\*</mark>     | string | <p>Unique Platform assigned ID for this transaction.<br>This ID is generally used to reconcile settlement data and should be passed to processing gateways</p> |
| transaction\_id<mark style="color:red;">\*</mark>     | string | Platform's transaction ID                                                                                                                                      |
| triggered\_rules<mark style="color:red;">\*</mark>    | array  | List of configured rules and decisions                                                                                                                          |
| {% endtab %}                                          |        |                                                                                                                                                                 |
| {% endtabs %}                                         |        |                                                                                                                                                                 |

**Sample Request / Response**

{% tabs %}
{% tab title="Request" %}
**Example Sale Request**

```json
{
    "transaction_type": "sale",
    "merchant_id": "a9e30f16-1ef5-41e5-9ec2-c8e51a15b406",
    "data": {
        "card_token": "card_test_FhoSMXnzRcG88fa85XtcSF2h",
        "transaction_amount": "1.4",
        "ip_address": "100.43.79.254"
    }
}
```

**Example Auth Request**

```json
{
    "transaction_type": "auth",
    "merchant_id": "a9e30f16-1ef5-41e5-9ec2-c8e51a15b406",
    "data": {
        "card_number": "4111111111111111",
        "cardholder_name": "John Doe",
        "card_exp": "12/27",
        "currency_code": "USD",
        "transaction_amount": "5.50",
        "ip_address": "100.43.79.254"
    }
}
```

**Example Refund Request**

```json
{
    "transaction_type": "refund",
    "id": "09536b98-d422-45e4-98b1-9068623ac509",
    "amount": "5.00",
    "reason": "Item retuned"
}
```

{% endtab %}

{% tab title="Response" %}

```json
{
    "processing_status": "decline",
    "transaction_status": "failed",
    "roc_text_data": "1eaf22fa-80fa-429b-870a-649d2cdd232a",
    "transaction_id": "1eaf22fa-80fa-429b-870a-649d2cdd232a",
    "triggered_rules": [
        {
            "rule": "auth-count-per-card",
            "data": {
                "amount": "3",
                "time_frame": "1 hours"
            },
            "decisions": {
                "preauth": "hold-merchant-captures"
            },
            "result": false,
            "execution_time": 8,
            "decision": "allow"
        },
        {
            "rule": "duplicate-transaction-count",
            "data": {
                "exceed_limit": "1",
                "time_frame": "1 hours"
            },
            "decisions": {
                "preauth": "hold-transaction-capture"
            },
            "result": false,
            "execution_time": 2,
            "decision": "allow"
        },
        {
            "rule": "duplicate-transaction-count",
            "data": {
                "exceed_limit": "1",
                "time_frame": "1 hours"
            },
            "decisions": {
                "preauth": "block-merchant"
            },
            "result": false,
            "execution_time": 1,
            "decision": "allow"
        },
        {
            "rule": "ip-address",
            "data": {
                "ip_address": "100.43.79.255"
            },
            "decisions": {
                "preauth": "decline"
            },
            "result": false,
            "execution_time": 0,
            "decision": "allow"
        },
        {
            "rule": "ip-address-origin-country",
            "data": {
                "countries": "RU"
            },
            "decisions": {
                "preauth": "decline"
            },
            "result": true,
            "execution_time": 0,
            "decision": "decline"
        }
    ]
}
```

{% endtab %}
{% endtabs %}