> For the complete documentation index, see [llms.txt](https://docs.dsyncstudios.store/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.dsyncstudios.store/products/dsync-banking/integrations/bank-card-item-ox_inventory.md).

# Bank Card Item (ox\_inventory)

## Bank Card Item (ox\_inventory)

This integration is only required when `Config.cards.mode = 'item'`. In `'virtual'` mode, skip this page entirely — cards exist only inside the UI.

### Adding the item

Add an entry to your **ox\_inventory** `data/items.lua`. The item name must match `Config.cards.itemName` (default: `bank_card`):

```lua
['bank_card'] = {
    label = 'Bank Card',
    weight = 5,
    stack = false,      -- each card is a unique object with its own metadata
    close = true,
    description = 'A personal bank card',
    client = {
        image = 'bank_card.png',
    },
},
```

`stack = false` is required — every card carries unique metadata (its card number and holder name), so identical stacks would merge that data incorrectly.

### Metadata

When a card is issued or reissued, Dsync-Banking writes metadata onto the item automatically:

```lua
{
  card_number = "5478 4500 1234 5678",
  holder      = "John Doe",
  description = "**Holder:** John Doe  \n**Card:** •••• •••• •••• 5678",
}
```

* `card_number` is the field every possession/authentication check keys on — don't rename it if you're customizing anything downstream.
* `description` is rendered by ox\_inventory's item tooltip (Markdown supported), so hovering the card in-game shows the holder's name and a **masked** card number. The full number and PIN are never exposed in metadata or in any log.

### Runtime behavior

* At an ATM in item mode, the player is prompted to choose which bank card (if they hold more than one) to authenticate with, then enter its PIN.
* Wrong PINs are rate-limited (5 attempts trigger a 60-second lockout).
* A **frozen** card is rejected at the PIN prompt with a clear reason.
* An **expired** card (3-year validity from issue) is rejected the same way.
* With `Config.cards.metadata = false`, only the citizen who owns the card record can authenticate with it — someone else holding the physical item gets a "this card does not belong to you" rejection.
* With `Config.cards.metadata = true`, any holder can authenticate, and a successful login opens the **card owner's** account for that ATM session — the person physically at the machine keeps their own cash, but deposits and withdrawals move the owner's bank balance. If the owner is offline, the session cannot open (their account can't be safely read/debited).

### Icon

Drop a `bank_card.png` into `ox_inventory/web/images/` if you want a custom icon instead of ox\_inventory's default placeholder.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.dsyncstudios.store/products/dsync-banking/integrations/bank-card-item-ox_inventory.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.