{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"How cards are modeled","siteUrl":"https://docs.peachfinance.com","description":"API and product documentation for Peach Finance, a lending-as-a-service platform.","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"how-cards-are-modeled","__idx":0},"children":["How cards are modeled"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A card ",{"$$mdtype":"Tag","name":"em","attributes":{},"children":["account"]}," on Peach is the line of credit itself. This page is about the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Card objects"]}," that sit on that line of credit — the records that represent the individual cards a borrower carries. One line of credit can hold many cards, and each card can be linked to the purchases, disputes, and events it generates."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page explains how Peach models cards. To create and manage cards through the API, see the ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-docs/api-public/cards"},"children":["Cards API reference"]},". For linking purchases, see ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-docs/api-public/line-of-credit-purchases"},"children":["Line of credit purchases"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"what-youll-learn","__idx":1},"children":["What you'll learn"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["How Peach models cards as first-class objects, with many cards per line of credit"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["What ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isExternal"]}," controls and why a card is external by default"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["What the card ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," field is and who sets it"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["How ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," links a purchase or dispute to a specific card, and what happens when it can't be resolved"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["How to query purchases and disputes by card with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardIds[]"]}," filter"]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"key-concepts","__idx":2},"children":["Key concepts"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Card object"]}," — A record representing a single card on a line of credit. Public id prefix ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CD-"]},". "]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isExternal"]}]}," — Whether Peach interacts with the card directly. Defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," (external): Peach does not interact with the card directly. "]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}]}," — The lender-owned card status. "]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}]}," — A validated link from a purchase or dispute to a Card object. "]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardIds[]"]}]}," — A query filter that returns only purchases or disputes linked to the given cards. "]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"terminology-used-on-this-page","__idx":3},"children":["Terminology used on this page"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This page is decoupled from the Credit Cards guide, so it carries the few terms it needs inline. Peach's object names do not always match the industry terms a card program manager uses."]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"Term"},"children":["Term"]},{"$$mdtype":"Tag","name":"th","attributes":{"align":"left","data-label":"What it means on this page"},"children":["What it means on this page"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Purchase"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["A card swipe — a charge posted to a draw."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Transaction"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["A payment against the account. Distinct from a purchase."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Draw"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["A subline of the line of credit."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Open to buy"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Available credit — the amount the borrower can still spend."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Card issuer (API object) (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VC-"]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["The API object for the processor relationship. Not the Card object."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["Card object (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CD-"]},")"]},{"$$mdtype":"Tag","name":"td","attributes":{"align":"left"},"children":["A record for an individual card on the line of credit. The subject of this page."]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"the-card-object","__idx":4},"children":["The Card object"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A Card object holds a foreign key to a line of credit, and that key carries no uniqueness constraint — so a single line of credit can hold any number of cards. The line's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cards"]}," collection is ordered by card id."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Each card has its own public id with the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CD-"]}," prefix."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is the multi-cardholder pattern the feature is built for: a business owner holds one line of credit and issues cards to employees, each card a Card object on the same account. Because every card can be virtual and physical, and cards are reissued over time, one line of credit can accumulate many Card objects — on the order of dozens of cardholders and several hundred card ids over a program's life."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"cards-are-external-by-default","__idx":5},"children":["Cards are external by default"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A card carries an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isExternal"]}," boolean that defaults to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]},". It controls whether Peach interacts with the card directly."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["true"]}," (the default)"]}," — Peach does not interact with the card directly. The object exists for visualization and filtering — for example, to bucket purchases by card on a statement."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]}]}," — Peach sends events to, and receives events from, the card object in another system. The lender supplies the issuer id and the issuer-specific card token or identifier (for example, a Lithic card token); Peach requires both when ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isExternal"]}," is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["false"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"card-status","__idx":6},"children":["Card status"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A card carries a lender-owned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["active"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["inactive"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["blocked"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["closed"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expired"]},", defaulting to ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["active"]},". You set it and keep it current — Peach never changes it from an issuer webhook. In code it is the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CardExternalStatus"]}," enum, surfaced through the serializer's ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["external_status"]}," attribute."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"A note on card payloads"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A card payload also contains a separate, pre-existing internal field nested under ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardDetails"]},". The field you set and read for a card's lender-facing status is the top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]}," described here."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"linking-a-purchase-to-a-card-with-cardid","__idx":7},"children":["Linking a purchase to a card with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A purchase can carry a top-level ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," that links it to a Card object. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," accepts a Peach id, a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CD-"]}," public id, or an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ext-"]}," lender external id; Peach resolves whichever form you send. The card must belong to the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["same line of credit"]}," as the purchase — if it belongs to a different line of credit, it does not resolve."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," cannot be resolved to a card on this line of credit, the request ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["does not fail"]},". Instead:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Peach returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validation.cardIdMissing: true"]}," in the response."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The link is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["not"]}," stored — the purchase keeps no ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card_id"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The rest of the purchase is created or updated normally."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["This is a soft warning, not an error. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validation"]}," block is a sibling of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}," at the top level of the response, and it is present only when a miss occurred. Sending ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId: null"]}," explicitly clears the link."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In responses, a resolved ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," is always returned as the Peach ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CD-"]}," public id, or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," when no card is linked."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," is a new linkage; the existing ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchaseDetails.externalCardId"]}," is unchanged and still fully supported. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCardId"]}," is a free-form string in a separate column from the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," foreign key. The two are independent: both can be set on the same purchase, neither overrides the other, and there is no precedence logic between them."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"querying-purchases-and-disputes-by-card","__idx":8},"children":["Querying purchases and disputes by card"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardIds[]"]}," query filter returns only the purchases or disputes linked to the cards you name. It is available on the four purchase list and timeline endpoints and on the two dispute list endpoints. Each value is a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CD-"]}," public id or an ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ext-"]}," external id."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To get a per-cardholder view, pass that cardholder's card ids. To get the account-wide view of every purchase on the line of credit, omit the parameter."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Two ways the cardIds filter surprises you"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["An unresolvable filter returns nothing, not everything."]}," Omitting ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardIds"]}," applies no filter and returns all purchases. But sending ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardIds"]}," with values that resolve to no cards returns an ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["empty"]}," result set — not all purchases. Internally the filter becomes ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card_id IN ()"]},", which matches nothing; the dispute endpoints short-circuit to an empty query the same way."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["The filter only matches cards linked through ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]},"."]}," It matches purchases whose ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card_id"]}," foreign key is set. A purchase booked with only ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCardId"]},", or booked before ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," was adopted, has a null ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["card_id"]}," and ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["will not appear"]}," in a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardIds[]"]}," result — a real caveat when you use this filter to bucket a statement by cardholder."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["On disputes, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," appears on the ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["response"]}," only. It is read-only and mirrors the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," of the disputed purchase. Dispute create and update requests do not accept ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," in the body — a dispute's card is always inherited from its purchase, never set on the dispute directly."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"cardid-on-events","__idx":9},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," on events"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The linked card travels with the purchase onto its event payloads. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," was added to these seven public purchase event payloads:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchase.created"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchase.changed"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchase.authorized"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchase.settled"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchase.applied"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchase.dispute.created"]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchase.dispute.updated"]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["When no card is linked to the purchase, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," is ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["omitted entirely"]}," from the event payload — it is not sent as ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"in-practice","__idx":10},"children":["In practice"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A landscaping company holds one line of credit. The owner issues cards to five employees, and each employee carries one virtual and one physical card — so the single line of credit already holds ten Card objects, each with its own ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CD-"]}," public id. Lost-card reissues add more over time."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["To track spending per employee, the lender records each purchase against the employee's card. When a $48.20 fuel charge posts for the employee Maria Alvarez, the lender sends ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId: \"CD-7F3A-22B1\""]}," on the purchase. Peach confirms that card belongs to this line of credit and stores the link. The same ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," then rides along on the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchase.created"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchase.authorized"]},", and ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchase.settled"]}," events."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For Maria's statement view, the lender lists purchases with ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardIds[]"]}," set to her two card ids. The result is only Maria's purchases."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["For the owner's account-wide view, the lender omits ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardIds"]},". Every purchase on the line of credit is returned."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the lender ever sends a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," that belongs to a different account, Peach returns ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["validation.cardIdMissing: true"]},", stores no link, and still records the purchase — so a mis-typed id never drops the charge."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"why-it-works-this-way","__idx":11},"children":["Why it works this way"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Modeling each card as its own object — many per line of credit, external by default — lets one account carry an arbitrary number of cardholders while Peach's role stays limited to recording and reporting. The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CD-"]}," Card object exists so a lender can attribute purchases, disputes, and events to a specific card without Peach issuing or processing that card. ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," makes that attribution a validated link to a real card on the same line of credit, while ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalCardId"]}," remains for lenders that only need to record a free-form identifier. The result is one statement and one credit limit per account, with a per-card view available on demand."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"related-api-references","__idx":12},"children":["Related API references"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The operations that implement everything on this page:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-docs/api-public/cards"},"children":["Cards"]}," — Create and manage Card objects: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["isExternal"]},", the lender-owned ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status"]},", and Get cards (status filter and pagination)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-docs/api-public/line-of-credit-purchases"},"children":["Line of credit purchases"]}," — The ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," field on purchase create and update, and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardIds"]}," list filter. Purchase disputes are documented in this area."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-docs/api-public/card-issuers"},"children":["Card issuers"]}," — The card issuer object (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["VC-"]},") representing the processor relationship."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-docs/api-public/section/events"},"children":["Events"]}," and ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/api-docs/api-public/section/identifiers"},"children":["Identifiers"]}," — How ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," appears on purchase events, and the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CD-"]}," / ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ext-"]}," id forms ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cardId"]}," accepts."]}]}]},"headings":[{"value":"How cards are modeled","id":"how-cards-are-modeled","depth":1},{"value":"What you'll learn","id":"what-youll-learn","depth":2},{"value":"Key concepts","id":"key-concepts","depth":2},{"value":"Terminology used on this page","id":"terminology-used-on-this-page","depth":3},{"value":"The Card object","id":"the-card-object","depth":2},{"value":"Cards are external by default","id":"cards-are-external-by-default","depth":2},{"value":"Card status","id":"card-status","depth":2},{"value":"Linking a purchase to a card with cardId","id":"linking-a-purchase-to-a-card-with-cardid","depth":2},{"value":"Querying purchases and disputes by card","id":"querying-purchases-and-disputes-by-card","depth":2},{"value":"cardId on events","id":"cardid-on-events","depth":2},{"value":"In practice","id":"in-practice","depth":2},{"value":"Why it works this way","id":"why-it-works-this-way","depth":2},{"value":"Related API references","id":"related-api-references","depth":2}],"frontmatter":{"title":"How cards are modeled","description":"How Peach models card objects on a line of credit: many cards per account, external by default, with cardId linking purchases, disputes, and events.","slug":"/credit-cards/how-cards-are-modeled","verifiedDate":"2026-06-22","verifiedRef":"peach@e2d63021c","verifiedSpec":"epic 73282, stories SC-73284 through SC-73293 + SC-73349","seo":{"title":"How cards are modeled"}},"lastModified":"2026-06-22T20:42:49.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/credit-cards/how-cards-are-modeled","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}