Skip to navigation
Terminal APICharge Card

Charge a card

Optionally prompts for a tip, 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.

The workflow runs in stages: tip (only when include_tip is true) → read → charge → print (only when print_receipt is true).

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.

Tipping

Set include_tip to true to prompt the customer for a tip before the card read. The card is then charged for the tip-inclusive total, and the status response returns base_amount, tip_amount, and amount.

  • tip_prompt, tip_percent_presets, and include_custom_tip_amount are only read (and validated) when include_tip is true.
  • If the terminal doesn’t support tipping (capabilities.tip is false) or the tip can’t be read, the charge still goes ahead for the original amount with no tip, and result.stage_errors.tip says why.
  • If the customer cancels on the tip screen, the interaction ends as cancelled and no card is read.
  • The tip is excluded from the surcharge calculation.

To collect a tip without charging, use Prompt for a tip.

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. When include_tip is true, this is the base amount before tip. Include a decimal point: an amount without one is read as cents, so "10" is ten cents.

include_tipbooleanOptionalDefaults to false

Prompt the customer for a tip before the card read and charge the tip-inclusive total. Requires capabilities.tip; if unsupported, the charge runs for amount with no tip.

tip_promptstringOptionalDefaults to Add a tip?

Text shown above the tip options on the terminal. Used only when include_tip is true.

tip_percent_presetslist of stringsOptional

Percentage buttons shown on the terminal, as whole numbers. Used only when include_tip is true.

include_custom_tip_amountbooleanOptionalDefaults to true

Show a button for the customer to enter their own tip amount. Used only when include_tip is true.

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