## Tokenize a card number

This endpoint securely converts sensitive card details into a token that can be safely
stored and used for future payments. The token can be used with the
`select-payment-method` endpoint to process card payments.

The tokenization process helps you maintain PCI compliance by avoiding the need to
handle raw card data directly in your systems. The token can only be used with your
merchant account and cannot be used to process payments elsewhere.

For security reasons, tokens are single-use by default. If you need to charge the same
card multiple times (like for subscriptions), set usage to `MULTIPLE` when creating the
token.

## Endpoint signature

```http
POST https://api.reservepay.com/sdk/tokenize-card HTTP/1.1
Content-Type: application/json
Accept: application/json

{
  merchant_id: string,
  installation_id: string,
  number: string,
  name: string,
  expiration_date: string,
  security_code: string,
  usage: string?,
  payment_method: string?,
  street_address_1: string?,
  street_address_2: string?,
  postal_code: string?,
  city: string?,
  state: string?,
  country: string?,
}
```

Returns: string

## Request arguments

### `merchant_id` (string)

**Required**. Your merchant ID that uniquely identifies your account.

### `installation_id` (string)

**Required**. The installation ID for this platform (e.g. your iOS app, Android app, website, or terminal).

### `number` (string)

**Required**. The card number (PAN) without any spaces or special characters.

### `name` (string)

**Required**. The cardholder's name exactly as it appears on the card.

### `expiration_date` (string)

**Required**. The card's expiration date in MM/YY format (e.g. 12/25).

### `security_code` (string)

**Required**. The card's security code (CVV/CVC). This is typically a 3-digit number on the back of the card, or 4 digits on the front for American Express.

### `usage` (string)

_Optional_. Controls how many times this card token can be used for payments:

- `SINGLE` (default): The token can only be used once and will be invalidated after
  the first payment attempt
- `MULTIPLE`: The token can be used multiple times, suitable for recurring payments
  or subscriptions

Allowed values:

- `SINGLE`
- `MULTIPLE`

### `payment_method` (string)

_Optional_. The card-based payment method this card will be charged with:

- `CARD` (default): a one-time card payment
- `INSTALLMENT`: a card installment payment

Allowed values:

- `CARD`
- `INSTALLMENT`

### `street_address_1` (string)

_Optional_. The first line of the cardholder's billing address (e.g. street number and name).

### `street_address_2` (string)

_Optional_. The second line of the cardholder's billing address (e.g. apartment, suite, or unit).

### `postal_code` (string)

_Optional_. The postal or ZIP code of the cardholder's billing address.

### `city` (string)

_Optional_. The city of the cardholder's billing address.

### `state` (string)

_Optional_. The state, province, or region of the cardholder's billing address.

### `country` (string)

_Optional_. The country of the cardholder's billing address.

## Errors specific to this endpoint

### `NOT_FOUND`

This error occurs when we cannot find the merchant account or installation with the IDs provided. Double check that you are using the correct IDs.

### `NOT_ENABLED`

This installation is currently disabled.

## Errors common to all endpoints

### `UNHANDLED_ERROR`

This error occurs when the server encounters an unexpected internal error that it cannot handle gracefully. This typically happens due to bugs, infrastructure issues, or edge cases that weren't anticipated during development.

### `INVALID_ARGUMENTS`

This error occurs when the request contains invalid or missing parameters. Common cases include missing required fields, or values that don't match the expected format or type.

### `BAD_VERSION`

This error occurs when making requests to an API version that is either deprecated or not yet released. This commonly happens when using an outdated SDK or when the API version specified in the request URL is incorrect.