Payment Methods

Payment methods represent stored cards or bank accounts for a customer. They are created during checkout (when storePaymentMethod: true) or via add-payment-method sessions.

note

getOne() only accepts merchantCustomerPaymentMethodId. Unlike transaction queries, there are no alternative identifiers (no providerCode, no internal code shorthand).

---

paymentMethods.getMany()

Returns a paginated list of stored payment methods matching the provided filters.

Filter parameters

Parameter	Type	Description
id	string	Filter by AccruPay payment method ID.
transactionProvider	TRANSACTION_PROVIDER	Filter by provider enum.
transactionProviderId	string	Filter by provider configuration ID.
providerCode	string	Filter by provider-assigned payment method code.
methodType	PAYMENT_METHOD	Filter by method type (e.g. PAYMENT_METHOD.CARD, PAYMENT_METHOD.ACH).
initialTransactionId	string	Filter by the transaction that created this payment method.
customerId	string	Filter by AccruPay customer ID.
merchantInternalCustomerCode	string	Filter by your customer identifier.
isDefault	boolean	Filter for default payment methods.
hasProviderError	boolean	Filter for methods with or without provider sync errors.
skip	number	Offset pagination: number of records to skip.
take	number	Offset pagination: number of records to return.
after	string	Cursor pagination: return records after this cursor.
first	number	Cursor pagination: number of records after cursor.
before	string	Cursor pagination: return records before this cursor.
last	number	Cursor pagination: number of records before cursor.
sorting	object	Sort configuration object.

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

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

const { items } = await sdk.paymentMethods.getMany({
  merchantInternalCustomerCode: 'customer-abc',
  methodType: PAYMENT_METHOD.CARD,
  isDefault: true,
  take: 10,
});

---

paymentMethods.getOne()

Returns a single payment method by its AccruPay ID.

note

getOne() only accepts merchantCustomerPaymentMethodId. There is no option to look up by providerCode or any other identifier — unlike transactions.getOne() which accepts multiple options.

Parameter	Type	Required	Description
merchantCustomerPaymentMethodId	string (CUID)	Yes	AccruPay payment method ID.

const method = await sdk.paymentMethods.getOne({
  merchantCustomerPaymentMethodId: 'cm1abc123def456ghi789jkl',
});

console.log(method.methodType, method.status);

Returns: MerchantCustomerPaymentMethod

---

paymentMethods.syncOne()

Pulls the latest state from the provider and updates the payment method record. All three parameters are required.

Parameter	Type	Required	Description
merchantTransactionProviderId	string	Yes	Provider configuration ID (routes the sync request to the correct provider).
providerCode	string	Yes	Provider-assigned payment method identifier.
customer	MerchantCustomerSelector	No	Customer selector, e.g. { merchantInternalCustomerCode: 'customer-abc' }.

const synced = await sdk.paymentMethods.syncOne({
  merchantTransactionProviderId: process.env.ACCRUPAY_PROVIDER_ID!,
  providerCode: 'provider-pm-code-xyz',
  customer: {
    merchantInternalCustomerCode: 'customer-abc',
  },
});

console.log(synced.status, synced.providerLastSyncedAt);

Returns: MerchantCustomerPaymentMethod

---

Payment method return shape

All payment method methods return a MerchantCustomerPaymentMethod object.

Core fields

Field	Type	Description
id	string	AccruPay payment method ID.
customerId	string | null	AccruPay customer ID this method belongs to.
initialTransactionId	string | null	ID of the transaction that created this payment method.
isDefault	boolean	Whether this is the customer's default payment method.
isEnabled	boolean	Whether this payment method is active and chargeable.
expiresAt	DateTimeISO | null	Expiration date (for cards).
status	PAYMENT_METHOD_STATUS	Current status (ENABLED, DISABLED, EXPIRED).
merchantInternalCustomerCode	string | null	Your customer identifier.
methodType	PAYMENT_METHOD	Type of payment method (CARD, ACH, OTHER).
providerCode	string	Provider-assigned payment method identifier.
providerCustomerCode	string | null	Provider-assigned customer identifier associated with this method.
providerError	string | null	Provider error detail from the last sync attempt.
providerLastSyncedAt	DateTimeISO | null	When the payment method was last synced with the provider.
providerLastVerifiedAt	DateTimeISO	When the payment method was last verified as chargeable.
providerStatus	PAYMENT_METHOD_STATUS	Status reported by the provider (ENABLED, DISABLED, EXPIRED).
transactionProviderId	string	Provider configuration ID associated with this method.
billing*	string	Billing address fields stored with this payment method.
createdAt	DateTimeISO	When the payment method was created.
updatedAt	DateTimeISO	When the payment method was last updated.

paymentMethodInfo union

The paymentMethodInfo field contains method-specific details. Its shape depends on methodType.

Credit card — MerchantCustomerPaymentMethodCreditCardInfo

Field	Type	Description
methodType	PAYMENT_METHOD	Always PAYMENT_METHOD.CARD.
cardBrand	string | null	Card network (e.g. Visa, Mastercard, Amex).
cardNumberMasked	string | null	Masked card number (e.g. ************4242).
expirationMonth	number | null	Expiration month (1–12).
expirationYear	number | null	Four-digit expiration year.

ACH — MerchantCustomerPaymentMethodAchInfo

Field	Type	Description
methodType	PAYMENT_METHOD	Always PAYMENT_METHOD.ACH.
accountNumber	string | null	Bank account number (may be masked).
bankName	string | null	Bank name, if resolved by the provider.
routingNumber	string | null	Bank routing (ABA) number.
secCode	TRANSACTION_ACH_SECCODE | null	NACHA Standard Entry Class code (CCD, WEB, TEL, UNKNOWN).
entityType	ENTITY_TYPE | null	Account holder entity type (COMPANY, INDIVIDUAL).

Generic — MerchantCustomerPaymentMethodGenericInfo

Field	Type	Description
methodType	PAYMENT_METHOD	The specific method type for this generic entry.

Used for provider-specific payment methods that don't map to card or ACH (e.g. digital wallets, provider-native methods).

Discriminating the union

The union is discriminated by __typename. Each member also carries a methodType, which maps MerchantCustomerPaymentMethodCreditCardInfo → PAYMENT_METHOD.CARD, MerchantCustomerPaymentMethodAchInfo → PAYMENT_METHOD.ACH, and MerchantCustomerPaymentMethodGenericInfo → PAYMENT_METHOD.OTHER.

const method = await sdk.paymentMethods.getOne({
  merchantCustomerPaymentMethodId: 'cm1abc123def456ghi789jkl',
});

const info = method.paymentMethodInfo;

switch (info?.__typename) {
  case 'MerchantCustomerPaymentMethodCreditCardInfo':
    // info.methodType === PAYMENT_METHOD.CARD
    console.log(info.cardBrand, info.cardNumberMasked);
    console.log(`Expires: ${info.expirationMonth}/${info.expirationYear}`);
    break;
  case 'MerchantCustomerPaymentMethodAchInfo':
    // info.methodType === PAYMENT_METHOD.ACH
    console.log(info.accountNumber, info.routingNumber, info.bankName);
    break;
  case 'MerchantCustomerPaymentMethodGenericInfo':
    // info.methodType === PAYMENT_METHOD.OTHER
    console.log(info.methodType);
    break;
}