--- title: "Create a session on a terminal" method: POST path: "/terminal-sessions" tags: ["Terminal sessions"] --- # Create a session on a terminal `POST /terminal-sessions` ## Request - Base URL: `https://api.dojo.tech` - URL: `https://api.dojo.tech/terminal-sessions` - Auth: API key in header `Authorization` - TypeScript: (a function with typed inputs; its response is checked against the schema) ## Headers - `version` string, date, required - `software-house-id` string, required - `reseller-id` string ## Request body - CreateTerminalSessionRequest: Create a terminal session, and decide what sort of transaction it is going to be associated with. Note that only one of the refund types can be specified, and this selection must be the same as the `sessionType`. - `terminalId` string, required: The unique identifier for the terminal. - `details` union, required: Details about the terminal session, including which type of transaction it is associated with. - object - `unlinkedRefund` TerminalSessionUnlinkedRefundDetails: A refund which is not linked to any previous transaction. - `amount` Money, required: The amount intended to be collected by this payment intent excluding `tipsAmount` `serviceChargeAmount` and `cashbackAmount`. - `value` integer, required: The amount in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) minor units, for example, "100" for 1.00 GBP. - `currencyCode` string, required: Three-letter currency code in [ISO 4217 alpha-3](https://www.iso.org/iso-4217-currency-codes.html) format. Accepts `GBP` and `EUR`. - `cardholderNotPresent` boolean: Indicates whether this transaction should be completed as Cardholder Not Present (CNP), with manual entry of card details. If the flag is true, the card machine skips the `Present Card` screen and goes directly into Key Card Number. - `matchedRefund` TerminalSessionMatchedRefundDetails: A matched refund is associated with the payment intent of the initial transaction. - `paymentIntentId` string, required: The unique identifier of the payment intent. - `amount` Money: The amount intended to be collected by this payment intent excluding `tipsAmount` `serviceChargeAmount` and `cashbackAmount`. - `value` integer, required: The amount in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) minor units, for example, "100" for 1.00 GBP. - `currencyCode` string, required: Three-letter currency code in [ISO 4217 alpha-3](https://www.iso.org/iso-4217-currency-codes.html) format. Accepts `GBP` and `EUR`. - `sale` TerminalSessionSaleDetails, required: Use this field when creating a terminal session request to name a payment intent by its ID to associate with the session. - `paymentIntentId` string, required: The unique identifier of the payment intent. - `sessionType` 'Sale' | 'MatchedRefund' | 'UnlinkedRefund', required: Decide which type of transaction a terminal session is going to be associated with. - object - `unlinkedRefund` TerminalSessionUnlinkedRefundDetails, required: A refund which is not linked to any previous transaction. - `amount` Money, required: The amount intended to be collected by this payment intent excluding `tipsAmount` `serviceChargeAmount` and `cashbackAmount`. - `value` integer, required: The amount in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) minor units, for example, "100" for 1.00 GBP. - `currencyCode` string, required: Three-letter currency code in [ISO 4217 alpha-3](https://www.iso.org/iso-4217-currency-codes.html) format. Accepts `GBP` and `EUR`. - `cardholderNotPresent` boolean: Indicates whether this transaction should be completed as Cardholder Not Present (CNP), with manual entry of card details. If the flag is true, the card machine skips the `Present Card` screen and goes directly into Key Card Number. - `matchedRefund` TerminalSessionMatchedRefundDetails: A matched refund is associated with the payment intent of the initial transaction. - `paymentIntentId` string, required: The unique identifier of the payment intent. - `amount` Money: The amount intended to be collected by this payment intent excluding `tipsAmount` `serviceChargeAmount` and `cashbackAmount`. - `value` integer, required: The amount in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) minor units, for example, "100" for 1.00 GBP. - `currencyCode` string, required: Three-letter currency code in [ISO 4217 alpha-3](https://www.iso.org/iso-4217-currency-codes.html) format. Accepts `GBP` and `EUR`. - `sale` TerminalSessionSaleDetails: Use this field when creating a terminal session request to name a payment intent by its ID to associate with the session. - `paymentIntentId` string, required: The unique identifier of the payment intent. - `sessionType` 'Sale' | 'MatchedRefund' | 'UnlinkedRefund', required: Decide which type of transaction a terminal session is going to be associated with. - object - `unlinkedRefund` TerminalSessionUnlinkedRefundDetails: A refund which is not linked to any previous transaction. - `amount` Money, required: The amount intended to be collected by this payment intent excluding `tipsAmount` `serviceChargeAmount` and `cashbackAmount`. - `value` integer, required: The amount in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) minor units, for example, "100" for 1.00 GBP. - `currencyCode` string, required: Three-letter currency code in [ISO 4217 alpha-3](https://www.iso.org/iso-4217-currency-codes.html) format. Accepts `GBP` and `EUR`. - `cardholderNotPresent` boolean: Indicates whether this transaction should be completed as Cardholder Not Present (CNP), with manual entry of card details. If the flag is true, the card machine skips the `Present Card` screen and goes directly into Key Card Number. - `matchedRefund` TerminalSessionMatchedRefundDetails, required: A matched refund is associated with the payment intent of the initial transaction. - `paymentIntentId` string, required: The unique identifier of the payment intent. - `amount` Money: The amount intended to be collected by this payment intent excluding `tipsAmount` `serviceChargeAmount` and `cashbackAmount`. - `value` integer, required: The amount in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) minor units, for example, "100" for 1.00 GBP. - `currencyCode` string, required: Three-letter currency code in [ISO 4217 alpha-3](https://www.iso.org/iso-4217-currency-codes.html) format. Accepts `GBP` and `EUR`. - `sale` TerminalSessionSaleDetails: Use this field when creating a terminal session request to name a payment intent by its ID to associate with the session. - `paymentIntentId` string, required: The unique identifier of the payment intent. - `sessionType` 'Sale' | 'MatchedRefund' | 'UnlinkedRefund', required: Decide which type of transaction a terminal session is going to be associated with. ## Response `200` Terminal session created. - TerminalSession: This is the terminal session object, containing detailed information about the history of the terminal session, and its current status. - `terminalId` string, required: The unique identifier for the terminal. - `createdAt` string, date-time, required: This is when the terminal session was created, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) UTC format. - `updatedAt` string, date-time, required: The timestamp of the update date, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) UTC format. - `id` string, required: The unique identifier of the terminal session. - `status` 'InitiateRequested' | 'Initiated' | 'Authorized' | 'Captured' | 'CancelRequested' | 'Canceled' | 'SignatureVerificationAccepted' | 'SignatureVerificationRejected' | 'SignatureVerificationRequired' | 'Expired' | 'Declined', required: The current status of the terminal session. A finalized, successful session will be `Captured`. - `expireAt` string, date-time, required: The timestamp and date of when a terminal session will be marked as `Expired`, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) UTC format. This changes throughout the life cycle of a terminal session as it moves to different states. - `notificationEvents` TerminalSessionNotificationEvent[], required: When a notification is issued, a notification event is created to record when it occurred. - `notificationType` string, required: Terminal notifications. (Approved, Declined, InsertCard, EnterPin, PleaseWait, PresentCard, PresentOnlyOneCard, RemoveCard, CardUnsupported, CardError, ReEnterCard) - `createdAt` string, date-time, required: This is when the terminal session was created, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) UTC format. - `statusEvents` TerminalSessionStatusEvent[], required: Status events include the capture, cancellation, and refund of payments. - `status` 'InitiateRequested' | 'Initiated' | 'Authorized' | 'Captured' | 'CancelRequested' | 'Canceled' | 'SignatureVerificationAccepted' | 'SignatureVerificationRejected' | 'SignatureVerificationRequired' | 'Expired' | 'Declined', required: The current status of the terminal session. A finalized, successful session will be `Captured`. - `createdAt` string, date-time, required: The creation date, in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) UTC format. - `debugMessage` string, required: The message to troubleshoot the terminal session by revealing the internal state of the terminal. - `receipt` TerminalSessionReceipt: The receipt object is a record of the transactions associated with a terminal session. - `lines` TerminalSessionReceiptLine[], required: The line items purchased by the customer. - `lineType` 'Text' | 'LogoImage' | 'NewLine' | 'SingleLineSeperator' | 'DoubleLineSeperator', required: These are the line types that will form the physical receipt. - `text` TerminalSessionReceiptText: Edit the content of text included with the terminal session receipt, and configure the text's appearance. - `value` string, required: This string field is for the actual receipt text body. - `size` 'SizeHeader1' | 'SizeHeader2' | 'SizeBody', required: Decide the size of included receipt text. - `align` 'AlignLeft' | 'AlignCenter' | 'AlignRight', required: Align the receipt text to the center, to the left, or to the right. - `emphasisBold` boolean, required: Decide whether the terminal session receipt text is bold. True/false. - `imageLogo` TerminalSessionReceiptImageLogo: An optional logo can be added to the terminals receipt. - `value` string, required - `align` 'AlignLeft' | 'AlignCenter' | 'AlignRight', required: Align the receipt text to the center, to the left, or to the right. - `details` union: Details about the terminal session, including which type of transaction it is associated with. - object - `unlinkedRefund` TerminalSessionUnlinkedRefundDetails: A refund which is not linked to any previous transaction. - `amount` Money, required: The amount intended to be collected by this payment intent excluding `tipsAmount` `serviceChargeAmount` and `cashbackAmount`. - `value` integer, required: The amount in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) minor units, for example, "100" for 1.00 GBP. - `currencyCode` string, required: Three-letter currency code in [ISO 4217 alpha-3](https://www.iso.org/iso-4217-currency-codes.html) format. Accepts `GBP` and `EUR`. - `cardholderNotPresent` boolean: Indicates whether this transaction should be completed as Cardholder Not Present (CNP), with manual entry of card details. If the flag is true, the card machine skips the `Present Card` screen and goes directly into Key Card Number. - `matchedRefund` TerminalSessionMatchedRefundDetails: A matched refund is associated with the payment intent of the initial transaction. - `paymentIntentId` string, required: The unique identifier of the payment intent. - `amount` Money: The amount intended to be collected by this payment intent excluding `tipsAmount` `serviceChargeAmount` and `cashbackAmount`. - `value` integer, required: The amount in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) minor units, for example, "100" for 1.00 GBP. - `currencyCode` string, required: Three-letter currency code in [ISO 4217 alpha-3](https://www.iso.org/iso-4217-currency-codes.html) format. Accepts `GBP` and `EUR`. - `sale` TerminalSessionSaleDetails, required: Use this field when creating a terminal session request to name a payment intent by its ID to associate with the session. - `paymentIntentId` string, required: The unique identifier of the payment intent. - `sessionType` 'Sale' | 'MatchedRefund' | 'UnlinkedRefund', required: Decide which type of transaction a terminal session is going to be associated with. - object - `unlinkedRefund` TerminalSessionUnlinkedRefundDetails, required: A refund which is not linked to any previous transaction. - `amount` Money, required: The amount intended to be collected by this payment intent excluding `tipsAmount` `serviceChargeAmount` and `cashbackAmount`. - `value` integer, required: The amount in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) minor units, for example, "100" for 1.00 GBP. - `currencyCode` string, required: Three-letter currency code in [ISO 4217 alpha-3](https://www.iso.org/iso-4217-currency-codes.html) format. Accepts `GBP` and `EUR`. - `cardholderNotPresent` boolean: Indicates whether this transaction should be completed as Cardholder Not Present (CNP), with manual entry of card details. If the flag is true, the card machine skips the `Present Card` screen and goes directly into Key Card Number. - `matchedRefund` TerminalSessionMatchedRefundDetails: A matched refund is associated with the payment intent of the initial transaction. - `paymentIntentId` string, required: The unique identifier of the payment intent. - `amount` Money: The amount intended to be collected by this payment intent excluding `tipsAmount` `serviceChargeAmount` and `cashbackAmount`. - `value` integer, required: The amount in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) minor units, for example, "100" for 1.00 GBP. - `currencyCode` string, required: Three-letter currency code in [ISO 4217 alpha-3](https://www.iso.org/iso-4217-currency-codes.html) format. Accepts `GBP` and `EUR`. - `sale` TerminalSessionSaleDetails: Use this field when creating a terminal session request to name a payment intent by its ID to associate with the session. - `paymentIntentId` string, required: The unique identifier of the payment intent. - `sessionType` 'Sale' | 'MatchedRefund' | 'UnlinkedRefund', required: Decide which type of transaction a terminal session is going to be associated with. - object - `unlinkedRefund` TerminalSessionUnlinkedRefundDetails: A refund which is not linked to any previous transaction. - `amount` Money, required: The amount intended to be collected by this payment intent excluding `tipsAmount` `serviceChargeAmount` and `cashbackAmount`. - `value` integer, required: The amount in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) minor units, for example, "100" for 1.00 GBP. - `currencyCode` string, required: Three-letter currency code in [ISO 4217 alpha-3](https://www.iso.org/iso-4217-currency-codes.html) format. Accepts `GBP` and `EUR`. - `cardholderNotPresent` boolean: Indicates whether this transaction should be completed as Cardholder Not Present (CNP), with manual entry of card details. If the flag is true, the card machine skips the `Present Card` screen and goes directly into Key Card Number. - `matchedRefund` TerminalSessionMatchedRefundDetails, required: A matched refund is associated with the payment intent of the initial transaction. - `paymentIntentId` string, required: The unique identifier of the payment intent. - `amount` Money: The amount intended to be collected by this payment intent excluding `tipsAmount` `serviceChargeAmount` and `cashbackAmount`. - `value` integer, required: The amount in [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) minor units, for example, "100" for 1.00 GBP. - `currencyCode` string, required: Three-letter currency code in [ISO 4217 alpha-3](https://www.iso.org/iso-4217-currency-codes.html) format. Accepts `GBP` and `EUR`. - `sale` TerminalSessionSaleDetails: Use this field when creating a terminal session request to name a payment intent by its ID to associate with the session. - `paymentIntentId` string, required: The unique identifier of the payment intent. - `sessionType` 'Sale' | 'MatchedRefund' | 'UnlinkedRefund', required: Decide which type of transaction a terminal session is going to be associated with. - `paymentDetails` PaymentDetails: The payment details object. - `transactionId` string, nullable: The unique identifier of the transaction. - `transactionDateTime` string, nullable: The date and time of the payment in [ISO 8601](https://en.wikipedia.org/wiki/ISO_8601) UTC format. - `message` string, nullable: The description of the operation. - `paymentMethodId` string, nullable: The unique identifier of the customer payment method. - `authCode` string, nullable: The acquirer's authorization code. This code is returned on a successful transaction. - `card` Card - `cardNumber` string, nullable: The card number. - `cardName` string, nullable: The name of the cardholder. - `expiryDate` string, nullable: If available, the expiry date of the card in the format 'MM/YY'. - `cardType` string, nullable: The card scheme. - `cardFundingType` string: The main funding types are credit, debit, pre-paid, and charge. - `last4PAN` string, nullable: The last four digits of the Primary Account Number. For Visa and Mastercard, this will be the four numbers at the end of the sixteen-digit card number. - `entryMode` string: Entry mode of the payment. (Contactless, ContactChip, Magstripe, ManualEntry, Unknown) - `verificationMethod` string: Method used to verify that the person presenting the card is the legitimate cardholder. The most common verification methods are PIN and signature. (Pin, Signature, Device, None) - `avsResult` string, nullable: The result of the Address Verification Service (AVS) check. ## Other responses - `400`: Bad request - `401`: Unauthorized - `404`: Not found - `409`: Conflict --- [API](https://skmtc.dev/dojo/apis/dojo-api.md) - [All operations](https://skmtc.dev/dojo/apis/dojo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/dojo/apis/dojo-api/revisions/29fc8900ba37?raw)