Device Sale
The credit card sale API obtains real-time authorization for a Credit Card Sale transaction through an approved cloud-connected device and enters the transaction into the unsettled batch
POST https://<PayEngine-host>/api/payment/sale
Request Body
merchant_id*
string
Merchant ID
data.transaction_amount*
string
Max Length=12 Allowed characters: 0-9 and .(dot) 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. Not supported in SoftPOS SDK (Amount is provided as part of the startTransaction API parameter)
data.device_id*
string
Registered and connected device ID
data.currency_code
string
ISO Currency code If not provided it defaults to US Dollar (USD) Not supported in SoftPOS SDK (Currency code is provided as part of the startTransaction API parameter)
data.address_line1
string
Address Line 1
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.
data.zip
string
Postal or ZIP Code
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.
data.order_number
string
Order Number to add to billing statement of the cardholder
data.internal_transaction_id
string
An internal ID from integrating system. Will be returned in the response and associated refunds if provided.
data.customer_name
string
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.
data.description
string
Transaction description. Character limit is 255
data.gateway_id
string
Gateway ID (optional, if multigateway mode enabled)
data.ip_address
string
IP address of cardholder
data.items
string
List of items sold
data.items[].name
string
Name of the item
data.items[].quantity
string
Item quantity. Default is 1
data.items[].unit_of_measure
string
Unit of measurement
data.items[].unit_cost
string
Unit cost of item
data.items[].total_amount
string
Total order amount for this item/s including the individual item tax
data.sales_tax
string
Sales Tax amount is included in the transaction amount
data.other_tax[]
array
Contains additional tax details applied to the transaction
data.other_tax[].name
string
Name of the tax (e.g., Bottle Deposit Fee) Note: It is required if data.other_tax[].amount is provided
data.other_tax[].amount
string
Value of the tax and it is included in the transaction Note: It is required if data.other_tax[].name is provided
data.metadata
string
Add any additional metadata by passing a json object
data.async_mode
boolean
Default is false.
See details of async mode below.
data.edc
string
CREDIT | DEBIT | EBT
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.
Note: 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.
id
string
PayEngine payment ID for the sale request
Required
transaction_id
string
Unique transaction ID
Required
merchant_id
string
Merchant ID
Required
device_id
string
Device ID provided in the request
Required
token
string
PayEngine token associated with the transaction
Required
gateway_id
string
ID of the gateway through which the transaction is processed.
Optional
description
string
Transaction description
Optional
internal_transaction_id
string
Internal Transaction ID provided in the request
Optional
currency_code
string
ISO Currency code provided in the request Note: Only returned if originally provided in the request
Optional
customer_name
string
Customer name provided in the request
Optional
order_number
string
Order number provided in the request
Optional
three_ds_action_required
boolean
Indicates whether 3DS challenge needs to be initiated
Required
sale_response.status
string
Transaction execution status. Allowed values:
PASSFAILPENDING
Required
sale_response.response_message
string
The corresponding message for the response code
Required
sale_response.auth_code
string
Authorization code received for the transaction
Optional
sale_response.host_reference_number
string
A unique reference number by the acquiring processor for each transaction
Optional
sale_response.host_response_code
string
Optional
sale_response.task_id
string
Task identification number from acquiring processor
Required
sale_response.transaction_id
string
Transaction Identifier
Optional
sale_response.transaction_timestamp
string
Transaction timestamp in merchant's timezone
Required
sale_response.transaction_amount
string
Total amount requested in this transaction
Optional
sale_response.partial_payment
boolean
True | False True - Indicates that transaction is a partial payment and refer to SaleResponse.processedAmount for the partial amount processed
Required
sale_response.processed_amount
string
Total amount processed in this transaction
Optional
sale_response.total_amount
string
Total amount of this transaction
Optional
sale_response.sales_tax
string
Sales tax included in the request
Optional
sale_response.card_type
string
Card Type - visa, mastercard, american express, discover, dinersclub, ebt
Required
sale_response.masked_card_number
string
The truncated card number displaying the last four digits
Required
sale_response.aci
string
When VISA is used, the returned Authorization Characteristics Indicator (ACI). This one character value provides information concerning the transaction's CPS qualification status.
Optional
sale_response.transaction_integrity_classification
string
Optional
sale_response.ucaf_collection_indicator
string
When Mastercard is used, Universal Cardholder Authentication Field.
Optional
sale_response.fraud_score
int
Return the fraud score between 0 - 100. 100 means less confidence i.e. more fraudulent i and 0 means lower chance of fraudulent. Note: The fraud monitoring has to be enabled. Please contact support to enable it
Optional
sale_response.kount_score
int
Return the Kount Omniscore
Optional
sale_response.customer_receipt
string
Printable customer receipt
Required
sale_response.merchant_receipt
string
Printable merchant receipt
Required
metadata
object
Return all the metadata sent in the request
Optional
Important considerations
Synchronous Flow
Submit a request to PayEngine 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. 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 PayEngine 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 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.
Sample Request / Responses
Example Request
{
"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" : "[email protected]"
}
}
}Example Request with items
{
"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" : "[email protected]"
}
}
}Webhook Payload Example
{
"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"
}
}Last updated