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

# Credit Card Sale

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

#### Request Body

<table><thead><tr><th width="286">Name</th><th width="98">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><strong>Note</strong>: 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><br><strong>Not supported in SoftPOS SDK (Amount is provided as part of the startTransaction API parameter)</strong></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><br><br><strong>Not supported in SoftPOS SDK</strong></td></tr><tr><td>attempt_3d_secure</td><td>boolean</td><td>Indicates whether this transaction should attempt 3D Secure or not. By default sale API doesn't attempt 3DS<br><br><strong>Note</strong>: As per Visa 3DS mandate, cardholder's email or phone number is mandatory. If attempt_3d_secure is true and card type is visa and liability shift required by partner = yes and email/phone is <strong>not</strong> present then the transaction will fail due to cardholder email/phone not being present<br><br><strong>Not supported in SoftPOS SDK</strong></td></tr><tr><td>browser_info</td><td>string</td><td>Required if <code>attempt_3d_secure</code> is set to true<br><br><strong>Not Supported in SoftPOS SDK</strong></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)<br><br><strong>Not supported in SoftPOS SDK (Currency code is provided as part of the startTransaction API parameter)</strong></td></tr><tr><td><mark style="color:blue;">data.order_number</mark></td><td>string</td><td>Order number or PO number specified in billing statement of the cardholder.<br>Alphanumeric (a-z A-Z 0-9) maximum 20 characters<br><strong>Note</strong>: This field is required for Level II and Level III data</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.customer_name</td><td>string</td><td>If a name other than the cardholder's name needs to be shown on the transaction list, include it in this field. Note that this alternative name will not be used as the cardholder's name during card authorization.</td></tr><tr><td>data.tax_code</td><td>string</td><td>Tax code which is declared in accounting software</td></tr><tr><td>data.address_line_1</td><td>string</td><td><p>Address Line 1<br></p><p>Commonly the house number and street name on the cardholder's / customer's account or billing address. Address Verification Service (AVS) data compared with the address on the card issuer's file.</p></td></tr><tr><td>data.zip</td><td>string</td><td><p>Postal or ZIP Code<br></p><p>ZIP code on the cardholder's account or billing address. (AVS) data compared with the postal or ZIP code on the card issuer's file.</p></td></tr><tr><td><mark style="color:blue;">data.items</mark></td><td>array</td><td>List of items sold<br><br><strong>Note</strong>: This field is required for Level III data</td></tr><tr><td><mark style="color:blue;">data.items[].name</mark></td><td>string</td><td>Name of the item<br><br><strong>Note</strong>: This field is required for Level III data</td></tr><tr><td><mark style="color:blue;">data.items[].quantity</mark></td><td>string</td><td><p>Item quantity, default is 1</p><p><br><strong>Note</strong>: This field is required for Level III data</p></td></tr><tr><td><mark style="color:blue;">data.items[].product_code</mark></td><td>string</td><td>Description code of the item<br><br><strong>Note</strong>: This field is required for Level III data</td></tr><tr><td><mark style="color:blue;">data.items[].description</mark></td><td>string</td><td>Item descriptions<br><br><strong>Note</strong>: This field is required for Level III data</td></tr><tr><td><mark style="color:blue;">data.items[].commodity_code</mark></td><td>string</td><td>International description code of the individual good or service being supplied.<br><strong>Note</strong>: This field is required for Level III data</td></tr><tr><td><mark style="color:blue;">data.items[].unit_of_measure</mark></td><td>string</td><td>Unit of measurement<br>Default: Each<br><br><strong>Note</strong>: This field is required for Level III data</td></tr><tr><td><mark style="color:blue;">data.items[].unit_cost</mark></td><td>string</td><td><p>Unit cost of item</p><p><br><strong>Note</strong>: This field is required for Level III data</p></td></tr><tr><td><mark style="color:blue;">data.items[].tax_rate</mark></td><td>string</td><td>Percentage representing the value-added tax applied<br>Default: 0.00<br><br><strong>Note</strong>: This field is required for Level III data</td></tr><tr><td><mark style="color:blue;">data.items[].tax_amount</mark></td><td>string</td><td>Amount on sales tax on specific item and this amount is included in the item amount<br>Default: 0.00<br><br><strong>Note</strong>: This field is required for Level III data</td></tr><tr><td><mark style="color:blue;">data.items[].total_amount</mark></td><td>string</td><td>Total order amount for this item/s including the individual item tax<br><br><strong>Note</strong>: This field is required for Level III data</td></tr><tr><td><mark style="color:blue;">data.sales_tax</mark></td><td>string</td><td>Tax amount in the <code>transaction_amount.</code><br><br><strong>Note</strong>: This field is required for Level II and Level III data</td></tr><tr><td>data.other_tax[]</td><td>array</td><td>Contains additional tax details applied to the transaction</td></tr><tr><td>data.other_tax[].name</td><td>string</td><td>Name of the tax (e.g., Bottle Deposit Fee)<br><br><strong>Note</strong>: It is required if data.other_tax[].amount is provided</td></tr><tr><td>data.other_tax[].amount</td><td>string</td><td>Value of the tax and it is included in the transaction<br><br><strong>Note</strong>: It is required if data.other_tax[].name is provided</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. Check this reference for how to generate the fraud monitor session ID<br><strong>Not supported in SoftPOS SDK</strong></td></tr><tr><td>data.surcharge_amount</td><td>string</td><td>dGhAEiI6qdYo</td></tr><tr><td>data.description</td><td>string</td><td>Transaction Description. Character limit is 255</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.metadata</td><td>object</td><td>Add any additional metadata by passing a json object</td></tr><tr><td>data.gateway_id</td><td>string</td><td>Gateway ID (optional, if multigateway mode enabled)</td></tr><tr><td>data.ip_address</td><td>string</td><td>IP address of cardholder</td></tr><tr><td><mark style="color:blue;">data.shipping_amount</mark></td><td>string</td><td>Shipping amount included in the transaction amount.<br>Default is 0.00<br><strong>Note</strong>: This field is required for Level III data</td></tr><tr><td><mark style="color:blue;">data.shipping_country</mark></td><td>string</td><td>Shipping Country e.g. US<br>Default will be Merchant's country<br><br><strong>Note</strong>: This field is required for Level III data</td></tr><tr><td><mark style="color:blue;">data.ship_from_postal</mark></td><td>string</td><td>Postal/ZIP code of the address from where purchased goods are being shipped, defaults to merchant profile postal code.<br><br><strong>Note</strong>: This field is required for Level III data</td></tr><tr><td><mark style="color:blue;">data.shipping_postal</mark></td><td>string</td><td>Postal/ZIP code of the address where purchased goods will be delivered. This field can be identical to the 'ship_from_postal' if the customer is present and takes immediate possession of the goods.<br><br><strong>Note</strong>: This field is required for Level III data</td></tr><tr><td><mark style="color:blue;">data.commodity_code</mark></td><td>string</td><td>4 character international description code of the overall goods or services being supplied<br><br><strong>Note</strong>: This field is required for Level III data</td></tr><tr><td>data.kount.user_defined_fields</td><td>object</td><td>This is optional. Add the user defined values in Kount Portal and pass the same field name (should be exactly same) and value in this object.<br><br>For example, if a user defined value called "fieldName1" is added in Kount portal, then the field name should be fieldName1 in this object.<br><br><strong>Not supported in SoftPOS SDK</strong></td></tr></tbody></table>

**Note**: All the blue colored parameters are required for Level III data

**Response**

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

<table><thead><tr><th width="282">Field Name</th><th width="94">Type</th><th width="340.810546875">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>gateway_id</td><td>string</td><td>ID of the gateway through which the transaction is processed.</td><td>Optional</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>Platform token associated with the transaction</td><td>Required</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>currency_code</td><td>string</td><td><a href="/pages/IWuzbQA5mk1yAih65rxM">ISO Currency code</a> provided in the request<br><br><strong>Note</strong>: Only returned if originally provided in the request</td><td>Optional</td></tr><tr><td>three_ds_action_required</td><td>boolean</td><td>Indicates whether 3DS challenge needs to be initiated</td><td>Required</td></tr><tr><td>three_ds_type</td><td>string</td><td>Type of 3DS attempted. Allowed values frictionless | challenge | attempted</td><td>Optional</td></tr><tr><td>three_ds_status</td><td>string</td><td>3DS status. Allowed values succeeded | failed</td><td>Optional</td></tr><tr><td>sale_response.status</td><td>string</td><td>Transaction execution status.<br>Allowed values PASS | FAIL | PENDING_3DSAUTH</td><td>Required</td></tr><tr><td>sale_response.response_code</td><td>string</td><td><a href="/pages/3svuRYXMTJ1St1Zhun0p">The code representing the status of the processed request</a>. It comes from the processor</td><td>Required</td></tr><tr><td>sale_response.response_message</td><td>string</td><td>The corresponding message for the response code and it comes from the processor</td><td>Required</td></tr><tr><td>sale_response.auth_code</td><td>string</td><td>Authorization code received for the transaction</td><td>Optional</td></tr><tr><td>sale_response.host_reference_number</td><td>string</td><td>A unique reference number by the acquiring processor for each transaction.<br>If it fails, before sending to processor, then the values be<br>a. D (represents 3DS failed)<br>b. 2 (represents failure)</td><td>Optional</td></tr><tr><td>sale_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>sale_response.task_id</td><td>string</td><td>Task identification number from acquiring processor</td><td>Required</td></tr><tr><td>sale_response.transaction_id</td><td>string</td><td>Transaction Identifier</td><td>Optional</td></tr><tr><td>sale_response.transaction_timestamp</td><td>string</td><td>Transaction timestamp in merchant's timezone</td><td>Required</td></tr><tr><td>sale_response.transaction_amount</td><td>string</td><td>Total amount <strong>requested</strong> in this transaction.<br><br>For example, if the transactionAmount in the request is $100, then this SaleResponse.transactionAmount is also $100</td><td>Optional</td></tr><tr><td>sale_response.processed_amount</td><td>string</td><td>The actual amount processed by the processor.<br><br>In standard processing, <code>processedAmount</code> is same as <code>transactionAmount</code> . The differences become relevant when features like partial authorization or multi-currency are enabled.<br><br>For example,<br>1. With partial authorization, <code>transactionAmount</code> represents the requested amount, <code>processedAmount</code> the actual processed amount, and a partial indicator is set to 'yes'. Without partial authorization, insufficient funds will result in transaction failure.<br><br>2. With multi-currency enabled, the <code>transactionAmount</code> is $100 CAD, and the <code>processedAmount</code> will be $80 USD (if the merchant's currency is in USD)<br></td><td>Optional</td></tr><tr><td>sale_response.total_amount</td><td>string</td><td>The total amount for this transaction. In standard processing, <code>totalAmount</code> is same as <code>transactionAmount</code> as well as <code>processedAmount</code> . If a separate fee is applied, <code>totalAmount</code> will exceed <code>transactionAmount</code>.</td><td>Optional</td></tr><tr><td>sale_response.sales_tax</td><td>string</td><td>Tax amount in the <code>transactionAmount.</code></td><td>Optional</td></tr><tr><td>sale_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>sale_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 codes</a></td><td>Optional</td></tr><tr><td>sale_response.card_type</td><td>string</td><td>Card Type - visa, mastercard, american express, discover, dinersclub, ebt</td><td>Required</td></tr><tr><td>sale_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>sale_response.commercial_card</td><td>string</td><td><a href="/pages/Bn8VoMBiJbiHPSYp4LCM">Commercial card type</a></td><td>Optional</td></tr><tr><td>sale_response.aci</td><td>string</td><td>When VISA is used, the returned <a href="/pages/TYN0woWtrR7u4UzSlrv5">Authorization Characteristics Indicator (ACI)</a>. This one character value provides information concerning the transaction's CPS qualification status.</td><td>Optional</td></tr><tr><td>sale_response.transaction_integrity_classification</td><td>string</td><td><a href="/pages/Tp9SENSQ9BXxzy4LExaP">Mastercard purchase transaction type</a></td><td>Optional</td></tr><tr><td>sale_response.ucaf_collection_indicator</td><td>string</td><td>When Mastercard is used, <a href="/pages/DZ4dtvZCsXqK7gPrNXuv">Universal Cardholder Authentication</a> Field.</td><td>Optional</td></tr><tr><td>sale_response.fraud_score</td><td>int</td><td>Return the fraud score between 0 - 100. 100 means less confidence i.e. more fraudulent i and 0 means lower chance of fraudulent.<br>Note: The fraud monitoring has to be enabled. Please contact support to enable it</td><td>Optional</td></tr><tr><td>sale_response.kount_score</td><td>int</td><td>Return the Kount Omniscore</td><td>Optional</td></tr><tr><td>sale_response.customer_receipt</td><td>string</td><td>Printable customer receipt</td><td>Required</td></tr><tr><td>sale_response.merchant_receipt</td><td>string</td><td>Printable merchant receipt</td><td>Required</td></tr><tr><td>sale_response.partial_payment</td><td>string</td><td>A boolean indicating if the transaction was partially processed. If <code>true</code>, the processed amount is less than the requested amount</td><td>Required</td></tr><tr><td>metadata</td><td>object</td><td>Return all the metadata sent in the request</td><td>Optional</td></tr></tbody></table>
{% endtab %}

{% tab title="3DS Response Field Definitions" %}
{% hint style="info" %}
For complete 3DS flow please refer to our [3D Secure developer guide.](https://docs.payengine.co/payengine-developer-docs/processing-payments/3d-secure)
{% endhint %}

<table><thead><tr><th></th><th width="150"></th><th></th><th></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>three_ds_action_required</td><td>boolean</td><td>Indicates whether 3DS challenge needs to be initiated</td><td>Required</td></tr><tr><td>sale_response.status</td><td>string</td><td>Transaction execution status. If <code>ThreeDSActionRequired</code> is returned as true this status us set to <code>PENDING_3DSAUTH</code></td><td>Required</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 (via Token)**

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "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"
    }
}
</code></pre>

**Example Request with 3DS**

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "attempt_3d_secure": true,
    "browser_info": "COLLECTED USING CLIENT BROWSER",    
    "data": {
        "transaction_amount": "110.00",
        "card_token": "card_sandbox_xxxx",
        "description": "Payment for the services"
    }
}
</code></pre>

**Example Request with Metadata**

```json
{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "data": {
        "transaction_amount": "110.00",
        "card_token": "card_sandbox_xxxx",
        "description": "Payment for the services",
        "metadata": {             
            "customer_id": "123",
            "email": "test@test.com"
        }
    }
}
```

**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": [
          {
              "id" : "Item123",
              "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"
             }
         ]
    }
}
```

**Example Request with Additional Data**

```json
{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "data": {
        "transaction_amount": "110.00",
        "card_token": "card_sandbox_xxxx",
        "description": "Payment for the services",
        "additional_data": { 
            "loan_number": "L255525"
        }
    }
}
```

**Example Request with Optional Kount Data**

```json
{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "data": {
        "transaction_amount": "110.00",
        "card_token": "card_sandbox_xxxx",
        "description": "Payment for the services",
        "kount": {
            "user_defined_fields": {
                "field_name1": "Value1",
                "field_name2": "Value2"
            }
        }
    }
}
```

{% endtab %}

{% tab title="Response - Success Case" %}
**Example Response for Success Case**

```json
{
    "data": {
        "id": "b755760f-7ac7-4b6c-ac10-8225b4a6f5c9",
        "transaction_id": "165a95aa-06bd-4f3e-848e-5f0a5d86c78b",
        "merchant_id": "1e4e6029-2cc9-4b2c-87c1-7a4b2af6d6c6",
        "gateway_id": "1f3e0f67-d560-494c-bb1a-97558a462cc5",
        "three_ds_action_required": false,
        "internal_transaction_id": "987654321",
        "sale_response": {
            "status": "PASS",
            "response_code": "A0000",
            "response_message": "Success",
            "auth_code": "379015",
            "host_response_code": "00",
            "host_reference_number": "178430592489",
            "task_id": "14695897",
            "transaction_id": "49006898",
            "transaction_timestamp": "2025-04-02T17:53:06",
            "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:53 PM         \\n           CREDIT - SALE            \\n         Entry Mode : KEYED         \\n      Transaction ID: 49006898      \\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:53 PM         \\n           CREDIT - SALE            \\n         Entry Mode : KEYED         \\n      Transaction ID: 49006898      \\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
        },
        "description": "Payment for the services",
        "token": "card_sandbox_8Aq30HAc8TLFUFvTjqwo556i",
        "order_number": "Order124",
        "sales_tax": "10",
        "customer_name": "John Doe",
        "currency_code": "USD"
    }
}
```

**Example 3DS Response**

```json
{
    "data": {
        "id": "785bee37-8e14-427e-ab07-a3b0c16756a7",
        "transaction_id": "06c2aa36-f968-4205-a5dd-8bf455bdad59",
        "merchant_id": "e6803b29-68a4-4c2a-b3ee-019dfad86c61",
        "gateway_id": "1f3e0f67-d560-494c-bb1a-97558a462cc5",
        "description": "Payment for the services",
        "three_ds_action_required": false,
        "token": "card_sandbox_tE8BT9Betjsp7PV46IS9xb1c",
        "three_ds_type": "frictionless",
        "three_ds_status": "succeeded",
        "three_ds_data": "eyJ0IjoiMDZjMmFhMzYtZjk2OC00MjA1LWE1ZGQtOGJmNDU1YmRhZDU5IiwiZSI6InNhbmRib3giLCJzIjoiMjAyMi0wMS0xOVQyMjozNDoyMS4wNzJaIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJjZjRjOGI2NS0wZjc5LTQzZjYtODhiZi0wMmYwNzYzZTgxMGQiLCJ0aHJlZURTTWV0aG9kVVJMIjoiaHR0cHM6Ly9hY3Muc2FuZGJveC4zZHNlY3VyZS5pby8zZHNtZXRob2QifQ",
        "sale_response": {
            "status": "PENDING_3DSAUTH"
        },
        "metadata": {
            "customer_id": "123",
            "email" : "test@test.com"
        }
    }
}
```

**Example Response with Metadata**

```json
{
    "data": {
        "id": "62430b78-3049-4d25-9637-b78f3ea16709",
        "transaction_id": "8760a4f8-51fd-46eb-a3b4-32f08e05e487",
        "merchant_id": "1e4e6029-2cc9-4b2c-87c1-7a4b2af6d6c6",
        "gateway_id": "1f3e0f67-d560-494c-bb1a-97558a462cc5",
        "three_ds_action_required": false,
        "internal_transaction_id": "987654321",
        "sale_response": {
            "status": "PASS",
            "response_code": "A0000",
            "response_message": "Success",
            "auth_code": "165201",
            "host_response_code": "00",
            "host_reference_number": "990551169365",
            "task_id": "90687488",
            "transaction_id": "69832290",
            "transaction_timestamp": "2025-04-02T17:49:08",
            "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:49 PM         \\n           CREDIT - SALE            \\n         Entry Mode : KEYED         \\n      Transaction ID: 69832290      \\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:49 PM         \\n           CREDIT - SALE            \\n         Entry Mode : KEYED         \\n      Transaction ID: 69832290      \\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
        },
        "description": "Payment for the services",
        "metadata": {
            "customer_id": "123",
            "email": "test@test.com"
        },
        "token": "card_sandbox_8Aq30HAc8TLFUFvTjqwo556i",
        "order_number": "Order124",
        "sales_tax": "10",
        "customer_name": "John Doe",
        "currency_code": "USD"
    }
}
```

**Example Response with Additional Data**

```json
{
    "data": {
        "id": "01886ffd-e722-4118-b0df-1b8994447791",
        "transaction_id": "f43cc773-fd99-480e-8634-f141db820800",
        "merchant_id": "8357832f-79c9-48fd-9647-d1dae251e434",
        "three_ds_action_required": false,
        "token": "card_sandbox_tE8BT9Betjsp7PV46IS9xb1c",
        "sale_response": {
            // normal saleResponse here
        },
        "additional_data": {
            "loan_number": "L52353545"
        },
        "metadata": {
            "customer_id": "123",
            "email" : "test@test.com"
        }
    }
}
```

{% endtab %}

{% tab title="Response - Error Case" %}
**Sample Response for Error case**

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "id": "c03ce6ad-1e78-4bd7-ad35-e0d46b6b765d",
    "transaction_id": "2a03cbbb-7c94-4c99-8bb5-b89767dca086",
    "merchant_id": "b0ad3bfe-c7a1-4def-9840-6c9b2570d2ce",
    "gateway_id": "1f3e0f67-d560-494c-bb1a-97558a462cc5",
    "description": "Payment for the services",
    "three_ds_action_required": false,
    "sale_response": {
        "status": "FAIL",
        "response_code": "2",
        "response_message": "Declined: NSF",
        "auth_code": "",
        "host_reference_number": "204723420634",
        "host_response_code": "200",
        "task_id": "3251193947",
        "transaction_id": "3066147279",
        "transaction_timestamp": "2022-02-16T15:45:24",
        "transaction_amount": "0.01",
        "processed_amount": "0.01",
        "total_amount": "0.01",
        "address_verification_code": "Z",
        "card_holder_verification_code": "M",
        "card_type": "visa",
        "masked_card_number": "4xxxxxxxxxxx6782",
        "commercial_card": "B",
        "aci": "N",
        "fraud_score": 99,
        "customer_receipt": "PRINTABLE RECEIPT",
        "merchant_receipt": "PRINTABLE RECEIPT"
    },
    "metadata": {
        "customer_id": "123",
        "email": "test@test.com"
    }
}
</code></pre>

**Sample Response when the card token is expired**

<pre class="language-json"><code class="lang-json"><strong>{
</strong>    "error":true,
    "message":"E136 - Card token expired"
}
</code></pre>

**Sample Response when card is not found**

```json
{
    "error":true,
    "message":"E135 - Card not found"
}
```

**Sample Response when 3DS is failed is not found**

```json
{
   "data": {
        "id":"cb7010a3-fbfd-4cfc-a1a2-cd6455f2058e",
        "transaction_id":"a4e28094-a243-4dc8-9ba3-63be4023cddd",
        "merchant_id":"90f60f5d-0f35-4125-91aa-3f4532f4bafe",
        "three_ds_action_required":false,
        "three_ds_status":"failed",
        "three_ds_type":"frictionless",
        "sale_response": {
            "status":"FAIL",
            "response_code":"D",
            "response_message":"3DS Directory Server Error" //Other error message could 3DS failed: transStatus`
        }
    }
}

```

**Sample Response when Kount fails the transaction**

```json
{
    "error":true,
    "data": {
        "id":"228aeb4d-33b6-4398-af78-207d72c09a60",
        "merchant_id":"0a22c769-b3bb-40b9-963d-a4be6fe1f34d",
        "transaction_id":"95781beb-f9ee-41c0-bc16-0753303549c0",
        "sale_response": {
            "status":"FAIL",
            "response_code":"2",
            "response_message":"Transaction declined due to high risk",
            "fraud_score":"97.00",
            "kount_score":"3.00"
        }
    }
}
```

{% endtab %}
{% endtabs %}

{% hint style="info" %}
For complete 3DS flow please refer to our [3D Secure developer guide.](https://docs.payengine.co/payengine-developer-docs/processing-payments/3d-secure)
{% endhint %}

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

#### Webhook Payload Example

```json
{
    "event_uid": "d2e9f63779ad668603a51b563ec68b6f",
    "event": "PAYMENT_SALE",
    "data": {
        "token": "card_sandbox_8Aq30HAc8TLFUFvTjqwo556i",
        "metadata": {
            "email": "test@test.com",
            "customer_id": "123"
        },
        "sales_tax": "10",
        "account_id": "fa3ac0a8-0cda-4e38-ba9d-357b0f0bd844",
        "gateway_id": "1f3e0f67-d560-494c-bb1a-97558a462cc5",
        "payment_id": "62430b78-3049-4d25-9637-b78f3ea16709",
        "description": "Payment for the services",
        "merchant_id": "1e4e6029-2cc9-4b2c-87c1-7a4b2af6d6c6",
        "currency_code": "USD",
        "order_number": "Order124",
        "customer_name": "John Doe",
        "sale_response": {
            "status": "PASS",
            "task_id": "90687488",
            "auth_code": "165201",
            "card_type": "visa",
            "total_amount": "110.00",
            "response_code": "A0000",
            "transaction_id": "69832290",
            "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:49 PM         \\n           CREDIT - SALE            \\n         Entry Mode : KEYED         \\n      Transaction ID: 69832290      \\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:49 PM         \\n           CREDIT - SALE            \\n         Entry Mode : KEYED         \\n      Transaction ID: 69832290      \\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": "990551169365",
            "transaction_timestamp": "2025-04-02T17:49:08",
            "address_verification_code": "X",
            "card_holder_verification_code": "N"
        },
        "transaction_id": "8760a4f8-51fd-46eb-a3b4-32f08e05e487",
        "internal_transaction_id": "987654321"
    }
}
```