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.

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

colony

Colonia del domicilio.

String

"San Pedro de los Pinos"

Opcional

reference

Referencia del domicilio.

String

"Edificio gris"

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",
        "colony": "San Pedro de los Pinos",
        "reference": "Edificio gris",
        "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": "Av Uno",
        "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",
        "street": "Av Uno",
        "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,la validación 3DS será activada en función del análisis de riesgo de la transacción.


Obtener el session_id

El session_id permite identificar al comprador. Para obtenerlo puedes implementar el siguiente script:

<script id="cybersource" src="https://tools.clip.mx/transparent/risk?session_id=${uuid}">
</script>

Donde ${uuid} (Por sus siglas “Universal Unique Identifier”), es un valor de 128 bits utilizado para identificar de forma única un objeto o entidad en Internet.

Ejemplo:

${uuid}: f47ac10b-58cc-4372-a567-0e02b2c3d479
<script id="cybersource" src="https://tools.clip.mx/transparent/risk?session_id=f47ac10b-58cc-4372-a567-0e02b2c3d479"></script>

📘

El uuid es generado por sesión y se puede tomar como ejemplo la siguiente URL: https://www.uuidgenerator.net


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
    }

Nota: Si envías un "request_3ds": true y tienes un "binary_mode":true la transacción será rechazada en automático ya que "binary_mode" tiene más jerarquía.



Obtener el user_agent

El user_agent permite identificar el navegador del comprador. Para obtenerlo puedes implementar el siguiente script:

<script>
	var user_agent=globalThis.navigator.userAgent;
</script>


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"
}



Realizar pago

Estos objetos 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",
        "session_id":"f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "user_agent":"Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)",
        "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"

}'