Tokenizer SDK (Android & iOS)

El Conekta Tokenizer SDK es una librería nativa multiplataforma (Android e iOS) que permite tokenizar datos de tarjeta de forma segura directamente desde tu aplicación móvil, sin necesidad de iframes ni WebViews.

📘
¿Qué es un Token?
Un Token es un elemento seguro que permite la interacción de sistemas sin exponer datos sensibles de tarjeta.
El SDK encripta los datos del tarjetahabiente (AES + RSA) y los envía de forma segura a Conekta, devolviendo un token de un solo uso que puedes utilizar para crear cargos.

Elementos clave del SDK

Concepto	Descripción
`TokenizerConfig`	Configuración del tokenizador: llave pública, nombre del comercio, opciones
`ConektaTokenizer`	Componente visual que renderiza el formulario completo de tarjeta
`TokenResult`	Resultado exitoso con el `token` y los últimos 4 dígitos (`lastFour`)
`TokenizerError`	Errores posibles: validación, red o API

Respuesta exitosa

Campo	Tipo	Descripción
token	String	Token único
lastFour	String	Últimos 4 dígitos

Manejo de errores

Tipo	Descripción	Ejemplo
ValidationError	Tarjeta inválida	"Número inválido"
NetworkError	Sin conexión	"Network request failed"
ApiError	Error API	code: "invalid_token"

Requisitos previos

Plataforma	Requisito mínimo
Android	minSdk 24, JDK 17, Jetpack Compose
iOS	iOS 15+, Xcode 15+

⚠️
Indispensable
Necesitas una llave pública de Conekta para utilizar el SDK.
Obtén la tuya desde el Panel de Conekta:

Producción: https://panel.conekta.com/

Integración en Android

Paso 1: Agregar la dependencia

dependencies {
    implementation("io.conekta:conekta-elements-compose:0.2.0-beta.2")
}

📘 Nota:

conekta-elements-shared se incluye de forma transitiva.
Los artefactos están publicados en Maven Central.

Paso 2: Configurar Coil para íconos de marca

import coil3.ImageLoader
import coil3.SingletonImageLoader
import io.conekta.compose.ConektaImageLoader

class MyApp : Application(), SingletonImageLoader.Factory {
    override fun newImageLoader(context: Context): ImageLoader {
        return ConektaImageLoader.newImageLoader(context)
    }
}

Registrar en AndroidManifest.xml:

<application
    android:name=".MyApp"
    ... >

Paso 3: Implementar el tokenizador

import io.conekta.compose.tokenizer.ConektaTokenizer
import io.conekta.elements.tokenizer.models.TokenizerConfig
import io.conekta.elements.tokenizer.models.TokenizerError

@Composable
fun PaymentScreen() {
    ConektaTokenizer(
        config = TokenizerConfig(
            publicKey = "key_xxxxx",
            merchantName = "Mi Tienda",
            collectCardholderName = true,
        ),
        onSuccess = { result ->
            val token = result.token
            val lastFour = result.lastFour
        },
        onError = { error ->
            when (error) {
                is TokenizerError.ValidationError -> {}
                is TokenizerError.NetworkError -> {}
                is TokenizerError.ApiError -> {}
            }
        },
    )
}

Integración en iOS

Paso 1: Agregar el SDK

Swift Package Manager

let package = Package(
    ...
    targets: [
        .binaryTarget(
            name: "composeKit",
            url: "https://github.com/conekta/conekta-elements/releases/download/0.2.0-beta.2/composeKit.xcframework.zip",
            checksum: "e5fc1a7030756eea3f8cc4c229c178baac9369e4c3ba3238274f03824fdb02b2"
        ),
        .target(
            name: "YourTarget",
            dependencies: ["composeKit"]
        )
    ]
)

Paso 2: Implementar el tokenizador

import SwiftUI
import composeKit

struct PaymentView: View {
    var body: some View {
        ConektaTokenizerView(
            config: TokenizerConfig(
                publicKey: "key_xxxxx",
                merchantName: "Mi Tienda",
                collectCardholderName: true
            ),
            onSuccess: { result in
                print("Token: \(result.token)")
            },
            onError: { error in
                print(error.localizedDescription)
            }
        )
        .ignoresSafeArea(.container, edges: .bottom)
    }
}

Flujo de tokenización

El usuario completa el formulario de tarjeta en el SDK.
El SDK valida y encripta los datos de forma segura.
El SDK genera un tok_xxx.
Se ejecuta onSuccess.
Tu aplicación envía el token a tu backend.
Tu backend crea el cargo utilizando la llave privada:

curl -X POST https://api.conekta.io/orders \
  -H "Accept: application/vnd.conekta-v2.2.0+json" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer key_private_xxxxx" \
  -d '{
    "currency": "MXN",
    "customer_info": {
      "name": "Juan Pérez",
      "email": "[email protected]",
      "phone": "+525512345678"
    },
    "line_items": [{
      "name": "Producto",
      "unit_price": 10000,
      "quantity": 1
    }],
    "charges": [{
      "payment_method": {
        "type": "card",
        "token_id": "tok_2o3Nk5FPjr7Ac8X9z"
      }
    }]
  }'

Conekta procesa el pago y devuelve el resultado del cargo.

🚧 Importante

El token es de un solo uso.
La key_private_xxxxx nunca debe estar en tu aplicación móvil.
El cargo siempre debe crearse desde tu backend.

Parámetros de configuración

Parámetro	Tipo	Requerido	Default	Descripción
publicKey	String	Sí	—	Llave pública de Conekta
merchantName	String	No	"Demo Store"	Nombre mostrado en el formulario
collectCardholderName	Boolean	No	true	Mostrar campo nombre
baseUrl	String	No	https://api.conekta.io/	URL base

Tarjetas de prueba

Marca	Número	CVV	Fecha
Visa	4242 4242 4242 4242	123	Futura
Mastercard	5105 1051 0510 5100	123	Futura
AMEX	3782 8224 6310 005	1234	Futura

Recursos adicionales

Repositorio en GitHub: https://github.com/conekta/conekta-elements
Ejemplos de integración: https://github.com/conekta/conekta-elements/tree/main/examples
API Reference: https://developers.conekta.com/reference