¿Qué es una Tarjeta?
Una tarjeta es un método de pago registrado a nombre de un cliente. Permite realizar cargos (débitos directos) a tarjetas de crédito o débito autorizadas.
Las tarjetas se crean en un dominio diferente (cards.onepay.la) por cumplimiento PCI DSS. OnePay cuenta con certificación PCI DSS Nivel 1.
¿Cuándo usar tarjetas?
| Escenario | Solución |
|---|
| Cobrar con un link de pago (el cliente elige cómo pagar) | Usa Payments, no necesitas registrar tarjeta |
| Debitar automáticamente una tarjeta autorizada | Registra la tarjeta y crea un Charge |
| Cobros recurrentes (suscripciones) | Registra la tarjeta y crea una Suscripción |
| Capturar datos de tarjeta de forma segura en tu frontend | Usa Elements SDK para tokenizar |
Ejemplo rápido
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"
}
}'
Si capturas datos de tarjeta directamente en tu backend, debes cumplir con PCI DSS. Usa el SDK Elements para capturar datos de forma segura desde el frontend. 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.
El campo authentication es opcional. Si no realizas autenticación 3DS externa, simplemente omítelo.
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 |
Personalización del checkout
Si buscas una experiencia embebida y personalizada en tu frontend, usa los Elementos de captura de datos sensibles para tokenizar tarjetas sin manejar datos PCI directamente.
Endpoints
| Método | Endpoint | Descripción |
|---|
POST | /cards | Registrar tarjeta |
GET | /cards | Listar tarjetas |
GET | /cards/ | Detalle de una tarjeta |
DELETE | /cards/ | Eliminar tarjeta |
