> 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/transactions/authorization.md).

# Credit Card Authorization

<mark style="color:green;">`POST`</mark> `https://<Platform-host>/api/payment/auth`

#### Request Body

<table><thead><tr><th width="231.1123046875">Name</th><th width="125.423828125">Type</th><th>Description</th></tr></thead><tbody><tr><td>merchant_id<mark style="color:red;">*</mark></td><td>string</td><td>Merchant ID</td></tr><tr><td>transaction_monitoring_bypass</td><td>boolean</td><td>Optional flag to explicitly skip transaction monitoring rules.</td></tr><tr><td>data.transaction_amount<mark style="color:red;">*</mark></td><td>string</td><td>Max Length=12<br>Allowed characters: 0-9 and .(dot)<br><br>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.<br></td></tr><tr><td>data.pre_settlement_fee_charge</td><td>string</td><td><p>An optional fee amount to be deducted from the transaction before settlement. This fee is processed at the processor level and reduces the net amount settled to the merchant. The value must be a positive number and cannot exceed the total transaction amount.<br><br>Applicable in scenarios where the merchant needs to collect fees separately or adjust the settlement amount.<br><br></p><p><em>Constraints</em>:</p><ul><li>Must be a positive decimal number.</li><li>Cannot be greater than the <code>transaction_amount</code>.</li><li>If set to zero or omitted, no pre-settlement fee will be deducted.</li></ul><p><em>Example</em>:</p><ul><li><strong>Transaction Amount</strong>: $100.00</li><li><strong><code>pre_settlement_fee_charge</code></strong>: $5.00</li><li><strong>Net Settlement to Merchant</strong>: $95.00 (after deducting the $5.00 fee)</li></ul><p><em>Note</em>: The customer will still be charged the full transaction amount of $100.00, but the merchant will receive $95.00 due to the $5.00 pre-settlement fee deduction.</p></td></tr><tr><td>data.post_settlement_fee_charge</td><td>string</td><td><p>An optional fee amount to be deducted after the transaction has been settled at the processor level but before the net amount is paid out to the merchant. This fee adjusts the final payout to the merchant while maintaining the full transaction amount charged to the customer.<br><br>Note:</p><ul><li>Use this parameter for fees such as processing charges, administrative fees, or adjustments that need to be applied after settlement but before the payout to the merchant.</li><li>Applicable for scenarios where deductions are required post-transaction processing.</li></ul><p><em>Constraints</em>:</p><ul><li>Must be a positive decimal number.</li><li>Cannot exceed the total <code>transaction_amount</code>.</li><li>If omitted or set to zero, no post-settlement fee will be deducted.</li></ul><p><em>Example</em>:</p><ul><li><strong>Transaction Amount</strong>: $100.00</li><li><strong>Settlement Amount</strong>: $100.00 (full amount settled)</li><li><strong><code>post_settlement_fee_charge</code></strong>: $7.50</li><li><strong>Net Payout to Merchant</strong>: $92.50 (after deducting the $7.50 fee)</li></ul><p><em>Note</em>: The customer will still see a charge of $100.00 for the transaction. The deduction is applied only to the merchant's payout after the settlement.</p></td></tr><tr><td>data.card_token<mark style="color:red;">*</mark></td><td>string</td><td>Card token generated by <a href="/pages/YN9W4Ldyth3zlYUEy6qa">Platform secure field API</a></td></tr><tr><td>data.internal_transaction_id</td><td>string</td><td>An internal ID from integrating system. Will be returned in the response and associated refunds if provided.</td></tr><tr><td>data.currency_code</td><td>string</td><td><a href="/pages/IWuzbQA5mk1yAih65rxM">ISO Currency Code</a> if not provided it defaults to US Dollar (USD)</td></tr><tr><td>data.order_number</td><td>string</td><td>Order number specified in billing statement of the cardholder.<br>Alphanumeric (a-z A-Z 0-9) maximum 20 characters.</td></tr><tr><td>data.customer_name</td><td>string</td><td>If a name other than the card holder's name is required to be shown on the transaction list, it is important to note that this alternative name will not serve as the card holder's name during card authorization.</td></tr><tr><td>data.gratuity</td><td>string</td><td>Gratuity amount added to the original sale</td></tr><tr><td>data.service_charge</td><td>string</td><td>Service charges, if any</td></tr><tr><td>data.items</td><td>array</td><td>List of items sold</td></tr><tr><td>data.items[].name</td><td>string</td><td>Name of the item</td></tr><tr><td>data.items[].description</td><td>string</td><td>Item description</td></tr><tr><td>data.items[].quantity</td><td>string</td><td>Item quantity, default is 1</td></tr><tr><td>data.items[].is_service</td><td>string</td><td>Flag to indicate item sold is a service; default is <code>false</code></td></tr><tr><td>data.items[].tax_rate</td><td>string</td><td>Tax rate applied to sale</td></tr><tr><td>data.items[].tax_amount</td><td>string</td><td>Total tax amount</td></tr><tr><td>data.items[].total_amount</td><td>string</td><td>Total order amount for this item/s</td></tr><tr><td>data.sales_tax</td><td>string</td><td>Tax amount in the <code>transaction_amount</code></td></tr><tr><td>data.other_tax[]</td><td>array</td><td>Contains additional tax details to the transaction</td></tr><tr><td>data.other_tax[].name</td><td>string</td><td>Name of the tax</td></tr><tr><td>data.other_tax[].amount</td><td>string</td><td>Value of the tax</td></tr><tr><td>data.fraud_monitor_session_id</td><td>String</td><td>Fraud monitor session ID. Obtain by using Platform's fraud prevention javascript library.</td></tr><tr><td>data.surcharge_amount</td><td>string</td><td><p>Max Length=12<br>Allowed characters: 0-9 and .(dot)<br></p><p>The surcharge amount should be included in the transaction amount.</p><p><br>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></td></tr><tr><td>data.description</td><td>string</td><td>Transaction Description. Character limit is 255</td></tr><tr><td>data.metadata</td><td>object</td><td>Add any additional metadata by passing a json object</td></tr><tr><td>data.additional_data</td><td>object</td><td>Optional data. Currently, it is specific to certain use case for accounting integration</td></tr><tr><td>data.ip_address</td><td>string</td><td>IP address of cardholder</td></tr><tr><td>data.gateway_id</td><td>string</td><td>Gateway ID (optional, if multigateway mode enabled)</td></tr></tbody></table>

{% tabs %}
{% tab title="200 " %}
{% tabs %}
{% tab title="Field Definitions" %}

<table><thead><tr><th width="288.15625">Field Name</th><th width="99.3671875">Type</th><th width="330.005859375">Description</th><th>Required?</th></tr></thead><tbody><tr><td>id</td><td>string</td><td>Platform payment ID for the sale request</td><td>Required</td></tr><tr><td>transaction_id</td><td>String</td><td>Unique transaction ID</td><td>Required</td></tr><tr><td>merchant_id</td><td>string</td><td>Merchant ID</td><td>Required</td></tr><tr><td>description</td><td>string</td><td>Transaction description</td><td>Optional</td></tr><tr><td>token</td><td>string</td><td>Card token provided in the request that is used to process this authorization</td><td>Required</td></tr><tr><td>currency_code</td><td>string</td><td>ISO Currency code provided in the request<br><br><strong>Note</strong>: Only returned if originally provided in the request</td><td>Optional</td></tr><tr><td>internal_transaction_id</td><td>string</td><td>Internal Transaction ID provided in the request</td><td>Optional</td></tr><tr><td>order_number</td><td>string</td><td>Order number provided in the request</td><td>Optional</td></tr><tr><td>customer_name</td><td>string</td><td>Customer name provided in the request</td><td>Optional</td></tr><tr><td>auth_response.status</td><td>string</td><td>Transaction execution status.<br>Allowed values PASS | FAIL | PENDING_3DSAUTH</td><td>Required</td></tr><tr><td>auth_response.response_code</td><td>string</td><td><a href="/pages/3svuRYXMTJ1St1Zhun0p">The code representing the status of the processed request</a></td><td>Required</td></tr><tr><td>auth_response.response_message</td><td>string</td><td>The corresponding message for the response code</td><td>Required</td></tr><tr><td>auth_response.auth_code</td><td>string</td><td>Authorization code received for the transaction</td><td>Optional</td></tr><tr><td>auth_response.host_reference_number</td><td>string</td><td>A unique reference number by the acquiring processor for each transaction</td><td>Optional</td></tr><tr><td>auth_response.host_response_code</td><td>string</td><td><a href="/pages/Jvv9mJQ96Xz9irQH3ll1">Response code indicating the status of the authorization request</a></td><td>Optional</td></tr><tr><td>auth_response.task_id</td><td>string</td><td>Task identification number from acquiring processor</td><td>Required</td></tr><tr><td>auth_response.transaction_id</td><td>string</td><td>Transaction Identifier</td><td>Optional</td></tr><tr><td>auth_response.transaction_timestamp</td><td>string</td><td>Transaction timestamp in merchant's timezone</td><td>Required</td></tr><tr><td>auth_response.transaction_amount</td><td>string</td><td>Total amount requested in this transaction</td><td>Optional</td></tr><tr><td>auth_response.processed_amount</td><td>string</td><td>Total amount processed in this transaction</td><td>Optional</td></tr><tr><td>auth_response.total_amount</td><td>string</td><td>Total amount of this transaction</td><td>Optional</td></tr><tr><td>auth_response.items[].name</td><td>string</td><td>Item name</td><td>Optional</td></tr><tr><td>auth_response.items[].quantity</td><td>string</td><td>Item quantity</td><td>Optional</td></tr><tr><td>auth_response.items[].unit_cost</td><td>string</td><td>Item cost</td><td>Optional</td></tr><tr><td>auth_response.items[].description</td><td>string</td><td>Item description</td><td>Optional</td></tr><tr><td>auth_response.items[].total_amount</td><td>string</td><td>Total amount for the item</td><td>Optional</td></tr><tr><td>auth_response.address_verification_code</td><td>string</td><td><a href="/pages/J5Kmr5zaPCENHDS0lhKy">Address verification system response</a></td><td>Optional</td></tr><tr><td>auth_response.card_holder_verification_code</td><td>string</td><td><a href="https://docs.payengine.co/payengine-api-reference/error-and-response-codes/cvv-verification-codes">CVV verification code</a></td><td>Optional</td></tr><tr><td>auth_response.card_type</td><td>string</td><td>Card Type - visa, mastercard, american express, discover, dinersclub, ebt</td><td>Required</td></tr><tr><td>auth_response.masked_card_number</td><td>string</td><td>The truncated card number displaying the last four digits</td><td>Required</td></tr><tr><td>auth_response.customer_receipt</td><td>string</td><td>Printable customer receipt</td><td>Required</td></tr><tr><td>auth_response.merchant_receipt</td><td>string</td><td>Printable merchant receipt</td><td>Required</td></tr><tr><td>auth_response.partial_payment</td><td>string</td><td>A boolean indicating if the transaction was partially authorized. If <code>true</code>, the processed amount is less than the requested amount</td><td>Required</td></tr><tr><td>metadata</td><td>string</td><td>Return all the metadata sent in the request</td><td>Optional</td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
When automatic [Network Tokenization](https://docs.payengine.co/developer-docs/tokenization/automatic-network-tokenization) is activated on your account, the transactions will be completed using card brand tokens and respective benefits wil apply.
{% endhint %}

### Sample Request / Response

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

```json
{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "data": {
        "transaction_amount": "110.00",
        "card_token": "card_sandbox_xxxx",
        "order_number": "Order124",
        "description": "Payment for the services",
        "customer_name": "John Doe",
        "ip_address": "10.10.10.10",
        "sales_tax": "10",
        "internal_transaction_id": "987654321",
        "currency_code": "USD"
    }
}
```

**Example Request with items**

```json
{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "attempt_3d_secure": true,
    "browser_info": "COLLECTED USING CLIENT BROWSER",    
    "data": {
        "transaction_amount": "200.20",
        "card_token": "card_sandbox_xxxx",
        "description": "Payment for the services",
        "items": [
          {
              "name": "Sample",
              "unit_cost": "95.00",
              "quantity": 2,
              "total_amount": "190.00" //included in the transaction amount
            }
         ],
         "sales_tax": "10.00",
         "other_tax": [
             {
                 "name": "CRV",
                 "amount": "0.20"
             }
         ],
        "metadata": {
            "customer_id": "123",
            "email" : "test@test.com"
        }
    }
}
```

{% endtab %}

{% tab title="Response" %}
**Example Response**

```json
{
    "data": {
        "id": "cd9f4405-a5c9-40a1-999d-7587f34e7b42",
        "transaction_id": "5f805b55-a7e0-4ce0-83d7-a6503b04be4b",
        "merchant_id": "1e4e6029-2cc9-4b2c-87c1-7a4b2af6d6c6",
        "description": "Payment for the services",
        "internal_transaction_id": "987654321",
        "token": "card_sandbox_8Aq30HAc8TLFUFvTjqwo556i",
        "gateway_id": "1f3e0f67-d560-494c-bb1a-97558a462cc5",
        "auth_response": {
            "status": "PASS",
            "response_code": "A0000",
            "response_message": "Success",
            "auth_code": "248293",
            "host_response_code": "00",
            "host_reference_number": "673084425015",
            "task_id": "93461014",
            "transaction_id": "47649279",
            "transaction_timestamp": "2025-04-02T17:57:20",
            "transaction_amount": "110.00",
            "processed_amount": "110.00",
            "total_amount": "110.00",
            "address_verification_code": "X",
            "card_holder_verification_code": "N",
            "card_type": "visa",
            "masked_card_number": "1111",
            "customer_receipt": "        Sandbox US Merchant         \\n        200 Epcot Center Dr         \\n         Orlando, FL 32836          \\n            800-490-8514            \\n                 \\n                 \\n        2025-04-02 05:57 PM         \\n           CREDIT - SALE            \\n         Entry Mode : KEYED         \\n      Transaction ID: 47649279      \\n      Invoice Number: Order124      \\nDescription: Payment for the service\\n                 s                  \\n       SUBTOTAL: USD $100.00        \\n       SALES TAX: USD $10.00        \\n         TOTAL: USD $110.00         \\n                 \\n                 \\n       NO SIGNATURE REQUIRED        \\n              APPROVED              \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n           Customer Copy            \\n",
            "merchant_receipt": "        Sandbox US Merchant         \\n        200 Epcot Center Dr         \\n         Orlando, FL 32836          \\n            800-490-8514            \\n                 \\n                 \\n        2025-04-02 05:57 PM         \\n           CREDIT - SALE            \\n         Entry Mode : KEYED         \\n      Transaction ID: 47649279      \\n      Invoice Number: Order124      \\nDescription: Payment for the service\\n                 s                  \\n       SUBTOTAL: USD $100.00        \\n       SALES TAX: USD $10.00        \\n         TOTAL: USD $110.00         \\n                 \\n                 \\n      X_______________________      \\nI AGREE TO PAY ABOVE TOTAL AMOUNT IN\\n ACCORDANCE WITH CARD ISSUER's AGREE\\nMENT (MERCHANT AGREEMENT IF CREDIT V\\n              OUCHER)               \\n     KEEP COPY FOR YOUR RECORDS     \\n               \\n \\n                \\n              APPROVED              \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n           Merchant Copy            \\n",
            "partial_payment": false
        },
        "order_number": "Order124",
        "sales_tax": "10",
        "customer_name": "John Doe",
        "currency_code": "USD"
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
Webhook event: **PAYMENT\_AUTH**
{% endhint %}

#### Webhook Payload Example

```json
{
    "event_uid": "9fff410f1903817978471c90e677b814",
    "event": "PAYMENT_AUTH",
    "data": {
        "token": "card_sandbox_8Aq30HAc8TLFUFvTjqwo556i",
        "sales_tax": "10",
        "account_id": "fa3ac0a8-0cda-4e38-ba9d-357b0f0bd844",
        "gateway_id": "1f3e0f67-d560-494c-bb1a-97558a462cc5",
        "payment_id": "cd9f4405-a5c9-40a1-999d-7587f34e7b42",
        "description": "Payment for the services",
        "merchant_id": "1e4e6029-2cc9-4b2c-87c1-7a4b2af6d6c6",
        "currency_code": "USD",
        "order_number": "Order124",
        "auth_response": {
            "status": "PASS",
            "task_id": "93461014",
            "auth_code": "248293",
            "card_type": "visa",
            "total_amount": "110.00",
            "response_code": "A0000",
            "transaction_id": "47649279",
            "partial_payment": false,
            "customer_receipt": "        Sandbox US Merchant         \\n        200 Epcot Center Dr         \\n         Orlando, FL 32836          \\n            800-490-8514            \\n                 \\n                 \\n        2025-04-02 05:57 PM         \\n           CREDIT - SALE            \\n         Entry Mode : KEYED         \\n      Transaction ID: 47649279      \\n      Invoice Number: Order124      \\nDescription: Payment for the service\\n                 s                  \\n       SUBTOTAL: USD $100.00        \\n       SALES TAX: USD $10.00        \\n         TOTAL: USD $110.00         \\n                 \\n                 \\n       NO SIGNATURE REQUIRED        \\n              APPROVED              \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n           Customer Copy            \\n",
            "merchant_receipt": "        Sandbox US Merchant         \\n        200 Epcot Center Dr         \\n         Orlando, FL 32836          \\n            800-490-8514            \\n                 \\n                 \\n        2025-04-02 05:57 PM         \\n           CREDIT - SALE            \\n         Entry Mode : KEYED         \\n      Transaction ID: 47649279      \\n      Invoice Number: Order124      \\nDescription: Payment for the service\\n                 s                  \\n       SUBTOTAL: USD $100.00        \\n       SALES TAX: USD $10.00        \\n         TOTAL: USD $110.00         \\n                 \\n                 \\n      X_______________________      \\nI AGREE TO PAY ABOVE TOTAL AMOUNT IN\\n ACCORDANCE WITH CARD ISSUER's AGREE\\nMENT (MERCHANT AGREEMENT IF CREDIT V\\n              OUCHER)               \\n     KEEP COPY FOR YOUR RECORDS     \\n               \\n \\n                \\n              APPROVED              \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n           Merchant Copy            \\n",
            "processed_amount": "110.00",
            "response_message": "Success",
            "host_response_code": "00",
            "masked_card_number": "1111",
            "transaction_amount": "110.00",
            "host_reference_number": "673084425015",
            "transaction_timestamp": "2025-04-02T17:57:20",
            "address_verification_code": "X",
            "card_holder_verification_code": "N"
        },
        "customer_name": "John Doe",
        "transaction_id": "5f805b55-a7e0-4ce0-83d7-a6503b04be4b",
        "internal_transaction_id": "987654321"
    }
}
```