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 CustomerPaymentMethod type.

Field	Type	Description
id	String!	AccruPay payment method ID
merchantCustomerPaymentMethodId	String!	Same as id — the canonical identifier for this payment method
providerCode	String	Provider-assigned reference for this payment method
customerId	String!	AccruPay customer ID that owns this payment method
merchantInternalCustomerCode	String	Your own reference for the owning customer
paymentMethod	PAYMENT_METHOD!	Type of payment instrument (CARD, ACH, OTHER)
isActive	Boolean!	Whether this payment method can be charged
createdAt	DateTimeISO!	When the payment method was stored
updatedAt	DateTimeISO!	When the record was last updated
paymentMethodInfo	PaymentMethodInfo	Payment-method-type-specific details (see union below)

---

paymentMethodInfo union

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

fragment PaymentMethodInfoFields on CustomerPaymentMethod {
  paymentMethodInfo {
    ... on CardPaymentMethodInfo {
      cardBrand
      cardLast4
      cardExpMonth
      cardExpYear
      cardHolderName
    }
    ... on AchPaymentMethodInfo {
      achAccountLast4
      achRoutingNumber
      achAccountType
      achBankName
      achSecCode
    }
    ... on OtherPaymentMethodInfo {
      description
    }
  }
}

CardPaymentMethodInfo fields

Field	Type	Description
cardBrand	String	Card network (e.g. "Visa", "Mastercard", "Amex")
cardLast4	String	Last four digits of the card number
cardExpMonth	Int	Expiration month (1–12)
cardExpYear	Int	Expiration year (4-digit)
cardHolderName	String	Name on the card

AchPaymentMethodInfo fields

Field	Type	Description
achAccountLast4	String	Last four digits of the bank account number
achRoutingNumber	String	Bank routing number
achAccountType	String	Account type (e.g. "checking", "savings")
achBankName	String	Name of the bank
achSecCode	TRANSACTION_ACH_SECCODE	ACH Standard Entry Class code

OtherPaymentMethodInfo fields

Field	Type	Description
description	String	Human-readable description of the payment method

---

merchantApiCustomerPaymentMethods — list payment methods

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

Query

query ListPaymentMethods(
  $take: Int
  $skip: Int
  $after: String
  $first: Int
  $customerId: String
  $merchantInternalCustomerCode: String
  $paymentMethod: PAYMENT_METHOD
  $isActive: Boolean
) {
  merchantApiCustomerPaymentMethods(
    take: $take
    skip: $skip
    after: $after
    first: $first
    customerId: $customerId
    merchantInternalCustomerCode: $merchantInternalCustomerCode
    paymentMethod: $paymentMethod
    isActive: $isActive
  ) {
    edges {
      node {
        id
        merchantCustomerPaymentMethodId
        providerCode
        customerId
        merchantInternalCustomerCode
        paymentMethod
        isActive
        createdAt
        paymentMethodInfo {
          ... on CardPaymentMethodInfo {
            cardBrand
            cardLast4
            cardExpMonth
            cardExpYear
          }
          ... on AchPaymentMethodInfo {
            achAccountLast4
            achBankName
            achAccountType
          }
          ... on OtherPaymentMethodInfo {
            description
          }
        }
      }
      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, $isActive: Boolean) { merchantApiCustomerPaymentMethods(merchantInternalCustomerCode: $merchantInternalCustomerCode, isActive: $isActive) { edges { node { id paymentMethod isActive paymentMethodInfo { ... on CardPaymentMethodInfo { cardBrand cardLast4 cardExpMonth cardExpYear } } } } totalCount } }",
    "variables": { "merchantInternalCustomerCode": "customer-456", "isActive": true }
  }'

Filter parameters

Parameter	Type	Description
take	Int	Page size for offset pagination
skip	Int	Offset for offset pagination
first	Int	Page size for cursor pagination (forward)
after	String	Cursor for forward pagination
customerId	String	Filter by AccruPay customer ID
merchantInternalCustomerCode	String	Filter by your own customer reference code
paymentMethod	PAYMENT_METHOD	Filter by payment method type (CARD, ACH, OTHER)
isActive	Boolean	Filter to only active (chargeable) methods

tip

Always filter by isActive: true when presenting saved payment methods to a customer. Inactive methods cannot be charged.

---

merchantApiCustomerPaymentMethod — get one payment method

Fetch a single stored payment method by its ID.

Query

query GetPaymentMethod($merchantCustomerPaymentMethodId: String!) {
  merchantApiCustomerPaymentMethod(
    merchantCustomerPaymentMethodId: $merchantCustomerPaymentMethodId
  ) {
    id
    merchantCustomerPaymentMethodId
    providerCode
    customerId
    merchantInternalCustomerCode
    paymentMethod
    isActive
    createdAt
    updatedAt
    paymentMethodInfo {
      ... on CardPaymentMethodInfo {
        cardBrand
        cardLast4
        cardExpMonth
        cardExpYear
        cardHolderName
      }
      ... on AchPaymentMethodInfo {
        achAccountLast4
        achRoutingNumber
        achAccountType
        achBankName
        achSecCode
      }
      ... on OtherPaymentMethodInfo {
        description
      }
    }
  }
}

Parameters

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

note

Unlike transactions, payment methods have only one lookup identifier: merchantCustomerPaymentMethodId. 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
    merchantCustomerPaymentMethodId
    providerCode
    paymentMethod
    isActive
    updatedAt
    paymentMethodInfo {
      ... on CardPaymentMethodInfo {
        cardBrand
        cardLast4
        cardExpMonth
        cardExpYear
      }
      ... on AchPaymentMethodInfo {
        achAccountLast4
        achBankName
      }
      ... on OtherPaymentMethodInfo {
        description
      }
    }
  }
}

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 isActive 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

MerchantCustomerSelector fields

Field	Type	Description
customerId	String	AccruPay customer ID
merchantInternalCustomerCode	String	Your own customer reference code

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, isActive will be set to false after sync.