Desarrolladores
Soporte a desarrolladores

Prevención de fraudes

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:

  1. Importa el SDK (clip-sdk.js)
  2. Configura el formulario y obtén el Card Token ID
  3. Autentícate con tu API Key e inicializa el SDK de Clip
  4. Despliega el formulario y obtén el token de la tarjeta (Card Token ID)
  5. Obtén los prevention_data
  6. 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

"[email protected]"

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": "[email protected]",
    "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.
  • source: Identifica el Shopping Cart o plataforma usada para crear el checkout.

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

source

Identifica el Shopping Cart.

String

"txo_woocommerce"

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"
    },     
    "source": "txo_woocommerce",
    "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 device_finger_print_token, 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.

device_finger_print_token

Identificador del dispositivo donde el comprador realiza el pago

String

"a68653f7-2310-40af-a7f2-43065d97954a"

Opcional

Se recomienda enviar este parámetro

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",
       "device_finger_print_token":"a68653f7-2310-40af-a7f2-43065d97954a",
       "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:

  1. session_id
  2. user_agent
  3. device_finger_print_token

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;
const device_finger_print_token= preventionData.device_finger_print_token;

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": "[email protected]",
        "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",
        "device_finger_print_token":device_finger_print_token,
        "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"
        },     
        "source": "txo_woocommerce",
        "website": "https://clip.mx"
    },
    "location": {
      	"ip": "130.41.173.243"
    },
    "webhook_url": "https://miwebhook.com"

}'