> ## Documentation Index
> Fetch the complete documentation index at: https://developers.paychoice.com.au/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokens

> Store a card or bank account once and charge it again later without holding the details.

If you want to keep a customer's card or bank account on file without holding the sensitive details yourself, store them with the token endpoints. PayChoice holds the details and returns a token you use in later charges instead of the raw card or account data.

> [!NOTE]
>
> Tokens expire after their first use unless they are attached to a customer under [Recurring billing](https://developers.paychoice.com.au/billing/payment-methods.md). Attach them if you intend to charge more than once.

If you'd rather not touch card or account details at all, the [Create Token page](https://developers.paychoice.com.au/storing-payment-methods/create-token-page.md) captures them on a PayChoice-hosted form and returns the same token.

## Store a credit card

```bash v5 (JSON) theme={null}
curl https://api-sandbox.paychoice.com.au/api/v5/token \
  -u "$PAYCHOICE_USERNAME:$PAYCHOICE_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "card[name]": "John Citizen",
    "card[number]": "4111111111111111",
    "card[cvv]": "123",
    "card[expiry_month]": "12",
    "card[expiry_year]": "28"
  }'
```

```bash v4 (form-data) theme={null}
curl https://api-sandbox.paychoice.com.au/api/v4/token/ \
  -u "$PAYCHOICE_USERNAME:$PAYCHOICE_PASSWORD" \
  -d "card[name]=John Citizen" -d "card[number]=4111111111111111" \
  -d "card[cvv]=123" -d "card[expiry_month]=12" -d "card[expiry_year]=28"
```

```json theme={null}
{
  "card": {
    "token": "c629ac3b-682b-41e4-9a81-9445960843cf",
    "card_name": "John Citizen",
    "masked_number": "411111XXXXXX1111",
    "expiry_month": "12",
    "expiry_year": "28",
    "card_type": "Visa",
    "key_id": 1,
    "link": { "href": "/api/v5/token/c629ac3b-682b-41e4-9a81-9445960843cf", "rel": "self" }
  },
  "object_type": "card",
  "merchant_guid": "315564b9-b863-4016-8c53-02c9d8cc80b7",
  "from_item": 0,
  "to_item": 0,
  "total_count": 0
}
```

Returns HTTP `200` on v4 and `201 Created` on v5. `merchant_guid` sits at the top level, outside `card`. `card_type` is one of `Visa`, `MasterCard`, `AmericanExpress`, `DinersClub`, `Jcb`, `Discover`, `BankCard` or `Unknown`.

Pass `card.token` as `card_token` on [Create a charge](https://developers.paychoice.com.au/taking-payments/charging-via-the-api.md) in place of the `card[...]` fields.

## Store a bank account

```bash theme={null}
curl https://api-sandbox.paychoice.com.au/api/v5/bank_token \
  -u "$PAYCHOICE_USERNAME:$PAYCHOICE_PASSWORD" \
  -H "Content-Type: application/json" \
  -d '{
    "bank[name]": "John Citizen",
    "bank[bsb]": "123123",
    "bank[number]": "123123123"
  }'
```

```json theme={null}
{
  "bank": {
    "bank_token": "9acf4194-3651-4414-8415-6b8eb74ece6d",
    "name": "John Citizen",
    "bsb": "123123",
    "number": "XXXXX3123",
    "merchantguid": "315564b9-b863-4016-8c53-02c9d8cc80b7",
    "link": { "href": "/api/v5/bank_token/9acf4194-3651-4414-8415-6b8eb74ece6d", "rel": "self" }
  },
  "object_type": "bank"
}
```

`bank[bsb]` is not required for New Zealand accounts; supply the full 15–16 digit account number instead. This response has no paging fields. Pass `bank.bank_token` as `bank_token` on a bank charge.

## Retrieve and remove

| | Card | Bank account |
| - | - | - |
| Retrieve | `GET /token/{token}` | `GET /bank_token/{bank_token}` |
| Remove | `DELETE /token/{token}` | `DELETE /bank_token/{bank_token}` |

Retrieve returns the stored details with any empty fields omitted; on the card endpoint `expiry_month` and `expiry_year` come back as integers. A token that has been removed returns `410 Gone`, which is a reliable way to check whether a token is still usable before charging it.

## Next

* [Payment methods](https://developers.paychoice.com.au/billing/payment-methods.md) — attach a token to a customer so it doesn't expire.
* [Create Token page](https://developers.paychoice.com.au/storing-payment-methods/create-token-page.md) — capture a token without seeing the details.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.