Skip to content
Docs
Open Backstage
Reference

BackstageClient.payments

BackstageClient.payments in @ticketlayer/backstage.

@ticketlayer/backstage

@ticketlayer/backstage / BackstageClient / payments

payments: {
  cancel: (paymentId: string, request: {
     reason?: string;
   }, requestOptions?: RequestOptions) => Promise<{
     amount: number;
     createdAt: string;
     currency: string;
     failedAt: string | null;
     failureCode: string | null;
     failureMessage: string | null;
     id: string;
     invoiceId: string | null;
     method: string | null;
     organisationId: string;
     paidAt: string | null;
     status: "succeeded" | "failed" | "cancelled" | "refunded" | "pending";
     updatedAt: string;
  }>;
  capturePaypal: (paymentId: string, requestOptions?: RequestOptions) => Promise<{
     captureId: string | null;
     orderId: string;
     orderStatus: string | null;
     paymentId: string;
     reason: string | null;
     status: "succeeded" | "failed" | "pending";
  }>;
  confirmSandbox: (paymentId: string, request: {
     token?: string;
   }, requestOptions?: RequestOptions) => Promise<{
     failureCode?: string;
     failureMessage?: string;
     ingestStatus: "duplicate" | "received";
     outcome: "succeeded" | "failed";
     paymentId: string;
     token: string;
     webhookEventId: string;
  }>;
  create: (request: {
     accountId: string;
     amount: number;
     currency: string;
     isPartialPayment?: boolean;
     metadata?: Record<string, any>;
     orderId: string;
     orderNumber: string;
     paymentProviderId?: string;
     paymentType:   | "in_person_cash"
        | "in_person_card"
        | "online_card"
        | "bank_transfer"
        | "cheque"
        | "online_bank_transfer"
        | "online_wallet";
     remainingBalance?: number;
     returnUrl?: string;
   }, requestOptions?: RequestOptions) => Promise<{
     amount: number;
     createdAt: string;
     currency: string;
     failedAt: string | null;
     failureCode: string | null;
     failureMessage: string | null;
     id: string;
     invoiceId: string | null;
     method: string | null;
     organisationId: string;
     paidAt: string | null;
     status: "succeeded" | "failed" | "cancelled" | "refunded" | "pending";
     updatedAt: string;
  }>;
  createRefund: (paymentId: string, request: {
     amount: number;
     destination?: "original" | "account_credit";
     metadata?: Record<string, any>;
     notes?: string;
     reason: string;
   }, requestOptions?: RequestOptions) => Promise<{
     amount: number;
     completedAt: string | null;
     createdAt: string;
     destination: "original" | "stored_value";
     externalRefundId: string | null;
     failedAt: string | null;
     failureCode: string | null;
     failureMessage: string | null;
     id: string;
     metadata:   | {
      [key: string]: unknown;
      }
        | null;
     notes: string | null;
     paymentId: string;
     reason: string;
     refundRequestId: string | null;
     source: "platform" | "provider";
     status: "succeeded" | "failed" | "cancelled" | "pending" | "processing";
     storedValueAccountId: string | null;
     updatedAt: string;
  }>;
  get: (paymentId: string, requestOptions?: RequestOptions) => Promise<{
     amount: number;
     createdAt: string;
     currency: string;
     failedAt: string | null;
     failureCode: string | null;
     failureMessage: string | null;
     id: string;
     invoiceId: string | null;
     method: string | null;
     organisationId: string;
     paidAt: string | null;
     status: "succeeded" | "failed" | "cancelled" | "refunded" | "pending";
     updatedAt: string;
  }>;
  list: (options?: {
     fromDate?: string;
     limit?: string;
     orderId?: string;
     page?: string;
     paymentProviderId?: string;
     paymentType?:   | "other"
        | "in_person_cash"
        | "in_person_card"
        | "online_card"
        | "bank_transfer"
        | "cheque"
        | "voucher"
        | "online_bank_transfer"
        | "online_wallet";
     status?:   | "created"
        | "expired"
        | "succeeded"
        | "failed"
        | "cancelled"
        | "pending"
        | "processing"
        | "requires_action";
     toDate?: string;
   }, requestOptions?: RequestOptions) => Promise<{
     amount: number;
     createdAt: string;
     currency: string;
     failedAt: string | null;
     failureCode: string | null;
     failureMessage: string | null;
     id: string;
     invoiceId: string | null;
     method: string | null;
     organisationId: string;
     paidAt: string | null;
     status: "succeeded" | "failed" | "cancelled" | "refunded" | "pending";
     updatedAt: string;
  }[]>;
  listRefunds: (paymentId: string, requestOptions?: RequestOptions) => Promise<{
     amount: number;
     completedAt: string | null;
     createdAt: string;
     destination: "original" | "stored_value";
     externalRefundId: string | null;
     failedAt: string | null;
     failureCode: string | null;
     failureMessage: string | null;
     id: string;
     metadata:   | {
      [key: string]: unknown;
      }
        | null;
     notes: string | null;
     paymentId: string;
     reason: string;
     refundRequestId: string | null;
     source: "platform" | "provider";
     status: "succeeded" | "failed" | "cancelled" | "pending" | "processing";
     storedValueAccountId: string | null;
     updatedAt: string;
  }[]>;
  raiseSandboxPayouts: (request: {
     currency?: string;
     providerId: string;
  }, requestOptions?: RequestOptions) => Promise<any>;
};

Defined in: client.ts:5921

Payments methods

cancel()#

cancel: (paymentId: string, request: {
  reason?: string;
}, requestOptions?: RequestOptions) => Promise<{
  amount: number;
  createdAt: string;
  currency: string;
  failedAt: string | null;
  failureCode: string | null;
  failureMessage: string | null;
  id: string;
  invoiceId: string | null;
  method: string | null;
  organisationId: string;
  paidAt: string | null;
  status: "succeeded" | "failed" | "cancelled" | "refunded" | "pending";
  updatedAt: string;
}>;

Cancel payment Cancel a pending payment

Parameters#

ParameterType
paymentIdstring
request{ reason?: string; }
request.reason?string
requestOptions?RequestOptions

Returns#

Promise<{ amount: number; createdAt: string; currency: string; failedAt: string | null; failureCode: string | null; failureMessage: string | null; id: string; invoiceId: string | null; method: string | null; organisationId: string; paidAt: string | null; status: "succeeded" | "failed" | "cancelled" | "refunded" | "pending"; updatedAt: string; }>

Operation Id#

cancelPayment

capturePaypal()#

capturePaypal: (paymentId: string, requestOptions?: RequestOptions) => Promise<{
  captureId: string | null;
  orderId: string;
  orderStatus: string | null;
  paymentId: string;
  reason: string | null;
  status: "succeeded" | "failed" | "pending";
}>;

Capture an approved PayPal payment Captures the PayPal order behind a payment once the buyer has approved it: what the PayPal JS SDK's onApprove callback asks for. A capture PayPal completes pays the order down the same path every processor's success takes; one it holds is answered 'pending' and settles when PayPal says so; one it declines fails the payment. Capturing again is safe: an order PayPal has captured already is read, not captured twice, and a payment that has succeeded answers as it is. When PayPal declines the funding source the buyer chose, the answer is 400 PAYPAL_INSTRUMENT_DECLINED and the payment stays capturable: restart the buttons so they can choose another. Needs payments.create, or orders.pay.

Parameters#

ParameterType
paymentIdstring
requestOptions?RequestOptions

Returns#

Promise<{ captureId: string | null; orderId: string; orderStatus: string | null; paymentId: string; reason: string | null; status: "succeeded" | "failed" | "pending"; }>

Operation Id#

capturePaypalPayment

confirmSandbox()#

confirmSandbox: (paymentId: string, request: {
  token?: string;
}, requestOptions?: RequestOptions) => Promise<{
  failureCode?: string;
  failureMessage?: string;
  ingestStatus: "duplicate" | "received";
  outcome: "succeeded" | "failed";
  paymentId: string;
  token: string;
  webhookEventId: string;
}>;

Confirm a sandbox payment Confirms a payment taken on a 'sandbox' provider, standing in for the card form a buyer would fill in. The test token decides the outcome: 'tl_test_pm_success' captures it, so the order is confirmed and its tickets are issued; 'tl_test_pm_decline', 'tl_test_pm_insufficient_funds' and 'tl_test_pm_expired_card' decline it with that failure code, so the order stays unpaid and nothing is issued. Defaults to 'tl_test_pm_success'. The outcome is raised as a provider webhook into the same ingress a real PSP posts to, so the whole path is the real one - and, like a redelivered PSP event, confirming the same token twice is a no-op. Only payments on a sandbox provider for a TEST order can be confirmed: the sandbox settles pretend money only. Needs payments.create, or orders.pay (taking payment for an order, which a channel secret key holds for its own channel's orders).

Parameters#

ParameterType
paymentIdstring
request{ token?: string; }
request.token?string
requestOptions?RequestOptions

Returns#

Promise<{ failureCode?: string; failureMessage?: string; ingestStatus: "duplicate" | "received"; outcome: "succeeded" | "failed"; paymentId: string; token: string; webhookEventId: string; }>

Operation Id#

confirmSandboxPayment

create()#

create: (request: {
  accountId: string;
  amount: number;
  currency: string;
  isPartialPayment?: boolean;
  metadata?: Record<string, any>;
  orderId: string;
  orderNumber: string;
  paymentProviderId?: string;
  paymentType:   | "in_person_cash"
     | "in_person_card"
     | "online_card"
     | "bank_transfer"
     | "cheque"
     | "online_bank_transfer"
     | "online_wallet";
  remainingBalance?: number;
  returnUrl?: string;
}, requestOptions?: RequestOptions) => Promise<{
  amount: number;
  createdAt: string;
  currency: string;
  failedAt: string | null;
  failureCode: string | null;
  failureMessage: string | null;
  id: string;
  invoiceId: string | null;
  method: string | null;
  organisationId: string;
  paidAt: string | null;
  status: "succeeded" | "failed" | "cancelled" | "refunded" | "pending";
  updatedAt: string;
}>;

Create payment Create a new payment for an order

Parameters#

ParameterType
request{ accountId: string; amount: number; currency: string; isPartialPayment?: boolean; metadata?: Record<string, any>; orderId: string; orderNumber: string; paymentProviderId?: string; paymentType: | "in_person_cash" | "in_person_card" | "online_card" | "bank_transfer" | "cheque" | "online_bank_transfer" | "online_wallet"; remainingBalance?: number; returnUrl?: string; }
request.accountIdstring
request.amount?number
request.currency?string
request.isPartialPayment?boolean
request.metadata?Record<string, any>
request.orderId?string
request.orderNumber?string
request.paymentProviderId?string
request.paymentType?| "in_person_cash" | "in_person_card" | "online_card" | "bank_transfer" | "cheque" | "online_bank_transfer" | "online_wallet"
request.remainingBalance?number
request.returnUrl?string
requestOptions?RequestOptions

Returns#

Promise<{ amount: number; createdAt: string; currency: string; failedAt: string | null; failureCode: string | null; failureMessage: string | null; id: string; invoiceId: string | null; method: string | null; organisationId: string; paidAt: string | null; status: "succeeded" | "failed" | "cancelled" | "refunded" | "pending"; updatedAt: string; }>

Operation Id#

createPayment

createRefund()#

createRefund: (paymentId: string, request: {
  amount: number;
  destination?: "original" | "account_credit";
  metadata?: Record<string, any>;
  notes?: string;
  reason: string;
}, requestOptions?: RequestOptions) => Promise<{
  amount: number;
  completedAt: string | null;
  createdAt: string;
  destination: "original" | "stored_value";
  externalRefundId: string | null;
  failedAt: string | null;
  failureCode: string | null;
  failureMessage: string | null;
  id: string;
  metadata:   | {
   [key: string]: unknown;
   }
     | null;
  notes: string | null;
  paymentId: string;
  reason: string;
  refundRequestId: string | null;
  source: "platform" | "provider";
  status: "succeeded" | "failed" | "cancelled" | "pending" | "processing";
  storedValueAccountId: string | null;
  updatedAt: string;
}>;

Create refund Create a refund for a payment: back to how it was paid, or (destination: 'account_credit') into the order's customer's account credit, which succeeds at once and moves nothing at the payment provider: the payment's holder keeps the money and owes the organisation, which owes the customer. An order with no customer cannot be refunded to credit (STORED_VALUE_CUSTOMER_REQUIRED). A gift card or credit spent goes back onto its balance, which must be active or frozen (STORED_VALUE_NOT_ACTIVE otherwise: refund it to account credit).

Parameters#

ParameterType
paymentIdstring
request{ amount: number; destination?: "original" | "account_credit"; metadata?: Record<string, any>; notes?: string; reason: string; }
request.amountnumber
request.destination?"original" | "account_credit"
request.metadata?Record<string, any>
request.notes?string
request.reason?string
requestOptions?RequestOptions

Returns#

Promise<{ amount: number; completedAt: string | null; createdAt: string; destination: "original" | "stored_value"; externalRefundId: string | null; failedAt: string | null; failureCode: string | null; failureMessage: string | null; id: string; metadata: | { [key: string]: unknown; } | null; notes: string | null; paymentId: string; reason: string; refundRequestId: string | null; source: "platform" | "provider"; status: "succeeded" | "failed" | "cancelled" | "pending" | "processing"; storedValueAccountId: string | null; updatedAt: string; }>

Operation Id#

createPaymentRefund

get()#

get: (paymentId: string, requestOptions?: RequestOptions) => Promise<{
  amount: number;
  createdAt: string;
  currency: string;
  failedAt: string | null;
  failureCode: string | null;
  failureMessage: string | null;
  id: string;
  invoiceId: string | null;
  method: string | null;
  organisationId: string;
  paidAt: string | null;
  status: "succeeded" | "failed" | "cancelled" | "refunded" | "pending";
  updatedAt: string;
}>;

Get payment Get a specific payment by ID

Parameters#

ParameterType
paymentIdstring
requestOptions?RequestOptions

Returns#

Promise<{ amount: number; createdAt: string; currency: string; failedAt: string | null; failureCode: string | null; failureMessage: string | null; id: string; invoiceId: string | null; method: string | null; organisationId: string; paidAt: string | null; status: "succeeded" | "failed" | "cancelled" | "refunded" | "pending"; updatedAt: string; }>

Operation Id#

getPayment

list()#

list: (options?: {
  fromDate?: string;
  limit?: string;
  orderId?: string;
  page?: string;
  paymentProviderId?: string;
  paymentType?:   | "other"
     | "in_person_cash"
     | "in_person_card"
     | "online_card"
     | "bank_transfer"
     | "cheque"
     | "voucher"
     | "online_bank_transfer"
     | "online_wallet";
  status?:   | "created"
     | "expired"
     | "succeeded"
     | "failed"
     | "cancelled"
     | "pending"
     | "processing"
     | "requires_action";
  toDate?: string;
}, requestOptions?: RequestOptions) => Promise<{
  amount: number;
  createdAt: string;
  currency: string;
  failedAt: string | null;
  failureCode: string | null;
  failureMessage: string | null;
  id: string;
  invoiceId: string | null;
  method: string | null;
  organisationId: string;
  paidAt: string | null;
  status: "succeeded" | "failed" | "cancelled" | "refunded" | "pending";
  updatedAt: string;
}[]>;

List payments List all payments with optional filtering and pagination

Parameters#

ParameterType
options?{ fromDate?: string; limit?: string; orderId?: string; page?: string; paymentProviderId?: string; paymentType?: | "other" | "in_person_cash" | "in_person_card" | "online_card" | "bank_transfer" | "cheque" | "voucher" | "online_bank_transfer" | "online_wallet"; status?: | "created" | "expired" | "succeeded" | "failed" | "cancelled" | "pending" | "processing" | "requires_action"; toDate?: string; }
options.fromDate?string
options.limit?string
options.orderId?string
options.page?string
options.paymentProviderId?string
options.paymentType?| "other" | "in_person_cash" | "in_person_card" | "online_card" | "bank_transfer" | "cheque" | "voucher" | "online_bank_transfer" | "online_wallet"
options.status?| "created" | "expired" | "succeeded" | "failed" | "cancelled" | "pending" | "processing" | "requires_action"
options.toDate?string
requestOptions?RequestOptions

Returns#

Promise<{ amount: number; createdAt: string; currency: string; failedAt: string | null; failureCode: string | null; failureMessage: string | null; id: string; invoiceId: string | null; method: string | null; organisationId: string; paidAt: string | null; status: "succeeded" | "failed" | "cancelled" | "refunded" | "pending"; updatedAt: string; }[]>

Operation Id#

listPayments

listRefunds()#

listRefunds: (paymentId: string, requestOptions?: RequestOptions) => Promise<{
  amount: number;
  completedAt: string | null;
  createdAt: string;
  destination: "original" | "stored_value";
  externalRefundId: string | null;
  failedAt: string | null;
  failureCode: string | null;
  failureMessage: string | null;
  id: string;
  metadata:   | {
   [key: string]: unknown;
   }
     | null;
  notes: string | null;
  paymentId: string;
  reason: string;
  refundRequestId: string | null;
  source: "platform" | "provider";
  status: "succeeded" | "failed" | "cancelled" | "pending" | "processing";
  storedValueAccountId: string | null;
  updatedAt: string;
}[]>;

List refunds List all refunds for a specific payment

Parameters#

ParameterType
paymentIdstring
requestOptions?RequestOptions

Returns#

Promise<{ amount: number; completedAt: string | null; createdAt: string; destination: "original" | "stored_value"; externalRefundId: string | null; failedAt: string | null; failureCode: string | null; failureMessage: string | null; id: string; metadata: | { [key: string]: unknown; } | null; notes: string | null; paymentId: string; reason: string; refundRequestId: string | null; source: "platform" | "provider"; status: "succeeded" | "failed" | "cancelled" | "pending" | "processing"; storedValueAccountId: string | null; updatedAt: string; }[]>

Operation Id#

listPaymentRefunds

raiseSandboxPayouts()#

raiseSandboxPayouts: (request: {
  currency?: string;
  providerId: string;
}, requestOptions?: RequestOptions) => Promise<any>;

Pay out a sandbox balance The sandbox payment provider paying its balance out, as a real one does on its schedule, so a test-mode organisation sees the whole cycle: the sale, the payout, and clearing back to zero. It pays out the sandbox balance's clearing total, one payout per currency (or only currency), listing the sandbox balance transactions not paid out before. The payout is raised as the sandbox's payout.paid webhook into the same ingress a real provider posts to, so it is recorded, posted (DR the holder's Cash, CR the balance's clearing, in the TEST book) and reconciled asynchronously by the same handlers; read it with GET /v1/ledger/payouts?book=test. Pretend money only: a sandbox balance is in the test book, and the operation is refused on the production stage. An empty list when there is nothing to pay out. Needs paymentproviders.update on the Account that owns the provider (across the whole organisation for an organisation-wide provider): it moves the balance of a provider, not the sale of a channel.

Parameters#

ParameterType
request{ currency?: string; providerId: string; }
request.currency?string
request.providerId?string
requestOptions?RequestOptions

Returns#

Promise<any>

Operation Id#

raiseSandboxPayouts