Skip to navigation
Terminal APICard Read

Initiate a card read

Connects to the terminal (if needed) and prompts the cardholder to swipe, dip, or tap. Returns an interaction_id immediately.

To get the result, poll Get card read status or subscribe to the channel terminal_job:{interaction_id} over WebSocket (see Generate WebSocket auth token).

Set include_signature to capture the cardholder’s signature as part of the same interaction. Signature capture is only available on terminals where capabilities.signature is true.

Use the returned token and amount with the Payments API Charge endpoint to complete the transaction, or use Charge a card to read and charge in one call.

Authentication

AuthorizationBearer

Use a Payments API key as the bearer token: Authorization: Bearer <api_key>. Get a fresh key from Refresh API Keys.

Path parameters

device_idstringRequired

Hardware Serial Number (HSN) of the terminal, provided by your Integration Delivery lead.

Query parameters

midstringOptional

Merchant ID. Required when your bearer token is an ISV token acting on behalf of a merchant. If the mid can't be resolved to an authorized account, the request returns 400.

Request

This endpoint expects an object.
amountstringRequired
Amount in decimal dollars, as a string. Must be greater than zero with at most two decimal places.
confirm_amountbooleanOptional
Prompt the cardholder to confirm the amount on the terminal.
beepbooleanOptional
Play a beep on the terminal when the prompt appears.
include_signaturebooleanOptional

Capture the cardholder's signature as part of the same interaction. Requires capabilities.signature.

signature_formatenumOptional
Image format of the captured signature.
Allowed values:
signature_gzipbooleanOptional
Compress the returned signature image.
signature_dimensionsstringOptionalformat: "^\d{1,3},\d{1,3}$"

Signature image size as "width,height". Each value is up to three digits (max 999).

signature_image_typeenumOptional
Color type of the signature image.
Allowed values:

Response

Interaction accepted. Use the interaction_id to poll for status or subscribe over WebSocket.

interaction_idstringformat: "uuid"
Identifier for the queued interaction.

Errors

400
Bad Request Error
401
Unauthorized Error
404
Not Found Error
429
Too Many Requests Error
503
Service Unavailable Error