Auth (Card Present)
Create an authorization using a physical payment terminal where the card is present. This will not result in a financial transaction and the card will be tokenized. A capture must be performed to complete the financial transaction.
Webhook Events
The following webhook events will be triggered during the authorization process:
auth.completed- when an authorization is processed and completed.token.created- when a card is tokenized and stored as a payment method.
Body
Required
The request to create a Card Present authorization using a physical payment terminal.
-
amount
number(uint32) Required The total transaction amount. This is the full amount that will be processed in the transaction. Transaction amounts are positive integers representing the amount in its smallest denomination of the configured currency (e.g. cents for USD or CAD).
Minimum value is
1, maximum value is999999999. -
amountBreakdown
object Optional fields to specify the portion of the total transaction amount that represents goods/services, tax, cashback and/or tip. These values are for reporting purposes only and will not be added to the Amount field. These amount are represented as a positive integer in the smallest denomination of the configured currency (e.g. cents for USD or CAD).
-
paymentMethodId
string The ID of the physical payment terminal that will process this Card Present transaction.
- Example format:
pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF - OPTIONAL ONLY if you have a single terminal configured
- REQUIRED if you have multiple physical terminals configured
You can retrieve all available physical payment terminal IDs for your account using the
GET /payment-methodsendpoint. - Example format:
-
invoiceNumber
string An optional alphanumeric invoice number for this transaction. If provided, the same value will be populated in the response.
Maximum length is
100. -
orderNumber
string An optional alphanumeric order number for this transaction. If provided, the same value will be populated in the response.
Maximum length is
100. -
referenceId
string An optional custom reference ID for this transaction. Include this if you want to use your own reference system for linking transactions together (for example, when processing captures and refunds). If provided, this value must be unique per merchant. The reference ID can be used for processing captures and referenced refunds by including it in the originalReferenceId field of subsequent transactions. If not provided, a unique reference ID will be generated automatically by the system.
Maximum length is
100.
curl \
--request POST 'https://api.omni.integratedcommerce.io/v1/transactions/physical-auth' \
--header "x-api-key: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"amount":1000,"orderNumber":"order_number_1234","referenceId":"ref_s192i49i","invoiceNumber":"inv_12345678","amountBreakdown":{"tax":100,"tip":0,"cashback":0,"amountGoodsAndServices":900},"paymentMethodId":"pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF"}'{
"amount": 1000,
"orderNumber": "order_number_1234",
"referenceId": "ref_s192i49i",
"invoiceNumber": "inv_12345678",
"amountBreakdown": {
"tax": 100,
"tip": 0,
"cashback": 0,
"amountGoodsAndServices": 900
},
"paymentMethodId": "pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF"
}{
"id": "trx_01J2F0EKHC7HY2R93C8ENBD1FG",
"type": "Auth",
"timestamp": "2025-05-27T18:49:31Z",
"resultCode": 0,
"resultText": "Successful transaction request",
"orderNumber": "order_number_1234",
"referenceId": "ref_s192i49i",
"balanceAmount": 0,
"invoiceNumber": "inv_12345678",
"paymentMethod": {
"id": "pmt_trm_01JRZPTMTBN41PC3VPQNZ5T3HF",
"type": "Physical",
"currency": "USD",
"description": "Main Store Terminal"
},
"approvedAmount": 1000,
"requestedAmount": 1000,
"transactionResponses": [
{
"receipt": {
"lines": [
" Test Merchant ",
" 300 S Wacker ",
" Loop, ",
" ",
" ",
"TERM # 11000367",
"RECORD # 0656191",
"HOST INVOICE # 000038",
"HOST SEQ # 1720656191",
"MERCH INVOICE. fgj24344",
"------------------------",
"CARD ************0011",
"VISA Contact",
"07/10/2024 20:03:05",
"------------------------",
" PRE AUTH ",
"TOTAL USD $10.00",
"------------------------",
"AUTH#:000AAA ",
" ",
" APPROVED 00 ",
" THANK YOU ",
" ",
" Visa Credit ",
"AID: A0000000031010",
"TC: 43F4ACF64B07551A",
"TVR: 8000008000",
"TSI: 7800",
" ",
" ",
" ",
" ",
" ",
" ",
" ",
" MERCHANT COPY ",
" Test Merchant ",
" 300 S Wacker ",
" Loop, ",
" ",
" ",
"TERM # 11000367",
"RECORD # 0656191",
"HOST INVOICE # 000038",
"HOST SEQ # 1720656191",
"MERCH INVOICE. fgj24344",
"------------------------",
"CARD ************0011",
"VISA Contact",
"07/10/2024 20:03:05",
"------------------------",
" PRE AUTH ",
"TOTAL USD $10.00",
"------------------------",
"AUTH#:000AAA ",
" ",
" APPROVED 00 ",
" THANK YOU ",
" ",
" Visa Credit ",
"AID: A0000000031010",
"TC: 43F4ACF64B07551A",
"TVR: 8000008000",
"TSI: 7800",
" ",
" ",
" ",
" ",
" ",
" ",
" ",
" CUSTOMER COPY "
]
},
"authCode": "000AAA",
"cardType": "VISA",
"accountType": "Credit",
"responseCode": 1,
"paymentMethod": {
"id": "pmt_tkn_01JRZPRGFF4J2SZC3HMDBYEN2J",
"type": "Token",
"cardType": "VISA",
"currency": "USD",
"cardExpDate": "1225",
"description": "Token for John Doe's Visa",
"maskedCardNumber": "************0011"
},
"amountApproved": 1000,
"hostResponseText": "APPROVED 00",
"approvedAmountBreakdown": {
"tax": 100,
"tip": 0,
"cashback": 0,
"amountGoodsAndServices": 900
}
}
]
}{
"code": 2000,
"status": "Rejected",
"message": "One or more validation errors occurred.",
"traceId": "1-6838bcce-5c0074e82ac7170d4f990d87",
"timestamp": "2025-05-29T20:00:15.5752808Z",
"errorDetails": [
{
"code": 2000,
"field": "Amount",
"details": "The Amount field must be a positive number between 1 and 999999999.",
"message": "Request validation failed"
}
]
}{
"code": 1000,
"status": "Rejected",
"message": "Invalid or missing API key",
"traceId": "1-6838be96-74c62f8e2804352739e63476",
"timestamp": "2025-05-29T20:07:50.4723483Z",
"errorDetails": []
}