Skip to content
Docs
Open Backstage
Reference

BackstageClient.terminal

BackstageClient.terminal in @ticketlayer/backstage.

@ticketlayer/backstage

@ticketlayer/backstage / BackstageClient / terminal

terminal: {
  cancelPayment: (orderId: string, terminalPaymentId: string, requestOptions?: RequestOptions) => Promise<{
     accountId: string;
     amount: number;
     applicationFee: number;
     card:   | {
        brand: string | null;
        last4: string | null;
      }
        | null;
     completedAt: string | null;
     createdAt: string;
     currency: string;
     failureCode: string | null;
     failureMessage: string | null;
     id: string;
     isTest: boolean;
     orderId: string;
     paymentId: string;
     provider: string;
     readerId: string;
     status: "succeeded" | "failed" | "cancelled" | "pending" | "processing";
     updatedAt: string;
  }>;
  chargeOrder: (orderId: string, request: {
     amount?: number;
     readerId: string;
   }, requestOptions?: RequestOptions) => Promise<{
     accountId: string;
     amount: number;
     applicationFee: number;
     card:   | {
        brand: string | null;
        last4: string | null;
      }
        | null;
     completedAt: string | null;
     createdAt: string;
     currency: string;
     failureCode: string | null;
     failureMessage: string | null;
     id: string;
     isTest: boolean;
     orderId: string;
     paymentId: string;
     provider: string;
     readerId: string;
     status: "succeeded" | "failed" | "cancelled" | "pending" | "processing";
     updatedAt: string;
  }>;
  getPayment: (orderId: string, terminalPaymentId: string, options?: {
     refresh?: "true" | "false";
   }, requestOptions?: RequestOptions) => Promise<{
     accountId: string;
     amount: number;
     applicationFee: number;
     card:   | {
        brand: string | null;
        last4: string | null;
      }
        | null;
     completedAt: string | null;
     createdAt: string;
     currency: string;
     failureCode: string | null;
     failureMessage: string | null;
     id: string;
     isTest: boolean;
     orderId: string;
     paymentId: string;
     provider: string;
     readerId: string;
     status: "succeeded" | "failed" | "cancelled" | "pending" | "processing";
     updatedAt: string;
  }>;
  getReader: (readerId: string, options?: {
     refresh?: "true" | "false";
   }, requestOptions?: RequestOptions) => Promise<{
     accountId: string;
     createdAt: string;
     deviceType: string | null;
     externalReaderId: string;
     id: string;
     label: string;
     lastSeenAt: string | null;
     livemode: boolean;
     locationId: string;
     networkStatus: string | null;
     paymentProviderId: string;
     provider: string;
     providerAccountId: string | null;
     serialNumber: string | null;
     updatedAt: string;
  }>;
  listReaders: (options?: {
     accountId?: string;
     locationId?: string;
   }, requestOptions?: RequestOptions) => Promise<{
     accountId: string;
     createdAt: string;
     deviceType: string | null;
     externalReaderId: string;
     id: string;
     label: string;
     lastSeenAt: string | null;
     livemode: boolean;
     locationId: string;
     networkStatus: string | null;
     paymentProviderId: string;
     provider: string;
     providerAccountId: string | null;
     serialNumber: string | null;
     updatedAt: string;
  }[]>;
  presentTestPaymentMethod: (readerId: string, request: {
     cardNumber?: string;
   }, requestOptions?: RequestOptions) => Promise<{
     accountId: string;
     createdAt: string;
     deviceType: string | null;
     externalReaderId: string;
     id: string;
     label: string;
     lastSeenAt: string | null;
     livemode: boolean;
     locationId: string;
     networkStatus: string | null;
     paymentProviderId: string;
     provider: string;
     providerAccountId: string | null;
     serialNumber: string | null;
     updatedAt: string;
  }>;
  registerReader: (request: {
     accountId?: string;
     address?: {
        city: string;
        country: string;
        line1: string;
        line2?: string;
        postalCode: string;
        state?: string;
     };
     externalReaderId?: string;
     label?: string;
     locationId: string;
     paymentProviderId?: string;
     registrationCode?: string;
   }, requestOptions?: RequestOptions) => Promise<{
     accountId: string;
     createdAt: string;
     deviceType: string | null;
     externalReaderId: string;
     id: string;
     label: string;
     lastSeenAt: string | null;
     livemode: boolean;
     locationId: string;
     networkStatus: string | null;
     paymentProviderId: string;
     provider: string;
     providerAccountId: string | null;
     serialNumber: string | null;
     updatedAt: string;
  }>;
  removeReader: (readerId: string, requestOptions?: RequestOptions) => Promise<{
     accountId: string;
     createdAt: string;
     deviceType: string | null;
     externalReaderId: string;
     id: string;
     label: string;
     lastSeenAt: string | null;
     livemode: boolean;
     locationId: string;
     networkStatus: string | null;
     paymentProviderId: string;
     provider: string;
     providerAccountId: string | null;
     serialNumber: string | null;
     updatedAt: string;
  }>;
};

Defined in: client.ts:5785

Terminal methods

cancelPayment()#

cancelPayment: (orderId: string, terminalPaymentId: string, requestOptions?: RequestOptions) => Promise<{
  accountId: string;
  amount: number;
  applicationFee: number;
  card:   | {
     brand: string | null;
     last4: string | null;
   }
     | null;
  completedAt: string | null;
  createdAt: string;
  currency: string;
  failureCode: string | null;
  failureMessage: string | null;
  id: string;
  isTest: boolean;
  orderId: string;
  paymentId: string;
  provider: string;
  readerId: string;
  status: "succeeded" | "failed" | "cancelled" | "pending" | "processing";
  updatedAt: string;
}>;

Cancel a terminal payment Cancels a terminal payment still in progress: the reader stops and the provider payment is cancelled. If the card was taken before the cancel reached the reader, the order is paid and the answer is 409 TERMINAL_PAYMENT_NOT_CANCELLABLE. Needs orders.update or orders.pay on the order, and devices.dispatch on the reader's account.

Parameters#

ParameterType
orderIdstring
terminalPaymentIdstring
requestOptions?RequestOptions

Returns#

Promise<{ accountId: string; amount: number; applicationFee: number; card: | { brand: string | null; last4: string | null; } | null; completedAt: string | null; createdAt: string; currency: string; failureCode: string | null; failureMessage: string | null; id: string; isTest: boolean; orderId: string; paymentId: string; provider: string; readerId: string; status: "succeeded" | "failed" | "cancelled" | "pending" | "processing"; updatedAt: string; }>

Operation Id#

cancelTerminalPayment

chargeOrder()#

chargeOrder: (orderId: string, request: {
  amount?: number;
  readerId: string;
}, requestOptions?: RequestOptions) => Promise<{
  accountId: string;
  amount: number;
  applicationFee: number;
  card:   | {
     brand: string | null;
     last4: string | null;
   }
     | null;
  completedAt: string | null;
  createdAt: string;
  currency: string;
  failureCode: string | null;
  failureMessage: string | null;
  id: string;
  isTest: boolean;
  orderId: string;
  paymentId: string;
  provider: string;
  readerId: string;
  status: "succeeded" | "failed" | "cancelled" | "pending" | "processing";
  updatedAt: string;
}>;

Charge an order on a terminal reader Charges the order's amount due on a card reader the API drives through the provider's cloud: a card-present payment on the reader's provider account, with the same application fee as an online charge, handed to the reader. Answers 201 at once with the new terminal payment, processing; the outcome arrives by the provider's webhooks and is readable with GET /orders/{orderId}/terminal-payments/{terminalPaymentId} (or the terminal_payment.* webhook events). A success completes the order payment exactly as an online payment does. One attempt at a time per order (TERMINAL_PAYMENT_IN_PROGRESS) and per reader (TERMINAL_READER_BUSY). The reader must belong to the order's account (TERMINAL_READER_ACCOUNT_MISMATCH), and a test order can be charged only on a test-mode reader. Needs orders.update or orders.pay on the order, and devices.dispatch on the reader's account.

Parameters#

ParameterTypeDescription
orderIdstring-
request{ amount?: number; readerId: string; }-
request.amount?numberDescription How much of the amount due to charge, integer minor units, for split tender (part on the card, the rest in cash or by voucher). Left out, everything still due. More than is due is refused (PAYMENT_AMOUNT_INVALID). Example 4500
request.readerId?stringDescription The reader to take the card on. It must belong to the order's account. Example trd_4f8a2c9e1b7d3a6c5e0f
requestOptions?RequestOptions-

Returns#

Promise<{ accountId: string; amount: number; applicationFee: number; card: | { brand: string | null; last4: string | null; } | null; completedAt: string | null; createdAt: string; currency: string; failureCode: string | null; failureMessage: string | null; id: string; isTest: boolean; orderId: string; paymentId: string; provider: string; readerId: string; status: "succeeded" | "failed" | "cancelled" | "pending" | "processing"; updatedAt: string; }>

Operation Id#

chargeOrderOnTerminal

getPayment()#

getPayment: (orderId: string, terminalPaymentId: string, options?: {
  refresh?: "true" | "false";
}, requestOptions?: RequestOptions) => Promise<{
  accountId: string;
  amount: number;
  applicationFee: number;
  card:   | {
     brand: string | null;
     last4: string | null;
   }
     | null;
  completedAt: string | null;
  createdAt: string;
  currency: string;
  failureCode: string | null;
  failureMessage: string | null;
  id: string;
  isTest: boolean;
  orderId: string;
  paymentId: string;
  provider: string;
  readerId: string;
  status: "succeeded" | "failed" | "cancelled" | "pending" | "processing";
  updatedAt: string;
}>;

Get a terminal payment Reads one terminal payment attempt. Poll it while processing; with refresh=true an attempt still in progress is first checked with the provider and settled from its answer, which is how the outcome is reached without webhooks.

Parameters#

ParameterType
orderIdstring
terminalPaymentIdstring
options?{ refresh?: "true" | "false"; }
options.refresh?"true" | "false"
requestOptions?RequestOptions

Returns#

Promise<{ accountId: string; amount: number; applicationFee: number; card: | { brand: string | null; last4: string | null; } | null; completedAt: string | null; createdAt: string; currency: string; failureCode: string | null; failureMessage: string | null; id: string; isTest: boolean; orderId: string; paymentId: string; provider: string; readerId: string; status: "succeeded" | "failed" | "cancelled" | "pending" | "processing"; updatedAt: string; }>

Operation Id#

getTerminalPayment

getReader()#

getReader: (readerId: string, options?: {
  refresh?: "true" | "false";
}, requestOptions?: RequestOptions) => Promise<{
  accountId: string;
  createdAt: string;
  deviceType: string | null;
  externalReaderId: string;
  id: string;
  label: string;
  lastSeenAt: string | null;
  livemode: boolean;
  locationId: string;
  networkStatus: string | null;
  paymentProviderId: string;
  provider: string;
  providerAccountId: string | null;
  serialNumber: string | null;
  updatedAt: string;
}>;

Get a terminal reader Gets one card reader. With refresh=true its network status is read from the provider first. Needs devices.read on the reader's account.

Parameters#

ParameterType
readerIdstring
options?{ refresh?: "true" | "false"; }
options.refresh?"true" | "false"
requestOptions?RequestOptions

Returns#

Promise<{ accountId: string; createdAt: string; deviceType: string | null; externalReaderId: string; id: string; label: string; lastSeenAt: string | null; livemode: boolean; locationId: string; networkStatus: string | null; paymentProviderId: string; provider: string; providerAccountId: string | null; serialNumber: string | null; updatedAt: string; }>

Operation Id#

getTerminalReader

listReaders()#

listReaders: (options?: {
  accountId?: string;
  locationId?: string;
}, requestOptions?: RequestOptions) => Promise<{
  accountId: string;
  createdAt: string;
  deviceType: string | null;
  externalReaderId: string;
  id: string;
  label: string;
  lastSeenAt: string | null;
  livemode: boolean;
  locationId: string;
  networkStatus: string | null;
  paymentProviderId: string;
  provider: string;
  providerAccountId: string | null;
  serialNumber: string | null;
  updatedAt: string;
}[]>;

List terminal readers Lists the card readers on the accounts the caller holds devices.list for, newest first.

Parameters#

ParameterType
options?{ accountId?: string; locationId?: string; }
options.accountId?string
options.locationId?string
requestOptions?RequestOptions

Returns#

Promise<{ accountId: string; createdAt: string; deviceType: string | null; externalReaderId: string; id: string; label: string; lastSeenAt: string | null; livemode: boolean; locationId: string; networkStatus: string | null; paymentProviderId: string; provider: string; providerAccountId: string | null; serialNumber: string | null; updatedAt: string; }[]>

Operation Id#

listTerminalReaders

presentTestPaymentMethod()#

presentTestPaymentMethod: (readerId: string, request: {
  cardNumber?: string;
}, requestOptions?: RequestOptions) => Promise<{
  accountId: string;
  createdAt: string;
  deviceType: string | null;
  externalReaderId: string;
  id: string;
  label: string;
  lastSeenAt: string | null;
  livemode: boolean;
  locationId: string;
  networkStatus: string | null;
  paymentProviderId: string;
  provider: string;
  providerAccountId: string | null;
  serialNumber: string | null;
  updatedAt: string;
}>;

Present a test card on a simulated reader Test mode only: taps a test card on a simulated reader that is processing a payment, as a buyer would. The provider then completes or declines the payment and raises its webhooks exactly as for a real card, so the terminal payment settles on the real path. Omit cardNumber for a card that succeeds. A live reader is refused with TERMINAL_READER_NOT_SIMULATED. Needs devices.dispatch on the reader's account.

Parameters#

ParameterTypeDescription
readerIdstring-
request{ cardNumber?: string; }-
request.cardNumber?stringDescription A provider test card number. Omit for a card that succeeds. Stripe's 4000000000000002 declines, 4000000000009995 declines for insufficient funds. Example 4000000000000002
requestOptions?RequestOptions-

Returns#

Promise<{ accountId: string; createdAt: string; deviceType: string | null; externalReaderId: string; id: string; label: string; lastSeenAt: string | null; livemode: boolean; locationId: string; networkStatus: string | null; paymentProviderId: string; provider: string; providerAccountId: string | null; serialNumber: string | null; updatedAt: string; }>

Operation Id#

presentTerminalTestPaymentMethod

registerReader()#

registerReader: (request: {
  accountId?: string;
  address?: {
     city: string;
     country: string;
     line1: string;
     line2?: string;
     postalCode: string;
     state?: string;
  };
  externalReaderId?: string;
  label?: string;
  locationId: string;
  paymentProviderId?: string;
  registrationCode?: string;
}, requestOptions?: RequestOptions) => Promise<{
  accountId: string;
  createdAt: string;
  deviceType: string | null;
  externalReaderId: string;
  id: string;
  label: string;
  lastSeenAt: string | null;
  livemode: boolean;
  locationId: string;
  networkStatus: string | null;
  paymentProviderId: string;
  provider: string;
  providerAccountId: string | null;
  serialNumber: string | null;
  updatedAt: string;
}>;

Register a terminal reader Registers a card reader to an account and a location, on the provider account that takes that account's card charges: the Ticketlayer Pay connected account, your own Stripe account (direct mode), or the connected account your Stripe account vends for the account (connected mode). Register by the code the reader shows (in Stripe test mode, simulated-wpe makes a simulated reader), or attach a reader already registered on that account by its id. The first reader at a location on a provider account needs the location's address, to create the provider's location object there. Needs devices.create on the location's account.

Parameters#

ParameterTypeDescription
request{ accountId?: string; address?: { city: string; country: string; line1: string; line2?: string; postalCode: string; state?: string; }; externalReaderId?: string; label?: string; locationId: string; paymentProviderId?: string; registrationCode?: string; }-
request.accountId?stringDescription Optional. When given it must be the location's account. Example acc_xyz789
request.address?{ city: string; country: string; line1: string; line2?: string; postalCode: string; state?: string; }-
request.address.city?stringExample London
request.address.country?stringDescription ISO 3166-1 alpha-2 Example GB
request.address.line1?stringExample 1 Theatre Street
request.address.line2?stringExample Stage door
request.address.postalCode?stringExample WC2E 7RQ
request.address.state?stringDescription Needed in some countries (US, CA, AU) Example CA
request.externalReaderId?stringDescription Attach a reader already registered at the provider, by its id. It must be on the provider account that takes this account's charges; a reader on any other account is refused. Example tmr_FDOt2wlRZEdpd7
request.label?stringDescription Shown on the reader and in lists. Defaults to the location's name. Example Box office 1
request.locationId?stringDescription The location the reader is at (GET /locations). The reader belongs to the location's account. Example loc_boxoffice01
request.paymentProviderId?stringDescription The payment provider whose account the reader lives on: Ticketlayer Pay, or your own Stripe account. Defaults to the provider this account's card payments go through. Example ppr_stripeXxx123
request.registrationCode?stringDescription The code the reader shows when it is ready to register. In Stripe test mode simulated-wpe (or another simulated- code) makes a simulated reader, so the whole flow can be exercised with no hardware. Give this or externalReaderId. Example simulated-wpe
requestOptions?RequestOptions-

Returns#

Promise<{ accountId: string; createdAt: string; deviceType: string | null; externalReaderId: string; id: string; label: string; lastSeenAt: string | null; livemode: boolean; locationId: string; networkStatus: string | null; paymentProviderId: string; provider: string; providerAccountId: string | null; serialNumber: string | null; updatedAt: string; }>

Operation Id#

registerTerminalReader

removeReader()#

removeReader: (readerId: string, requestOptions?: RequestOptions) => Promise<{
  accountId: string;
  createdAt: string;
  deviceType: string | null;
  externalReaderId: string;
  id: string;
  label: string;
  lastSeenAt: string | null;
  livemode: boolean;
  locationId: string;
  networkStatus: string | null;
  paymentProviderId: string;
  provider: string;
  providerAccountId: string | null;
  serialNumber: string | null;
  updatedAt: string;
}>;

Remove a terminal reader Removes a card reader from the provider account and from Ticketlayer. A reader taking a payment is refused with TERMINAL_READER_BUSY; cancel the payment first. Needs devices.revoke on the reader's account.

Parameters#

ParameterType
readerIdstring
requestOptions?RequestOptions

Returns#

Promise<{ accountId: string; createdAt: string; deviceType: string | null; externalReaderId: string; id: string; label: string; lastSeenAt: string | null; livemode: boolean; locationId: string; networkStatus: string | null; paymentProviderId: string; provider: string; providerAccountId: string | null; serialNumber: string | null; updatedAt: string; }>

Operation Id#

removeTerminalReader