Skip to navigation
Terminal APICharge Card

Charge a card

Reads the card, optionally captures a signature, charges the card, and optionally prints and emails a receipt, all in one call. Returns an interaction_id immediately. Get the result with Get charge status or over WebSocket.

Requesting a step the terminal can’t perform (for example, print_receipt on an Ingenico device) never fails the transaction. The charge completes and the skipped step is listed in stage_errors on the status response.

charge-card interactions can’t be cancelled through the API.

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 a signature during the read stage. Checked against capabilities.signature before the read starts.

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:
print_receiptbooleanOptional
Print a receipt after the charge, if the terminal has a printer.
send_receiptbooleanOptional

Email a receipt after the charge. Independent of print_receipt.

emailstringOptionalformat: "email"

Recipient email address when send_receipt is true.

order_idstringOptional

Order ID for the transaction. If omitted, one is generated in the format <4-digit random><yymmddHHMMSS>.

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