Pagos con Tarjeta

El flujo de pago único es el más simple: el cliente ingresa los datos de su tarjeta, se tokeniza y se cobra en ese momento. La tarjeta no se guarda.

1. Crear un Customer (opcional)

Si quieres asociar el pago a un cliente registrado en Conekta, crea un customer primero y usa su customer_id al crear la orden. Si no, puedes incluir los datos del cliente directamente en el campo customer_info de la orden.

curl --location 'https://api.conekta.io/customers' \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer key_XXXXXXX' \
  --data '{
    "name": "Jorge Martínez",
    "email": "[email protected]",
    "phone": "+52181818181"
  }'

2. Tokenizar la tarjeta

Integra el Tokenizador de Conekta en tu plataforma para capturar los datos de la tarjeta sin que pasen por tus servidores:

• Tokenizador Web — componente iframe para integraciones web.
• Tokenizador Mobile (SDKs nativos) — SDKs para Android, iOS y React Native.

Ambas opciones te devuelven un token_id a través del callback onCreateTokenSucceeded.

3. Crear la orden

Usa el token_id directamente en el objeto charges de la orden:

curl --location 'https://api.conekta.io/orders' \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer key_XXXXXXX' \
  --data '{
    "currency": "MXN",
    "customer_info": {
      "name": "Jorge Martínez",
      "email": "[email protected]",
      "phone": "+52181818181"
    },
    "line_items": [
      {
        "name": "Nombre del producto",
        "unit_price": 50000,
        "quantity": 1
      }
    ],
    "charges": [
      {
        "payment_method": {
          "type": "card",
          "token_id": "tok_2ww3PnDK3FtuqJ6pU"
        }
      }
    ]
  }'

El cargo bajo demanda te permite guardar la tarjeta de un cliente una vez y ejecutar cobros posteriores cuando tu negocio lo requiera, sin intervención del cliente.

1. Crear un Customer

Registra la información mínima del cliente para asociarle métodos de pago. Guarda el customer_id de la respuesta.

curl --location 'https://api.conekta.io/customers' \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer key_XXXXXXX' \
  --data '{
    "name": "Jorge Martínez",
    "email": "[email protected]",
    "phone": "+52181818181"
  }'

{
  "id": "cus_2tTSkfScREpvaRJsE",
  "object": "customer",
  "name": "Jorge Martínez",
  "email": "[email protected]",
  "phone": "+52181818181"
}

🚧

Si ya tienes un customer_id asociado al usuario, no es necesario que realices este paso de nuevo.

2. Tokenizar la tarjeta

Integra el Tokenizador de Conekta en tu plataforma:

• Tokenizador Web — componente iframe para integraciones web.
• Tokenizador Mobile (SDKs nativos) — SDKs para Android, iOS y React Native.

Ambas opciones te devuelven un token_id a través del callback onCreateTokenSucceeded.

3. Guardar la tarjeta

Asocia el token_id al customer enviándolo al endpoint de payment_sources. Guarda el payment_source_id (src_...) de la respuesta — lo usarás en el siguiente paso y para cobros futuros.

curl --location 'https://api.conekta.io/customers/cus_2tTSkfScREpvaRJsE/payment_sources' \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer key_XXXXXXX' \
  --data '{
    "type": "card",
    "token_id": "tok_2ww3PnDK3FtuqJ6pU"
  }'

{
  "id": "src_2ww3QXmem27BfQqNg",
  "object": "payment_source",
  "type": "card",
  "last4": "4242",
  "brand": "visa",
  "parent_id": "cus_2tTSkfScREpvaRJsE",
  "payment_source_status": "active"
}

4. Realizar el primer pago

⚠️

Este paso es obligatorio e inmediato

El primer pago debe ejecutarse en cuanto guardes la tarjeta. El CVV incluido en el token es de un solo uso y expira rápidamente.

Si el cargo falla: elimina el payment_source creado en el paso anterior y solicita al cliente que ingrese una tarjeta diferente.

cURL

curl --location --request DELETE \
  'https://api.conekta.io/customers/cus_2tTSkfScREpvaRJsE/payment_sources/src_2ww3QXmem27BfQqNg' \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Authorization: Bearer key_XXXXXXX'

Crea una orden usando el payment_source_id guardado en el paso anterior:

curl --location 'https://api.conekta.io/orders' \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer key_XXXXXXX' \
  --data '{
    "currency": "MXN",
    "customer_info": {
      "customer_id": "cus_2tTSkfScREpvaRJsE"
    },
    "line_items": [
      {
        "name": "Verificación de tarjeta",
        "unit_price": 100,
        "quantity": 1
      }
    ],
    "charges": [
      {
        "payment_method": {
          "type": "card",
          "payment_source_id": "src_2ww3QXmem27BfQqNg"
        }
      }
    ]
  }'

5. Revertir el cargo de verificación

Una vez que la tarjeta quedó guardada correctamente, devuelve el cargo realizado en el paso 4. Un cargo no comunicado al usuario puede generar contracargos y fricciones innecesarias.

Antes de procesar la devolución, te recomendamos informar al usuario en tu frontend que se realizará un pequeño cargo temporal para validar su tarjeta y que será revertido de inmediato.

curl --location 'https://api.conekta.io/orders/ord_2ww3UnHWMi8yqV5GG/refund' \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer key_XXXXXXX' \
  --data '{}'

6. Cobrar bajo demanda

Una vez guardada la tarjeta, puedes ejecutar cargos en cualquier momento usando el payment_source_id, sin volver a tokenizar.

curl --location 'https://api.conekta.io/orders' \
  --header 'Accept: application/vnd.conekta-v2.3.0+json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer key_XXXXXXX' \
  --data '{
    "currency": "MXN",
    "customer_info": {
      "customer_id": "cus_2tTSkfScREpvaRJsE"
    },
    "line_items": [
      {
        "name": "Suscripción mensual",
        "unit_price": 29900,
        "quantity": 1
      }
    ],
    "charges": [
      {
        "payment_method": {
          "type": "card",
          "payment_source_id": "src_2ww3QXmem27BfQqNg"
        }
      }
    ]
  }'

Las suscripciones permiten cobrar automáticamente a un cliente de forma recurrente según un plan predefinido (semanal, mensual, anual, etc.), sin necesidad de intervención del cliente en cada ciclo de cobro.

1. Crear un Customer — Registra al cliente en Conekta.
2. Tokenizar la tarjeta — Obtén un token_id usando el Tokenizador.
3. Guardar la tarjeta — Asocia el token al customer como payment_source.
4. Crear un plan — Define la frecuencia y monto del cobro recurrente.
5. Suscribir al customer — Asocia el customer al plan para activar los cobros automáticos.

Para la documentación completa de cada paso, consulta la sección de Suscripciones.