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

# Device Sale

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

#### Request Body

<table><thead><tr><th width="276">Name</th><th width="101.5751953125">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>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><br><strong>Not supported in SoftPOS SDK (Amount is provided as part of the startTransaction API parameter)</strong></td></tr><tr><td>data.device_id<mark style="color:red;">*</mark></td><td>string</td><td>Registered and connected device ID</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>data.address_line1</td><td>string</td><td><p>Address Line 1</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</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>data.order_number</td><td>string</td><td>Order Number to add to billing statement of the cardholder</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.description</td><td>string</td><td>Transaction description. Character limit is 255</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>data.items</td><td>string</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[].quantity</td><td>string</td><td>Item quantity. Default is 1</td></tr><tr><td>data.items[].unit_of_measure</td><td>string</td><td>Unit of measurement</td></tr><tr><td>data.items[].unit_cost</td><td>string</td><td>Unit cost of item</td></tr><tr><td>data.items[].total_amount</td><td>string</td><td>Total order amount for this item/s including the individual item tax</td></tr><tr><td>data.sales_tax</td><td>string</td><td>Sales Tax amount is included in the transaction amount</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) <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 <strong>Note</strong>: It is required if data.other_tax[].name is provided</td></tr><tr><td>data.metadata</td><td>string</td><td>Add any additional metadata by passing a json object</td></tr><tr><td>data.async_mode</td><td>boolean</td><td><p>Default is <code>false</code>.</p><p>See details of async mode below.</p></td></tr><tr><td>data.edc</td><td>string</td><td><p><strong>CREDIT | DEBIT | EBT</strong></p><p>An optional parameter to specify a particular payment method. If not provided, customers will be given the option to select their preferred payment type, provided this feature is enabled in your account.</p><p><strong>Note:</strong> If a specific payment method is specified, the terminal will be restricted to processing only that type of payment. This could lead to a transaction failure if the merchant is not configured to accept the specified payment method.</p></td></tr></tbody></table>

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

<table><thead><tr><th width="345.4169921875">Field Name</th><th width="104">Type</th><th width="303.705810546875">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>device_id</td><td>string</td><td>Device ID provided in the request</td><td>Required</td></tr><tr><td>token</td><td>string</td><td>Platform token associated with the transaction</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>internal_transaction_id</td><td>string</td><td>Internal Transaction ID provided in the request</td><td>Optional</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>customer_name</td><td>string</td><td>Customer name 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>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><p>Transaction execution status. Allowed values:</p><ul><li><code>PASS</code></li><li><code>FAIL</code></li><li><code>PENDING</code></li></ul></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>.</td><td>Required</td></tr><tr><td>sale_response.response_message</td><td>string</td><td>The corresponding message for the response code</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</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 requested in this transaction</td><td>Optional</td></tr><tr><td>sale_response.partial_payment</td><td>boolean</td><td>True | False<br>True - Indicates that transaction is a partial payment and refer to SaleResponse.processedAmount for the partial amount processed</td><td>Required</td></tr><tr><td>sale_response.processed_amount</td><td>string</td><td>Total amount processed in this transaction</td><td>Optional</td></tr><tr><td>sale_response.total_amount</td><td>string</td><td>Total amount of this transaction</td><td>Optional</td></tr><tr><td>sale_response.sales_tax</td><td>string</td><td>Sales tax included in the request</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 code</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>metadata</td><td>object</td><td>Return all the metadata sent in the request</td><td>Optional</td></tr></tbody></table>
{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}

#### Important considerations

####

#### Synchronous Flow

Submit a request to Platform and wait for its reply. Customer engagement with the card reader may result in a wait time of up to 90 seconds. Expect a transaction ID and a standard transaction response.\
\
**Why use synchronous flow**: Less development, and the API response is identical to a standard [**sale API response**](/payengine-api-v2.5/transactions/sale.md). Parsing the response, if you already use the sale API, will be identical\
\
Please note that due to internet connectivity issues, if you lose internet connectivity while waiting for the API call, you will not receive the API response. This will require you to [**query Platform**](/payengine-api-v2.5/transactions/search-transactions/transaction-detail.md) or log into the partner console to see the status of the transaction. To avoid this result altogether, please use the async flow.

#### Asynchronous Flow

Submit a request setting `async_mode` to true, and immediately receive a response featuring a PENDING status and transaction ID. Payment processing occurs asynchronously. To obtain the final transaction status, either poll the [transaction detail](/payengine-api-v2.5/transactions/search-transactions/transaction-detail.md) API until completion or listen for the PAYMENT\_SALE webhook to complete the process.

#### Other considerations

* **Offline transactions**: If you're in an environment where internet connectivity issues can occur frequently and the device is offline as a result, we can set you up with a device solution that supports store and forward. With this set-up your transaction will still be captured on the device and will get submitted when internet is back on.
  {% endhint %}

### Sample Request / Responses

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

```json
{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "data": {
        "async_mode": true,
        "transaction_amount": "110.00",
        "device_id": "e68f0d4b-6a64-4426-a7b7-062be8e332e",
        "gateway_id": "4bf4e48e-21da-4efe-8fab-e5635590da74",
        "description": "Payment for the services",
        "metadata": {
            "customerId": "123",
            "email" : "test@test.com"
        }
    }
}
```

**Example Request with items**

```json
{
    "merchant_id": "a447b0b8-0dbb-4e07-bfc2-c35bba8d71e8",
    "attempt3DSecure": true,
    "browserInfo": "COLLECTED USING CLIENT BROWSER",    
    "data": {
        "transaction_amount": "110.00",
        "device_id": "e68f0d4b-6a64-4426-a7b7-062be8e332e",
        "description": "Payment for the services",
        "items": [
          {
              "id" : "Item123",
              "name": "sample",
              "unit_cost": "50.00",
              "quantity": 2,
              "total_amount": "100.00"
            }
         ],
         "sales_tax": "9.80",
         "other_tax": [
             {
                 "name": "CRV",
                 "amount": "0.20"
             }
         ],
        "metadata": {
            "customerId": "123",
            "email" : "test@test.com"
        }
    }
}
```

{% endtab %}

{% tab title="Response (synchronous flow)" %}
**Example Response**

<pre class="language-json"><code class="lang-json">{
    "id": "c03ce6ad-1e78-4bd7-ad35-e0d46b6b765d",
    "transaction_id": "2a03cbbb-7c94-4c99-8bb5-b89767dca086",
    "merchant_id": "b0ad3bfe-c7a1-4def-9840-6c9b2570d2ce",
    "device_id": "e68f0d4b-6a64-4426-a7b7-062be8e332e",
    "gateway_id": "1f3e0f67-d560-494c-bb1a-97558a462cc5",
    "description": "Payment for the services",
    "internal_transaction_id": "987654321",
    "token": "card_sandbox_8Aq30HAc8TLFUFvTjqwo556i",
    "three_ds_action_required": false,
    "sale_response": {
            "status": "PASS",
            "response_code": "AA",
            "response_message": "APPROVAL",
            "auth_code": "502362",
            "host_reference_number": "331145734",
            "host_response_code": "00",
            "task_id": "331145734",
            "transaction_id": "331145734",
            "record_number": "6",
            "batch_number": "056",
            "issuer_response_code": "00",
            "icc_arpc": "3FB9A43FF7C7D0123030",
            "transaction_timestamp": "2025-03-31T14:57:34.000Z",
            "transaction_amount": "0.01",
            "processed_amount": "0.01",
            "total_amount": "0.01",
            "address_verification_code": "",
            "card_holder_verification_code": "",
            "card_type": "Visa",
            "masked_card_number": "************4403",
            "customer_receipt": "\n\nSandbox Merchant, Inc.\n3005 Mesa Verde Dr\nBurbank, CA 91504\n818-730-1662\n\nCREDIT CARD\n\n\nTOTAL:USD $0.01\n\n ************null\nDATE &#x26; TIME:03-31-25 07:57:26\nREC #: 6\nAUTH CODE: 502362\nTYPE: SALE\nTOTAL: USD $0.01\nDECLINED\nNO SIGNATURE REQUIRED\nRefunds permitted as necessary. Not guaranteed.\nTHANK YOU\nCardholder Copy\nRetain this copy for statement verification.\n\n\n\n\n\n\n\n",
            "merchant_receipt": "\n\nSandbox Merchant, Inc.\n3005 Mesa Verde Dr\nBurbank, CA 91504\n818-730-1662\n\nCREDIT CARD\n\n\nTOTAL:USD $0.01\n\n ************null\nDATE &#x26; TIME:03-31-25 07:57:26\nREC #: 6\nAUTH CODE: 502362\nTYPE: SALE\nTOTAL: USD $0.01\nDECLINED\nX_______________________\nI AGREE TO PAY ABOVE TOTAL AMOUNT IN ACCORDANCE WITH CARD ISSUER's AGREEMENT (MERCHANT AGREEMENT IF CREDIT VOUCHER)\nRefunds permitted as necessary. Not guaranteed.\nTHANK YOU\nMerchant Copy\nRetain this copy for statement verification.\n\n\n\n\n\n\n\n",
            "log_id": "556f8c4e-d3bd-4e2a-843c-a9cc8314e2d3",
            "card_id": "0a558295-3fce-4196-8fcb-fa8dee37c247",
            "partial_payment": false
<strong>     },
</strong>     "metadata": {
            "customerId": "123",
            "email" : "test@test.com"
    },
     "order_number": "12345678910",
     "sales_tax": "0.01",
     "customer_name": "Anna Maria",
     "currency_code": "USD"
}
</code></pre>

{% endtab %}

{% tab title="Response (asynchronous flow)" %}
**Example Response**

```json
{
    "id": "c03ce6ad-1e78-4bd7-ad35-e0d46b6b765d",
    "transaction_id": "2a03cbbb-7c94-4c99-8bb5-b89767dca086",
    "merchant_id": "b0ad3bfe-c7a1-4def-9840-6c9b2570d2ce",
    "device_id": "e68f0d4b-6a64-4426-a7b7-062be8e332e",
    "gateway_id": "1f3e0f67-d560-494c-bb1a-97558a462cc5",
    "description": "Payment for the services",
    "three_ds_action_required": false,
    "token": "card_sandbox_8Aq30HAc8TLFUFvTjqwo556i",
    "sale_response": {
        "status": "PENDING"
    },
    "metadata": {
        "customerId": "123",
         "email" : "test@test.com"
    }
}
```

{% endtab %}
{% endtabs %}

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

#### Webhook Payload Example

```json
{
  "event_uid": "d53d8ef7b97f9be29b756ffb824cce57",
  "event": "PAYMENT_SALE",
  "data": {
    "token": "card_sandbox_SOjzsBONRMTtPSgsmN0k44v4",
    "device_id": "ad6c156e-8aa3-4c81-a850-d5fd2d8a7138",
    "metadata": {
      "payerID": "id",
      "payerEmail": "email"
    },
    "device_id": "ad6c156e-8aa3-4c81-a850-d5fd2d8a7138",
    "account_id": "fdd24695-1298-496f-b997-89733fc17413",
    "gateway_id": "bcd7fdb7-b2bc-43c3-a79c-b5c4f2ff1b4d",
    "payment_id": "a99f5363-48a7-4c8b-9f1b-4b1012a83a3b",
    "description": "Device Sale",
    "merchant_id": "186b9dfd-de11-46db-8fdb-4124e0b1e155",
    "currency_code": "USD",
    "order_number": "XXX12345",
    "sale_response": {
      "status": "PASS",
      "task_id": "123456789012345",
      "auth_code": "DSC035",
      "card_type": "discover",
      "total_amount": "2.00",
      "response_code": "00",
      "transaction_id": "511300501628",
      "partial_payment": false,
      "customer_receipt": "           Joes Plumbing            \\n        200 Epcot Center Dr         \\n         Orlando, FL 32836          \\n            310-908-5741            \\n                 \\n                 \\n        2025-04-22 05:03 PM         \\n           CREDIT - SALE            \\n            Card # 0828             \\n        Card Type: DISCOVER         \\n            Chip Reader             \\n      Entry Mode : CONTACTLESS      \\n  Transaction ID: 123456789012345   \\n         Auth Code: DSC035          \\n        AID: A0000001523010         \\n     AID Name: Discover/Diners      \\n             ATC: 012E              \\n        AC: D1B8BDC324B83EAA        \\n      Invoice Number: XXX12345      \\n        SUBTOTAL: USD $0.75         \\n        SALES TAX: USD $1.25        \\n          TOTAL: USD $2.00          \\n                 \\n                 \\n      X_______________________      \\n              APPROVED              \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n                 \\n           Customer Copy            \\n",
      "merchant_receipt": "           Joes Plumbing            \\n        200 Epcot Center Dr         \\n         Orlando, FL 32836          \\n            310-908-5741            \\n                 \\n                 \\n        2025-04-22 05:03 PM         \\n           CREDIT - SALE            \\n            Card # 0828             \\n        Card Type: DISCOVER         \\n            Chip Reader             \\n      Entry Mode : CONTACTLESS      \\n  Transaction ID: 123456789012345   \\n         Auth Code: DSC035          \\n        AID: A0000001523010         \\n     AID Name: Discover/Diners      \\n             ATC: 012E              \\n        AC: D1B8BDC324B83EAA        \\n      Invoice Number: XXX12345      \\n        SUBTOTAL: USD $0.75         \\n        SALES TAX: USD $1.25        \\n          TOTAL: USD $2.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": "2.00",
      "response_message": "APPROVAL DSC035",
      "host_response_code": "00",
      "masked_card_number": "0828",
      "transaction_amount": "2.00",
      "host_reference_number": "511300501628",
      "transaction_timestamp": "2025-04-23T00:03:32.407Z",
      "address_verification_code": "0",
      "card_holder_verification_code": null
    },
    "transaction_id": "552e605f-eabf-444e-9bf9-4fa412e1fe82",
    "internal_transaction_id": "987654321"
  }
}
```