Client Sessions

Client sessions are short-lived tokens that authorize the React SDK (browser) to interact with a payment provider on behalf of your merchant account. All session lifecycle operations run on your backend; only the session token is passed to the frontend.

Session types

Type	Method namespace	Use case
payment	clientSessions.payments	Collect card details and charge immediately
add-payment-method	clientSessions.paymentMethod.add	Store a card without charging
authorization	clientSessions.authorizations	Place a hold; settle or void later

---

getBaseConfig()

Fetch provider configuration before creating a session — useful for preloading the React SDK while the customer fills in a form.

const config = await accrupay.transactions.clientSessions.getBaseConfig({
  merchantTransactionProviderId: process.env.ACCRUPAY_PROVIDER_ID,
  // OR: transactionProvider: TRANSACTION_PROVIDER.EXAMPLE
});

Parameter	Type	Required	Description
merchantTransactionProviderId	string	One of	Internal provider record ID.
transactionProvider	TRANSACTION_PROVIDER	One of	Provider enum value. Mutually exclusive with merchantTransactionProviderId.

---

getOne()

Retrieve an existing session by any available identifier.

const session = await accrupay.transactions.clientSessions.getOne({
  id: 'session-id',
});

Parameter	Type	Description
id	string	Session UUID.
merchantInternalTransactionCode	string	Your internal transaction reference.
providerCode	string	Provider-assigned session reference.

---

getMany()

List sessions with pagination and optional filters.

const { data, total } = await accrupay.transactions.clientSessions.getMany({
  take: 20,
  skip: 0,
});

---

Payment sessions

clientSessions.payments.start()

Creates a session for a one-time card payment. Pass the returned token to the React SDK.

import AccruPay, { CURRENCY, COUNTRY_ISO_2 } from '@accrupay/node';

const session = await accrupay.transactions.clientSessions.payments.start({
  merchantTransactionProviderId: process.env.ACCRUPAY_PROVIDER_ID,
  data: {
    merchantInternalTransactionCode: 'order-8821',
    amount: 10000n, // $100.00
    currency: CURRENCY.USD,
    storePaymentMethod: false,
    billing: {
      billingFirstName: 'Jane',
      billingLastName: 'Smith',
      billingEmail: 'jane@example.com',
      billingAddressCountry: COUNTRY_ISO_2.US,
      billingPhone: '+12125550100',
      billingAddressState: 'US-NY',
      billingAddressCity: 'New York',
      billingAddressLine1: '123 Main St',
      billingAddressPostalCode: '10001',
    },
    customer: {
      merchantInternalCustomerCode: 'customer-4421',
    },
  },
});

// Pass session.token to the React SDK

Top-level parameters

Parameter	Type	Required	Description
merchantTransactionProviderId	string	One of	Internal provider record ID.
transactionProvider	TRANSACTION_PROVIDER	One of	Provider enum. Mutually exclusive with merchantTransactionProviderId.

data fields

Field	Type	Required	Description
merchantInternalTransactionCode	string	Yes	Your unique reference for this transaction.
amount	bigint	Yes	Amount in the smallest currency unit (e.g. 10000n = $100.00).
currency	CURRENCY	Yes	ISO 4217 currency code.
storePaymentMethod	boolean	Yes	Store the card for future charges if true.
billing	BillingDataSchema	Yes	Billing contact and address. See Billing fields.
customer.merchantInternalCustomerCode	string	No	Link session to an existing customer record.
shipping	ShippingDataSchema	No	Shipping address.
user	UserDataSchema	No	End-user identity.
device	DeviceDataSchema	No	Device fingerprint data.

Billing fields

Field	Type	Required	Description
billingFirstName	string	Yes
billingLastName	string	Yes
billingEmail	string	Yes
billingAddressCountry	COUNTRY_ISO_2	Yes	ISO 3166-1 alpha-2.
billingPhone	string	No	E.164 format (e.g. +12125550100).
billingAddressState	string	No	ISO 3166-2 subdivision (e.g. US-NY).
billingAddressCity	string	No
billingAddressLine1	string	No
billingAddressLine2	string	No
billingAddressPostalCode	string	No

Session response fields

Field	Type	Description
id	string	Session UUID.
token	string	Short-lived token for the React SDK.
tokenExpiresAt	string	ISO 8601 expiry timestamp.
status	string	Current session status.
action	string	Expected next action.
kind	string	Session type (payment, add-payment-method, authorization).
amount	bigint	Confirmed amount.
currency	CURRENCY	Confirmed currency.
merchantInternalTransactionCode	string	Echo of your reference.
transactionProviderId	string	Resolved provider record ID.
storePaymentMethod	boolean
payload	object	Provider-specific configuration payload for the React SDK.
paymentMethod	object | null	Populated after the session completes.
transactionProvider	TRANSACTION_PROVIDER | null
transactions	MerchantTransaction[]	Transactions created in this session.

---

clientSessions.payments.verify()

Call after the React SDK signals completion. Returns a MerchantTransaction, not a session.

const transaction = await accrupay.transactions.clientSessions.payments.verify({
  id: session.id,
});

console.log(transaction.status); // `SUCCEEDED` | `FAILED` | `DECLINED` | ...

warning

verify() returns a MerchantTransaction object, not a session. The shape is different from start(). Always use the returned transaction.status to determine the payment outcome — do not rely solely on the absence of an error.

Identifier options (pass exactly one)

Parameter	Type	Description
id	string	Session UUID.
token	string	Session token.
providerCode	string	Provider-assigned reference.
merchantInternalTransactionCode	string	Your internal reference.

---

Add-payment-method sessions

Use this flow to store a card without charging it. The amount and storePaymentMethod fields are not present — the intent is always to store.

clientSessions.paymentMethod.add.start()

const session = await accrupay.transactions.clientSessions.paymentMethod.add.start({
  merchantTransactionProviderId: process.env.ACCRUPAY_PROVIDER_ID,
  data: {
    merchantInternalTransactionCode: 'add-pm-3310',
    currency: CURRENCY.USD,
    billing: {
      billingFirstName: 'Jane',
      billingLastName: 'Smith',
      billingEmail: 'jane@example.com',
      billingAddressCountry: COUNTRY_ISO_2.US,
    },
    customer: {
      merchantInternalCustomerCode: 'customer-4421',
    },
  },
});

The data schema is identical to the payment session except:

• amount — not accepted
• storePaymentMethod — not accepted (always true implicitly)

clientSessions.paymentMethod.add.verify()

const result = await accrupay.transactions.clientSessions.paymentMethod.add.verify({
  id: session.id,
});

Accepts the same four identifier options as payments.verify(). Returns a MerchantTransaction.

note

The stored payment method ID appears in result.paymentMethod.id. Pass this to transactions.payments.paymentMethod.charge() for future charges.

---

Authorization sessions

Authorizations place a hold on funds without capturing. Settle or void the hold from the backend after verification.

clientSessions.authorizations.start()

const session = await accrupay.transactions.clientSessions.authorizations.start({
  merchantTransactionProviderId: process.env.ACCRUPAY_PROVIDER_ID,
  data: {
    merchantInternalTransactionCode: 'auth-5540',
    amount: 25000n, // $250.00
    currency: CURRENCY.USD,
    storePaymentMethod: false,
    billing: {
      billingFirstName: 'Jane',
      billingLastName: 'Smith',
      billingEmail: 'jane@example.com',
      billingAddressCountry: COUNTRY_ISO_2.US,
    },
  },
});

The data schema is identical to the payment session — amount and storePaymentMethod are both required.

clientSessions.authorizations.verify()

const transaction = await accrupay.transactions.clientSessions.authorizations.verify({
  id: session.id,
});

Accepts the same four identifier options as payments.verify(). Returns a MerchantTransaction.

note

After a successful authorization, use transactions.authorizations.settle() to capture funds or transactions.authorizations.void() to release the hold. Both methods take the transaction.id returned here.