Payment Methods

Stored payment methods are saved payment credentials created through a previous payment or add-payment-method session. Once stored, they can be charged directly from your backend without requiring the customer to re-enter their payment details.

All operations on this page require the accrupay-api-secret header and must be called from your backend.

---

Payment method fields

The following fields are available on the MerchantCustomerPaymentMethod type.

Field	Type	Description
id	ID!	AccruPay payment method ID
customerId	String	AccruPay customer ID that owns this payment method
initialTransactionId	String	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	Expiration date (for cards)
status	PAYMENT_METHOD_STATUS!	Current status (ENABLED, DISABLED, EXPIRED)
merchantInternalCustomerCode	String	Your own reference for the owning customer
methodType	PAYMENT_METHOD!	Type of payment instrument (CARD, ACH, OTHER)
providerCode	String!	Provider-assigned reference for this payment method
providerCustomerCode	String	Provider-assigned customer reference associated with this method
providerError	String	Provider error detail from the last sync attempt
providerLastSyncedAt	DateTimeISO	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
billingFirstName	String	Billing contact first name
billingLastName	String	Billing contact last name
billingEmail	String	Billing email
billingPhone	String	Billing phone
billingAddressLine1	String	Billing address line 1
billingAddressLine2	String	Billing address line 2
billingAddressCity	String	Billing address city
billingAddressState	String	Billing address state
billingAddressCountry	COUNTRY_ISO_2	Billing address country (ISO 3166-1 alpha-2)
billingAddressPostalCode	String	Billing address postal code
createdAt	DateTimeISO!	When the payment method was stored
updatedAt	DateTimeISO!	When the record was last updated
paymentMethodInfo	MerchantCustomerPaymentMethodInfo	Payment-method-type-specific details (see union below)

---

paymentMethodInfo union

The paymentMethodInfo field returns the MerchantCustomerPaymentMethodInfo union. Query with inline fragments to get type-specific fields.

fragment PaymentMethodInfoFields on MerchantCustomerPaymentMethod {
  paymentMethodInfo {
    ... on MerchantCustomerPaymentMethodCreditCardInfo {
      methodType
      cardBrand
      cardNumberMasked
      expirationMonth
      expirationYear
    }
    ... on MerchantCustomerPaymentMethodAchInfo {
      methodType
      accountNumber
      bankName
      routingNumber
      secCode
      entityType
    }
    ... on MerchantCustomerPaymentMethodGenericInfo {
      methodType
    }
  }
}

MerchantCustomerPaymentMethodCreditCardInfo fields

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

MerchantCustomerPaymentMethodAchInfo fields

Field	Type	Description
methodType	PAYMENT_METHOD!	Always ACH
accountNumber	String	Bank account number (may be masked)
bankName	String	Name of the bank
routingNumber	String	Bank routing (ABA) number
secCode	TRANSACTION_ACH_SECCODE	NACHA Standard Entry Class code (CCD, WEB, TEL, UNKNOWN)
entityType	ENTITY_TYPE	Account holder entity type (COMPANY, INDIVIDUAL)

MerchantCustomerPaymentMethodGenericInfo fields

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.

---

merchantApiCustomerPaymentMethods — list payment methods

Returns a paginated list of stored payment methods for your merchant account.

Query

query ListPaymentMethods(
  $take: Int
  $skip: Int
  $after: ConnectionCursor
  $first: Int
  $customerId: String
  $merchantInternalCustomerCode: String
  $methodType: PAYMENT_METHOD
  $isDefault: Boolean
  $hasProviderError: Boolean
) {
  merchantApiCustomerPaymentMethods(
    take: $take
    skip: $skip
    after: $after
    first: $first
    customerId: $customerId
    merchantInternalCustomerCode: $merchantInternalCustomerCode
    methodType: $methodType
    isDefault: $isDefault
    hasProviderError: $hasProviderError
  ) {
    edges {
      node {
        id
        customerId
        merchantInternalCustomerCode
        methodType
        isEnabled
        isDefault
        status
        providerCode
        createdAt
        paymentMethodInfo {
          ... on MerchantCustomerPaymentMethodCreditCardInfo {
            methodType
            cardBrand
            cardNumberMasked
            expirationMonth
            expirationYear
          }
          ... on MerchantCustomerPaymentMethodAchInfo {
            methodType
            accountNumber
            bankName
            routingNumber
          }
          ... on MerchantCustomerPaymentMethodGenericInfo {
            methodType
          }
        }
      }
      cursor
    }
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
    totalCount
  }
}

curl example

curl -X POST https://api.pay.accru.co/graphql \
  -H "Content-Type: application/json" \
  -H "accrupay-api-secret: YOUR_SECRET" \
  -d '{
    "query": "query ListPaymentMethods($merchantInternalCustomerCode: String, $isDefault: Boolean) { merchantApiCustomerPaymentMethods(merchantInternalCustomerCode: $merchantInternalCustomerCode, isDefault: $isDefault) { edges { node { id methodType isEnabled isDefault paymentMethodInfo { ... on MerchantCustomerPaymentMethodCreditCardInfo { methodType cardBrand cardNumberMasked expirationMonth expirationYear } } } } totalCount } }",
    "variables": { "merchantInternalCustomerCode": "customer-456", "isDefault": true }
  }'

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 payment method type (CARD, ACH, OTHER)
initialTransactionId	String	Filter by the transaction that created this payment method
customerId	String	Filter by AccruPay customer ID
merchantInternalCustomerCode	String	Filter by your own customer reference code
isDefault	Boolean	Filter for default payment methods
hasProviderError	Boolean	Filter for methods with or without provider sync errors
skip	Int	Offset for offset pagination
take	Int	Page size for offset pagination
after	ConnectionCursor	Cursor for forward pagination
first	Int	Page size for cursor pagination (forward)
before	ConnectionCursor	Cursor for backward pagination
last	Int	Page size for cursor pagination (backward)
sorting	[SortingFieldSchema!]	Sort configuration

tip

Filter by isDefault: true to fetch a customer's default payment method, or use hasProviderError: true to surface methods that failed their last provider sync.

---

merchantApiCustomerPaymentMethod — get one payment method

Fetch a single stored payment method by its ID.

Query

query GetPaymentMethod($merchantCustomerPaymentMethodId: String!) {
  merchantApiCustomerPaymentMethod(
    merchantCustomerPaymentMethodId: $merchantCustomerPaymentMethodId
  ) {
    id
    customerId
    merchantInternalCustomerCode
    methodType
    isEnabled
    isDefault
    status
    providerCode
    providerStatus
    providerLastVerifiedAt
    expiresAt
    createdAt
    updatedAt
    paymentMethodInfo {
      ... on MerchantCustomerPaymentMethodCreditCardInfo {
        methodType
        cardBrand
        cardNumberMasked
        expirationMonth
        expirationYear
      }
      ... on MerchantCustomerPaymentMethodAchInfo {
        methodType
        accountNumber
        bankName
        routingNumber
        secCode
        entityType
      }
      ... on MerchantCustomerPaymentMethodGenericInfo {
        methodType
      }
    }
  }
}

Parameters

Parameter	Type	Required	Description
merchantCustomerPaymentMethodId	String!	Yes	AccruPay payment method ID

note

merchantCustomerPaymentMethodId is the query argument, not a field on the MerchantCustomerPaymentMethod type — the returned object exposes the ID as id. Payment methods have only this one lookup identifier; use merchantApiCustomerPaymentMethods with a filter if you need to look up by customer code.

---

merchantApiCustomerPaymentMethodSyncOne — sync a payment method

Fetches the latest state of a stored payment method from the provider and updates AccruPay's record. Use this when you suspect the local state is stale.

Mutation

mutation SyncPaymentMethod(
  $merchantTransactionProviderId: String!
  $providerCode: String!
  $customer: MerchantCustomerSelector
) {
  merchantApiCustomerPaymentMethodSyncOne(
    merchantTransactionProviderId: $merchantTransactionProviderId
    providerCode: $providerCode
    customer: $customer
  ) {
    id
    methodType
    isEnabled
    status
    providerStatus
    providerLastSyncedAt
    providerError
    updatedAt
    paymentMethodInfo {
      ... on MerchantCustomerPaymentMethodCreditCardInfo {
        methodType
        cardBrand
        cardNumberMasked
        expirationMonth
        expirationYear
      }
      ... on MerchantCustomerPaymentMethodAchInfo {
        methodType
        accountNumber
        bankName
      }
      ... on MerchantCustomerPaymentMethodGenericInfo {
        methodType
      }
    }
  }
}

curl example

curl -X POST https://api.pay.accru.co/graphql \
  -H "Content-Type: application/json" \
  -H "accrupay-api-secret: YOUR_SECRET" \
  -d '{
    "query": "mutation SyncPaymentMethod($merchantTransactionProviderId: String!, $providerCode: String!, $customer: MerchantCustomerSelector) { merchantApiCustomerPaymentMethodSyncOne(merchantTransactionProviderId: $merchantTransactionProviderId, providerCode: $providerCode, customer: $customer) { id isEnabled status providerLastSyncedAt updatedAt } }",
    "variables": {
      "merchantTransactionProviderId": "provider-config-id",
      "providerCode": "pm_provider_ref_123",
      "customer": { "merchantInternalCustomerCode": "customer-456" }
    }
  }'

Parameters

Parameter	Type	Required	Description
merchantTransactionProviderId	String!	Yes	ID of the merchant-provider configuration to sync against
providerCode	String!	Yes	Provider-assigned reference for this payment method
customer	MerchantCustomerSelector	No	Customer selector to scope the lookup
merchantInternalCustomerCode	String	No	Deprecated — use customer selector instead.

MerchantCustomerSelector fields

Field	Type	Required	Description
id	String	No	AccruPay customer ID
merchantInternalCustomerCode	String!	Yes	Your own customer reference code
providerCode	String	No	Customer code on the transaction provider
resolutionStrategy	CUSTOMER_RESOLUTION_STRATEGY	No	How to resolve the customer from the provided identifiers

danger

Syncing a payment method will overwrite its local state with whatever the provider returns. If the provider marks the method as invalid or expired, isEnabled will be set to false and status will reflect the provider state after sync.

---

merchantApiCustomerPaymentMethodSyncAll — bulk-sync payment methods

Pull and reconcile all of a customer's payment methods from the provider in one call. Use this for bulk reconciliation rather than calling syncOne per method.

mutation SyncAllPaymentMethods(
  $merchantTransactionProviderId: String!
  $customer: MerchantCustomerSelector
) {
  merchantApiCustomerPaymentMethodSyncAll(
    merchantTransactionProviderId: $merchantTransactionProviderId
    customer: $customer
  ) {
    id
    methodType
    isEnabled
    status
    providerCode
  }
}

Arguments

Argument	Type	Required	Description
merchantTransactionProviderId	String	Yes	Provider to sync against
customer	MerchantCustomerSelector	No	Scope the sync to a single customer. When provided, merchantInternalCustomerCode is required within it.
merchantInternalCustomerCode	String	No	Deprecated. Use the customer selector instead.

Returns: a plain array [MerchantCustomerPaymentMethod!]! (not a pagination connection).

note

There is no Node SDK wrapper for SyncAll — call it as raw GraphQL. The SDK exposes only paymentMethods.syncOne.