Captures a card present payment on a physical terminal in a single step, combining authorization and capture. Use this endpoint to charge a guest's card for a completed ticket at the point of sale. The terminal prompts for the card, processes the EMV transaction, and returns the approval or decline outcome.

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.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": "rika19882"
  },
  "payment": {
    "id": "desk41231",
    "amount": 666,
    "inv_number": "INV-1024"
  },
  "user_id_external": 5488,
  "webhook_id": "7614fc1bd4saf6",
  "terminal_id": 100
}

cURL Example

curl --request POST \
  --url https://sandbox-api.softpoint.io/interface/v1/locations/YOUR_LOCATION_ID/webhook/sale \
  --header "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "ticket": { "void": false, "id": "rika19882" },
    "payment": { "id": "desk41231", "amount": 666, "inv_number": "INV-1024" },
    "user_id_external": 5488,
    "webhook_id": "7614fc1bd4saf6",
    "terminal_id": 100
  }'

Success Response

An approved sale returns response: "APPROVED" together with the settled transaction details.

{
  "response": "APPROVED",
  "data": {
    "id": 7137,
    "id_external": null,
    "amount": 1081,
    "tip": 400,
    "surcharge": 0,
    "transaction_id": "28040181",
    "card_holder": "Test/Card 01",
    "reference_id": "8",
    "auth_code": "TAS547",
    "card_type": "VISA",
    "last4": "0010",
    "entry_type": "Chip",
    "customer_id_external": "inf3509263926"
  }
}

Response Fields

Error Responses

Declined Transaction

A decline is returned with HTTP 200 and response: "DECLINE". Inspect the response field rather than relying solely on the status code.

{
  "response": "DECLINE",
  "data": {
    "id": 17845,
    "id_external": "7da29929a5548",
    "amount": 0,
    "tip": 0,
    "total": 0,
    "refunded_amount": 0,
    "surcharge": 0,
    "transaction_id": "",
    "card_holder": "DI Test/Card 01",
    "reference_id": "",
    "auth_code": "",
    "card_type": "AMEX",
    "last4": "0119",
    "entry_type": "Chip",
    "status": 2
  }
}

Terminal Not Found

Returned when the supplied terminal_id does not correspond to a registered terminal.

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

Missing Required Parameter

Returned when a required field, such as terminal_id, is absent from the request body.

{
  "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 Sale endpoint is the terminal step in the card-present payment flow:

1. Generate an interface access token.

2. Register and configure the terminal.

3. Open or reference a ticket.

4. Submit the sale to the terminal.

5. Reconcile the result using the returned transaction details, or issue a refund if required.

Notes

• Amounts are expressed in minor units (cents). The returned amount reflects the final total, which may include tip and surcharge applied at the terminal and can therefore differ from the requested payment.amount.

• A decline is reported with HTTP 200 and response: "DECLINE". Always branch on the response field.

• The terminal interaction is asynchronous from the cardholder's perspective. Supply a webhook_id to correlate the eventual result.

• The ticket object may be supplied either as a compact reference containing an id or as a fully embedded ticket structure. Both forms are accepted.

Common Mistakes

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

• Sending the amount in major units (dollars) instead of minor units (cents).

• Omitting terminal_id, which results in error code 10109.

• Referencing a terminal that has not been registered for the location, which results in error code 10107.