Authorizes a card present payment on a physical terminal without capturing funds. An authorization places a hold on the cardholder's account for the requested amount, which can later be captured or allowed to expire. Use this endpoint for workflows that separate authorization from settlement, such as bar tabs or scenarios where the final amount is not yet known.

Request Headers

Request Parameters

Path Parameters

Request Body Fields

Object Fields

The ticket object may be sent as a compact reference (just id) or as a fully embedded structure. When embedded, it supports the fields below. All embedded fields are optional, and monetary values are expressed in minor units (cents).

ticket object

ticket.customer object

ticket.totals object

All values are integers in minor units (cents).

ticket._embedded object

Container for nested ticket entities. May include ebt_type, discounts[], items[], and payments[]. Item-level entities (employee, order_type, revenue_center, table, and modifiers[]) are nested within each items[] entry.

ebt_type

discounts[] (array)

items[] (array)

items[].employee (object)

items[].order_type (object)

items[].revenue_center (object)

items[].table (object)

payments[] (array)

items[]._embedded.modifiers[] (array)

Request Example

{
  "ticket": {
    "void": false,
    "id": 21
  },
  "payment": {
    "id": "19",
    "amount": 666
  },
  "user_id_external": 5488,
  "webhook_id": "7614fc1bd4saf6",
  "terminal_id": 110,
  "debug": 1
}

cURL Example

curl --request POST \
  --url https://sandbox-api.softpoint.io/interface/v1/locations/YOUR_LOCATION_ID/webhook/auth \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "ticket": { "void": false, "id": 21 },
    "payment": { "id": "19", "amount": 666 },
    "user_id_external": 5488,
    "webhook_id": "7614fc1bd4saf6",
    "terminal_id": 110,
    "debug": 1
  }'

Success Response

An approved authorization returns response: "APPROVED". The total field reflects the authorized amount, while amount (the captured amount) remains 0 until a capture occurs.

{
  "response": "APPROVED",
  "data": {
    "id": 37224,
    "id_external": "7da2ab5fdd617",
    "amount": 0,
    "tip": 0,
    "total": 1000,
    "refunded_amount": 0,
    "surcharge": 0,
    "transaction_id": "57904823",
    "card_holder": "ATH PRIMA/Test Card 01",
    "reference_id": "4",
    "auth_code": "TAS261",
    "card_type": "VISA",
    "last4": "0043",
    "entry_type": "Chip",
    "result_message": "OK",
    "emv_tags": "{\"Status\":\"\",\"ATC\":\"0B05\",\"TVR\":\"08C0808000\",\"APPPN\":\"Visa Credit\",\"TSI\":\"E800\",\"APPLAB\":\"VISA CREDIT\",\"AID\":\"A0000000031010\",\"IAD\":\"06010A0321A804\",\"ARQC\":\"25F8FE045F8013D2\",\"Balance\":\"$0.0\",\"CID\":\"00\"}",
    "status": 1
  }
}

Response Fields

Error Responses

The Auth endpoint shares the error model of the Sale endpoint. A decline is returned with HTTP 200 and response: "DECLINE". Structured errors use the standard envelope.

Terminal Not Found

{
  "error": {
    "code": 10107,
    "message": "The selected terminal doesn't exist.",
    "details": null
  }
}

Missing Required Parameter

{
  "error": {
    "code": 10109,
    "message": "The request is missing one or more required parameter(s).",
    "details": {
      "terminal_id": [
        "missing_required_parameters"
      ]
    }
  }
}

Status Codes

Workflow Placement

The Auth endpoint begins a two-step card-present payment:

1. Generate an interface access token.

2. Submit an authorization to place a hold on the card.

Notes

• Amounts are expressed in minor units (cents).

• For an authorization, the held amount appears in total, and amount remains 0 until the funds are captured.

• The emv_tags field is a JSON-encoded string and must be parsed separately if its contents are required.

• Setting debug to 1 enriches the response with additional processor diagnostics and is intended for development environments.

Common Mistakes

• Assuming funds are captured at authorization. An authorization only places a hold; a separate capture is required to settle.

• Reading the captured value from amount rather than the authorized value in total.

• Treating an HTTP 200 response as a guaranteed approval without checking the response field.

• Omitting terminal_id, which results in error code 10109.