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 |
|
|
|
|
|
Correo del cliente que realiza la transacción. |
String |
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.
- 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": "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"
},
"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,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?org_id=k8vif92e&session_id=clip_mx${session_id}">
</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?org_id=k8vif92e&session_id=clip_mx7376d6ec-e9f6-48d5-a1ce-26241bd7e5d7"></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",
"device_finger_print_token":"f47ac10b-58cc-4372-a567-0e02b2c3d479",
"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",
"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
},
"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"
}'