> ## Documentation Index
> Fetch the complete documentation index at: https://docs.onepay.la/llms.txt
> Use this file to discover all available pages before exploring further.

# Tokenizar tarjeta

> Registra una nueva tarjeta de crédito/débito para el cliente autenticado usando tokenización.

Registra una nueva tarjeta de crédito o débito para el cliente autenticado. Requiere un token temporal generado previamente por tu frontend con el SDK de tokenización.

<Warning>
  Nunca envíes datos de tarjeta (PAN, CVV, fecha de expiración) directamente a este endpoint. Usa el SDK de tokenización para obtener un `token` seguro.
</Warning>

### Headers

<ParamField header="Authorization" type="string" required>
  Bearer token de tu empresa.
</ParamField>

<ParamField header="X-Customer-Token" type="string" required>
  Token de sesión del cliente obtenido en [/customers/login/verify](verify-otp).
</ParamField>

### Body

<ParamField body="token" type="string" required placeholder="tok_1a2b3c4d5e6f">
  Token temporal de la tarjeta obtenido del SDK de tokenización. Este token es de un solo uso.
</ParamField>

### Respuesta

<ResponseField name="id" type="string">
  ID de la tarjeta registrada.
</ResponseField>

<ResponseField name="brand" type="string">
  Marca de la tarjeta: `visa`, `mastercard`, `amex`, `diners`.
</ResponseField>

<ResponseField name="last_four" type="string">
  Últimos 4 dígitos de la tarjeta.
</ResponseField>

<ResponseField name="label" type="string">
  Etiqueta legible (ej. `Visa ····4242`).
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://api.onepay.la/v1/customers/session/payment-methods \
    -X POST \
    -H "Authorization: Bearer sk_test_xxx" \
    -H "X-Customer-Token: 12|a1b2c3d4e5f6..." \
    -H "Content-Type: application/json" \
    -d '{
      "token": "tok_1a2b3c4d5e6f"
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.onepay.la/v1/customers/session/payment-methods', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_test_xxx',
      'X-Customer-Token': '12|a1b2c3d4e5f6...',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      token: 'tok_1a2b3c4d5e6f'
    })
  });

  const card = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://api.onepay.la/v1/customers/session/payment-methods',
      headers={
          'Authorization': 'Bearer sk_test_xxx',
          'X-Customer-Token': '12|a1b2c3d4e5f6...',
          'Content-Type': 'application/json'
      },
      json={
          'token': 'tok_1a2b3c4d5e6f'
      }
  )

  card = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 201 theme={null}
  {
    "id": "bb02b2fd-154c-4c90-9fdf-cec3a0b25cf5",
    "brand": "visa",
    "last_four": "4242",
    "label": "Visa ····4242"
  }
  ```

  ```json 422 theme={null}
  {
    "message": "El campo token es obligatorio.",
    "errors": {
      "token": [
        "El campo token es obligatorio."
      ]
    }
  }
  ```

  ```json 401 theme={null}
  {
    "message": "Token de sesión inválido o expirado."
  }
  ```
</ResponseExample>