> ## 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.

# Introducción

> Gestiona las tarjetas de tus clientes.

## ¿Qué es una Tarjeta?

Una tarjeta es un método de pago registrado a nombre de un [cliente](/client/customers/index). Permite realizar cargos (débitos directos) a tarjetas de crédito o débito autorizadas.

<Note>
  Las tarjetas se crean en un dominio diferente (`cards.onepay.la`) por cumplimiento PCI DSS. OnePay cuenta con certificación **PCI DSS Nivel 1**.
</Note>

## ¿Cuándo usar tarjetas?

| Escenario                                                | Solución                                                                  |
| -------------------------------------------------------- | ------------------------------------------------------------------------- |
| Cobrar con un link de pago (el cliente elige cómo pagar) | Usa [Payments](/client/payments/index), no necesitas registrar tarjeta    |
| Debitar automáticamente una tarjeta autorizada           | Registra la tarjeta y crea un [Charge](/client/charges/index)             |
| Cobros recurrentes (suscripciones)                       | Registra la tarjeta y crea una [Suscripción](/client/subscriptions/index) |
| Capturar datos de tarjeta de forma segura en tu frontend | Usa [Elements SDK](/docs/elements/index) para tokenizar                   |

## Ejemplo rápido

```bash theme={null}
curl https://cards.onepay.la/v1/cards \
  -X POST \
  -H "Authorization: Bearer pk_test_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "card_number": "4242424242424242",
    "expiration_year": "29",
    "expiration_month": "12",
    "ccv": "123",
    "holder_name": "MARIA LOPEZ",
    "customer_id": "CUSTOMER_ID",
    "authorization": true,
    "authentication": {
      "cavv": "AAABBEg0VhI0VniQEjRWAAAAAAA=",
      "eci": "05",
      "version": "2.2.0",
      "status": "Y"
    }
  }'
```

<Warning>
  Si capturas datos de tarjeta directamente en tu backend, debes cumplir con PCI DSS. Usa el [SDK Elements](/docs/elements/introduction) para capturar datos de forma segura desde el frontend.
</Warning>

## Ambientes

Usa API keys diferentes para cada ambiente:

* **Test** (`pk_test_`): Registra tarjetas de prueba para validar tu integración.
* **Producción** (`pk_live_`): Registra tarjetas reales para transacciones efectivas.

## 3DS (3D Secure)

OnePay permite enviar datos de autenticación 3D Secure al registrar una tarjeta vía API. Si realizas la autenticación 3DS de forma externa (por ejemplo, con tu propio servidor 3DS), puedes enviar el criptograma resultante en el campo `authentication` al crear la tarjeta. Los datos de autenticación se almacenan y se envían automáticamente al proveedor de pago cuando se procese un cobro con esa tarjeta.

<Note>
  El campo `authentication` es opcional. Si no realizas autenticación 3DS externa, simplemente omítelo.
</Note>

## Tarjetas de prueba (exitosas)

| Número           | Marca              | CVV                  | Fecha de vencimiento   |
| ---------------- | ------------------ | -------------------- | ---------------------- |
| 4242424242424242 | Visa Crédito       | 3 dígitos cualquiera | Cualquier fecha futura |
| 4000056655665556 | Visa Débito        | 3 dígitos cualquiera | Cualquier fecha futura |
| 5555555555554444 | Mastercard Crédito | 3 dígitos cualquiera | Cualquier fecha futura |
| 5200828282828210 | Mastercard Débito  | 3 dígitos cualquiera | Cualquier fecha futura |

## Tarjetas de prueba (declinadas)

| Número           | Marca              | CVV       | Fecha  | Resultado             |
| ---------------- | ------------------ | --------- | ------ | --------------------- |
| 4000000000000002 | Visa Crédito       | 3 dígitos | Futura | Fondos insuficientes  |
| 4000000000009995 | Visa Crédito       | 3 dígitos | Futura | Tarjeta robada        |
| 5555555555555557 | Mastercard Crédito | 3 dígitos | Futura | Transacción rechazada |
| 5200828282828211 | Mastercard Crédito | 3 dígitos | Futura | Expirada              |
| 4000000000000101 | Visa Crédito       | 3 dígitos | Futura | Fallo genérico        |

## Personalización del checkout

Si buscas una experiencia embebida y personalizada en tu frontend, usa los [Elementos de captura de datos sensibles](/docs/elements/index) para tokenizar tarjetas sin manejar datos PCI directamente.

## Endpoints

| Método   | Endpoint                             | Descripción                                                              |
| -------- | ------------------------------------ | ------------------------------------------------------------------------ |
| `POST`   | [/cards](create)                     | Registrar tarjeta                                                        |
| `POST`   | [/cards/tokenized](create-tokenized) | Registrar tarjeta tokenizada con [Elements](/docs/elements/introduction) |
| `GET`    | [/cards](list)                       | Listar tarjetas                                                          |
| `GET`    | [/cards/{id}](detail)                | Detalle de una tarjeta                                                   |
| `DELETE` | [/cards/{id}](delete)                | Eliminar tarjeta                                                         |