Recomendaciones en la prevención de fraudes

Para contar con una mejor tasa de aprobación y una clasificación adecuada del riesgo de fraude de la transacción, se recomienda proporcionar los siguientes campos al momento de hacer un pago con la API de Checkout Transparente:

customer: Información del clienteque realiza el pago.
prevention_data: información para la prevención de riesgo.
metadata: Datos complementarios del pago.
location: La IP pública con la ubicación del comprador.

Flujo

El flujo es el mismo, con el paso adicional de capturar la información de prevención de fraudes o prevention_data y proporcionar la información requerida para la prevención de fraudes:

Importa el SDK (clip-sdk.js)
Configura el formulario y obtén el Card Token ID
Autentícate con tu API Key e inicializa el SDK de Clip
Despliega el formulario y obtén el token de la tarjeta (Card Token ID)
Obtén los prevention_data
Realiza el cargo con la API de Payments utilizando el token de la tarjeta (Card Token ID) y proporcionando todos los datos necesarios para la prevención de fraudes.

Objetos

Objeto customer

El objeto customer contiene la información del cliente o comprador. El correo y el teléfono son campos obligatorios.

La siguiente tabla describe el esquema del objeto customer:

Parámetro			Descripción	Tipo	Ejemplo	Requerido / Opcional	Notas
customer			Objeto con la información del cliente que realiza la transacción.	Objeto
	first_name		Nombre o nombres del cliente que que realiza la transacción.	String	"Dong"	Opcional
	last_name		Apellidos del cliente que que realiza la transacción.	String	"Lee"	Opcional
	email		Correo del cliente que realiza la transacción.	String	"buyer@email.com"	Requerido
	phone		Teléfono del cliente que realiza la transacción.	String	“5512345678”	Requerido
	description		Texto describiendo al cliente.	String	“Gerente de la fábrica de pintura”	Opcional
	address		Objeto con la dirección del cliente.	Objeto
		postal_code	Código postal.	String	"03800"	Opcional	Este campo es obligatorio para American Express.
		street	Nombre de la calle.	String	"Av Uno"	Opcional	Este campo es obligatorio para American Express.
		exterior_number	Número exterior del domicilio.	String	“104"	Opcional	Este campo es obligatorio para American Express.
		internal_number	Número interior del domicilio.	String	“A203"	Opcional
		city	Delegación o municipio.	String	"Benito Juárez"	Opcional
		country	País.	String	"México"	Opcional
		state	Estado.	String	"Ciudad de México"	Opcional
	identification		Objeto con los datos de la identificación del cliente.	Objeto
		id	Número de identificación.	String	"AAA840621HCAAA01"	Opcional	Número de folio o número de identificación
		type	Tipo de identificación.	String	"CURP"	Opcional	Pueden ser: INE, pasaporte o CURP

El siguiente JSON muestra el objeto customer:

"customer": {
    "first_name": "Dong", 
    "last_name": "Lee",  
    "email": "buyer@email.com",
    "phone": "5512345678",
    "description": "Gerente de la fábrica de pintura", 
    "address":{ 
        "postal_code":"03800",
        "street": "Av Uno",
        "exterior_number": "104",
        "internal_number": "A203", 
        "city": "Benito Juárez", 
        "country": "México", 
        "state":"Ciudad de México"            
    },
    "identification": { 
        "id": "AAA840621HCAAA01", 
        "type": "CURP"
    }        
}

Objeto metadata

El objeto metadata contiene la información adicional de la transacción, y se compone a su vez de los siguientes objetos y atributos:

billing_address: Dirección de facturación.
shipping_address: Dirección de envío (cuando aplica).
website: Sitio web del comercio donde se está realizando el pago.

La siguiente tabla describe el esquema del objeto metadata:

Parámetro			Descripción	Tipo	Ejemplo	Requerido / Opcional	Notas
metadata			Objeto con información adicional de la transacción.	Objeto
	billing_address		Objeto con la dirección de facturación.	Objeto
		postal_code	Código postal.	String	"03800"	Opcional
		street	Nombre de la calle.	String	"Av Uno"	Opcional
		exterior_number	Número exterior del domicilio.	String	“104"	Opcional
		internal_number	Número interior del domicilio.	String	“A203"	Opcional
		colony	Colonia del domicilio.	String	"San Miguel Chapultepec"	Opcional
		reference	Referencia del domicilio.	String	"Puerta de color negro"	Opcional
		city	Delegación o municipio.	String	"Benito Juárez"	Opcional
		country	País.	String	"México"	Opcional
		state	Estado.	String	"Ciudad de México"	Opcional
	shipping_address		Objeto con la dirección de envío.	Objeto
		postal_code	Código postal.	String	"03800"	Opcional
		street	Nombre de la calle.	String	"Av Uno"	Opcional
		exterior_number	Número exterior del domicilio.	String	“104"	Opcional
		internal_number	Número interior del domicilio.	String	“A203"	Opcional
		colony	Colonia del domicilio.	String	"San Miguel Chapultepec"	Opcional
		reference	Referencia del domicilio.	String	"Puerta de color negro"	Opcional
		city	Delegación o municipio.	String	"Benito Juárez"	Opcional
		country	País.	String	"México"	Opcional
		state	Estado.	String	"Ciudad de México"	Opcional
	website		Sitio web del comercio donde se está realizando el pago.	String	"https://clip.mx"	Opcional

El siguiente JSON muestra el objeto customer:

"metadata": {         
    "billing_address": {
        "postal_code": "03800",
        "street": "vip",
        "exterior_number": "104",
        "internal_number": "A203",
        "colony": "San Miguel Chapultepec",
        "reference": "Puerta de color negro",
        "city": "Benito Juárez",
        "country": "México",
        "state": "Ciudad de México"
    },
    "shipping_address": { 
        "postal_code": "03800",
        "exterior_number": "104",
        "internal_number": "A203",
        "colony": "San Miguel Chapultepec",
        "reference": "Puerta de color negro",
        "city": "México",
        "country": "Benito Juárez",
        "state": "Ciudad de México"
    },     
    "website": "https://clip.mx"
}

Objeto prevention_data

El objeto prevention_data contiene la información para prevención de riesgo.

🚧
Todos estos parámetros son opcionales, sin embargo te recomendamos enviar por lo menos el session_id y user_agent para una mejor tasa de aprobación.

La siguiente tabla describe el esquema del objeto prevention_data:

Parámetro		Descripción	Tipo	Ejemplo	Requerido / Opcional	Notas
prevention_data		Objeto con la información para prevención de riesgo	Objeto
	customer_type	Tipo de comprador o cliente	String	"returning_buyer"	Opcional	Posibles valores: "vip" o "returning_buyer"
	submerchant_id	Identificador del subcomercio o vertical de negocio	String	"1234abc"	Opcional	Este parámetro es opcional y es un ejemplo de lo que puedes incluir para clasificar transacciones
	customer_risk_score	Puntaje o nivel de riesgo asignado para este comprador	Numeric	52	Opcional	El puntaje lo tienes que asignar en una escala del 1 al 100, en donde 1 es bajo y 100 es alto
	transaction_risk_level	Nivel de riesgo asignado a la transacción	String	"med"	Opcional	El nivel de riesgo lo puedes asignar usando estos valores: "low" si es bajo, "med" si es medio o "high" si es alto.
	session_id	id que sirve para identificar un cliente o comprador.	String	"f47ac10b-58cc-4372-a567-0e02b2c3d479"	Opcional	Se recomienda enviar este parámetro
	user_agent	Información del browser o software desde donde se realiza el pago de la tarjeta.	String	"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)"	Opcional	Se recomienda enviar este parámetro
	request_3ds	Te permite solicitar que la transacción requiera autenticación 3DS.	Booleano	true	Opcional	Si es true se realizará la validación 3DS, si es false se omitirá..

El siguiente JSON muestra el objeto prevention_data:

"prevention_data": {
       "customer_type": "returning_buyer",
       "submerchant_id":"id 001",
       "customer_risk_score":15,
       "transaction_risk_level":"low",
       "session_id":"f47ac10b-58cc-4372-a567-0e02b2c3d479",
       "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
       "request_3ds": true
    }

Objeto location

El objeto location contiene la dirección IP pública del cliente o comprador.

La siguiente tabla describe el esquema del objeto location:

Parámetro		Descripción	Tipo	Ejemplo	Requerido / Opcional	Notas
metadata		Objeto con la información de la IP.	Objeto
	ip	Dirección IP pública del cliente o comprador.	String	"92.228.17.57"	Opcional

El siguiente JSON muestra el objeto customer:

"location": {
	"ip": "130.41.173.243"
}

Prevention data en el SDK

Los únicos datos de prevención de riesgo que se pueden obtener a través del SDK son:

session_id
user_agent

Los demás parámetros son asignados por el comercio.

Desplegar el formulario de captura de tarjeta

Desplegar el formulario como se indica en las instrucciones de configuración del SDK de checkout transparente:

// Los colores o temas disponibles son: 'light'(default) y 'dark'
// Los idiomas disponibles son: 'en' para Inglés, 'es' para Español, 
//y el valor por defecto es el idioma del navegador.

// Crea un elemento tarjeta con el SDK de Clip
      const card = clip.element.create("Card", {
        theme: "light",
        locale: "es",
      });
      card.mount("checkout");

Obtener el Card Token ID

Obtener el card token:

// Maneja el evento de envío del formulario
      document.querySelector("#payment-form").addEventListener("submit", async (event) => {
        event.preventDefault();
        let cardToken = null;
        try {
          
          // Obtén el token de la tarjeta
          cardToken = await card.cardToken();
        } catch (error) {
       
          // Maneja errores durante la tokenización de la tarjeta
          switch (error.code) {
            case "CL2200":
            case "CL2290":
              alert("Error: " + error.message);
              throw error;
              break;
            case "AI1300":
              console.log("Error: ", error.message);
              break;
            default:
              break;
          }
        }

Guardar el card token:

// Guarda el Card Token ID de la tarjeta en una constante
        const cardTokenID = cardToken.id;
        console.log("Card Token ID:", cardTokenID);
      });

Obtener los prevention_data

Obtener los prevention_data:

// Obtener datos específicos relacionados con la prevención de riesgos ingresados en el Card Element.
        const preventionData = await card.preventionData();

Guardar los prevention_data:

const session_id = preventionData.session_id;
const user_agent = preventionData.user_agent;

Realizar pago

El objeto prevention_data junto con todos sus parámetros se debe incluir dentro del request al endpoint de POST /payments de la siguiente forma:

curl --location --request POST 'https://api.payclip.com/payments' \
--header 'Authorization: Basic MTBkMTA2Y2QtMTOjExgtNGY1ZS04ODRmLWVhMTM0YjVhNTUyNA==' \
--header 'Content-Type: application/json' \
--data-raw '{
    "amount": 100,
    "currency": "MXN",
    "description": "Pago con datos de prevención de fraude",
    "payment_method": {
        "token": "0915e7-f6f-862-89e-0c5d71ae6"
    },
    "customer": {
        "first_name": "Dong", 
        "last_name": "Lee",  
        "email": "buyer@email.com",
        "phone": "5512345678",
        "description": "Gerente de la fábrica de pintura", 
        "address":{ 
            "postal_code":"03800",
            "street": "Av Uno",
            "exterior_number": "104",
            "internal_number": "A203", 
            "city": "Benito Juárez", 
            "country": "México", 
            "state":"Ciudad de México"            
        },
        "identification": { 
            "id": "AAA840621HCAAA01", 
            "type": "CURP"
        }        
    },
    "prevention_data": {
        "customer_type": "returning_buyer",
        "submerchant_id":"id 001",
        "customer_risk_score":15,
        "transaction_risk_level":"low",
        "session_id":session_id,
        "user_agent":user_agent,
        "request_3ds": true
    },
    "metadata": {         
        "billing_address": {
            "postal_code": "03800",
            "street": "vip",
            "exterior_number": "104",
            "internal_number": "A203",
            "colony": "San Miguel Chapultepec",
            "reference": "Puerta de color negro",
            "city": "Benito Juárez",
            "country": "México",
            "state": "Ciudad de México"
        },
        "shipping_address": { 
            "postal_code": "03800",
            "exterior_number": "104",
            "internal_number": "A203",
            "colony": "San Miguel Chapultepec",
            "reference": "Puerta de color negro",
            "city": "México",
            "country": "Benito Juárez",
            "state": "Ciudad de México"
        },     
        "website": "https://clip.mx"
    },
    "location": {
      	"ip": "130.41.173.243"
    },
    "webhook_url": "https://miwebhook.com"

}'