Transaction Operations

Use these methods to query, refund, void, sync, and capture transactions after they have been created. These are backend operations — all calls require your API secret.

---

transactions.getMany()

Returns a paginated list of transactions matching the provided filters.

Filter parameters

Parameter	Type	Description
id	string	Filter by transaction ID.
paymentMethodId	string	Filter by stored payment method ID.
paymentMethodCode	string	Filter by payment method provider code.
paymentMethodType	PAYMENT_METHOD	Filter by payment method type (card, ACH, etc.).
paymentPlanId	string	Filter by payment plan ID.
transactionProviderId	string	Filter by provider configuration ID.
clientTransactionSessionId	string	Filter by client session that created the transaction.
action	TRANSACTION_ACTION	Filter by a single transaction action.
actions	TRANSACTION_ACTION[]	Filter by multiple transaction actions (OR).
status	TRANSACTION_STATUS	Filter by a single status.
statuses	TRANSACTION_STATUS[]	Filter by multiple statuses (OR).
currency	CURRENCY	Filter by currency.
transactionProvider	TRANSACTION_PROVIDER	Filter by provider enum.
providerCode	string	Filter by provider-assigned transaction code.
providerRelatedCode	string	Filter by provider-assigned related code.
hasProviderError	boolean	Filter for transactions with or without provider errors.
merchantInternalCustomerCode	string	Filter by your customer identifier.
merchantInternalTransactionCode	string	Filter by your transaction idempotency key.
customerId	string	Filter by AccruPay customer ID.
relatedTransactionId	string	Filter by parent/related transaction (e.g. original charge for a refund).
failed	boolean	Include only failed transactions.
started	boolean	Include only started (in-progress) transactions.
disputed	boolean	Include only disputed transactions.
reverted	boolean	Include only reverted transactions.
canceled	boolean	Include only canceled transactions.
succeeded	boolean	Include only successful transactions.
transactionDateFrom	DateTimeISO	Filter transactions on or after this date.
transactionDateTo	DateTimeISO	Filter transactions on or before this date.
sorting	object	Sort configuration object.

Pagination

getMany() supports two mutually exclusive pagination styles. Do not mix them in a single call.

Offset pagination

Simpler and suitable when you don't need stable cursors (e.g. admin dashboards, exports).

Parameter	Type	Description
skip	number	Number of records to skip.
take	number	Number of records to return.

const page2 = await sdk.transactions.getMany({
  succeeded: true,
  currency: CURRENCY.USD,
  skip: 20,
  take: 10,
});

Cursor pagination

Use when building infinite scroll, feeds, or any UI where the list can change between requests. Cursors are stable — inserting a new record won't shift your page boundaries.

Parameter	Type	Description
after	string	Return records after this cursor (forward pagination).
first	number	Number of records to return after the cursor.
before	string	Return records before this cursor (backward pagination).
last	number	Number of records to return before the cursor.

// Forward — first page
const result = await sdk.transactions.getMany({ first: 20 });
const cursor = result.pageInfo.endCursor;

// Forward — next page
const nextPage = await sdk.transactions.getMany({ first: 20, after: cursor });

Code example

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

const sdk = new AccruPay({ apiSecret: process.env.ACCRUPAY_API_SECRET! });

const { data, pageInfo } = await sdk.transactions.getMany({
  succeeded: true,
  currency: CURRENCY.USD,
  transactionDateFrom: '2024-01-01T00:00:00Z',
  transactionDateTo: '2024-12-31T23:59:59Z',
  first: 50,
});

---

transactions.getOne()

Returns a single transaction by one of three identifiers. Provide exactly one.

Parameter	Type	Description
id	string	AccruPay transaction ID.
merchantInternalTransactionCode	string	Your idempotency key.
providerCode	string	Provider-assigned transaction identifier.

const transaction = await sdk.transactions.getOne({
  merchantInternalTransactionCode: 'order-9876-charge',
});

Returns: MerchantTransaction

---

transactions.voidOne()

Voids a transaction, canceling it before settlement. Not all providers support post-authorization voids outside of the authorization flow — use transactions.authorizations.void() for authorized-but-uncaptured transactions.

Parameter	Type	Description
id	string	AccruPay transaction ID.
merchantInternalTransactionCode	string	Your idempotency key.
providerCode	string	Provider-assigned transaction identifier.

const voided = await sdk.transactions.voidOne({
  id: 'txn_abc123',
});

Returns: MerchantTransaction

---

transactions.refundOne()

Refunds a settled transaction. amount is always required — there is no shorthand for refunding the full amount.

warning

amount is required on every refund call. There is no "refund full" shorthand. To refund the full amount, pass transaction.amount.

Parameters

Parameter	Type	Required	Description
amount	bigint	Yes	Amount to refund in smallest currency unit.
id	string	No	AccruPay transaction ID.
merchantInternalTransactionCode	string	No	Your idempotency key.
providerCode	string	No	Provider-assigned transaction identifier.

Provide exactly one identifier alongside amount.

Partial refunds

• Pass an amount less than transaction.amount to issue a partial refund.
• Multiple partial refunds are allowed. Cumulative refunds cannot exceed the original transaction.amount.
• transaction.refundedAmount tracks how much has been refunded so far.

// Full refund
const fullRefund = await sdk.transactions.refundOne({
  id: 'txn_abc123',
  amount: transaction.amount, // e.g. 4999n
});

// Partial refund
const partialRefund = await sdk.transactions.refundOne({
  id: 'txn_abc123',
  amount: 1000n, // $10.00 back
});

Returns: MerchantTransaction

---

transactions.syncOne()

Pulls the latest state from the provider and updates the transaction record. Use this for ACH transactions (which settle asynchronously) or to reconcile any transaction whose status is uncertain.

Parameters

Parameter	Type	Required	Description
merchantTransactionProviderId	string	Yes	Provider configuration ID (required for routing the sync request).
id	string	No	AccruPay transaction ID.
merchantInternalTransactionCode	string	No	Your idempotency key.
providerCode	string	No	Provider-assigned transaction identifier.

const synced = await sdk.transactions.syncOne({
  merchantTransactionProviderId: process.env.ACCRUPAY_PROVIDER_ID!,
  merchantInternalTransactionCode: 'ach-order-1234',
});

console.log(synced.status); // SUCCEEDED or FAILED after settlement

Returns: MerchantTransaction

---

transactions.authorizations.settle()

Captures funds from a previously authorized transaction. Call this after serverSessions.authorizations.paymentMethod.start() to finalize the charge.

note

Partial capture is supported — pass an amount less than the authorized amount. The remainder of the hold is released.

Parameters

Parameter	Type	Required	Description
amount	bigint	Yes	Amount to capture. Must be ≤ the authorized amount.
id	string	No	AccruPay transaction ID.
merchantInternalTransactionCode	string	No	Your idempotency key from the authorization.
providerCode	string	No	Provider-assigned authorization code.

// Full capture
const captured = await sdk.transactions.authorizations.settle({
  merchantInternalTransactionCode: 'order-5555-auth',
  amount: 10000n, // capture the full $100.00
});

// Partial capture — releases the uncaptured remainder
const partial = await sdk.transactions.authorizations.settle({
  merchantInternalTransactionCode: 'order-5555-auth',
  amount: 7500n, // capture $75.00, release remaining $25.00 hold
});

Returns: MerchantTransaction

---

transactions.authorizations.void()

Releases an authorized hold without capturing any funds.

Parameter	Type	Description
id	string	AccruPay transaction ID.
merchantInternalTransactionCode	string	Your idempotency key from the authorization.
providerCode	string	Provider-assigned authorization code.

const voided = await sdk.transactions.authorizations.void({
  merchantInternalTransactionCode: 'order-5555-auth',
});

Returns: MerchantTransaction

---

Transaction return shape

All transaction methods return a MerchantTransaction object with the following key fields.

Field	Type	Description
id	string	AccruPay transaction ID.
action	TRANSACTION_ACTION	Type of transaction (e.g. PAYMENT, REFUND, AUTHORIZATION, CAPTURE, VOID).
status	TRANSACTION_STATUS	Current status (PENDING, SUCCEEDED, FAILED, CANCELED, DECLINED, EXPIRED, etc.).
providerStatus	string	Raw status string from the payment provider.
providerCode	string	Provider-assigned primary transaction identifier.
providerRelatedCode	string	Provider-assigned related transaction identifier (e.g. parent auth code).
providerAuthorizationCode	string	Authorization code from the provider (for card transactions).
providerError	object | null	Provider error detail when the transaction fails.
amount	bigint	Transaction amount in smallest currency unit.
refundedAmount	bigint	Total refunded so far (sum of all partial/full refunds).
currency	CURRENCY	ISO 4217 currency code.
merchantInternalTransactionCode	string	Your idempotency key.
merchantInternalCustomerCode	string | null	Your customer identifier (deprecated field — prefer customer).
storePaymentMethod	boolean	Whether the payment method was stored during this transaction.
billing*	string	Billing address fields (billingFirstName, billingEmail, etc.).
shipping*	string	Shipping address fields.
user*	string	End-user identity fields.
transactionDate	DateTimeISO	Effective date of the transaction.
startedAt	DateTimeISO | null	When the transaction was initiated.
succeededAt	DateTimeISO | null	When the transaction succeeded.
failedAt	DateTimeISO | null	When the transaction failed.
canceledAt	DateTimeISO | null	When the transaction was canceled.
disputedAt	DateTimeISO | null	When a dispute was opened.
refundedAt	DateTimeISO | null	When the first refund was issued.
voidedAt	DateTimeISO | null	When the transaction was voided.