Skip to main content

InvoicePayment — new field cardDetails (PaymentCardDetails)

Summary​

The GraphQL type InvoicePayment (returned under Invoice.payments) now exposes a read-only field cardDetails of type PaymentCardDetails, with:

  • lastFourDigits — the last four digits of the card used (String).
  • cardType — the card brand/type, e.g. visa, mastercard (String).
  • expiryDate — the card expiry date in MM/YY format (String).

This lets finance integrations reconcile card transactions with the specific card used, rather than relying on the coarse paymentSource (e.g. CREDIT_CARD, DEBIT_CARD) alone.

This release is additive: existing invoice and invoices calls behave as before. If you do not request cardDetails, behaviour and performance are unchanged.

Population rules:

  • cardDetails is null for non-card payments (e.g. cash, bank transfer).
  • For card payments captured after this release, all three sub-fields are populated where Stripe provides them.
  • For card payments taken before this release, lastFourDigits and cardType are derived from stored payment metadata where available, and expiryDate is null (the expiry was not stored historically).

Query example​

query InvoiceCardDetails($id: ID!) {
  invoice(id: $id) {
    id
    payments {
      id
      paymentSource
      paymentAmount
      paymentDate
      cardDetails {
        lastFourDigits
        cardType
        expiryDate
      }
    }
  }
}

The invoices connection supports the same nested selection on each item in data.

Integration guidance​

  • Optional field: Add cardDetails { ... } only when your integration needs card-level reconciliation; omit it otherwise.
  • Handle nulls: Expect cardDetails to be null for non-card payments, and expiryDate to be null on older card payments.
  • Format: expiryDate is a MM/YY string (e.g. 08/27), not a date.

If something breaks after this change​

Problems are unlikely unless you use strict schema validation that rejects unknown fields on InvoicePayment. Refresh your schema snapshot, regenerate clients, and extend your InvoicePayment types to include optional cardDetails.

See also​