Tokenizer Mobile SDKs

Integra el tokenizador de tarjetas nativo en tu aplicación Android o iOS, React Native usando el SDK de Conekta Elements.

Para integrar nuestro tokenizador en aplicaciones mobiles, contamos con SDKs para:

  1. Android & iOS
  2. React Native

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

ConceptoDescripción
TokenizerConfigConfiguración del tokenizador: llave pública, nombre del comercio, opciones
ConektaTokenizerComponente visual que renderiza el formulario completo de tarjeta
TokenResultResultado exitoso con el token y los últimos 4 dígitos (lastFour)
TokenizerErrorErrores posibles: validación, red o API

Respuesta exitosa

CampoTipoDescripción
tokenStringToken único
lastFourStringÚltimos 4 dígitos

Manejo de errores

TipoDescripciónEjemplo
ValidationErrorTarjeta inválida"Número inválido"
NetworkErrorSin conexión"Network request failed"
ApiErrorError APIcode: "invalid_token"

Requisitos previos

PlataformaRequisito mínimo
AndroidminSdk 24, JDK 17, Jetpack Compose
iOSiOS 15+, Xcode 15+
⚠️

Indispensable

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


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

  1. El usuario completa el formulario de tarjeta en el SDK.
  2. El SDK valida y encripta los datos de forma segura.
  3. El SDK genera un tok_xxx.
  4. Se ejecuta onSuccess.
  5. Tu aplicación envía el token a tu backend.
  6. 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"
      }
    }]
  }'
  1. 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ámetroTipoRequeridoDefaultDescripción
publicKeyStringLlave pública de Conekta
merchantNameStringNo"Demo Store"Nombre mostrado en el formulario
collectCardholderNameBooleanNotrueMostrar campo nombre
baseUrlStringNohttps://api.conekta.io/URL base


Integración en React Native

El SDK de React Native proporciona un wrapper que renderiza directamente la UI nativa de Conekta Elements en Android e iOS a través de un puente JavaScript ligero.

Requisitos

PlataformaVersión mínima
AndroidAPI 24 (Android 7.0)
iOS14.0
React Native0.71+
⚠️

Indispensable: Necesitas una llave pública de Conekta para utilizar el SDK.

📘

Expo Go no es compatible. Es una app sandboxed con un conjunto fijo de módulos nativos. Usa un Development Build o el workflow Bare.

Paso 1: Instalar la dependencia

npm install conekta-elements-react-native

iOS

Después de instalar, ejecuta:

cd ios && pod install

pod install descarga automáticamente el XCFramework de Compose desde GitHub Releases.

Android

El autolinking registra el módulo automáticamente. No se requiere configuración adicional.

Paso 2: Implementar el tokenizador

import React, { useState } from 'react';
import { SafeAreaView } from 'react-native-safe-area-context';
import { ConektaTokenizer } from 'conekta-elements-react-native';
import type { TokenResult, TokenizerError } from 'conekta-elements-react-native';

export default function CheckoutScreen() {
  const [token, setToken] = useState('');

  function handleSuccess(result: TokenResult) {
    console.log('Token:', result.token, 'Last four:', result.lastFour);
    setToken(result.token);
  }

  function handleError(error: TokenizerError) {
    console.error(`[${error.type}] ${error.message}`);
  }

  return (
    <SafeAreaView style={{ flex: 1 }}>
      <ConektaTokenizer
        config={{
          publicKey: 'key_XXXXXXXXXXXXXXXX',
          merchantName: 'Mi Tienda',
        }}
        onSuccess={handleSuccess}
        onError={handleError}
        style={{ flex: 1 }}
      />
    </SafeAreaView>
  );
}

Componente <ConektaTokenizer />

PropTipoRequeridoDescripción
configTokenizerConfigLlave pública y configuración del comercio
onSuccess(result: TokenResult) => voidSe ejecuta cuando la tokenización es exitosa
onError(error: TokenizerError) => voidSe ejecuta cuando la tokenización falla
styleStyleProp<ViewStyle>NoEstilo del contenedor

Parámetros de configuración

ParámetroTipoRequeridoDefaultDescripción
publicKeystringLlave pública de Conekta
merchantNamestringNo"Demo Store"Nombre del comercio mostrado en el formulario

Respuesta exitosa

Cuando el usuario completa el formulario y la tokenización es exitosa, el callback onSuccess recibe un objeto TokenResult:

interface TokenResult {
  token: string;     // Token de la tarjeta
  lastFour: string;  // Últimos cuatro dígitos de la tarjeta
}

Manejo de errores

El callback onError recibe un objeto TokenizerError que puede ser uno de los siguientes tipos:

type TokenizerError =
  | { type: 'ValidationError'; message: string }  // Error de validación del formulario
  | { type: 'NetworkError'; message: string }      // Error de conectividad
  | { type: 'ApiError'; code: string; message: string }  // Error de la API de Conekta

Compatibilidad con Expo

WorkflowCompatible
Expo Go❌ No
Development Build✅ Sí
Bare workflow✅ Sí
EAS Build✅ Sí

Para usar con Expo, crea un Development Build:

npx expo install expo-dev-client

# Build local
npx expo run:ios
npx expo run:android

# O build con EAS
eas build --profile development

Tarjetas de prueba

MarcaNúmeroCVVFecha
Visa4242 4242 4242 4242123Futura
Mastercard5105 1051 0510 5100123Futura
AMEX3782 8224 6310 0051234Futura

Recursos adicionales