Tokenize

post

https://sandbox-api.softpoint.io/interface/v1/locations/YOUR_LOCATION_ID/webhook/tokenize

Tokenizes a physically present card on a terminal. The device prompts the customer to insert their card, captures it securely, and returns a token representing the card for future use.

Request Headers

Header	Required	Description
Authorization	Yes	Bearer YOUR_ACCESS_TOKEN
Content-Type	Yes	`application/json`

Request Parameters

Path Parameters:

Parameter	Type	Required	Description
location_id	integer	Yes	Location operating the terminal.

Request Body Fields:

Field	Type	Required	Description
ticket	object	Yes	The ticket context. See `ticket` object below.
payment	object	Yes	Payment context. See `payment` object below.
user_id_external	string	No	Identifies the guest user. This ID represents the owner of the associated credit card token.
webhook_id	string	Yes	Unique identifier for the webhook.
terminal_id	string	Yes	Unique identifier for the POS terminal.

Object Fields

`ticket` object

Field	Type	Required	Description
id	string	Yes	The unique identifier of the ticket.
name	string	No	The name of the ticket.
open	boolean	No	Indicates whether the ticket is still open.
opened_at	timestamp	No	The timestamp when the ticket was opened.
closed_at	timestamp	No	The timestamp when the ticket was closed.
ticket_number	integer	No	The ticket number.

`payment` object

Field	Type	Required	Description
id	string	Yes	Unique identifier for the payment.
amount	integer	Yes	For tokenization, the amount is automatically set to `0`.

Request Example

{
  "ticket": { "void": false, "id": 21 },
  "payment": { "id": "19", "amount": 0 },
  "user_id_external": 2476,
  "webhook_id": "7614fc1bd4saf6",
  "terminal_id": 110
}

cURL Example

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

Success Response

{
  "response": "APPROVED",
  "data": {
    "id": 0,
    "id_external": "7526183624636356904606",
    "order_id_external": "19",
    "amount": 0,
    "transaction_id": "7526183624636356904606",
    "reference_id": "8c9c10f884824e2489227a3004015a13",
    "auth_code": "831000",
    "card_type": "MC",
    "last4": "0045",
    "entry_type": "Chip",
    "result_message": "APPROVED",
    "status": 1
  }
}

Response Fields

Field	Type	Description
response	string	`APPROVED` or `DECLINE`.
data.id_external	string	The token / external transaction reference for the captured card.
data.transaction_id	string	Processor transaction identifier.
data.reference_id	string	Reference for reconciliation.
data.auth_code	string	Authorization code.
data.card_type	string	Card brand (for example, `MC`, `VISA`, `AMEX`).
data.last4	string	Last four digits of the card.
data.entry_type	string	How the card was read (for example, `Chip`).
data.emv_tags	string	JSON-encoded EMV tag data, when present.
data.status	integer	Processor status flag.

Error Responses

Unauthorized / Invalid Token

{
  "error": {
    "code": 10759,
    "message": "Operation timed out. Please try again.",
    "details": { "Exception": "Token could not be parsed from the request." }
  }
}

Status Codes

Code	Description
200	Tokenization completed (check the `response` field for `APPROVED`/`DECLINE`)
401	Token missing or invalid

Workflow Placement

Used to store a card on file during a terminal interaction, ahead of future charges.

Notes

Set payment.amount to 0 to tokenize without charging.
Always inspect the body's response field; an HTTP 200 can still carry DECLINE.
webhook_id should be unique per attempt for correlation.

Common Mistakes

Targeting a terminal that is offline or unknown.
Ignoring the response field and assuming 200 means approved.

Responses

200OK

401Unauthorized