Introducción

¿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
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 para tokenizar tarjetas sin manejar datos PCI directamente.

Endpoints

Método	Endpoint	Descripción
`POST`	/cards	Registrar tarjeta
`POST`	/cards/tokenized	Registrar tarjeta tokenizada con Elements
`GET`	/cards	Listar tarjetas
`GET`	/cards/	Detalle de una tarjeta
`DELETE`	/cards/	Eliminar tarjeta

API

Empresas

Métodos de pago

Recaudo

Balances

Webhooks

Fintech as a service

¿Qué es una Tarjeta?

¿Cuándo usar tarjetas?

Ejemplo rápido

Ambientes

3DS (3D Secure)

Tarjetas de prueba (exitosas)

Tarjetas de prueba (declinadas)

Personalización del checkout

Endpoints

​¿Qué es una Tarjeta?

​¿Cuándo usar tarjetas?

​Ejemplo rápido

​Ambientes

​3DS (3D Secure)

​Tarjetas de prueba (exitosas)

​Tarjetas de prueba (declinadas)

​Personalización del checkout

​Endpoints

¿Qué es una Tarjeta?

¿Cuándo usar tarjetas?

Ejemplo rápido

Ambientes

3DS (3D Secure)

Tarjetas de prueba (exitosas)

Tarjetas de prueba (declinadas)

Personalización del checkout

Endpoints