Objetivo
Cuando deseamos guardar la tarjeta de un cliente para que la pueda ocupar en múltiples ocasiones sin necesidad de volverla a introducir los datos, lo tenemos que hacer en guardar la tarjeta.
Los pasos para guardar la tarjeta de nuestro cliente son:
- Crear un cliente
- Guardar tarjeta de Cliente
1. Crear un Cliente
Para crear un nuevo cliente, debemos de usar el método POST /cliente, es recomendable que se envíe la mayor cantidad de datos en las peticiones para mejorar el análisis de riesgo que se efectúa antes de procesar una transacción. En el siguiente ejemplo enviaremos solamente datos básicos de un cliente.
Request:
{
"id_externo": "123",
"email": "usuario@example.com"
}
Response:
{
"status": "success",
"data": {
"cliente": {
"id_externo": "123",
"email": "usuario@example.com",
"id": "ba3e968d-95d0-4a4d-928b-808a58ffbb55",
"estado": "activo",
"actualizacion": "2018-08-28T11:47:19-05:00",
"creacion": "2018-08-28T11:47:19-05:00"
}
},
"http_code": 200,
"datetime": "2018-08-28T11:47:19-05:00",
"timestamp": 1535474839
}.
Nota: No es recomendable el envío del correo electrónico del cliente como un identificador en la plataforma del comercio (id_externo), ya que un cliente podrá actualizar su cuenta y cambiar de correo. El valor que se proporcione como id_externo puede ser alfanumérico y no debe estar duplicado.
2. Guardar tarjeta de Cliente
Este método te permitirá guardar la tarjeta de un cliente y te regresará el token y la marca y 4 últimos dígitos de la tarjeta. Tu servidor deberá guardar estos datos para que puedas mostrarle a tu cliente la marca y terminación de sus tarjetas para que elija con cual quiere pagar. Ejemplo: Visa 1234, Mastercard 2345.
En caso de que tu servidor no pueda guardar esta información podrás usar el método de Búsqueda de tarjetas.
Para guardar la tarjeta de un cliente ya creado se deberá realizar una petición al método POST /tarjeta.
En el ejemplo se incluirán sólo datos básicos, incluyendo el PAN (16 dígitos de una tarjeta), Nombre del tarjetahabiente, fecha de expiración, CVV2 (código de seguridad, usualmente está en la parte posterior de una tarjeta) y los datos del cliente.
Request:
{
"nombre": "NOMBRE DE CLIENTE",
"pan": "4242424242424242",
"expiracion_mes": "03",
"expiracion_anio": "22",
"cvv2": "123",
"cliente_id": "ba3e968d-95d0-4a4d-928b-808a58ffbb55",
"default": true
}
Response:
{
"status": "success",
"data": {
"tarjeta": {
"cliente_id": "ba3e968d-95d0-4a4d-928b-808a58ffbb55",
"default": true,
"nombre": "NOMBRE DE CLIENTE",
"iin": "424242",
"terminacion": "4242",
"pan": "424242******4242",
"marca": "visa",
"expiracion_mes": "03",
"expiracion_anio": "22",
"token": "5c4a7103-d35f-4136-98be-6210d57b0ca3",
"actualizacion": "2018-08-28T11:52:11-05:00",
"creacion": "2018-08-28T11:52:11-05:00"
}
},
"http_code": 200,
"datetime": "2018-08-28T11:52:11-05:00",
"timestamp": 1535475131
}
Importante: el código CVV de la tarjeta será eliminado cuando se haya completado el primer cargo, ya que por regulación no puede ser almacenado después de que se haya hecho la autorización. Este dato no es obligatorio para hacer cargos posteriores, sin embargo, si la transacción si incluye este dato tiene mayor probabilidad de ser aprobada por el banco. Es por esto que tu puedes decidir si le pides a tu cliente el código CVV antes de hacer un cargo con una tarjeta guardada o no. Para incluir el CVV en un cargo con tarjeta almacenada, deberás actualizar la tarjeta con el método Actualizar tarjeta justo antes de enviar el cargo.
Buscar tarjetas asociadas a cliente
Para realizar la búsqueda de tarjetas, debemos usar el método GET /cliente/{id}/tarjeta, de acuerdo al siguiente ejemplo:
Request (cURL):
curl -X GET \
https://api.sandbox.claropagos.com/v1/cliente/ba3e968d-95d0-4a4d-928b-808a58ffbb55/tarjeta \
-H 'Authorization: Bearer BEARER_TOKEN' \
-H 'Cache-Control: no-cache' \
Nota: El ejemplo se provee en cURL ya que la petición sólo contiene parámetros en la ruta solicitada (path).
Response:
{
"status": "success",
"http_code": 200,
"datetime": "2018-08-28T20:47:26.674Z",
"timestamp": 0,
"data": {
"tarjetas": {
"data": [
{
"token": "5c4a7103-d35f-4136-98be-6210d57b0ca3",
"cliente_id": "ba3e968d-95d0-4a4d-928b-808a58ffbb55",
"iin": "424242",
"marca": "visa",
"pan": "424242******4242",
"terminacion": "4242",
"nombre": "NOMBRE DE CLIENTE",
"expiracion_mes": "03",
"expiracion_anio": "22",
"default": true,
"cargo_unico": false,
"creacion": "2018-08-28T11:52:11-05:00",
"actualizacion": "2018-08-28T11:52:11-05:00"
}
],
"desde": 1,
"hasta": 1,
"registros_por_pagina": 25,
"pagina_actual": 1,
"ultima_pagina": 1,
"total_pagina": 1,
"total": 1
}
}
}
Actualizar tarjeta para incluir código CVV
Al actualizar una tarjeta para incluir el código CVV, podremos añadir un nivel más de seguridad al hacer un cargo. El código CVV permitirá al banco realizar una mejor evaluación de la transacción.
Con el token para identificar la tarjeta, debemos de usar el método PUT /tarjeta, incluyendo el código CVV en el cuerpo de la petición.
Request:
{
"cvv2": 321
}
Al actualizar una tarjeta, la respuesta contendrá el objeto con los cambios realizados, pero NO incluirá el código CVV, por lo que se omite la respuesta en el ejemplo.
3. Editar un Cliente
La edición de un cliente, por medio del método PUT /cliente, permitirá un ajuste de datos ya registrados de un cliente del comercio. Es altamente recomendable mantener actualizados los datos del cliente ya que los datos almacenados en el sistema T1pagos son los que se usarán en el sistema de prevención de fraude.
Request:
{
"nombre": "NuevoNombre",
"apellido_paterno": "paterno",
"apellido_materno": "materno",
"email": "nuevocorreo@example.com"
}
Response:
{
"status": "success",
"data": {
"cliente": {
"id": "ba3e968d-95d0-4a4d-928b-808a58ffbb55",
"id_externo": "123",
"nombre": "NuevoNombre",
"apellido_paterno": "paterno",
"apellido_materno": "materno",
"email": "nuevocorreo@example.com",
"estado": "activo",
"creacion": "2018-08-28T11:47:19-05:00",
"actualizacion": "2018-09-03T09:32:08-05:00"
}
},
"http_code": 200,
"datetime": "2018-09-03T09:32:08-05:00",
"timestamp": 1535985128
}
4. Crear un cargo a un cliente y tarjeta registrados
En el siguiente ejemplo, se realizará un cargo a un cliente ya almacenado incluyendo en la petición un gran porcentaje de los campos que pueden ser enviados al momento de generar un cargo. La generación del cargo se realizará a través del método POST /cargo.
Request:
{
"monto": "10",
"descripcion": "Venta online",
"metodo_pago": "tarjeta",
"tarjeta": {
"token": "5c4a7103-d35f-4136-98be-6210d57b0ca3"
},
"pedido": {
"id_externo": "orden-1",
"total_articulos": 2,
"es_regalo": false,
"monto_articulos": 200.00,
"monto_envio": 0.0,
"total_monto": 200.00,
"device_fingerprint": "d9SN7sTv8tFLBzWxdrramTh7dSmNmkTR"
},
"cliente": {
"id": "ba3e968d-95d0-4a4d-928b-808a58ffbb55",
"id_externo": "123",
"creacion_externa": "2018-08-29T05:12:49.641Z",
"nombre": "Roberto",
"apellido_paterno": "Gómez",
"email": "usuario@example.com"
}
}
Response:
{
"status": "success",
"data": {
"cargo": {
"id": "ce6fa69d-a2ab-471a-b2a9-9ed18f3241b7",
"monto": "200.0000",
"tipo": "cargo",
"orden_id": 0,
"cliente_id": "ba3e968d-95d0-4a4d-928b-808a58ffbb55",
"estatus": "rechazada-banco",
"prueba": true,
"error": {
"codigo": "05",
"tipo": "Banco",
"descripcion": "Rechazada por el banco"
},
"tarjeta": {
"creacion": "2018-08-29T00:56:45-05:00",
"nombre": "NOMBRE DE CLIENTE",
"expiracion_mes": "03",
"expiracion_anio": "22",
"token": "5c4a7103-d35f-4136-98be-6210d57b0ca3",
"iin": "424242",
"marca": "visa",
"terminacion": "4242"
}
}
},
"http_code": 200,
"datetime": "2018-08-29T00:56:45-05:00",
"timestamp": 1535522205
}
El cargo será procesado incluyendo el código CVV, en caso de que la tarjeta haya sido actualizada previamente. Si el cargo es completado exitosamente se conservará el registro de la tarjeta, sin código CVV, en la bóveda. En caso de que el cargo falle, la tarjeta podrá ser eliminada de la bóveda.
Para ayudarte a resolver tus dudas haz clic aquí y genera una solicitud a Servicio al Cliente, te respondemos lo más pronto posible.